com.ibm.jms
Class JMSBytesMessage

java.lang.Object
  |
  +--com.ibm.jms.JMSMessage
        |
        +--com.ibm.jms.JMSBytesMessage
All Implemented Interfaces:
javax.jms.BytesMessage, javax.jms.Message, java.io.Serializable

public class JMSBytesMessage
extends JMSMessage
implements javax.jms.BytesMessage

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, 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 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, or when clearBody() has been 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, the 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.

See Also:
Serialized Form

Field Summary
static int ENC_FLOAT_IEEE_NORMAL
          Encoding Mask - floating point - IEEE normal.
static int ENC_FLOAT_IEEE_REVERSED
          Encoding Mask - floating point - IEEE reversed.
static int ENC_FLOAT_MASK
          Encoding Mask - used to separate the float component.
static int ENC_FLOAT_S390
          Encoding Mask - floating point - zSeries.
static int ENC_FLOAT_UNDEFINED
          Encoding Mask - floating point - integer undefined.
static int ENC_INTEGER_MASK
          Encoding Mask - used to separate the integer component.
static int ENC_INTEGER_NORMAL
          Encoding Mask - binary integers - integer normal.
static int ENC_INTEGER_REVERSED
          Encoding Mask - binary integers - integer reversed.
static int ENC_INTEGER_UNDEFINED
          Encoding Mask - binary integers - integer undefined.
   
Fields inherited from interface javax.jms.Message
DEFAULT_DELIVERY_MODE, DEFAULT_PRIORITY, DEFAULT_TIME_TO_LIVE
 
Method Summary
 void clearBody()
          Clears out the message body.
 long getBodyLength()
          Gets the number of bytes of the message body when the message is in read-only mode.
 boolean readBoolean()
          Reads a boolean from the bytes message.
 byte readByte()
          Reads a signed 8-bit value from the bytes message.
 int readBytes(byte[] value)
          Reads a byte array from the bytes message.
 int readBytes(byte[] value, int length)
          Reads a portion of the bytes message.
 char readChar()
          Reads a Unicode character value from the bytes message.
 double readDouble()
          Reads a double from the bytes message.
 float readFloat()
          Reads a float from the bytes message.
 int readInt()
          Reads a signed 32-bit integer from the bytes message.
 long readLong()
          Reads a signed 64-bit integer from the bytes message.
 short readShort()
          Reads a signed 16-bit number from the bytes message.
 int readUnsignedByte()
          Reads an unsigned 8-bit number from the bytes message.
 int readUnsignedShort()
          Reads an unsigned 16-bit number from the bytes message.
 java.lang.String readUTF()
          Reads a string that has been encoded using a modified UTF-8 format from the bytes message.
 void reset()
          Puts the message in read-only mode, and repositions the stream of bytes to the beginning.
 java.lang.String toString()
          Returns a String containing a formatted version of the Message.
 void writeBoolean(boolean value)
          Writes a boolean to the bytes message as a 1-byte value.
 void writeByte(byte value)
          Writes a byte to the bytes message as a 1-byte value.
 void writeBytes(byte[] value)
          Writes a byte array to the bytes message.
 void writeBytes(byte[] value, int offset, int length)
          Writes a portion of a byte array to the bytes message.
 void writeChar(char value)
          Writes a char to the bytes message as a 2-byte value, high byte first.
 void writeDouble(double value)
          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.
 void writeFloat(float value)
          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.
 void writeInt(int value)
          Writes an int to the bytes message as four bytes, high byte first.
 void writeLong(long value)
          Writes a long to the bytes message as eight bytes, high byte first.
 void writeObject(java.lang.Object value)
          Writes a Java object to the bytes message.
 void writeShort(short value)
          Writes a short to the bytes message as two bytes, high byte first.
 void writeUTF(java.lang.String value)
          Writes a string to the BytesMessage using UTF-8 encoding in a machine-independent manner.
 
Methods inherited from class com.ibm.jms.JMSMessage
acknowledge, 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
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface javax.jms.Message
acknowledge, 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
 

Field Detail

ENC_INTEGER_MASK

public static final int ENC_INTEGER_MASK
Encoding Mask - used to separate the integer component.

See Also:
Constant Field Values

ENC_FLOAT_MASK

public static final int ENC_FLOAT_MASK
Encoding Mask - used to separate the float component.

See Also:
Constant Field Values

ENC_INTEGER_UNDEFINED

public static final int ENC_INTEGER_UNDEFINED
Encoding Mask - binary integers - integer undefined.

See Also:
Constant Field Values

ENC_INTEGER_NORMAL

public static final int ENC_INTEGER_NORMAL
Encoding Mask - binary integers - integer normal.

See Also:
Constant Field Values

ENC_INTEGER_REVERSED

public static final int ENC_INTEGER_REVERSED
Encoding Mask - binary integers - integer reversed.

