KMBytesMessage Class Reference
Overview
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 JMS API allows the use of message properties with byte messages, they are typically not used, since the inclusion of properties may affect the format.
The primitive types can be written explicitly using methods for each type. They may also be written generically as objects. For instance, a call to BytesMessage.WriteInt(6) is equivalent to BytesMessage.WriteObject(new Integer(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 method 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 KMMessageNotReadableException is thrown.
If a client attempts to write a message in read-only mode, a KMMessageNotWriteableException is thrown.
Warning: Note that the following methods of KMBytesMessage are currently not implemented:
- readFloat
- readDouble
- writeFloat
- writeDouble
- writeObject
Tasks
-
– bodyLength
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.
-
– readBoolean
Reads a bool from the bytes message stream.
-
– readByte
Reads a signed 8-bit value from the bytes message stream.
-
– readUnsignedByte
Reads an unsigned 8-bit number from the bytes message stream.
-
– readShort
Reads a signed 16-bit number from the bytes message stream.
-
– readUnsignedShort
Reads an unsigned 16-bit number from the bytes message stream.
-
– readChar
Reads a Unicode character value from the bytes message stream.
-
– readInt
Reads a signed 32-bit integer from the bytes message stream.
-
– readLong
Reads a signed 64-bit integer from the bytes message stream.
-
– readFloat
Reads a float from the bytes message stream.
-
– readDouble
Reads a double from the bytes message stream.
-
– readUTF
Reads a string that has been encoded using a modified UTF-8 format from the bytes message stream.
-
– readBytes:
Reads a byte array from the bytes message stream.
-
– readBytes:length:
Reads a portion of the bytes message stream.
-
– writeBoolean:
Writes a bool to the bytes message stream as a 1-byte value. The value true is written as the value (byte)1; the value false is written as the value (byte)0.
-
– writeByte:
Writes a byte to the bytes message stream as a 1-byte value.
-
– writeShort:
Writes a short to the bytes message stream as two bytes, high byte first.
-
– writeChar:
Writes a char to the bytes message stream as a 2-byte value, high byte first.
-
– writeInt:
Writes an int to the bytes message stream as four bytes, high byte first.
-
– writeLong:
Writes a long to the bytes message stream as eight bytes, high byte first.
-
– writeFloat:
Converts the float argument to an int using the floatToIntBits method in class Float, and then writes that int value to the bytes message stream as a 4-byte quantity, high byte first.
-
– writeDouble:
Converts the double argument to a long using the doubleToLongBits method in class Double, and then writes that long value to the bytes message stream as an 8-byte quantity, high byte first.
-
– writeUTF:
Writes a string to the bytes message stream using UTF-8 encoding in a machine-independent manner.
-
– writeBytes:
Writes a byte array to the bytes message stream.
-
– writeBytes:offset:length:
Writes a portion of a byte array to the bytes message stream.
-
– writeObject:
Writes an object to the bytes message stream.
-
– reset
Puts the message body in read-only mode and repositions the stream of bytes to the beginning.
Instance Methods
bodyLength
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.
- (long long)bodyLength
Return Value
number of bytes in the message
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageNotReadableException
if the message is in write-only mode.
Declared In
KMBytesMessage.h
readBoolean
Reads a bool from the bytes message stream.
- (BOOL)readBoolean
Return Value
the bool value read
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageEOFException
if unexpected end of bytes stream has been reached.
- KMMessageNotReadableException
if the message is in write-only mode.
Declared In
KMBytesMessage.h
readByte
Reads a signed 8-bit value from the bytes message stream.
- (char)readByte
Return Value
the next byte from the bytes message stream as a signed 8-bit byte
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageEOFException
if unexpected end of bytes stream has been reached.
- KMMessageNotReadableException
if the message is in write-only mode.
Declared In
KMBytesMessage.h
readBytes:
Reads a byte array from the bytes message stream.
- (int)readBytes:(NSMutableData *)value
Parameters
- value
the buffer into which the data is read
Return Value
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached
Discussion
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.
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageNotReadableException
if the message is in write-only mode.
Declared In
KMBytesMessage.h
readBytes:length:
Reads a portion of the bytes message stream.
- (int)readBytes:(NSMutableData *)value length:(int)length
Parameters
- value
the buffer into which the data is read
- length
the number of bytes to read; must be less than or equal to value.length
Return Value
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached
Discussion
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 a KMIndexOutOfRangeException is thrown. No bytes will be read from the stream for this exception case.
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageNotReadableException
if the message is in write-only mode.
Declared In
KMBytesMessage.h
readChar
Reads a Unicode character value from the bytes message stream.
- (unichar)readChar
Return Value
the next two bytes from the bytes message stream as a Unicode character
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageEOFException
if unexpected end of bytes stream has been reached.
- KMMessageNotReadableException
if the message is in write-only mode.
Declared In
KMBytesMessage.h
readDouble
Reads a double from the bytes message stream.
- (double)readDouble
Return Value
the next eight bytes from the bytes message stream, interpreted as a double
Discussion
Warning: Currently, this method is not implemented.
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageEOFException
if unexpected end of bytes stream has been reached.
- KMMessageNotReadableException
if the message is in write-only mode.
Declared In
KMBytesMessage.h
readFloat
Reads a float from the bytes message stream.
- (float)readFloat
Return Value
the next four bytes from the bytes message stream, interpreted as a float
Discussion
Warning: Currently, this method is not implemented.
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageEOFException
if unexpected end of bytes stream has been reached.
- KMMessageNotReadableException
if the message is in write-only mode.
Declared In
KMBytesMessage.h
readInt
Reads a signed 32-bit integer from the bytes message stream.
- (int)readInt
Return Value
the next four bytes from the bytes message stream, interpreted as an int
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageEOFException
if unexpected end of bytes stream has been reached.
- KMMessageNotReadableException
if the message is in write-only mode.
Declared In
KMBytesMessage.h
readLong
Reads a signed 64-bit integer from the bytes message stream.
- (long long)readLong
Return Value
the next eight bytes from the bytes message stream, interpreted as a long
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageEOFException
if unexpected end of bytes stream has been reached.
- KMMessageNotReadableException
if the message is in write-only mode.
Declared In
KMBytesMessage.h
readShort
Reads a signed 16-bit number from the bytes message stream.
- (short)readShort
Return Value
the next two bytes from the bytes message stream, interpreted as a signed 16-bit number
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageEOFException
if unexpected end of bytes stream has been reached.
- KMMessageNotReadableException
if the message is in write-only mode.
Declared In
KMBytesMessage.h
readUTF
Reads a string that has been encoded using a modified UTF-8 format from the bytes message stream.
- (NSString *)readUTF
Return Value
a Unicode string from the bytes message stream
Discussion
For more information on the UTF-8 format, see “File System Safe UCS Transformation Format (FSS_UTF)”, X/Open Preliminary Specification, X/Open Company Ltd., Document Number: P316. This information also appears in ISO/IEC 10646, Annex P.
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageEOFException
if unexpected end of bytes stream has been reached.
- KMMessageNotReadableException
if the message is in write-only mode.
Declared In
KMBytesMessage.h
readUnsignedByte
Reads an unsigned 8-bit number from the bytes message stream.
- (unsigned char)readUnsignedByte
Return Value
the next byte from the bytes message stream, interpreted as an unsigned 8-bit number
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageEOFException
if unexpected end of bytes stream has been reached.
- KMMessageNotReadableException
if the message is in write-only mode.
Declared In
KMBytesMessage.h
readUnsignedShort
Reads an unsigned 16-bit number from the bytes message stream.
- (unsigned short)readUnsignedShort
Return Value
the next two bytes from the bytes message stream, interpreted as an unsigned 16-bit integer
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageEOFException
if unexpected end of bytes stream has been reached.
- KMMessageNotReadableException
if the message is in write-only mode.
Declared In
KMBytesMessage.h
reset
Puts the message body in read-only mode and repositions the stream of bytes to the beginning.
- (void)reset
Exceptions
- KMJMSException
if the JMS provider fails to reset the message due to some internal error.
- KMMessageFormatException
if the message has an invalid format.
Declared In
KMBytesMessage.h
writeBoolean:
Writes a bool to the bytes message stream as a 1-byte value. The value true is written as the value (byte)1; the value false is written as the value (byte)0.
- (void)writeBoolean:(BOOL)value
Parameters
- value
the bool value to be written
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMBytesMessage.h
writeByte:
Writes a byte to the bytes message stream as a 1-byte value.
- (void)writeByte:(unsigned char)value
Parameters
- value
the byte value to be written
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMBytesMessage.h
writeBytes:
Writes a byte array to the bytes message stream.
- (void)writeBytes:(NSData *)value
Parameters
- value
the byte array to be written
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMBytesMessage.h
writeBytes:offset:length:
Writes a portion of a byte array to the bytes message stream.
- (void)writeBytes:(NSData *)value offset:(int)offset length:(int)length
Parameters
- value
the byte array value to be written
- offset
the initial offset within the byte array
- length
the number of bytes to use
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMBytesMessage.h
writeChar:
Writes a char to the bytes message stream as a 2-byte value, high byte first.
- (void)writeChar:(unichar)value
Parameters
- value
the char value to be written
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMBytesMessage.h
writeDouble:
Converts the double argument to a long using the doubleToLongBits method in class Double, and then writes that long value to the bytes message stream as an 8-byte quantity, high byte first.
- (void)writeDouble:(double)value
Parameters
- value
the double value to be written
Discussion
Warning: Currently, this method is not implemented.
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMBytesMessage.h
writeFloat:
Converts the float argument to an int using the floatToIntBits method in class Float, and then writes that int value to the bytes message stream as a 4-byte quantity, high byte first.
- (void)writeFloat:(float)value
Parameters
- value
the float value to be written
Discussion
Warning: Currently, this method is not implemented.
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMBytesMessage.h
writeInt:
Writes an int to the bytes message stream as four bytes, high byte first.
- (void)writeInt:(int)value
Parameters
- value
the int to be written
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMBytesMessage.h
writeLong:
Writes a long to the bytes message stream as eight bytes, high byte first.
- (void)writeLong:(long long)value
Parameters
- value
the long to be written
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMBytesMessage.h
writeObject:
Writes an object to the bytes message stream.
- (void)writeObject:(NSObject *)value
Parameters
- value
the object value to be written
Discussion
This method works only for the objectified primitive object types (Integer, Double, Long…), String objects, and byte arrays.
Warning: Currently, this method is not implemented.
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- KMMessageFormatException
if the object is of an invalid type.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMBytesMessage.h
writeShort:
Writes a short to the bytes message stream as two bytes, high byte first.
- (void)writeShort:(short)value
Parameters
- value
the short to be written
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMBytesMessage.h
writeUTF:
Writes a string to the bytes message stream using UTF-8 encoding in a machine-independent manner.
- (void)writeUTF:(NSString *)value
Parameters
- value
the String value to be written
Discussion
For more information on the UTF-8 format, see “File System Safe UCS Transformation Format (FSS_UTF)”, X/Open Preliminary Specification, X/Open Company Ltd., Document Number: P316. This information also appears in ISO/IEC 10646, Annex P.
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMBytesMessage.h