|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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, 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:
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
.
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 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 |
public static final int ENC_INTEGER_MASK
public static final int ENC_FLOAT_MASK
public static final int ENC_INTEGER_UNDEFINED
public static final int ENC_INTEGER_NORMAL
public static final int ENC_INTEGER_REVERSED
public static final int ENC_FLOAT_UNDEFINED
public static final int ENC_FLOAT_IEEE_NORMAL
public static final int ENC_FLOAT_IEEE_REVERSED
public static final int ENC_FLOAT_S390
Method Detail |
public void clearBody() throws javax.jms.JMSException
clearBody
in interface javax.jms.Message
clearBody
in class JMSMessage
javax.jms.JMSException
- if an internal error occurs.public boolean readBoolean() throws javax.jms.JMSException
readBoolean
in interface javax.jms.BytesMessage
javax.jms.JMSException
- with reasons
public byte readByte() throws javax.jms.JMSException
readByte
in interface javax.jms.BytesMessage
javax.jms.JMSException
- with reasons
MQJMS_EXCEPTION_MESSAGE_NOT_READABLE
MQJMS_EXCEPTION_MESSAGE_EOF
- if the end of the message stream has been reached.
public int readBytes(byte[] value) throws javax.jms.JMSException
readBytes
in interface javax.jms.BytesMessage
value
- the buffer into which the data is read.
javax.jms.JMSException
- with reason
MQJMS_EXCEPTION_MESSAGE_NOT_READABLE
javax.jms.MessageEOFException
- if the end of the message stream has been reachedpublic int readBytes(byte[] value, int length) throws javax.jms.JMSException
readBytes
in interface javax.jms.BytesMessage
value
- the buffer into which the data is read.length
- the number of bytes to read.
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 reachedpublic char readChar() throws javax.jms.JMSException
readChar
in interface javax.jms.BytesMessage
javax.jms.JMSException
- with reasons
public double readDouble() throws javax.jms.JMSException
readDouble
in interface javax.jms.BytesMessage
javax.jms.JMSException
- with reasons
public float readFloat() throws javax.jms.JMSException
readFloat
in interface javax.jms.BytesMessage
javax.jms.JMSException
- with reasons
public int readInt() throws javax.jms.JMSException
readInt
in interface javax.jms.BytesMessage
javax.jms.JMSException
- with reasons
java.io.IOException
- if an I/O error has occurred.public long readLong() throws javax.jms.JMSException
readLong
in interface javax.jms.BytesMessage
javax.jms.JMSException
- with reasons
java.io.IOException
- if an I/O error has occurred.public short readShort() throws javax.jms.JMSException
readShort
in interface javax.jms.BytesMessage
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.public int readUnsignedByte() throws javax.jms.JMSException
readUnsignedByte
in interface javax.jms.BytesMessage
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.public int readUnsignedShort() throws javax.jms.JMSException
readUnsignedShort
in interface javax.jms.BytesMessage
javax.jms.JMSException
- with reasons
java.io.IOException
- if an I/O error has occurred.public java.lang.String readUTF() throws javax.jms.JMSException
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.
readUTF
in interface javax.jms.BytesMessage
javax.jms.JMSException
- with reasons
java.io.IOException
- if an I/O error has occurred.public void reset() throws javax.jms.JMSException
reset
in interface javax.jms.BytesMessage
javax.jms.JMSException
- if JMS fails to reset the message due to some internal JMS error
javax.jms.MessageFormatException
- if message has an invalid formatpublic java.lang.String toString()
toString
in class JMSMessage
public void writeBoolean(boolean value) throws javax.jms.JMSException
true
is written out as the value
(byte)1; the value false
is written out as
the value (byte)0.
writeBoolean
in interface javax.jms.BytesMessage
value
- the boolean value to be written.
javax.jms.JMSException
- with reasons
public void writeByte(byte value) throws javax.jms.JMSException
writeByte
in interface javax.jms.BytesMessage
value
- the byte value to be written.
javax.jms.JMSException
- with reasons
public void writeBytes(byte[] value) throws javax.jms.JMSException
writeBytes
in interface javax.jms.BytesMessage
value
- the byte array to be written.
javax.jms.JMSException
- with reason
public void writeBytes(byte[] value, int offset, int length) throws javax.jms.JMSException
writeBytes
in interface javax.jms.BytesMessage
value
- the byte array value to be written.offset
- the initial offset within the byte array.length
- the number of bytes to use.
javax.jms.JMSException
- with reason
public void writeChar(char value) throws javax.jms.JMSException
writeChar
in interface javax.jms.BytesMessage
value
- the char value to be written.
javax.jms.JMSException
- with reason
public void writeDouble(double value) throws javax.jms.JMSException
writeDouble
in interface javax.jms.BytesMessage
value
- the double value to be written.
javax.jms.JMSException
- with reason
public void writeFloat(float value) throws javax.jms.JMSException
writeFloat
in interface javax.jms.BytesMessage
value
- the float value to be written.
javax.jms.JMSException
- with reason
public void writeInt(int value) throws javax.jms.JMSException
writeInt
in interface javax.jms.BytesMessage
value
- the int to be written.
javax.jms.JMSException
- with reason
public void writeLong(long value) throws javax.jms.JMSException
writeLong
in interface javax.jms.BytesMessage
value
- the long to be written.
javax.jms.JMSException
- with reason
public void writeObject(java.lang.Object value) throws javax.jms.JMSException
Note that this method only works for the 'objectified' primitive object types (Integer, Double, Long ...), Strings and byte arrays.
writeObject
in interface javax.jms.BytesMessage
value
- the Java Object to be written.
javax.jms.JMSException
- with reason
public void writeShort(short value) throws javax.jms.JMSException
writeShort
in interface javax.jms.BytesMessage
value
- the short to be written.
javax.jms.JMSException
- with reason
public void writeUTF(java.lang.String value) throws javax.jms.JMSException
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.
writeUTF
in interface javax.jms.BytesMessage
value
- the String value to be written.
javax.jms.JMSException
- with reason
public long getBodyLength() throws javax.jms.JMSException, javax.jms.MessageNotReadableException
getBodyLength
in interface javax.jms.BytesMessage
javax.jms.JMSException
- with reasons
javax.jms.MessageNotReadableException
|
(c) Copyright IBM Corp. 2005. All Rights Reserved. | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |