|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
A StreamMessage is used to send a stream of Java primitives.
It is filled and read sequentially. It inherits from Message
and adds a stream message body. It's 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 may also be read or written generically as objects.
For instance, 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 reset
has been made, the message body 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 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
must be supported. The unmarked cases must throw a JMSException. The
String to primitive conversions may 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 must be treated
as calling the primitive's corresponding valueOf(String)
conversion method with a null value. Since char does not support a String
conversion, attempting to read a null value as a char must throw
NullPointerException.
Session.createStreamMessage()
,
BytesMessage
,
MapMessage
,
Message
,
ObjectMessage
,
TextMessage
Fields inherited from interface javax.jms.Message |
DEFAULT_DELIVERY_MODE,
DEFAULT_PRIORITY,
DEFAULT_TIME_TO_LIVE |
Method Summary | |
boolean |
readBoolean()
Read a boolean from the stream message. |
byte |
readByte()
Read a byte value from the stream message. |
int |
readBytes(byte[] value)
Read a byte array field from the stream message into the specified byte[] object (the read buffer). |
char |
readChar()
Read a Unicode character value from the stream message. |
double |
readDouble()
Read a double from the stream message. |
float |
readFloat()
Read a float from the stream message. |
int |
readInt()
Read a 32-bit integer from the stream message. |
long |
readLong()
Read a 64-bit integer from the stream message. |
java.lang.Object |
readObject()
Read a Java object from the stream message. |
short |
readShort()
Read a 16-bit number from the stream message. |
java.lang.String |
readString()
Read in a string from the stream message. |
void |
reset()
Put the message body in read-only mode, and reposition the stream to the beginning. |
void |
writeBoolean(boolean value)
Write a boolean to the stream message. |
void |
writeByte(byte value)
Write out a byte to the stream message. |
void |
writeBytes(byte[] value)
Write a byte array field to the stream message. |
void |
writeBytes(byte[] value,
int offset,
int length)
Write a portion of a byte array as a byte array field to the stream message. |
void |
writeChar(char value)
Write a char to the stream message. |
void |
writeDouble(double value)
Write a double to the stream message. |
void |
writeFloat(float value)
Write a float to the stream message. |
void |
writeInt(int value)
Write an int to the stream message. |
void |
writeLong(long value)
Write a long to the stream message. |
void |
writeObject(java.lang.Object value)
Write a Java object to the stream message. |
void |
writeShort(short value)
Write a short to the stream message. |
void |
writeString(java.lang.String value)
Write a string to the stream message. |
Method Detail |
public boolean readBoolean() throws JMSException
boolean
from the stream message.boolean
value read.public byte readByte() throws JMSException
byte
.public short readShort() throws JMSException
public char readChar() throws JMSException
public int readInt() throws JMSException
int
.public long readLong() throws JMSException
long
.public float readFloat() throws JMSException
float
from the stream message.float
value from the stream message.public double readDouble() throws JMSException
double
from the stream message.double
value from the stream message.public java.lang.String readString() throws JMSException
public int readBytes(byte[] value) throws 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 value 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.
Once the first readBytes call on a byte[] field value has been done, the full value of the field must be read before it is valid to read the next field. An attempt to read the next field before that has been done will throw a MessageFormatException.
To read the byte field value into a new byte[] object, use the readObject method.
value
- the buffer into which the data is read.readObject()
public java.lang.Object readObject() throws JMSException
Note that this method can be used to return in objectified format,
an object that had been written to the Stream with the equivalent
Note that byte values are returned as byte[], not Byte[].writeObject
method call, or it's equivalent primitive
write
public void writeBoolean(boolean value) throws JMSException
boolean
to the stream message.
The value true
is written out as the value
(byte)1
; the value false
is written out as
the value (byte)0
.value
- the boolean
value to be written.public void writeByte(byte value) throws JMSException
byte
to the stream message.value
- the byte
value to be written.public void writeShort(short value) throws JMSException
short
to the stream message.value
- the short
to be written.public void writeChar(char value) throws JMSException
char
to the stream message.value
- the char
value to be written.public void writeInt(int value) throws JMSException
int
to the stream message.value
- the int
to be written.public void writeLong(long value) throws JMSException
long
to the stream message.value
- the long
to be written.public void writeFloat(float value) throws JMSException
float
to the stream message.value
- the float
value to be written.public void writeDouble(double value) throws JMSException
double
to the stream message.value
- the double
value to be written.public void writeString(java.lang.String value) throws JMSException
value
- the String
value to be written.public void writeBytes(byte[] value) throws JMSException
The byte array value
is written as a byte array field
into the StreamMessage. Consecutively written byte array fields are
treated as two distinct fields when reading byte array fields.
value
- the byte array to be written.public void writeBytes(byte[] value, int offset, int length) throws JMSException
The a portion of the byte array value
is written as a
byte array field into the StreamMessage. Consecutively written byte
array fields are treated as two distinct fields when reading byte array
fields.
value
- the byte array value to be written.offset
- the initial offset within the byte array.length
- the number of bytes to use.public void writeObject(java.lang.Object value) throws JMSException
Note that this method only works for the objectified primitive object types (Integer, Double, Long ...), String's and byte arrays.
value
- the Java object to be written.public void reset() throws JMSException
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |