javax.jms
Interface BytesMessage


public interface BytesMessage
extends Message

A BytesMessage is used to send a message containing a stream of uninterpreted bytes. It inherits Message and adds a bytes message body. The receiver of the message supplies the interpretation of the bytes.

It's methods are based largely on those found in java.io.DataInputStream and java.io.DataOutputStream.

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 JMS allows the use of message properties with byte messages it is typically not done since the inclusion of properties affects 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. When a message has been sent, by definition, the provider calls reset in order to read it's content, and 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.

See Also:
Session.createBytesMessage(), MapMessage, Message, ObjectMessage, StreamMessage, TextMessage

Fields inherited from interface javax.jms.Message
DEFAULT_DELIVERY_MODE, DEFAULT_PRIORITY, DEFAULT_TIME_TO_LIVE
 
Method Summary
 boolean readBoolean()
          Read a boolean from the bytes message stream.
 byte readByte()
          Read a signed 8-bit value from the bytes message stream.
 int readBytes(byte[] value)
          Read a byte array from the bytes message stream.
 int readBytes(byte[] value, int length)
          Read a portion of the bytes message stream.
 char readChar()
          Read a Unicode character value from the bytes message stream.
 double readDouble()
          Read a double from the bytes message stream.
 float readFloat()
          Read a float from the bytes message stream.
 int readInt()
          Read a signed 32-bit integer from the bytes message stream.
 long readLong()
          Read a signed 64-bit integer from the bytes message stream.
 short readShort()
          Read a signed 16-bit number from the bytes message stream.
 int readUnsignedByte()
          Read an unsigned 8-bit number from the bytes message stream.
 int readUnsignedShort()
          Read an unsigned 16-bit number from the bytes message stream.
 java.lang.String readUTF()
          Read in a string that has been encoded using a modified UTF-8 format from the bytes message stream.
 void reset()
          Put the message body in read-only mode, and reposition the stream of bytes to the beginning.
 void writeBoolean(boolean value)
          Write a boolean to the bytes message stream as a 1-byte value.
 void writeByte(byte value)
          Write out a byte to the bytes message stream as a 1-byte value.
 void writeBytes(byte[] value)
          Write a byte array to the bytes message stream.
 void writeBytes(byte[] value, int offset, int length)
          Write a portion of a byte array to the bytes message stream.
 void writeChar(char value)
          Write a char to the bytes message stream as a 2-byte value, high byte first.
 void writeDouble(double value)
          Convert 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 writeFloat(float value)
          Convert 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 writeInt(int value)
          Write an int to the bytes message stream as four bytes, high byte first.
 void writeLong(long value)
          Write a long to the bytes message stream as eight bytes, high byte first.
 void writeObject(java.lang.Object value)
          Write a Java object to the bytes message stream.
 void writeShort(short value)
          Write a short to the bytes message stream as two bytes, high byte first.
 void writeUTF(java.lang.String value)
          Write a string to the bytes message stream using UTF-8 encoding in a machine-independent manner.
 
Methods inherited from interface javax.jms.Message
acknowledge, clearBody, clearProperties, getBooleanProperty, getByteProperty, getDoubleProperty, getFloatProperty, getIntProperty, getJMSCorrelationID, getJMSCorrelationIDAsBytes, getJMSDeliveryMode, getJMSDestination, getJMSExpiration, getJMSMessageID, getJMSPriority, getJMSRedelivered, getJMSReplyTo, getJMSTimestamp, getJMSType, getLongProperty, getObjectProperty, getPropertyNames, getShortProperty, getStringProperty, propertyExists, setBooleanProperty, setByteProperty, setDoubleProperty, setFloatProperty, setIntProperty, setJMSCorrelationID, setJMSCorrelationIDAsBytes, setJMSDeliveryMode, setJMSDestination, setJMSExpiration, setJMSMessageID, setJMSPriority, setJMSRedelivered, setJMSReplyTo, setJMSTimestamp, setJMSType, setLongProperty, setObjectProperty, setShortProperty, setStringProperty
 

Method Detail

readBoolean

public boolean readBoolean()
                    throws JMSException
Read a boolean from the bytes message stream.
Returns:
the boolean value read.
Throws:
MessageNotReadableException - if message in write-only mode.
JMSException - if JMS fails to read message due to some internal JMS error.
MessageEOFException - if end of bytes stream

readByte

public byte readByte()
              throws JMSException
Read a signed 8-bit value from the bytes message stream.
Returns:
the next byte from the bytes message stream as a signed 8-bit byte.
Throws:
MessageNotReadableException - if message in write-only mode.
MessageEOFException - if end of message stream
JMSException - if JMS fails to read message due to some internal JMS error.

readUnsignedByte

public int readUnsignedByte()
                     throws JMSException
Read an unsigned 8-bit number from the bytes message stream.
Returns:
the next byte from the bytes message stream, interpreted as an unsigned 8-bit number.
Throws:
MessageNotReadableException - if message in write-only mode.
MessageEOFException - if end of message stream
JMSException - if JMS fails to read message due to some internal JMS error.

readShort

public short readShort()
                throws JMSException
Read a signed 16-bit number from the bytes message stream.
Returns:
the next two bytes from the bytes message stream, interpreted as a signed 16-bit number.
Throws:
MessageNotReadableException - if message in write-only mode.
MessageEOFException - if end of message stream
JMSException - if JMS fails to read message due to some internal JMS error.

readUnsignedShort

public int readUnsignedShort()
                      throws JMSException
Read an unsigned 16-bit number from the bytes message stream.
Returns:
the next two bytes from the bytes message stream, interpreted as an unsigned 16-bit integer.
Throws:
MessageNotReadableException - if message in write-only mode.
MessageEOFException - if end of message stream
JMSException - if JMS fails to read message due to some internal JMS error.

readChar

public char readChar()
              throws JMSException
Read a Unicode character value from the bytes message stream.
Returns:
the next two bytes from the bytes message stream as a Unicode character.
Throws:
MessageNotReadableException - if message in write-only mode.
MessageEOFException - if end of message stream
JMSException - if JMS fails to read message due to some internal JMS error.

readInt

public int readInt()
            throws JMSException
Read a signed 32-bit integer from the bytes message stream.
Returns:
the next four bytes from the bytes message stream, interpreted as an int.
Throws:
MessageNotReadableException - if message in write-only mode.
MessageEOFException - if end of message stream
JMSException - if JMS fails to read message due to some internal JMS error.

readLong

public long readLong()
              throws JMSException
Read a signed 64-bit integer from the bytes message stream.
Returns:
the next eight bytes from the bytes message stream, interpreted as a long.
Throws:
MessageNotReadableException - if message in write-only mode.
MessageEOFException - if end of message stream
JMSException - if JMS fails to read message due to some internal JMS error.

readFloat

public float readFloat()
                throws JMSException
Read a float from the bytes message stream.
Returns:
the next four bytes from the bytes message stream, interpreted as a float.
Throws:
MessageNotReadableException - if message in write-only mode.
MessageEOFException - if end of message stream
JMSException - if JMS fails to read message due to some internal JMS error.

readDouble

public double readDouble()
                  throws JMSException
Read a double from the bytes message stream.
Returns:
the next eight bytes from the bytes message stream, interpreted as a double.
Throws:
MessageNotReadableException - if message in write-only mode.
MessageEOFException - if end of message stream
JMSException - if JMS fails to read message due to some internal JMS error.

readUTF

public java.lang.String readUTF()
                         throws JMSException
Read in a string that has been encoded using a modified UTF-8 format from the bytes message stream.

For more information on the UTF-8 format, see "File System Safe UCS Transformation Format (FSS_UFT)", X/Open Preliminary Specification, X/Open Company Ltd., Document Number: P316. This information also appears in ISO/IEC 10646, Annex P.

Returns:
a Unicode string from the bytes message stream.
Throws:
MessageNotReadableException - if message in write-only mode.
MessageEOFException - if end of message stream
JMSException - if JMS fails to read message due to some internal JMS error.

readBytes

public int readBytes(byte[] value)
              throws JMSException
Read a byte array from the bytes message stream.

If the length of array value is less than the bytes remaining to be read from the stream, the array should be filled. A subsequent call reads the next increment, etc.

If the 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.

Parameters:
value - the buffer into which the data is read.
Returns:
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.
Throws:
MessageNotReadableException - if message in write-only mode.
JMSException - if JMS fails to read message due to some internal JMS error.

readBytes

public int readBytes(byte[] value,
                     int length)
              throws JMSException
Read a portion of the bytes message stream.

If the length of array value is less than the bytes remaining to be read from the stream, the array should be filled. A subsequent call reads the next increment, etc.

If the 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 IndexOutOfBoundsException is thrown. No bytes will be read from the stream for this exception case.

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.
Returns:
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.
Throws:
MessageNotReadableException - if message in write-only mode.
JMSException - if JMS fails to read message due to some internal JMS error

