src/nms-api/IBytesMessage.cs

/* * 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. */ namespace Apache.NMS { /// <summary> /// /// A BytesMessage object is used to send a message containing a stream of uninterpreted /// bytes. It inherits from the Message interface and adds a bytes message body. The /// receiver of the message supplies the interpretation of the bytes. /// /// This message type is for client encoding of existing message formats. If possible, /// one of the other self-defining message types should be used instead. /// /// Although the NMS API allows the use of message properties with byte messages, they /// are typically not used, since the inclusion of properties may affect the format. /// /// 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 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. /// </summary> public interface IBytesMessage : IMessage { byte[] Content { get; set; } /// <value> /// Gets the number of bytes of the message body when the message is in read-only mode. /// The value returned can be used to allocate a byte array. The value returned is the /// entire length of the message body, regardless of where the pointer for reading the /// message is currently located. /// </value> /// <exception cref="Apache.NMS.MessageNotReadableException"> /// Thrown when the Message is in write-only mode. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> long BodyLength { get; } /// <summary> /// Reads a byte from the Message Stream. /// </summary> /// <returns> /// A <see cref="System.Byte"/> /// </returns> /// <exception cref="Apache.NMS.MessageNotReadableException"> /// Thrown when the Message is in write-only mode. /// </exception> /// <exception cref="Apache.NMS.MessageEOFException"> /// Thrown when an unexpected end of bytes has been reached. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> byte ReadByte(); /// <summary> /// Writes a byte to the Message stream. /// </summary> /// <param name="value"> /// A <see cref="System.Byte"/> /// </param> /// <exception cref="Apache.NMS.MessageNotWriteableException"> /// Thrown when the Message is in read-only mode. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> void WriteByte(byte value); /// <summary> /// Reads a boolean from the Message Stream. /// </summary> /// <returns> /// A <see cref="System.Boolean"/> /// </returns> /// <exception cref="Apache.NMS.MessageNotReadableException"> /// Thrown when the Message is in write-only mode. /// </exception> /// <exception cref="Apache.NMS.MessageEOFException"> /// Thrown when an unexpected end of bytes has been reached. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> bool ReadBoolean(); /// <summary> /// Write a one byte value to the message stream representing the boolean /// value passed. /// </summary> /// <param name="value"> /// A <see cref="System.Boolean"/> /// </param> /// <exception cref="Apache.NMS.MessageNotWriteableException"> /// Thrown when the Message is in read-only mode. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> void WriteBoolean(bool value); /// <summary> /// Reads a char from the Message Stream. /// </summary> /// <returns> /// A <see cref="System.Char"/> /// </returns> /// <exception cref="Apache.NMS.MessageNotReadableException"> /// Thrown when the Message is in write-only mode. /// </exception> /// <exception cref="Apache.NMS.MessageEOFException"> /// Thrown when an unexpected end of bytes has been reached. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> char ReadChar(); /// <summary> /// Write a two byte value to the message stream representing the character /// value passed. High byte first. /// </summary> /// <param name="value"> /// A <see cref="System.Char"/> /// </param> /// <exception cref="Apache.NMS.MessageNotWriteableException"> /// Thrown when the Message is in read-only mode. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> void WriteChar(char value); /// <summary> /// Reads a Short from the Message Stream. /// </summary> /// <returns> /// A <see cref="System.Int16"/> /// </returns> /// <exception cref="Apache.NMS.MessageNotReadableException"> /// Thrown when the Message is in write-only mode. /// </exception> /// <exception cref="Apache.NMS.MessageEOFException"> /// Thrown when an unexpected end of bytes has been reached. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> short ReadInt16(); /// <summary> /// Write a two byte value to the message stream representing the short /// value passed. High byte first. /// </summary> /// <param name="value"> /// A <see cref="System.Int16"/> /// </param> /// <exception cref="Apache.NMS.MessageNotWriteableException"> /// Thrown when the Message is in read-only mode. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> void WriteInt16(short value); /// <summary> /// Reads an int from the Message Stream. /// </summary> /// <returns> /// A <see cref="System.Int32"/> /// </returns> /// <exception cref="Apache.NMS.MessageNotReadableException"> /// Thrown when the Message is in write-only mode. /// </exception> /// <exception cref="Apache.NMS.MessageEOFException"> /// Thrown when an unexpected end of bytes has been reached. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> int ReadInt32(); /// <summary> /// Write a four byte value to the message stream representing the integer /// value passed. High byte first. /// </summary> /// <param name="value"> /// A <see cref="System.Int32"/> /// </param> /// <exception cref="Apache.NMS.MessageNotWriteableException"> /// Thrown when the Message is in read-only mode. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> void WriteInt32(int value); /// <summary> /// Reads a long from the Message Stream. /// </summary> /// <returns> /// A <see cref="System.Int64"/> /// </returns> /// <exception cref="Apache.NMS.MessageNotReadableException"> /// Thrown when the Message is in write-only mode. /// </exception> /// <exception cref="Apache.NMS.MessageEOFException"> /// Thrown when an unexpected end of bytes has been reached. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> long ReadInt64(); /// <summary> /// Write a eight byte value to the message stream representing the long /// value passed. High byte first. /// </summary> /// <param name="value"> /// A <see cref="System.Int64"/> /// </param> /// <exception cref="Apache.NMS.MessageNotWriteableException"> /// Thrown when the Message is in read-only mode. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> void WriteInt64(long value); /// <summary> /// Reads a float from the Message Stream. /// </summary> /// <returns> /// A <see cref="System.Single"/> /// </returns> /// <exception cref="Apache.NMS.MessageNotReadableException"> /// Thrown when the Message is in write-only mode. /// </exception> /// <exception cref="Apache.NMS.MessageEOFException"> /// Thrown when an unexpected end of bytes has been reached. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> float ReadSingle(); /// <summary> /// Write a four byte value to the message stream representing the float /// value passed. High byte first. /// </summary> /// <param name="value"> /// A <see cref="System.Single"/> /// </param> /// <exception cref="Apache.NMS.MessageNotWriteableException"> /// Thrown when the Message is in read-only mode. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> void WriteSingle(float value); /// <summary> /// Reads an double from the Message Stream. /// </summary> /// <returns> /// A <see cref="System.Double"/> /// </returns> /// <exception cref="Apache.NMS.MessageNotReadableException"> /// Thrown when the Message is in write-only mode. /// </exception> /// <exception cref="Apache.NMS.MessageEOFException"> /// Thrown when an unexpected end of bytes has been reached. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> double ReadDouble(); /// <summary> /// Write a eight byte value to the message stream representing the double /// value passed. High byte first. /// </summary> /// <param name="value"> /// A <see cref="System.Double"/> /// </param> /// <exception cref="Apache.NMS.MessageNotWriteableException"> /// Thrown when the Message is in read-only mode. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> void WriteDouble(double value); /// <summary> /// Reads a byte array from the bytes message stream. /// /// If the length of array value is less than the number of bytes remaining to /// be read from the stream, the array should be filled. A subsequent call reads /// the next increment, and so on. /// /// If the number of bytes remaining in the stream is less than the length of array /// value, the bytes should be read into the array. The return value of the total number /// of bytes read will be less than the length of the array, indicating that there are /// no more bytes left to be read from the stream. The next read of the stream returns -1. /// </summary> /// <param name="value"> /// The byte array that will be used as a buffer to read into. /// </param> /// <returns> /// A <see cref="System.Int32"/> /// The number of bytes read into the passed byte array, or -1 if there are no more /// bytes left to be read from the stream. /// </returns> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> /// <exception cref="Apache.NMS.MessageNotReadableException"> /// Thrown when the Message is in write-only mode. /// </exception> int ReadBytes(byte[] value); /// <summary> /// Reads a portion of the bytes message stream. /// /// If the length of array value is less than the number of bytes remaining to be /// read from the stream, the array should be filled. A subsequent call reads the /// next increment, and so on. /// /// If the number of bytes remaining in the stream is less than the length of array /// value, the bytes should be read into the array. The return value of the total /// number of bytes read will be less than the length of the array, indicating that /// there are no more bytes left to be read from the stream. The next read of the /// stream returns -1. /// /// If length is negative, or length is greater than the length of the array value, /// then an Exception is thrown. No bytes will be read from the stream for this /// exception case. /// </summary> /// <param name="value"> /// The byte array that will be used as a buffer to read into. /// </param> /// <param name="length"> /// The amount of bytes to read into the buffer. /// </param> /// <returns> /// A <see cref="System.Int32"/> /// The number of bytes read into the passed byte array, or -1 if there are no more /// bytes left to be read from the stream. /// </returns> /// <exception cref="Apache.NMS.MessageNotReadableException"> /// Thrown when the Message is in write-only mode. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> int ReadBytes(byte[] value, int length); /// <summary> /// Writes a byte array to the bytes message stream. /// </summary> /// <param name="value"> /// A <see cref="System.Byte"/> /// </param> /// <exception cref="Apache.NMS.MessageNotWriteableException"> /// Thrown when the Message is in read-only mode. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> void WriteBytes(byte[] value); /// <summary> /// Writes a portion of a byte array to the bytes message stream. /// </summary> /// <param name="value"> /// A <see cref="System.Byte"/> /// </param> /// <param name="offset"> /// A <see cref="System.Int32"/> /// </param> /// <param name="length"> /// A <see cref="System.Int32"/> /// </param> /// <exception cref="Apache.NMS.MessageNotWriteableException"> /// Thrown when the Message is in read-only mode. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> void WriteBytes(byte[] value, int offset, int length); /// <summary> /// Reads a string that has been encoded using a modified UTF-8 format from the bytes /// message stream. /// </summary> /// <returns> /// A <see cref="System.String"/> /// </returns> /// <exception cref="Apache.NMS.MessageNotReadableException"> /// Thrown when the Message is in write-only mode. /// </exception> /// <exception cref="Apache.NMS.MessageEOFException"> /// Thrown when an unexpected end of bytes has been reached. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> string ReadString(); /// <summary> /// Writes a string to the bytes message stream using UTF-8 encoding in a /// machine-independent manner. /// </summary> /// <param name="value"> /// A <see cref="System.String"/> /// </param> /// <exception cref="Apache.NMS.MessageNotWriteableException"> /// Thrown when the Message is in read-only mode. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> void WriteString(string value); /// <summary> /// Writes an object to the bytes message stream. /// /// This method works only for the objectified primitive object types /// (Int32, Double, Boolean ...), String objects, and byte arrays. /// </summary> /// <param name="value"> /// A <see cref="System.Object"/> /// the object in the .NET programming language to be written; it must not be null /// </param> /// <exception cref="Apache.NMS.MessageFormatException"> /// Thrown when the Message has an invalid format. /// </exception> /// <exception cref="Apache.NMS.MessageNotWriteableException"> /// Thrown when the Message is in read-only mode. /// </exception> /// <exception cref="Apache.NMS.NMSException"> /// Thrown when there is an unhandled exception thrown from the provider. /// </exception> void WriteObject(System.Object value); /// <summary> /// Puts the message body in read-only mode and repositions the stream of bytes 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(); } }

src/nms-api/IBytesMessage.cs (32 lines of code) (raw):