You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@activemq.apache.org by ta...@apache.org on 2009/10/06 16:39:01 UTC
svn commit: r822294 -
/activemq/activemq-dotnet/Apache.NMS/trunk/src/main/csharp/IStreamMessage.cs
Author: tabish
Date: Tue Oct 6 14:38:59 2009
New Revision: 822294
URL: http://svn.apache.org/viewvc?rev=822294&view=rev
Log:
https://issues.apache.org/activemq/browse/AMQNET-116
Add IStreamMessage to NMS API.
Added:
activemq/activemq-dotnet/Apache.NMS/trunk/src/main/csharp/IStreamMessage.cs (with props)
Added: activemq/activemq-dotnet/Apache.NMS/trunk/src/main/csharp/IStreamMessage.cs
URL: http://svn.apache.org/viewvc/activemq/activemq-dotnet/Apache.NMS/trunk/src/main/csharp/IStreamMessage.cs?rev=822294&view=auto
==============================================================================
--- activemq/activemq-dotnet/Apache.NMS/trunk/src/main/csharp/IStreamMessage.cs (added)
+++ activemq/activemq-dotnet/Apache.NMS/trunk/src/main/csharp/IStreamMessage.cs Tue Oct 6 14:38:59 2009
@@ -0,0 +1,518 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+using System;
+
+namespace Apache.NMS
+{
+ /// <summary>
+ /// A StreamMessage object is used to send a stream of primitive types in the
+ /// .NET programming language. It is filled and read sequentially. It inherits
+ /// from the Message interface and adds a stream message body.
+ ///
+ /// The primitive types can be read or written explicitly using methods for each
+ /// type. They may also be read or written generically as objects. For instance,
+ /// a call to IStreamMessage.WriteInt32(6) is equivalent to
+ /// StreamMessage.WriteObject( (Int32)6 ). Both forms are provided, because the
+ /// explicit form is convenient for static programming, and the object form is
+ /// needed when types are not known at compile time.
+ ///
+ /// When the message is first created, and when ClearBody is called, the body of
+ /// the message is in write-only mode. After the first call to reset has been made,
+ /// the message body is in read-only mode. After a message has been sent, the
+ /// client that sent it can retain and modify it without affecting the message
+ /// that has been sent. The same message object can be sent multiple times. When a
+ /// message has been received, the provider has called reset so that the message
+ /// body is in read-only mode for the client.
+ ///
+ /// If ClearBody is called on a message in read-only mode, the message body is
+ /// cleared and the message body is in write-only mode.
+ ///
+ /// If a client attempts to read a message in write-only mode, a
+ /// MessageNotReadableException is thrown.
+ ///
+ /// If a client attempts to write a message in read-only mode, a
+ /// MessageNotWriteableException is thrown.
+ ///
+ /// IStreamMessage objects support the following conversion table. The marked cases
+ /// must be supported. The unmarked cases must throw a NMSException. The
+ /// String-to-primitive conversions may throw a runtime exception if the primitive's
+ /// valueOf() method does not accept it as a valid String representation of the
+ /// primitive.
+ ///
+ /// A value written as the row type can be read as the column type.
+ ///
+ /// | | boolean byte short char int long float double String byte[]
+ /// |----------------------------------------------------------------------
+ /// |boolean | X X
+ /// |byte | X X X X X
+ /// |short | X X X X
+ /// |char | X X
+ /// |int | X X X
+ /// |long | X X
+ /// |float | X X X
+ /// |double | X X
+ /// |String | X X X X X X X X
+ /// |byte[] | X
+ /// |----------------------------------------------------------------------
+ ///
+ /// </summary>
+ public interface IStreamMessage : IMessage
+ {
+
+ /// <summary>
+ /// Reads a boolean from the stream message.
+ /// </summary>
+ /// <returns>
+ /// A <see cref="System.Boolean"/>
+ /// </returns>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to read the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageEOFException">
+ /// if unexpected end of message stream has been reached.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageFormatException">
+ /// if this type conversion is invalid.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotReadableException">
+ /// if the message is in write-only mode.
+ /// </exception>
+ bool ReadBoolean();
+
+ /// <summary>
+ /// Reads a byte from the stream message.
+ /// </summary>
+ /// <returns>
+ /// A <see cref="System.Byte"/>
+ /// </returns>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to read the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageEOFException">
+ /// if unexpected end of message stream has been reached.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageFormatException">
+ /// if this type conversion is invalid.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotReadableException">
+ /// if the message is in write-only mode.
+ /// </exception>
+ byte ReadByte();
+
+ /// <summary>
+ /// Reads a byte array field from the stream message into the specified byte[]
+ /// object (the read buffer).
+ ///
+ /// To read the field value, ReadBytes should be successively called until it returns
+ /// a value less than the length of the read buffer. The value of the bytes in the
+ /// buffer following the last byte read is undefined.
+ ///
+ /// If ReadBytes returns a value equal to the length of the buffer, a subsequent
+ /// ReadBytes call must be made. If there are no more bytes to be read, this call
+ /// returns -1.
+ ///
+ /// If the byte array field value is null, ReadBytes returns -1.
+ /// If the byte array field value is empty, ReadBytes returns 0.
+ ///
+ /// Once the first ReadBytes call on a byte[] field value has been made, the full
+ /// value of the field must be read before it is valid to read the next field.
+ /// An attempt to read the next field before that has been done will throw a
+ /// MessageFormatException.
+ ///
+ /// To read the byte field value into a new byte[] object, use the ReadObject method.
+ /// </summary>
+ /// <param name="value">
+ /// A <see cref="System.Byte"/>
+ /// </param>
+ /// <returns>
+ /// A <see cref="System.Byte"/>
+ /// the total number of bytes read into the buffer, or -1 if there is no more data
+ /// because the end of the byte field has been reached
+ /// </returns>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to read the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageEOFException">
+ /// if unexpected end of message stream has been reached.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageFormatException">
+ /// if this type conversion is invalid.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotReadableException">
+ /// if the message is in write-only mode.
+ /// </exception>
+ /// <seealso cref="ReadObject"/>
+ int ReadBytes(byte[] value);
+
+ /// <summary>
+ /// Reads a char from the stream message.
+ /// </summary>
+ /// <returns>
+ /// A <see cref="System.Char"/>
+ /// </returns>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to read the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageEOFException">
+ /// if unexpected end of message stream has been reached.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageFormatException">
+ /// if this type conversion is invalid.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotReadableException">
+ /// if the message is in write-only mode.
+ /// </exception>
+ char ReadChar();
+
+ /// <summary>
+ /// Reads a short from the stream message.
+ /// </summary>
+ /// <returns>
+ /// A <see cref="System.Int16"/>
+ /// </returns>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to read the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageEOFException">
+ /// if unexpected end of message stream has been reached.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageFormatException">
+ /// if this type conversion is invalid.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotReadableException">
+ /// if the message is in write-only mode.
+ /// </exception>
+ short ReadInt16();
+
+ /// <summary>
+ /// Reads a int from the stream message.
+ /// </summary>
+ /// <returns>
+ /// A <see cref="System.Int32"/>
+ /// </returns>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to read the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageEOFException">
+ /// if unexpected end of message stream has been reached.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageFormatException">
+ /// if this type conversion is invalid.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotReadableException">
+ /// if the message is in write-only mode.
+ /// </exception>
+ int ReadInt32();
+
+ /// <summary>
+ /// Reads a long from the stream message.
+ /// </summary>
+ /// <returns>
+ /// A <see cref="System.Int64"/>
+ /// </returns>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to read the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageEOFException">
+ /// if unexpected end of message stream has been reached.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageFormatException">
+ /// if this type conversion is invalid.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotReadableException">
+ /// if the message is in write-only mode.
+ /// </exception>
+ long ReadInt64();
+
+ /// <summary>
+ /// Reads a float from the stream message.
+ /// </summary>
+ /// <returns>
+ /// A <see cref="System.Single"/>
+ /// </returns>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to read the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageEOFException">
+ /// if unexpected end of message stream has been reached.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageFormatException">
+ /// if this type conversion is invalid.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotReadableException">
+ /// if the message is in write-only mode.
+ /// </exception>
+ float ReadSingle();
+
+ /// <summary>
+ /// Reads a double from the stream message.
+ /// </summary>
+ /// <returns>
+ /// A <see cref="System.Double"/>
+ /// </returns>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to read the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageEOFException">
+ /// if unexpected end of message stream has been reached.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageFormatException">
+ /// if this type conversion is invalid.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotReadableException">
+ /// if the message is in write-only mode.
+ /// </exception>
+ double ReadDouble();
+
+ /// <summary>
+ /// Reads a string from the stream message.
+ /// </summary>
+ /// <returns>
+ /// A <see cref="System.String"/>
+ /// </returns>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to read the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageEOFException">
+ /// if unexpected end of message stream has been reached.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageFormatException">
+ /// if this type conversion is invalid.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotReadableException">
+ /// if the message is in write-only mode.
+ /// </exception>
+ string ReadString();
+
+ /// <summary>
+ /// Reads a Object from the stream message.
+ /// </summary>
+ /// <returns>
+ /// A <see cref="System.Object"/>
+ /// </returns>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to read the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageEOFException">
+ /// if unexpected end of message stream has been reached.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageFormatException">
+ /// if this type conversion is invalid.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotReadableException">
+ /// if the message is in write-only mode.
+ /// </exception>
+ Object ReadObject();
+
+ /// <summary>
+ /// Writes a boolean to the stream message.
+ /// </summary>
+ /// <param name="value">
+ /// A <see cref="System.Boolean"/>
+ /// </param>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to write to the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotWriteableException">
+ /// if the message is in read-only mode.
+ /// </exception>
+ void WriteBoolean(bool value);
+
+ /// <summary>
+ /// Writes a byte to the stream message.
+ /// </summary>
+ /// <param name="value">
+ /// A <see cref="System.Byte"/>
+ /// </param>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to write to the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotWriteableException">
+ /// if the message is in read-only mode.
+ /// </exception>
+ void WriteByte(byte value);
+
+ /// <summary>
+ /// Writes a byte array field to the stream message.
+ ///
+ /// The byte array value is written to the message as a byte array field.
+ /// Consecutively written byte array fields are treated as two distinct
+ /// fields when the fields are read.
+ /// </summary>
+ /// <param name="value">
+ /// A <see cref="System.Byte"/>
+ /// </param>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to write to the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotWriteableException">
+ /// if the message is in read-only mode.
+ /// </exception>
+ void WriteBytes(byte[] value);
+
+ /// <summary>
+ /// Writes a portion of a byte array as a byte array field to the stream message.
+ ///
+ /// The a portion of the byte array value is written to the message as a byte
+ /// array field. Consecutively written byte array fields are treated as two distinct
+ /// fields when the fields are read.
+ /// </summary>
+ /// <param name="value">
+ /// A <see cref="System.Byte"/>
+ /// </param>
+ /// <param name="offset">
+ /// A <see cref="System.Int32"/> value that indicates the point in the buffer to
+ /// begin writing to the stream message.
+ /// </param>
+ /// <param name="length">
+ /// A <see cref="System.Int32"/> value that indicates how many bytes in the buffer
+ /// to write to the stream message.
+ /// </param>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to write to the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotWriteableException">
+ /// if the message is in read-only mode.
+ /// </exception>
+ void WriteBytes(byte[] value, int offset, int length);
+
+ /// <summary>
+ /// Writes a char to the stream message.
+ /// </summary>
+ /// <param name="value">
+ /// A <see cref="System.Char"/>
+ /// </param>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to write to the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotWriteableException">
+ /// if the message is in read-only mode.
+ /// </exception>
+ void WriteChar(char value);
+
+ /// <summary>
+ /// Writes a short to the stream message.
+ /// </summary>
+ /// <param name="value">
+ /// A <see cref="System.Int16"/>
+ /// </param>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to write to the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotWriteableException">
+ /// if the message is in read-only mode.
+ /// </exception>
+ void WriteInt16(short value);
+
+ /// <summary>
+ /// Writes a int to the stream message.
+ /// </summary>
+ /// <param name="value">
+ /// A <see cref="System.Int32"/>
+ /// </param>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to write to the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotWriteableException">
+ /// if the message is in read-only mode.
+ /// </exception>
+ void WriteInt32(int value);
+
+ /// <summary>
+ /// Writes a long to the stream message.
+ /// </summary>
+ /// <param name="value">
+ /// A <see cref="System.Int64"/>
+ /// </param>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to write to the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotWriteableException">
+ /// if the message is in read-only mode.
+ /// </exception>
+ void WriteInt64(long value);
+
+ /// <summary>
+ /// Writes a float to the stream message.
+ /// </summary>
+ /// <param name="value">
+ /// A <see cref="System.Single"/>
+ /// </param>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to write to the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotWriteableException">
+ /// if the message is in read-only mode.
+ /// </exception>
+ void WriteSingle(float value);
+
+ /// <summary>
+ /// Writes a double to the stream message.
+ /// </summary>
+ /// <param name="value">
+ /// A <see cref="System.Double"/>
+ /// </param>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to write to the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotWriteableException">
+ /// if the message is in read-only mode.
+ /// </exception>
+ void WriteDouble(double value);
+
+ /// <summary>
+ /// Writes a string to the stream message.
+ /// </summary>
+ /// <param name="value">
+ /// A <see cref="System.String"/>
+ /// </param>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to write to the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotWriteableException">
+ /// if the message is in read-only mode.
+ /// </exception>
+ void WriteString(string value);
+
+ /// <summary>
+ /// Writes a boolean to the stream message.
+ /// </summary>
+ /// <param name="value">
+ /// A <see cref="System.Boolean"/>
+ /// </param>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// if the NMS provider fails to write to the message due to some internal error.
+ /// </exception>
+ /// <exception cref="Apache.NMS.MessageNotWriteableException">
+ /// if the message is in read-only mode.
+ /// </exception>
+ void WriteObject(Object value);
+
+ /// <summary>
+ /// Puts the message body in read-only mode and repositions the stream to the beginning.
+ /// </summary>
+ /// <exception cref="Apache.NMS.MessageFormatException">
+ /// Thrown when the Message has an invalid format.
+ /// </exception>
+ /// <exception cref="Apache.NMS.NMSException">
+ /// Thrown when there is an unhandled exception thrown from the provider.
+ /// </exception>
+ void Reset();
+
+ }
+}
Propchange: activemq/activemq-dotnet/Apache.NMS/trunk/src/main/csharp/IStreamMessage.cs
------------------------------------------------------------------------------
svn:eol-style = native