javax.jms
Interface BytesMessage

public abstract 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 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 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.

Version:

1.0 - 6 August 1998

Author:

Mark Hapner, Rich Burridge

See Also:

MapMessage, Message, ObjectMessage, StreamMessage, TextMessage, InputStream, OutputStream

Fields inherited from class javax.jms.Message

DEFAULT_DELIVERY_MODE, DEFAULT_PRIORITY, DEFAULT_TIME_TO_LIVE

Method Summary

boolean	readBoolean() Read a boolean from the stream message.
byte	readByte() Read a signed 8-bit value from the stream message.
int	readBytes(byte[] value) Read a byte array from the stream message.
int	readBytes(byte[] value, int length) Read a portion of the bytes message.
char	readChar() Read a Unicode character value from the stream message.
double	readDouble() Read a double from the stream message.
float	readFloat() Read a float from the stream message.
int	readInt() Read a signed 32-bit integer from the stream message.
long	readLong() Read a signed 64-bit integer from the stream message.
short	readShort() Read a signed 16-bit number from the stream message.
int	readUnsignedByte() Read an unsigned 8-bit number from the stream message.
int	readUnsignedShort() Read an unsigned 16-bit number from the stream message.
java.lang.String	readUTF() Read in a string that has been encoded using a modified UTF-8 format from the stream message.
void	reset() Put the message in read-only mode, and reposition the stream of bytes to the beginning.
void	writeBoolean(boolean value) Write a boolean to the stream message as a 1-byte value.
void	writeByte(byte value) Write out a byte to the stream message as a 1-byte value.
void	writeBytes(byte[] value) Write a byte array to the stream message.
void	writeBytes(byte[] value, int offset, int length) Write a portion of a byte array to the stream message.
void	writeChar(char value) Write a char to the stream message 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 stream message 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 stream message as a 4-byte quantity, high byte first.
void	writeInt(int value) Write an int to the stream message as four bytes, high byte first.
void	writeLong(long value) Write a long to the stream message as eight bytes, high byte first.
void	writeObject(java.lang.Object value) Write a Java object to the stream message.
void	writeShort(short value) Write a short to the stream message as two bytes, high byte first.
void	writeUTF(java.lang.String value) Write a string to the stream message 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 stream message.

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 message stream

readByte

public byte readByte()

              throws JMSException

Read a signed 8-bit value from the stream message.

Returns:

the next byte from the stream message 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 stream message.

Returns:

the next byte from the stream message, 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 stream message.

Returns:

the next two bytes from the stream message, 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 stream message.

Returns:

the next two bytes from the stream message, 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 stream message.

Returns:

the next two bytes from the stream message 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 stream message.

Returns:

the next four bytes from the stream message, 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 stream message.

Returns:

the next eight bytes from the stream message, 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 stream message.

Returns:

the next four bytes from the stream message, 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 stream message.

Returns:

the next eight bytes from the stream message, 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 stream message.

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 stream message.

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 stream message.

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.

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,

                     int length)

              throws JMSException

Read a portion of the bytes message.

Parameters:

value - the buffer into which the data is read.

length - the number of bytes to 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.

MessageEOFException - if end of message stream

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 stream message 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 stream message 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 stream message 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 stream message 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 stream message 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 stream message 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 stream message 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 stream message 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 stream message 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 stream message.

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 stream message.

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 stream message.

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.

Throws:

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 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