See Also:
Constant Field Values

ENC_FLOAT_UNDEFINED

public static final int ENC_FLOAT_UNDEFINED
Encoding Mask - floating point - integer undefined.

See Also:
Constant Field Values

ENC_FLOAT_IEEE_NORMAL

public static final int ENC_FLOAT_IEEE_NORMAL
Encoding Mask - floating point - IEEE normal.

See Also:
Constant Field Values

ENC_FLOAT_IEEE_REVERSED

public static final int ENC_FLOAT_IEEE_REVERSED
Encoding Mask - floating point - IEEE reversed.

See Also:
Constant Field Values

ENC_FLOAT_S390

public static final int ENC_FLOAT_S390
Encoding Mask - floating point - zSeries.

See Also:
Constant Field Values
Method Detail

clearBody

public void clearBody()
               throws javax.jms.JMSException
Clears out the message body. All other parts of the message are left untouched.

Specified by:
clearBody in interface javax.jms.Message
Specified by:
clearBody in class JMSMessage
Throws:
javax.jms.JMSException - if an internal error occurs.

readBoolean

public boolean readBoolean()
                    throws javax.jms.JMSException
Reads a boolean from the bytes message.

Specified by:
readBoolean in interface javax.jms.BytesMessage
Returns:
the boolean value read.
Throws:
javax.jms.JMSException - with reasons

readByte

public byte readByte()
              throws javax.jms.JMSException
Reads a signed 8-bit value from the bytes message.

Specified by:
readByte in interface javax.jms.BytesMessage
Returns:
the next byte from the bytes message as a signed 8-bit byte.
Throws:
javax.jms.JMSException - with reasons

readBytes

public int readBytes(byte[] value)
              throws javax.jms.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.

Specified by:
readBytes in interface javax.jms.BytesMessage
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:
javax.jms.JMSException - with reason MQJMS_EXCEPTION_MESSAGE_NOT_READABLE
javax.jms.MessageEOFException - if the end of the message stream has been reached

readBytes

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

Specified by:
readBytes in interface javax.jms.BytesMessage
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:
javax.jms.JMSException - with reason MQJMS_EXCEPTION_MESSAGE_NOT_READABLE
java.lang.IndexOutOfBoundsException - if length is inconsistent with value.
javax.jms.MessageEOFException - if the end of the message stream has been reached

readChar

public char readChar()
              throws javax.jms.JMSException
Reads a Unicode character value from the bytes message.

Specified by:
readChar in interface javax.jms.BytesMessage
Returns:
the next two bytes from the bytes message as a Unicode character.
Throws:
javax.jms.JMSException - with reasons

readDouble

public double readDouble()
                  throws javax.jms.JMSException
Reads a double from the bytes message.

Specified by:
readDouble in interface javax.jms.BytesMessage
Returns:
the next eight bytes from the bytes message, interpreted as a double.
Throws:
javax.jms.JMSException - with reasons

readFloat

public float readFloat()
                throws javax.jms.JMSException
Reads a float from the bytes message.

Specified by:
readFloat in interface javax.jms.BytesMessage
Returns:
the next four bytes from the bytes message, interpreted as a float.
Throws:
javax.jms.JMSException - with reasons

readInt

public int readInt()
            throws javax.jms.JMSException
Reads a signed 32-bit integer from the bytes message.

Specified by:
readInt in interface javax.jms.BytesMessage
Returns:
the next four bytes from the bytes message, interpreted as an int.
Throws:
javax.jms.JMSException - with reasons
java.io.IOException - if an I/O error has occurred.

readLong

public long readLong()
              throws javax.jms.JMSException
Reads a signed 64-bit integer from the bytes message.

Specified by:
readLong in interface javax.jms.BytesMessage
Returns:
the next eight bytes from the bytes message, interpreted as a long.
Throws:
javax.jms.JMSException - with reasons
java.io.IOException - if an I/O error has occurred.

readShort

public short readShort()
                throws javax.jms.JMSException
Reads a signed 16-bit number from the bytes message.

Specified by:
readShort in interface javax.jms.BytesMessage
Returns:
the next two bytes from the bytes message, interpreted as a signed 16-bit number.
Throws:
javax.jms.MessageEOFException - if the end of the message stream has been reached
javax.jms.JMSException - with reasons
java.io.IOException - if an I/O error has occurred.

readUnsignedByte

public int readUnsignedByte()
                     throws javax.jms.JMSException
Reads an unsigned 8-bit number from the bytes message.

Specified by:
readUnsignedByte in interface javax.jms.BytesMessage
Returns:
the next byte from the bytes message, interpreted as an unsigned 8-bit number.
Throws:
javax.jms.MessageEOFException - if the end of the message stream has been reached.
javax.jms.JMSException - with reasons
java.io.IOException - if an I/O error has occurred.

readUnsignedShort

