-
- All Superinterfaces:
Message
public interface StreamMessage extends Message
AStreamMessage
object is used to send a stream of primitive types in the Java programming language. It is filled and read sequentially. It inherits from theMessage
interface and adds a stream message body. Its methods are based largely on those found injava.io.DataInputStream
andjava.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 toStreamMessage.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 toreset
has been made, the message body is in read-only mode. After a message has been sent, the client that sent it can retain and modify it without affecting the message that has been sent. The same message object can be sent multiple times. When a message has been received, the provider has calledreset
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.StreamMessage
objects support the following conversion table. The marked cases must be supported. The unmarked cases must throw aJMSException
. TheString
-to-primitive conversions may throw a runtime exception if the primitive'svalueOf()
method does not accept it as a validString
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 primitive type must be treated as calling the primitive's corresponding
valueOf(String)
conversion method with a null value. Sincechar
does not support aString
conversion, attempting to read a null value as achar
must throw aNullPointerException
.- Since:
- JMS 1.0
- Version:
- Jakarta Messaging 2.0
- See Also:
Session.createStreamMessage()
,BytesMessage
,MapMessage
,Message
,ObjectMessage
,TextMessage
-
-
Field Summary
-
Fields inherited from interface jakarta.jms.Message
DEFAULT_DELIVERY_DELAY, DEFAULT_DELIVERY_MODE, DEFAULT_PRIORITY, DEFAULT_TIME_TO_LIVE
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description boolean
readBoolean()
Reads aboolean
from the stream message.byte
readByte()
Reads abyte
value from the stream message.int
readBytes(byte[] value)
Reads a byte array field from the stream message into the specifiedbyte[]
object (the read buffer).char
readChar()
Reads a Unicode character value from the stream message.double
readDouble()
Reads adouble
from the stream message.float
readFloat()
Reads afloat
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.Object
readObject()
Reads an object from the stream message.short
readShort()
Reads a 16-bit integer from the stream message.String
readString()
Reads aString
from the stream message.void
reset()
Puts the message body in read-only mode and repositions the stream to the beginning.void
writeBoolean(boolean value)
Writes aboolean
to the stream message.void
writeByte(byte value)
Writes abyte
to the stream message.void
writeBytes(byte[] value)
Writes a byte array field to the stream message.void
writeBytes(byte[] value, int offset, int length)
Writes a portion of a byte array as a byte array field to the stream message.void
writeChar(char value)
Writes achar
to the stream message.void
writeDouble(double value)
Writes adouble
to the stream message.void
writeFloat(float value)
Writes afloat
to the stream message.void
writeInt(int value)
Writes anint
to the stream message.void
writeLong(long value)
Writes along
to the stream message.void
writeObject(Object value)
Writes an object to the stream message.void
writeShort(short value)
Writes ashort
to the stream message.void
writeString(String value)
Writes aString
to the stream message.-
Methods inherited from interface jakarta.jms.Message
acknowledge, clearBody, clearProperties, getBody, getBooleanProperty, getByteProperty, getDoubleProperty, getFloatProperty, getIntProperty, getJMSCorrelationID, getJMSCorrelationIDAsBytes, getJMSDeliveryMode, getJMSDeliveryTime, getJMSDestination, getJMSExpiration, getJMSMessageID, getJMSPriority, getJMSRedelivered, getJMSReplyTo, getJMSTimestamp, getJMSType, getLongProperty, getObjectProperty, getPropertyNames, getShortProperty, getStringProperty, isBodyAssignableTo, propertyExists, setBooleanProperty, setByteProperty, setDoubleProperty, setFloatProperty, setIntProperty, setJMSCorrelationID, setJMSCorrelationIDAsBytes, setJMSDeliveryMode, setJMSDeliveryTime, setJMSDestination, setJMSExpiration, setJMSMessageID, setJMSPriority, setJMSRedelivered, setJMSReplyTo, setJMSTimestamp, setJMSType, setLongProperty, setObjectProperty, setShortProperty, setStringProperty
-
-
-
-
Method Detail
-
readBoolean
boolean readBoolean() throws JMSException
Reads aboolean
from the stream message.- Returns:
- the
boolean
value read - Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageEOFException
- if unexpected end of message stream has been reached.MessageFormatException
- if this type conversion is invalid.MessageNotReadableException
- if the message is in write-only mode.
-
readByte
byte readByte() throws JMSException
Reads abyte
value from the stream message.- Returns:
- the next byte from the stream message as a 8-bit
byte
- Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageEOFException
- if unexpected end of message stream has been reached.MessageFormatException
- if this type conversion is invalid.MessageNotReadableException
- if the message is in write-only mode.
-
readShort
short readShort() throws JMSException
Reads a 16-bit integer from the stream message.- Returns:
- a 16-bit integer from the stream message
- Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageEOFException
- if unexpected end of message stream has been reached.MessageFormatException
- if this type conversion is invalid.MessageNotReadableException
- if the message is in write-only mode.
-
readChar
char readChar() throws JMSException
Reads a Unicode character value from the stream message.- Returns:
- a Unicode character from the stream message
- Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageEOFException
- if unexpected end of message stream has been reached.MessageFormatException
- if this type conversion is invalidMessageNotReadableException
- if the message is in write-only mode.
-
readInt
int readInt() throws JMSException
Reads a 32-bit integer from the stream message.- Returns:
- a 32-bit integer value from the stream message, interpreted as an
int
- Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageEOFException
- if unexpected end of message stream has been reached.MessageFormatException
- if this type conversion is invalid.MessageNotReadableException
- if the message is in write-only mode.
-
readLong
long readLong() throws JMSException
Reads a 64-bit integer from the stream message.- Returns:
- a 64-bit integer value from the stream message, interpreted as a
long
- Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageEOFException
- if unexpected end of message stream has been reached.MessageFormatException
- if this type conversion is invalid.MessageNotReadableException
- if the message is in write-only mode.
-
readFloat
float readFloat() throws JMSException
Reads afloat
from the stream message.- Returns:
- a
float
value from the stream message - Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageEOFException
- if unexpected end of message stream has been reached.MessageFormatException
- if this type conversion is invalid.MessageNotReadableException
- if the message is in write-only mode.
-
readDouble
double readDouble() throws JMSException
Reads adouble
from the stream message.- Returns:
- a
double
value from the stream message - Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageEOFException
- if unexpected end of message stream has been reached.MessageFormatException
- if this type conversion is invalid.MessageNotReadableException
- if the message is in write-only mode.
-
readString
String readString() throws JMSException
Reads aString
from the stream message.- Returns:
- a Unicode string from the stream message
- Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageEOFException
- if unexpected end of message stream has been reached.MessageFormatException
- if this type conversion is invalid.MessageNotReadableException
- if the message is in write-only mode.
-
readBytes
int readBytes(byte[] value) throws JMSException
Reads a byte array field from the stream message into the specifiedbyte[]
object (the read buffer).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 is undefined.If
readBytes
returns a value equal to the length of the buffer, a subsequentreadBytes
call must be made. If there are no more bytes to be read, this call returns -1.If the byte array field value is null,
readBytes
returns -1.If the byte array field value is empty,
readBytes
returns 0.Once the first
readBytes
call on abyte[]
field value has been made, 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 aMessageFormatException
.To read the byte field value into a new
byte[]
object, use thereadObject
method.- 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 byte field has been reached
- Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageEOFException
- if unexpected end of message stream has been reached.MessageFormatException
- if this type conversion is invalid.MessageNotReadableException
- if the message is in write-only mode.- See Also:
readObject()
-
readObject
Object readObject() throws JMSException
Reads an object from the stream message.This method can be used to return, in objectified format, an object in the Java programming language ("Java object") that has been written to the stream with the equivalent
writeObject
method call, or its equivalent primitivewritetype
method.Note that byte values are returned as
byte[]
, notByte[]
.An attempt to call
readObject
to read a byte field value into a newbyte[]
object before the full value of the byte field has been read will throw aMessageFormatException
.- Returns:
- a Java object from the stream message, in objectified format (for example, if the object was written as an
int
, anInteger
is returned) - Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageEOFException
- if unexpected end of message stream has been reached.MessageFormatException
- if this type conversion is invalid.MessageNotReadableException
- if the message is in write-only mode.- See Also:
readBytes(byte[] value)
-
writeBoolean
void writeBoolean(boolean value) throws JMSException
Writes aboolean
to the stream message. The valuetrue
is written as the value(byte)1
; the valuefalse
is written as the value(byte)0
.- Parameters:
value
- theboolean
value to be written- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.MessageNotWriteableException
- if the message is in read-only mode.
-
writeByte
void writeByte(byte value) throws JMSException
Writes abyte
to the stream message.- Parameters:
value
- thebyte
value to be written- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.MessageNotWriteableException
- if the message is in read-only mode.
-
writeShort
void writeShort(short value) throws JMSException
Writes ashort
to the stream message.- Parameters:
value
- theshort
value to be written- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.MessageNotWriteableException
- if the message is in read-only mode.
-
writeChar
void writeChar(char value) throws JMSException
Writes achar
to the stream message.- Parameters:
value
- thechar
value to be written- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.MessageNotWriteableException
- if the message is in read-only mode.
-
writeInt
void writeInt(int value) throws JMSException
Writes anint
to the stream message.- Parameters:
value
- theint
value to be written- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.MessageNotWriteableException
- if the message is in read-only mode.
-
writeLong
void writeLong(long value) throws JMSException
Writes along
to the stream message.- Parameters:
value
- thelong
value to be written- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.MessageNotWriteableException
- if the message is in read-only mode.
-
writeFloat
void writeFloat(float value) throws JMSException
Writes afloat
to the stream message.- Parameters:
value
- thefloat
value to be written- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.MessageNotWriteableException
- if the message is in read-only mode.
-
writeDouble
void writeDouble(double value) throws JMSException
Writes adouble
to the stream message.- Parameters:
value
- thedouble
value to be written- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.MessageNotWriteableException
- if the message is in read-only mode.
-
writeString
void writeString(String value) throws JMSException
Writes aString
to the stream message.- Parameters:
value
- theString
value to be written- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.MessageNotWriteableException
- if the message is in read-only mode.
-
writeBytes
void writeBytes(byte[] value) throws JMSException
Writes a byte array field to the stream message.The byte array
value
is written to the message as a byte array field. Consecutively written byte array fields are treated as two distinct fields when the fields are read.- Parameters:
value
- the byte array value to be written- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.MessageNotWriteableException
- if the message is in read-only mode.
-
writeBytes
void writeBytes(byte[] value, int offset, int length) throws JMSException
Writes a portion of a byte array as a byte array field to the stream message.The a portion of the byte array
value
is written to the message as a byte array field. Consecutively written byte array fields are treated as two distinct fields when the fields are read.- Parameters:
value
- the byte array value to be writtenoffset
- the initial offset within the byte arraylength
- the number of bytes to use- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.MessageNotWriteableException
- if the message is in read-only mode.
-
writeObject
void writeObject(Object value) throws JMSException
Writes an object to the stream message.This method works only for the objectified primitive object types (
Integer
,Double
,Long
...),String
objects, and byte arrays.- Parameters:
value
- the Java object to be written- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.MessageFormatException
- if the object is invalid.MessageNotWriteableException
- if the message is in read-only mode.
-
reset
void reset() throws JMSException
Puts the message body in read-only mode and repositions the stream to the beginning.- Throws:
JMSException
- if the Jakarta Messaging provider fails to reset the message due to some internal error.MessageFormatException
- if the message has an invalid format.
-
-