|
||||||||||
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.JMSStreamMessage
A StreamMessage is used to send a stream of Java primitives.
It is filled and read sequentially. It inherits from JMSMessage
and adds a stream message body. Its methods are based largely on those
found in java.io.DataInputStream
and
java.io.DataOutputStream
.
The primitive types can be read or written explicitly using methods
for each type. They can also be read or written generically as objects.
For example, a call to StreamMessage.writeInt(6)
is
equivalent to StreamMessage.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 body is in read-only mode. When a message has been sent, the provider always calls the reset() method to read its content. Likewise, when a message has been received, the provider calls 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 body 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.
Stream messages support the following conversion table. The marked cases are supported and the unmarked cases throw a JMSException. The String to primitive conversions throw a runtime exception if the primitives valueOf() method does not accept it as a valid String representation of the primitive.
A value written as the row type can be read as the column type.
boolean byte short char int long float double String byte[] -------------------------------------------------------------------------- boolean X X byte X X X X X short X X X X char X X int X X X long X X float X X X double X X String X X X X X X X X byte[] X --------------------------------------------------------------------------
Attempting to read a null value as a Java primitive type is treated as calling the primitive's corresponding valueOf(String) conversion method with a null value. Because char does not support a String conversion, attempting to read a null value as a char throws a NullPointerException.
Field Summary |
Fields inherited from interface javax.jms.Message |
DEFAULT_DELIVERY_MODE, DEFAULT_PRIORITY, DEFAULT_TIME_TO_LIVE |
Method Summary | |
void |
clearBody()
Clears the message body. |
boolean |
readBoolean()
Reads a boolean from the stream message. |
byte |
readByte()
Reads a byte value from the stream message. |
int |
readBytes(byte[] value)
Reads a byte array field from the stream message into the specified byte[] object (the read buffer). |
char |
readChar()
Reads a Unicode character value from the stream message. |
double |
readDouble()
Reads a double from the stream message. |
float |
readFloat()
Reads a float from the stream message. |
int |
readInt()
Reads a 32-bit integer from the stream message. |
long |
readLong()
Reads a 64-bit integer from the stream message. |
java.lang.Object |
readObject()
Reads a Java object from the stream message. |
short |
readShort()
Reads a 16-bit integer from the stream message. |
java.lang.String |
readString()
Reads in a String from the stream message. |
void |
reset()
Puts the message in read-only mode, and repositions the stream to the beginning. |
java.lang.String |
toString()
Gets a String containing a formatted version of the Message. |
void |
writeBoolean(boolean value)
Writes a boolean to the stream message. |
void |
writeByte(byte value)
Writes a byte to the stream message. |
void |
writeBytes(byte[] value)
Writes a byte array to the stream message. |
void |
writeBytes(byte[] value,
int offset,
int length)
Writes a portion of a byte array to the stream message. |
void |
writeChar(char value)
Writes a char to the stream message. |
void |
writeDouble(double value)
Writes a double to the stream message. |
void |
writeFloat(float value)
Writes a float to the stream message. |
void |
writeInt(int value)
Writes an int to the stream message. |
void |
writeLong(long value)
Writes a long to the stream message. |
void |
writeObject(java.lang.Object value)
Writes a Java object to the stream message. |
void |
writeShort(short value)
Write a short to the stream message. |
void |
writeString(java.lang.String value)
Writes a String to the stream message. |
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 |
Method Detail |
public void clearBody() throws javax.jms.JMSException
clearBody
in interface javax.jms.Message
clearBody
in class JMSMessage
javax.jms.JMSException
- if the action fails to due to an internal JMS error.public boolean readBoolean() throws javax.jms.JMSException
readBoolean
in interface javax.jms.StreamMessage
javax.jms.JMSException
- if JMS fails to read the message due to an internal JMS error.
javax.jms.MessageEOFException
- if an end of message stream.
javax.jms.MessageFormatException
- if this type conversion is not valid.
javax.jms.MessageNotReadableException
- if the message is in write-only mode.public byte readByte() throws javax.jms.JMSException
readByte
in interface javax.jms.StreamMessage
javax.jms.JMSException
- if JMS fails to read the message due to an internal JMS error.
javax.jms.MessageEOFException
- if an end of message stream.
javax.jms.MessageFormatException
- if this type conversion is not valid.
javax.jms.MessageNotReadableException
- if the message is in write-only mode.public int readBytes(byte[] value) throws javax.jms.JMSException
To read the field value, readBytes() should be successively called until it returns a value less than the length of the read buffer. The values of the bytes in the buffer following the last byte read are undefined.
If readBytes() returns a value equal to the length of the buffer, a subsequent readBytes() call must be made. If there are no more bytes to be read this call will return -1.
If the bytes array field value is null, readBytes() returns -1.
If the bytes array field value is empty, readBytes() returns 0.
After the first readBytes() call on a byte[] field value has been made, the full value of the field must be read before the next field can be read. An attempt to read the next field before that has been done will throw a MessageFormatException.
readBytes
in interface javax.jms.StreamMessage
value
- the buffer into which the data is read.
javax.jms.JMSException
- if JMS fails to read the message due to an internal JMS error.
javax.jms.MessageEOFException
- if an end of message stream.
javax.jms.MessageFormatException
- if this type conversion is not valid.
javax.jms.MessageNotReadableException
- if the message is in write-only mode.public char readChar() throws javax.jms.JMSException
readChar
in interface javax.jms.StreamMessage
javax.jms.JMSException
- if JMS fails to read the message due to
an internal JMS error.
javax.jms.MessageEOFException
- if an end of message stream.
javax.jms.MessageFormatException
- if this type conversion is not valid.
javax.jms.MessageNotReadableException
- if the message is in write-only mode.public double readDouble() throws javax.jms.JMSException
readDouble
in interface javax.jms.StreamMessage
javax.jms.JMSException
- if JMS fails to read the message due to
an internal JMS error.
javax.jms.MessageEOFException
- if an end of message stream.
javax.jms.MessageFormatException
- if this type conversion is not valid.
javax.jms.MessageNotReadableException
- if the message is in write-only mode.public float readFloat() throws javax.jms.JMSException
readFloat
in interface javax.jms.StreamMessage
javax.jms.JMSException
- if JMS fails to read the message due to
an internal JMS error.
javax.jms.MessageEOFException
- if an end of message stream.
javax.jms.MessageFormatException
- if this type conversion is not valid.
javax.jms.MessageNotReadableException
- if the message is in write-only mode.public int readInt() throws javax.jms.JMSException
readInt
in interface javax.jms.StreamMessage
int
.
javax.jms.JMSException
- if JMS fails to read the message due to
an internal JMS error.
javax.jms.MessageEOFException
- if an end of message stream.
javax.jms.MessageFormatException
- if this type conversion is not valid.
javax.jms.MessageNotReadableException
- if the message is in write-only mode.public long readLong() throws javax.jms.JMSException
readLong
in interface javax.jms.StreamMessage
long
.
javax.jms.JMSException
- if JMS fails to read the message due to
an internal JMS error.
javax.jms.MessageEOFException
- if an end of message stream.
javax.jms.MessageFormatException
- if this type conversion is not valid.
javax.jms.MessageNotReadableException
- if the message is in write-only mode.public java.lang.Object readObject() throws javax.jms.JMSException
This method can be used to return in 'objectified' format,
an object that had been written to the stream with the equivalent
writeObject() method call, or its equivalent primitive
write
readObject
in interface javax.jms.StreamMessage
javax.jms.JMSException
- if JMS fails to read the message due to
an internal JMS error.
javax.jms.MessageEOFException
- if an end of message stream.
javax.jms.MessageNotReadableException
- if the message is in write-only mode.public short readShort() throws javax.jms.JMSException
readShort
in interface javax.jms.StreamMessage
javax.jms.JMSException
- if JMS fails to read the message due to
an internal JMS error.
javax.jms.MessageEOFException
- if an end of message stream.
javax.jms.MessageFormatException
- if this type conversion is not valid.
javax.jms.MessageNotReadableException
- if the message is in write-only mode.public java.lang.String readString() throws javax.jms.JMSException
readString
in interface javax.jms.StreamMessage
javax.jms.JMSException
- if JMS fails to read the message due to
an internal JMS error.
javax.jms.MessageEOFException
- if an end of message stream.
javax.jms.MessageFormatException
- if this type conversion is not valid.
javax.jms.MessageNotReadableException
- if the message is in write-only mode.public void reset() throws javax.jms.JMSException
reset
in interface javax.jms.StreamMessage
javax.jms.JMSException
- if JMS fails to reset the message due to
an internal JMS error.
javax.jms.MessageFormatException
- if the message's format is not validpublic java.lang.String toString()
toString
in class JMSMessage
public void writeBoolean(boolean value) throws javax.jms.JMSException
true
is written as the value
(byte)1
; the value false
is written as
the value (byte)0
.
writeBoolean
in interface javax.jms.StreamMessage
value
- the boolean value to be written.
javax.jms.JMSException
- if JMS fails to write the boolean to the message due to
an internal JMS error.
javax.jms.MessageNotWriteableException
- if the message is in read-only mode.public void writeByte(byte value) throws javax.jms.JMSException
writeByte
in interface javax.jms.StreamMessage
value
- the byte value to be written.
javax.jms.JMSException
- if JMS fails to write the byte to the message due to
an internal JMS error.
javax.jms.MessageNotWriteableException
- if the message is in read-only mode.public void writeBytes(byte[] value) throws javax.jms.JMSException
writeBytes
in interface javax.jms.StreamMessage
value
- the byte array to be written.
javax.jms.JMSException
- if JMS fails to write the byte array to the message due to
an internal JMS error.
javax.jms.MessageNotWriteableException
- if the message is in read-only mode.public void writeBytes(byte[] value, int offset, int length) throws javax.jms.JMSException
writeBytes
in interface javax.jms.StreamMessage
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
- if JMS fails to write the byte array portion to the message due to
an internal JMS error.
javax.jms.MessageNotWriteableException
- if the message is in read-only mode.public void writeChar(char value) throws javax.jms.JMSException
writeChar
in interface javax.jms.StreamMessage
value
- the char value to be written.
javax.jms.JMSException
- if JMS fails to write the char to the message due to
an internal JMS error.
javax.jms.MessageNotWriteableException
- if the message is in read-only mode.public void writeDouble(double value) throws javax.jms.JMSException
writeDouble
in interface javax.jms.StreamMessage
value
- the double value to be written.
javax.jms.JMSException
- if JMS fails to write the double to the message due to
an internal JMS error.
javax.jms.MessageNotWriteableException
- if the message is in read-only mode.public void writeFloat(float value) throws javax.jms.JMSException
writeFloat
in interface javax.jms.StreamMessage
value
- the float value to be written.
javax.jms.JMSException
- if JMS fails to write the float to the message due to
an internal JMS error.
javax.jms.MessageNotWriteableException
- if the message is in read-only mode.public void writeInt(int value) throws javax.jms.JMSException
writeInt
in interface javax.jms.StreamMessage
value
- the int to be written.
javax.jms.JMSException
- if JMS fails to write the int to the message due to
an internal JMS error.
javax.jms.MessageNotWriteableException
- if the message is in read-only mode.public void writeLong(long value) throws javax.jms.JMSException
writeLong
in interface javax.jms.StreamMessage
value
- the long to be written.
javax.jms.JMSException
- if JMS fails to write the long to the message due to
an internal JMS error.
javax.jms.MessageNotWriteableException
- if the message is in read-only mode.public void writeObject(java.lang.Object value) throws javax.jms.JMSException
This method only works for the 'objectified' primitive object types (Integer, Double, Long ...), Strings and byte arrays.
writeObject
in interface javax.jms.StreamMessage
value
- the Java object to be written.
javax.jms.JMSException
- if JMS fails to write the object to the message due to
an internal JMS error.
javax.jms.MessageNotWriteableException
- if the message is in read-only mode.
javax.jms.MessageFormatException
- if the object is not validpublic void writeShort(short value) throws javax.jms.JMSException
writeShort
in interface javax.jms.StreamMessage
value
- the short to be written.
javax.jms.JMSException
- if JMS fails to write the short to the message due to
an internal JMS error.
javax.jms.MessageNotWriteableException
- if the message is in read-only mode.public void writeString(java.lang.String value) throws javax.jms.JMSException
writeString
in interface javax.jms.StreamMessage
value
- the String value to be written.
javax.jms.JMSException
- if JMS fails to write the String to the message due to
an internal JMS error.
javax.jms.MessageNotWriteableException
- if the message is in read-only mode.
|
(c) Copyright IBM Corp. 2005. All Rights Reserved. | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |