Top Description Fields Methods
javax.jms

public Interface BytesMessage

extends Message
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.

The BytesMessage 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 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. When a BytesMessage is sent asynchronously, the provider must call reset on the BytesMessage passed to the CompletionListener. This means that the CompletionListener can read the message body without needing to call reset. 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.

Since
JMS 1.0
Version
JMS 2.0
See Also
javax.jms.Session#createBytesMessage(), javax.jms.MapMessage, javax.jms.Message, javax.jms.ObjectMessage, javax.jms.StreamMessage, javax.jms.TextMessage

Field Summary

Inherited from javax.jms.Message:
DEFAULT_DELIVERY_DELAYDEFAULT_DELIVERY_MODEDEFAULT_PRIORITYDEFAULT_TIME_TO_LIVE

Method Summary

Modifier and TypeMethod and Description
public long

Returns:

number of bytes in the message
getBodyLength()

Gets the number of bytes of the message body when the message is in read-only mode.

public boolean

Returns:

the boolean value read
readBoolean()

Reads a boolean from the bytes message stream.

public byte

Returns:

the next byte from the bytes message stream as a signed 8-bit byte
readByte()

Reads a signed 8-bit value from the bytes message stream.

public int

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
readBytes(byte[]
the buffer into which the data is read
value)

Reads a byte array from the bytes message stream.

public int

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
readBytes(byte[]
the buffer into which the data is read
value, int
the number of bytes to read; must be less than or equal to value.length
length)

Reads a portion of the bytes message stream.

public char

Returns:

the next two bytes from the bytes message stream as a Unicode character
readChar()

Reads a Unicode character value from the bytes message stream.

public double

Returns:

the next eight bytes from the bytes message stream, interpreted as a double
readDouble()

Reads a double from the bytes message stream.

public float

Returns:

the next four bytes from the bytes message stream, interpreted as a float
readFloat()

Reads a float from the bytes message stream.

public int

Returns:

the next four bytes from the bytes message stream, interpreted as an int
readInt()

Reads a signed 32-bit integer from the bytes message stream.

public long

Returns:

the next eight bytes from the bytes message stream, interpreted as a long
readLong()

Reads a signed 64-bit integer from the bytes message stream.

public short

Returns:

the next two bytes from the bytes message stream, interpreted as a signed 16-bit number
readShort()

Reads a signed 16-bit number from the bytes message stream.

public int

Returns:

the next byte from the bytes message stream, interpreted as an unsigned 8-bit number
readUnsignedByte()

Reads an unsigned 8-bit number from the bytes message stream.

public int

Returns:

the next two bytes from the bytes message stream, interpreted as an unsigned 16-bit integer
readUnsignedShort()

Reads an unsigned 16-bit number from the bytes message stream.

public String

Returns:

a Unicode string from the bytes message stream
readUTF()

Reads a string that has been encoded using a modified UTF-8 format from the bytes message stream.

public void
reset()

Puts the message body in read-only mode and repositions the stream of bytes to the beginning.

public void
writeBoolean(boolean
the boolean value to be written
value)

Writes a boolean to the bytes message stream as a 1-byte value.

public void
writeByte(byte
the byte value to be written
value)

Writes a byte to the bytes message stream as a 1-byte value.

public void
writeBytes(byte[]
the byte array to be written
value)

Writes a byte array to the bytes message stream.

public void
writeBytes(byte[]
the byte array value to be written
value, int
the initial offset within the byte array
offset, int
the number of bytes to use
length)

Writes a portion of a byte array to the bytes message stream.

public void
writeChar(char
the char value to be written
value)

Writes a char to the bytes message stream as a 2-byte value, high byte first.

public void
writeDouble(double
the double value to be written
value)

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.

public void
writeFloat(float
the float value to be written
value)

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.

public void
writeInt(int
the int to be written
value)

Writes an int to the bytes message stream as four bytes, high byte first.

public void
writeLong(long
the long to be written
value)

Writes a long to the bytes message stream as eight bytes, high byte first.

public void
writeObject(Object
the object in the Java programming language ("Java object") to be written; it must not be null
value)

Writes an object to the bytes message stream.

public void
writeShort(short
the short to be written
value)

Writes a short to the bytes message stream as two bytes, high byte first.

public void
writeUTF(String
the String value to be written
value)

Writes a string to the bytes message stream using UTF-8 encoding in a machine-independent manner.

Inherited from javax.jms.Message:
acknowledgeclearBodyclearPropertiesgetBodygetBooleanPropertygetBytePropertygetDoublePropertygetFloatPropertygetIntPropertygetJMSCorrelationIDgetJMSCorrelationIDAsBytesgetJMSDeliveryModegetJMSDeliveryTimegetJMSDestinationgetJMSExpirationgetJMSMessageIDgetJMSPrioritygetJMSRedeliveredgetJMSReplyTogetJMSTimestampgetJMSTypegetLongPropertygetObjectPropertygetPropertyNamesgetShortPropertygetStringPropertyisBodyAssignableTopropertyExistssetBooleanPropertysetBytePropertysetDoublePropertysetFloatPropertysetIntPropertysetJMSCorrelationIDsetJMSCorrelationIDAsBytessetJMSDeliveryModesetJMSDeliveryTimesetJMSDestinationsetJMSExpirationsetJMSMessageIDsetJMSPrioritysetJMSRedeliveredsetJMSReplyTosetJMSTimestampsetJMSTypesetLongPropertysetObjectPropertysetShortPropertysetStringProperty

Method Detail

getBodyLengthback to summary
public long getBodyLength() throws JMSException

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.

Returns:long

number of bytes in the message

Exceptions
JMSException:
if the JMS provider fails to read the message due to some internal error.
MessageNotReadableException:
if the message is in write-only mode.
Since
JMS 1.1
readBooleanback to summary
public boolean readBoolean() throws JMSException

Reads a boolean from the bytes message stream.

Returns:boolean

the boolean value read

Exceptions
JMSException:
if the JMS provider fails to read the message due to some internal error.
MessageEOFException:
if unexpected end of bytes stream has been reached.
MessageNotReadableException:
if the message is in write-only mode.
readByteback to summary
public byte readByte() throws JMSException

Reads a signed 8-bit value from the bytes message stream.

Returns:byte

the next byte from the bytes message stream as a signed 8-bit byte

Exceptions
JMSException:
if the JMS provider fails to read the message due to some internal error.
MessageEOFException:
if unexpected end of bytes stream has been reached.
MessageNotReadableException:
if the message is in write-only mode.
readBytesback to summary
public int readBytes(byte[] value) throws JMSException

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.

Parameters
value:byte[]

the buffer into which the data is read

Returns:int

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

Exceptions
JMSException:
if the JMS provider fails to read the message due to some internal error.
MessageNotReadableException:
if the message is in write-only mode.
readBytesback to summary
public int readBytes(byte[] value, int length) throws JMSException

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

Parameters
value:byte[]

the buffer into which the data is read

length:int

the number of bytes to read; must be less than or equal to value.length

Returns:int

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

Exceptions
JMSException:
if the JMS provider fails to read the message due to some internal error.
MessageNotReadableException:
if the message is in write-only mode.
readCharback to summary
public char readChar() throws JMSException

Reads a Unicode character value from the bytes message stream.

Returns:char

the next two bytes from the bytes message stream as a Unicode character

Exceptions
JMSException:
if the JMS provider fails to read the message due to some internal error.
MessageEOFException:
if unexpected end of bytes stream has been reached.
MessageNotReadableException:
if the message is in write-only mode.
readDoubleback to summary
public double readDouble() throws JMSException

Reads a double from the bytes message stream.

Returns:double

the next eight bytes from the bytes message stream, interpreted as a double

Exceptions
JMSException:
if the JMS provider fails to read the message due to some internal error.
MessageEOFException:
if unexpected end of bytes stream has been reached.
MessageNotReadableException:
if the message is in write-only mode.
readFloatback to summary
public float readFloat() throws JMSException

Reads a float from the bytes message stream.

Returns:float

the next four bytes from the bytes message stream, interpreted as a float

Exceptions
JMSException:
if the JMS provider fails to read the message due to some internal error.
MessageEOFException:
if unexpected end of bytes stream has been reached.
MessageNotReadableException:
if the message is in write-only mode.
readIntback to summary
public int readInt() throws JMSException

Reads a signed 32-bit integer from the bytes message stream.

Returns:int

the next four bytes from the bytes message stream, interpreted as an int

Exceptions
JMSException:
if the JMS provider fails to read the message due to some internal error.
MessageEOFException:
if unexpected end of bytes stream has been reached.
MessageNotReadableException:
if the message is in write-only mode.
readLongback to summary
public long readLong() throws JMSException

Reads a signed 64-bit integer from the bytes message stream.

Returns:long

the next eight bytes from the bytes message stream, interpreted as a long

Exceptions
JMSException:
if the JMS provider fails to read the message due to some internal error.
MessageEOFException:
if unexpected end of bytes stream has been reached.
MessageNotReadableException:
if the message is in write-only mode.
readShortback to summary
public short readShort() throws JMSException

Reads a signed 16-bit number from the bytes message stream.

Returns:short

the next two bytes from the bytes message stream, interpreted as a signed 16-bit number

Exceptions
JMSException:
if the JMS provider fails to read the message due to some internal error.
MessageEOFException:
if unexpected end of bytes stream has been reached.
MessageNotReadableException:
if the message is in write-only mode.
readUnsignedByteback to summary
public int readUnsignedByte() throws JMSException

Reads an unsigned 8-bit number from the bytes message stream.

Returns:int

the next byte from the bytes message stream, interpreted as an unsigned 8-bit number

Exceptions
JMSException:
if the JMS provider fails to read the message due to some internal error.
MessageEOFException:
if unexpected end of bytes stream has been reached.
MessageNotReadableException:
if the message is in write-only mode.
readUnsignedShortback to summary
public int readUnsignedShort() throws JMSException

Reads an unsigned 16-bit number from the bytes message stream.

Returns:int

the next two bytes from the bytes message stream, interpreted as an unsigned 16-bit integer

Exceptions
JMSException:
if the JMS provider fails to read the message due to some internal error.
MessageEOFException:
if unexpected end of bytes stream has been reached.
MessageNotReadableException:
if the message is in write-only mode.
readUTFback to summary
public String readUTF() throws JMSException

Reads 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_UTF)", X/Open Preliminary Specification, X/Open Company Ltd., Document Number: P316. This information also appears in ISO/IEC 10646, Annex P.

Returns:String

a Unicode string from the bytes message stream

Exceptions
JMSException:
if the JMS provider fails to read the message due to some internal error.
MessageEOFException:
if unexpected end of bytes stream has been reached.
MessageNotReadableException:
if the message is in write-only mode.
resetback to summary
public void reset() throws JMSException

Puts the message body in read-only mode and repositions the stream of bytes to the beginning.

Exceptions
JMSException:
if the JMS provider fails to reset the message due to some internal error.
MessageFormatException:
if the message has an invalid format.
writeBooleanback to summary
public void writeBoolean(boolean value) throws JMSException

Writes a boolean 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.

Parameters
value:boolean

the boolean value to be written

Exceptions
JMSException:
if the JMS provider fails to write the message due to some internal error.
MessageNotWriteableException:
if the message is in read-only mode.
writeByteback to summary
public void writeByte(byte value) throws JMSException

Writes a byte to the bytes message stream as a 1-byte value.

Parameters
value:byte

the byte value to be written

Exceptions
JMSException:
if the JMS provider fails to write the message due to some internal error.
MessageNotWriteableException:
if the message is in read-only mode.
writeBytesback to summary
public void writeBytes(byte[] value) throws JMSException

Writes a byte array to the bytes message stream.

Parameters
value:byte[]

the byte array to be written

Exceptions
JMSException:
if the JMS provider fails to write the message due to some internal error.
MessageNotWriteableException:
if the message is in read-only mode.
writeBytesback to summary
public void writeBytes(byte[] value, int offset, int length) throws JMSException

Writes a portion of a byte array to the bytes message stream.

Parameters
value:byte[]

the byte array value to be written

offset:int

the initial offset within the byte array

length:int

the number of bytes to use

Exceptions
JMSException:
if the JMS provider fails to write the message due to some internal error.
MessageNotWriteableException:
if the message is in read-only mode.
writeCharback to summary
public void writeChar(char value) throws JMSException

Writes a char to the bytes message stream as a 2-byte value, high byte first.

Parameters
value:char

the char value to be written

Exceptions
JMSException:
if the JMS provider fails to write the message due to some internal error.
MessageNotWriteableException:
if the message is in read-only mode.
writeDoubleback to summary
public void writeDouble(double value) throws JMSException

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.

Parameters
value:double

the double value to be written

Exceptions
JMSException:
if the JMS provider fails to write the message due to some internal error.
MessageNotWriteableException:
if the message is in read-only mode.
writeFloatback to summary
public void writeFloat(float value) throws JMSException

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.

Parameters
value:float

the float value to be written

Exceptions
JMSException:
if the JMS provider fails to write the message due to some internal error.
MessageNotWriteableException:
if the message is in read-only mode.
writeIntback to summary
public void writeInt(int value) throws JMSException

Writes an int to the bytes message stream as four bytes, high byte first.

Parameters
value:int

the int to be written

Exceptions
JMSException:
if the JMS provider fails to write the message due to some internal error.
MessageNotWriteableException:
if the message is in read-only mode.
writeLongback to summary
public void writeLong(long value) throws JMSException

Writes a long to the bytes message stream as eight bytes, high byte first.

Parameters
value:long

the long to be written

Exceptions
JMSException:
if the JMS provider fails to write the message due to some internal error.
MessageNotWriteableException:
if the message is in read-only mode.
writeObjectback to summary
public void writeObject(Object value) throws JMSException

Writes an object to the bytes message stream.

This method works only for the objectified primitive object types (Integer, Double, Long ...), String objects, and byte arrays.

Parameters
value:Object

the object in the Java programming language ("Java object") to be written; it must not be null

Exceptions
JMSException:
if the JMS provider fails to write the message due to some internal error.
MessageFormatException:
if the object is of an invalid type.
MessageNotWriteableException:
if the message is in read-only mode.
NullPointerException:
if the parameter value is null.
writeShortback to summary
public void writeShort(short value) throws JMSException

Writes a short to the bytes message stream as two bytes, high byte first.

Parameters
value:short

the short to be written

Exceptions
JMSException:
if the JMS provider fails to write the message due to some internal error.
MessageNotWriteableException:
if the message is in read-only mode.
writeUTFback to summary
public void writeUTF(String value) throws JMSException

Writes 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_UTF)", X/Open Preliminary Specification, X/Open Company Ltd., Document Number: P316. This information also appears in ISO/IEC 10646, Annex P.

Parameters
value:String

the String value to be written

Exceptions
JMSException:
if the JMS provider fails to write the message due to some internal error.
MessageNotWriteableException:
if the message is in read-only mode.