Websphere MQ Everyplace

com.ibm.mqe.jms
Class MQeBytesMessage

java.lang.Object
  |
  +--com.ibm.mqe.jms.MQeMessage
        |
        +--com.ibm.mqe.jms.MQeBytesMessage
All Implemented Interfaces:
javax.jms.BytesMessage, javax.jms.Message

public class MQeBytesMessage
extends MQeMessage
implements javax.jms.BytesMessage

A BytesMessage is used to send a message containing a stream of uninterpreted bytes. It inherits from MQeMessage and adds a bytes message body. The receiver of the message must interpret these bytes. This message type is intended for client encoding of existing message formats, and, if possible, one of the other self-defining message types should be used instead.

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 MQeMessage.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 MQeMessage.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, and similarly 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

Field Summary
 
Fields inherited from class com.ibm.mqe.jms.MQeMessage
DEFAULT_DELIVERY_MODE
 
Fields inherited from interface javax.jms.Message
DEFAULT_DELIVERY_MODE, DEFAULT_PRIORITY, DEFAULT_TIME_TO_LIVE
 
Constructor Summary
MQeBytesMessage()
           
 
Method Summary
 long getBodyLength()
          Gets the number of bytes of the message body when the message is in read-only mode.
 boolean readBoolean()
          Read a boolean from the bytes message.
 byte readByte()
          Read a signed 8-bit value from the bytes message.
 int readBytes(byte[] value)
          Read a byte array from the bytes message.
 int readBytes(byte[] value, int length)
          Read a portion of the bytes message.
 char readChar()
          Read a Unicode character value from the bytes message.
 double readDouble()
          Read a double from the bytes message.
 float readFloat()
          Read a float from the bytes message.
 int readInt()
          Read a signed 32-bit integer from the bytes message.
 long readLong()
          Read a signed 64-bit integer from the bytes message.
 short readShort()
          Read a signed 16-bit number from the bytes message.
 int readUnsignedByte()
          Read an unsigned 8-bit number from the bytes message.
 int readUnsignedShort()
          Read an unsigned 16-bit number from the bytes message.
 java.lang.String readUTF()
          Read in a string that has been encoded using a modified UTF-8 format from the bytes 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 bytes message as a 1-byte value.
 void writeByte(byte value)
          Write out a byte to the bytes message as a 1-byte value.
 void writeBytes(byte[] value)
          Write a byte array to the byte message.
 void writeBytes(byte[] value, int offset, int length)
          Write a portion of a byte array to the byte message.
 void writeChar(char value)
          Write a char to the bytes 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 bytes message as four bytes, high byte first.
 void writeLong(long value)
          Write a long to the bytes message as eight bytes, high byte first.
 void writeObject(java.lang.Object value)
          Write a Java object to the bytes message.
 void writeShort(short value)
          Write a short to the bytes message as two bytes, high byte first.
 void writeUTF(java.lang.String value)
          Write a string to the bytes message using UTF-8 encoding in a machine-independent manner.
 
Methods inherited from class com.ibm.mqe.jms.MQeMessage
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
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
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
 

Constructor Detail

MQeBytesMessage

public MQeBytesMessage()
Method Detail

getBodyLength

public long getBodyLength()
                   throws javax.jms.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:
number of bytes in the message
Throws:
javax.jms.JMSException - if the JMS provider fails to read the message due to some internal error.
javax.jms.MessageNotReadableException - if the message is in write-only mode.
Since:
1.1

readBoolean

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

Specified by:
readBoolean in interface javax.jms.BytesMessage
Returns:
the boolean value read.
Throws:
javax.jms.MessageNotReadableException - if message in write-only mode.
javax.jms.JMSException - if JMS fails to read message due to some internal JMS error.
javax.jms.MessageEOFException - if end of message stream

readByte

public byte readByte()
              throws javax.jms.JMSException
Read 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.MessageNotReadableException - if message in write-only mode.
javax.jms.MessageEOFException - if end of message stream
javax.jms.JMSException - if JMS fails to read message due to some internal JMS error.

readUnsignedByte

public int readUnsignedByte()
                     throws javax.jms.JMSException
Read 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.MessageNotReadableException - if message in write-only mode.
javax.jms.MessageEOFException - if end of message stream
javax.jms.JMSException - if JMS fails to read message due to some internal JMS error.

readShort

public short readShort()
                throws javax.jms.JMSException
Read 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.MessageNotReadableException - if message in write-only mode.
javax.jms.MessageEOFException - if end of message stream
javax.jms.JMSException - if JMS fails to read message due to some internal JMS error.

readUnsignedShort

public int readUnsignedShort()
                      throws javax.jms.JMSException
Read 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.MessageNotReadableException - if message in write-only mode.
javax.jms.MessageEOFException - if end of message stream
javax.jms.JMSException - if JMS fails to read message due to some internal JMS error.

readChar

public char readChar()
              throws javax.jms.JMSException
Read 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.MessageNotReadableException - if message in write-only mode.
javax.jms.MessageEOFException - if end of message stream
javax.jms.JMSException - if JMS fails to read message due to some internal JMS error.

readInt

