JMSBytesMessage

public class JMSBytesMessage
extends JMSMessage
implements BytesMessage
java.lang.Object
   |
   +----com.ibm.jms.JMSMessage
           |
           +----com.ibm.jms.JMSBytesMessage
          

JMSBytesMessage is used to send a message containing a stream of uninterpreted bytes. The receiver of the message supplies the interpretation of the bytes.

Its 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, use one of the other self-defining message types 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; this is the recommended method. They can also be written generically as objects. For example, 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 the reset method has been made, the message is in read-only mode. When a message has been sent, the provider always calls reset to read its content. Likewise, when a message has been received, the provider calls 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.

JMSBytesMessage can be used by a JMS application to read or write a message that is sent to or from a non-Java application. As this non-Java application might be hosted on a platform with different integer or floating point encoding conventions, JMSBytesMessage class includes routines to represent its numeric data types in a number of different ways.

The only character set supported by JMSBytesMessage is the Java version of UTF-8. This includes a two-byte length prefix, and is limited to strings less than 65536 bytes in long. Applications wanting to send a string in different character set have a choice of two methods:

  1. Send the message as a JMSTextMessage - if it is entirely made up of strings.
  2. Convert the String to a byte array and then write it into JMSBytesMessage using the writeBytes() method.

The type of numeric encoding to be used can be set by the transport code when importing or exporting the message as a byte array. The type of encoding is specified using an int, which is effectively the sum of two separate enums, as defined by the ENC_* fields. This follows the convention laid down by WebSphere MQ in the MQMD.encoding field. For convenience, the constants defined here take precisely the same values as their MQENC counterparts defined in com.ibm.mq.MQC.

Methods

clearBody

public void clearBody() throws JMSException;

Clears out the message body. All other parts of the message are left untouched.

Exceptions

getBodyLength

public long getBodyLength() throws JMSException, 
            MessageNotReadableException;

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
Exceptions

readBoolean

public boolean readBoolean() throws JMSException;

Reads a boolean from the bytes message.

Returns
Exceptions

readByte

public byte readByte() throws JMSException;

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

Returns
Exceptions

readBytes

public int readBytes(byte[] value) throws JMSException;

Reads a byte array from the bytes message. If there are sufficient bytes remaining in the stream the entire buffer is filled. If not, the buffer is partially filled.

Parameters
Returns
Exceptions

readBytes

public int readBytes(byte[] value, int length) throws JMSException;

Reads a portion of the bytes message.

Parameters
Returns
Exceptions

readChar

public char readChar() throws JMSException;

Reads a Unicode character value from the bytes message.

Returns
Exceptions

readDouble

public double readDouble() throws JMSException;

Reads a double from the bytes message.

Returns
Exceptions

readFloat

public float readFloat() throws JMSException;

Reads a float from the bytes message.

Returns
Exceptions

readInt

public int readInt() throws JMSException;

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

Returns
Exceptions

readLong

public long readLong() throws JMSException;

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

Returns
Exceptions

readShort

public short readShort() throws JMSException;

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

Returns
Exceptions

readUnsignedByte

public int readUnsignedByte() throws JMSException;

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

Returns
Exceptions

readUnsignedShort

public int readUnsignedShort() throws JMSException;

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

Returns
Exceptions

readUTF

public String readUTF() throws JMSException;

Reads a string that has been encoded using a modified UTF-8 format from the bytes 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
Exceptions

reset

public void reset() throws JMSException;

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

Exceptions

toString

public String toString();

Returns a String containing a formatted version of the Message.

Returns

writeBoolean

public void writeBoolean(boolean value) throws JMSException;

Writes a boolean to the bytes 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
Exceptions

writeByte

public void writeByte(byte value) throws JMSException;

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

Parameters
Exceptions

writeBytes

public void writeBytes(byte[] value) throws JMSException;

Writes a byte array to the bytes message.

Parameters
Exceptions

writeBytes

public void writeBytes(byte[] value, int offset, int length) 
              throws JMSException;

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

Parameters
Exceptions

writeChar

public void writeChar(char value) throws JMSException;

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

Parameters
Exceptions

writeDouble

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 stream message as an 8-byte quantity, high byte first.

Parameters
Exceptions

writeFloat

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 stream message as a 4-byte quantity, high byte first.

Parameters
Exceptions

writeInt

public void writeInt(int value) throws JMSException;

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

Parameters
Exceptions

writeLong

public void writeLong(long value) throws JMSException;

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

Parameters
Exceptions

writeObject

public void writeObject(Object value) throws JMSException;

Writes a Java object to the bytes message.

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

Parameters
Exceptions

writeShort

public void writeShort(short value) throws JMSException;

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

Parameters
Exceptions

writeUTF

public void writeUTF(String value) throws JMSException;

Write a string to the bytes 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
Exceptions