public int readUnsignedShort()
                      throws javax.jms.JMSException
Reads an unsigned 16-bit number from the bytes message.

Specified by:
readUnsignedShort in interface javax.jms.BytesMessage
Returns:
the next two bytes from the bytes message, interpreted as an unsigned 16-bit integer.
Throws:
javax.jms.JMSException - with reasons
java.io.IOException - if an I/O error has occurred.

readUTF

public java.lang.String readUTF()
                         throws javax.jms.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.

Specified by:
readUTF in interface javax.jms.BytesMessage
Returns:
a Unicode string from the bytes message.
Throws:
javax.jms.JMSException - with reasons
java.io.IOException - if an I/O error has occurred.

reset

public void reset()
           throws javax.jms.JMSException
Puts the message in read-only mode, and repositions the stream of bytes to the beginning.

Specified by:
reset in interface javax.jms.BytesMessage
Throws:
javax.jms.JMSException - if JMS fails to reset the message due to some internal JMS error
javax.jms.MessageFormatException - if message has an invalid format

toString

public java.lang.String toString()
Returns a String containing a formatted version of the Message.

Overrides:
toString in class JMSMessage
Returns:
java.lang.String

writeBoolean

public void writeBoolean(boolean value)
                  throws javax.jms.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.

Specified by:
writeBoolean in interface javax.jms.BytesMessage
Parameters:
value - the boolean value to be written.
Throws:
javax.jms.JMSException - with reasons

writeByte

public void writeByte(byte value)
               throws javax.jms.JMSException
Writes a byte to the bytes message as a 1-byte value.

Specified by:
writeByte in interface javax.jms.BytesMessage
Parameters:
value - the byte value to be written.
Throws:
javax.jms.JMSException - with reasons

writeBytes

public void writeBytes(byte[] value)
                throws javax.jms.JMSException
Writes a byte array to the bytes message.

Specified by:
writeBytes in interface javax.jms.BytesMessage
Parameters:
value - the byte array to be written.
Throws:
javax.jms.JMSException - with reason

writeBytes

public void writeBytes(byte[] value,
                       int offset,
                       int length)
                throws javax.jms.JMSException
Writes a portion of a byte array to the bytes message.

Specified by:
writeBytes in interface javax.jms.BytesMessage
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:
javax.jms.JMSException - with reason

writeChar

public void writeChar(char value)
               throws javax.jms.JMSException
Writes a char to the bytes message as a 2-byte value, high byte first.

Specified by:
writeChar in interface javax.jms.BytesMessage
Parameters:
value - the char value to be written.
Throws:
javax.jms.JMSException - with reason

writeDouble

public void writeDouble(double value)
                 throws javax.jms.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.

Specified by:
writeDouble in interface javax.jms.BytesMessage
Parameters:
value - the double value to be written.
Throws:
javax.jms.JMSException - with reason

writeFloat

public void writeFloat(float value)
                throws javax.jms.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.

Specified by:
writeFloat in interface javax.jms.BytesMessage
Parameters:
value - the float value to be written.
Throws:
javax.jms.JMSException - with reason

writeInt

public void writeInt(int value)
              throws javax.jms.JMSException
Writes an int to the bytes message as four bytes, high byte first.

Specified by:
writeInt in interface javax.jms.BytesMessage
Parameters:
value - the int to be written.
Throws:
javax.jms.JMSException - with reason

writeLong

public void writeLong(long value)
               throws javax.jms.JMSException
Writes a long to the bytes message as eight bytes, high byte first.

Specified by:
writeLong in interface javax.jms.BytesMessage
Parameters:
value - the long to be written.
Throws:
javax.jms.JMSException - with reason

writeObject

public void writeObject(java.lang.Object value)
                 throws javax.jms.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.

Specified by:
writeObject in interface javax.jms.BytesMessage
Parameters:
value - the Java Object to be written.
Throws:
javax.jms.JMSException - with reason

writeShort

public void writeShort(short value)
                throws javax.jms.JMSException
Writes a short to the bytes message as two bytes, high byte first.

Specified by:
writeShort in interface javax.jms.BytesMessage
Parameters:
value - the short to be written.
Throws:
javax.jms.JMSException - with reason

writeUTF

public void writeUTF(java.lang.String value)
              throws javax.jms.JMSException
Writes a string to the BytesMessage 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.

Specified by:
writeUTF in interface javax.jms.BytesMessage
Parameters:
value - the String value to be written.
Throws:
javax.jms.JMSException - with reason

getBodyLength

public long getBodyLength()
                   throws javax.jms.JMSException,
                          javax.jms.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.

Specified by:
getBodyLength in interface javax.jms.BytesMessage
Returns:
number of bytes in the message
Throws:
javax.jms.JMSException - with reasons
javax.jms.MessageNotReadableException
Since:
1.1

(c) Copyright IBM Corp. 2005. All Rights Reserved.