writeBoolean

public void writeBoolean(boolean value)
                  throws JMSException
Write a boolean to the bytes message stream as a 1-byte value. The value true is written out as the value (byte)1; the value false is written out as the value (byte)0.
Parameters:
value - the boolean value to be written.
Throws:
MessageNotWriteableException - if message in read-only mode.
JMSException - if JMS fails to write message due to some internal JMS error.

writeByte

public void writeByte(byte value)
               throws JMSException
Write out a byte to the bytes message stream as a 1-byte value.
Parameters:
value - the byte value to be written.
Throws:
MessageNotWriteableException - if message in read-only mode.
JMSException - if JMS fails to write message due to some internal JMS error.

writeShort

public void writeShort(short value)
                throws JMSException
Write a short to the bytes message stream as two bytes, high byte first.
Parameters:
value - the short to be written.
Throws:
MessageNotWriteableException - if message in read-only mode.
JMSException - if JMS fails to write message due to some internal JMS error.

writeChar

public void writeChar(char value)
               throws JMSException
Write a char to the bytes message stream as a 2-byte value, high byte first.
Parameters:
value - the char value to be written.
Throws:
MessageNotWriteableException - if message in read-only mode.
JMSException - if JMS fails to write message due to some internal JMS error.

writeInt

public void writeInt(int value)
              throws JMSException
Write an int to the bytes message stream as four bytes, high byte first.
Parameters:
value - the int to be written.
Throws:
MessageNotWriteableException - if message in read-only mode.
JMSException - if JMS fails to write message due to some internal JMS error.

writeLong

public void writeLong(long value)
               throws JMSException
Write a long to the bytes message stream as eight bytes, high byte first.
Parameters:
value - the long to be written.
Throws:
MessageNotWriteableException - if message in read-only mode.
JMSException - if JMS fails to write message due to some internal JMS error.

writeFloat

public void writeFloat(float value)
                throws JMSException
Convert 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.
Parameters:
value - the float value to be written.
Throws:
MessageNotWriteableException - if message in read-only mode.
JMSException - if JMS fails to write message due to some internal JMS error.

writeDouble

public void writeDouble(double value)
                 throws JMSException
Convert 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.
Parameters:
value - the double value to be written.
Throws:
MessageNotWriteableException - if message in read-only mode.
JMSException - if JMS fails to write message due to some internal JMS error.

writeUTF

public void writeUTF(java.lang.String value)
              throws JMSException
Write a string to the bytes message stream using UTF-8 encoding in a machine-independent manner.

For more information on the UTF-8 format, see "File System Safe UCS Transformation Format (FSS_UFT)", X/Open Preliminary Specification, X/Open Company Ltd., Document Number: P316. This information also appears in ISO/IEC 10646, Annex P.

Parameters:
value - the String value to be written.
Throws:
MessageNotWriteableException - if message in read-only mode.
JMSException - if JMS fails to write message due to some internal JMS error.

writeBytes

public void writeBytes(byte[] value)
                throws JMSException
Write a byte array to the bytes message stream.
Parameters:
value - the byte array to be written.
Throws:
MessageNotWriteableException - if message in read-only mode.
JMSException - if JMS fails to write message due to some internal JMS error.

writeBytes

public void writeBytes(byte[] value,
                       int offset,
                       int length)
                throws JMSException
Write a portion of a byte array to the bytes message stream.
Parameters:
value - the byte array value to be written.
offset - the initial offset within the byte array.
length - the number of bytes to use.
Throws:
MessageNotWriteableException - if message in read-only mode.
JMSException - if JMS fails to write message due to some internal JMS error.

writeObject

public void writeObject(java.lang.Object value)
                 throws JMSException
Write a Java object to the bytes message stream.

Note that this method only works for the objectified primitive object types (Integer, Double, Long ...), String's and byte arrays.

Parameters:
value - the Java object to be written. Must not be null.
Throws:
NullPointerException - if parameter value is null.
MessageNotWriteableException - if message in read-only mode.
MessageFormatException - if object is invalid type.
JMSException - if JMS fails to write message due to some internal JMS error.

reset

public void reset()
           throws JMSException
Put the message body in read-only mode, and reposition the stream of bytes to the beginning.
Throws:
JMSException - if JMS fails to reset the message due to some internal JMS error.
MessageFormatException - if message has an invalid format