/*
* 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
{
///
/// 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
/// |----------------------------------------------------------------------
///
///
public interface IStreamMessage : IMessage
{
///
/// Reads a boolean from the stream message.
///
///
/// A
///
///
/// if the NMS provider fails to read the message due to some internal error.
///
///
/// if unexpected end of message stream has been reached.
///
///
/// if this type conversion is invalid.
///
///
/// if the message is in write-only mode.
///
bool ReadBoolean();
///
/// Reads a byte from the stream message.
///
///
/// A
///
///
/// if the NMS provider fails to read the message due to some internal error.
///
///
/// if unexpected end of message stream has been reached.
///
///
/// if this type conversion is invalid.
///
///
/// if the message is in write-only mode.
///
byte ReadByte();
///
/// 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.
///
///
/// A
///
///
/// A
/// 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
///
///
/// if the NMS provider fails to read the message due to some internal error.
///
///
/// if unexpected end of message stream has been reached.
///
///
/// if this type conversion is invalid.
///
///
/// if the message is in write-only mode.
///
///
int ReadBytes(byte[] value);
///
/// Reads a char from the stream message.
///
///
/// A
///
///
/// if the NMS provider fails to read the message due to some internal error.
///
///
/// if unexpected end of message stream has been reached.
///
///
/// if this type conversion is invalid.
///
///
/// if the message is in write-only mode.
///
char ReadChar();
///
/// Reads a short from the stream message.
///
///
/// A
///
///
/// if the NMS provider fails to read the message due to some internal error.
///
///
/// if unexpected end of message stream has been reached.
///
///
/// if this type conversion is invalid.
///
///
/// if the message is in write-only mode.
///
short ReadInt16();
///
/// Reads a int from the stream message.
///
///
/// A
///
///
/// if the NMS provider fails to read the message due to some internal error.
///
///
/// if unexpected end of message stream has been reached.
///
///
/// if this type conversion is invalid.
///
///
/// if the message is in write-only mode.
///
int ReadInt32();
///
/// Reads a long from the stream message.
///
///
/// A
///
///
/// if the NMS provider fails to read the message due to some internal error.
///
///
/// if unexpected end of message stream has been reached.
///
///
/// if this type conversion is invalid.
///
///
/// if the message is in write-only mode.
///
long ReadInt64();
///
/// Reads a float from the stream message.
///
///
/// A
///
///
/// if the NMS provider fails to read the message due to some internal error.
///
///
/// if unexpected end of message stream has been reached.
///
///
/// if this type conversion is invalid.
///
///
/// if the message is in write-only mode.
///
float ReadSingle();
///
/// Reads a double from the stream message.
///
///
/// A
///
///
/// if the NMS provider fails to read the message due to some internal error.
///
///
/// if unexpected end of message stream has been reached.
///
///
/// if this type conversion is invalid.
///
///
/// if the message is in write-only mode.
///
double ReadDouble();
///
/// Reads a string from the stream message.
///
///
/// A
///
///
/// if the NMS provider fails to read the message due to some internal error.
///
///
/// if unexpected end of message stream has been reached.
///
///
/// if this type conversion is invalid.
///
///
/// if the message is in write-only mode.
///
string ReadString();
///
/// Reads a Object from the stream message.
///
///
/// A
///
///
/// if the NMS provider fails to read the message due to some internal error.
///
///
/// if unexpected end of message stream has been reached.
///
///
/// if this type conversion is invalid.
///
///
/// if the message is in write-only mode.
///
Object ReadObject();
///
/// Writes a boolean to the stream message.
///
///
/// A
///
///
/// if the NMS provider fails to write to the message due to some internal error.
///
///
/// if the message is in read-only mode.
///
void WriteBoolean(bool value);
///
/// Writes a byte to the stream message.
///
///
/// A
///
///
/// if the NMS provider fails to write to the message due to some internal error.
///
///
/// if the message is in read-only mode.
///
void WriteByte(byte value);
///
/// 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.
///
///
/// A
///
///
/// if the NMS provider fails to write to the message due to some internal error.
///
///
/// if the message is in read-only mode.
///
void WriteBytes(byte[] value);
///
/// 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.
///
///
/// A
///
///
/// A value that indicates the point in the buffer to
/// begin writing to the stream message.
///
///
/// A value that indicates how many bytes in the buffer
/// to write to the stream message.
///
///
/// if the NMS provider fails to write to the message due to some internal error.
///
///
/// if the message is in read-only mode.
///
void WriteBytes(byte[] value, int offset, int length);
///
/// Writes a char to the stream message.
///
///
/// A
///
///
/// if the NMS provider fails to write to the message due to some internal error.
///
///
/// if the message is in read-only mode.
///
void WriteChar(char value);
///
/// Writes a short to the stream message.
///
///
/// A
///
///
/// if the NMS provider fails to write to the message due to some internal error.
///
///
/// if the message is in read-only mode.
///
void WriteInt16(short value);
///
/// Writes a int to the stream message.
///
///
/// A
///
///
/// if the NMS provider fails to write to the message due to some internal error.
///
///
/// if the message is in read-only mode.
///
void WriteInt32(int value);
///
/// Writes a long to the stream message.
///
///
/// A
///
///
/// if the NMS provider fails to write to the message due to some internal error.
///
///
/// if the message is in read-only mode.
///
void WriteInt64(long value);
///
/// Writes a float to the stream message.
///
///
/// A
///
///
/// if the NMS provider fails to write to the message due to some internal error.
///
///
/// if the message is in read-only mode.
///
void WriteSingle(float value);
///
/// Writes a double to the stream message.
///
///
/// A
///
///
/// if the NMS provider fails to write to the message due to some internal error.
///
///
/// if the message is in read-only mode.
///
void WriteDouble(double value);
///
/// Writes a string to the stream message.
///
///
/// A
///
///
/// if the NMS provider fails to write to the message due to some internal error.
///
///
/// if the message is in read-only mode.
///
void WriteString(string value);
///
/// Writes a boolean to the stream message.
///
///
/// A
///
///
/// if the NMS provider fails to write to the message due to some internal error.
///
///
/// if the message is in read-only mode.
///
void WriteObject(Object value);
///
/// Puts the message body in read-only mode and repositions the stream to the beginning.
///
///
/// Thrown when the Message has an invalid format.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
void Reset();
}
}