public int readInt()
            throws javax.jms.JMSException
Read 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.MessageNotReadableException - if message in write-only mode.
javax.jms.MessageEOFException - if end of message stream
javax.jms.JMSException - if JMS fails to read message due to some internal JMS error.

readLong

public long readLong()
              throws javax.jms.JMSException
Read 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.MessageNotReadableException - if message in write-only mode.
javax.jms.MessageEOFException - if end of message stream
javax.jms.JMSException - if JMS fails to read message due to some internal JMS error.

readFloat

public float readFloat()
                throws javax.jms.JMSException
Read 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.MessageNotReadableException - if message in write-only mode.
javax.jms.MessageEOFException - if end of message stream
javax.jms.JMSException - if JMS fails to read message due to some internal JMS error.

readDouble

public double readDouble()
                  throws javax.jms.JMSException
Read 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.MessageNotReadableException - if message in write-only mode.
javax.jms.MessageEOFException - if end of message stream
javax.jms.JMSException - if JMS fails to read message due to some internal JMS error.

readUTF

public java.lang.String readUTF()
                         throws javax.jms.JMSException
Read in a string that has been encoded using a modified UTF-8 format from the bytes message. The first two bytes are interpreted as a two-byte length field.

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

readBytes

public int readBytes(byte[] value)
              throws javax.jms.JMSException
Read 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.MessageNotReadableException - if message in write-only mode.
javax.jms.MessageEOFException - if end of message stream
javax.jms.JMSException - if JMS fails to read message due to some internal JMS error.

readBytes

public int readBytes(byte[] value,
                     int length)
              throws javax.jms.JMSException
Read 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.MessageNotReadableException - if message in write-only mode.
javax.jms.MessageEOFException - if end of message stream
javax.jms.JMSException - if JMS fails to read message due to some internal JMS error.
java.lang.IndexOutOfBoundsException - if length is negative or greater than the length of the supplied byte array

writeBoolean

public void writeBoolean(boolean value)
                  throws javax.jms.JMSException
Write 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.MessageNotWriteableException - if message in read-only mode.
javax.jms.JMSException - if JMS fails to write message due to some internal JMS error.

writeByte

public void writeByte(byte value)
               throws javax.jms.JMSException
Write out 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.MessageNotWriteableException - if message in read-only mode.
javax.jms.JMSException - if JMS fails to write message due to some internal JMS error.

writeShort

public void writeShort(short value)
                throws javax.jms.JMSException
Write 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.MessageNotWriteableException - if message in read-only mode.
javax.jms.JMSException - if JMS fails to write message due to some internal JMS error.

writeChar

public void writeChar(char value)
               throws javax.jms.JMSException
Write 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.MessageNotWriteableException - if message in read-only mode.
javax.jms.JMSException - if JMS fails to write message due to some internal JMS error.

writeInt

public void writeInt(int value)
              throws javax.jms.JMSException
Write 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.MessageNotWriteableException - if message in read-only mode.
javax.jms.JMSException - if JMS fails to write message due to some internal JMS error.

writeLong

public void writeLong(long value)
               throws javax.jms.JMSException
Write 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.MessageNotWriteableException - if message in read-only mode.
javax.jms.JMSException - if JMS fails to write message due to some internal JMS error.

writeFloat

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

Specified by:
writeFloat in interface javax.jms.BytesMessage
Parameters:
value - the float value to be written.
Throws:
javax.jms.MessageNotWriteableException - if message in read-only mode.
javax.jms.JMSException - if JMS fails to write message due to some internal JMS error.

writeDouble

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

Specified by:
writeDouble in interface javax.jms.BytesMessage
Parameters:
value - the double value to be written.
Throws:
javax.jms.MessageNotWriteableException - if message in read-only mode.
javax.jms.JMSException - if JMS fails to write message due to some internal JMS error.

writeUTF

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

Specified by:
writeUTF in interface javax.jms.BytesMessage
Parameters:
value - the String value to be written.
Throws:
javax.jms.MessageNotWriteableException - if message in read-only mode.
javax.jms.JMSException - if JMS fails to write message due to some internal JMS error.

writeBytes

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

Specified by:
writeBytes in interface javax.jms.BytesMessage
Parameters:
value - the byte array to be written.
Throws:
javax.jms.MessageNotWriteableException - if message in read-only mode.
javax.jms.JMSException - if JMS fails to write message due to some internal JMS error.

writeBytes

public void writeBytes(byte[] value,
                       int offset,
                       int length)
                throws javax.jms.JMSException
Write a portion of a byte array to the byte 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.MessageNotWriteableException - if message in read-only mode.
javax.jms.JMSException - if JMS fails to write message due to some internal JMS error.

writeObject

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

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

Specified by:
writeObject in interface javax.jms.BytesMessage
Parameters:
value - the Java object to be written.
Throws:
javax.jms.MessageNotWriteableException - if message in read-only mode.
javax.jms.MessageFormatException - if object is invalid type.
javax.jms.JMSException - if JMS fails to write message due to some internal JMS error.

reset

public void reset()
           throws javax.jms.JMSException
Put the message in read-only mode, and reposition 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

Websphere MQ Everyplace