-
- All Superinterfaces:
Message
public interface BytesMessage extends Message
ABytesMessage
object is used to send a message containing a stream of uninterpreted bytes. It inherits from theMessage
interface and adds a bytes message body. The receiver of the message supplies the interpretation of the bytes.The
BytesMessage
methods are based largely on those found injava.io.DataInputStream
andjava.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 the Jakarta Messaging API allows the use of message properties with byte messages, they are typically not used, since the inclusion of properties may affect the format.
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 toBytesMessage.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. When aBytesMessage
is sent asynchronously, the provider must callreset
on theBytesMessage
passed to theCompletionListener
. This means that theCompletionListener
can read the message body without needing to callreset
. 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 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.- Since:
- JMS 1.0
- Version:
- Jakarta Messaging 2.0
- See Also:
Session.createBytesMessage()
,MapMessage
,Message
,ObjectMessage
,StreamMessage
,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 long
getBodyLength()
Gets the number of bytes of the message body when the message is in read-only mode.boolean
readBoolean()
Reads aboolean
from the bytes message stream.byte
readByte()
Reads a signed 8-bit value from the bytes message stream.int
readBytes(byte[] value)
Reads a byte array from the bytes message stream.int
readBytes(byte[] value, int length)
Reads a portion of the bytes message stream.char
readChar()
Reads a Unicode character value from the bytes message stream.double
readDouble()
Reads adouble
from the bytes message stream.float
readFloat()
Reads afloat
from the bytes message stream.int
readInt()
Reads a signed 32-bit integer from the bytes message stream.long
readLong()
Reads a signed 64-bit integer from the bytes message stream.short
readShort()
Reads a signed 16-bit number from the bytes message stream.int
readUnsignedByte()
Reads an unsigned 8-bit number from the bytes message stream.int
readUnsignedShort()
Reads an unsigned 16-bit number from the bytes message stream.String
readUTF()
Reads a string that has been encoded using a modified UTF-8 format from the bytes message stream.void
reset()
Puts the message body in read-only mode and repositions the stream of bytes to the beginning.void
writeBoolean(boolean value)
Writes aboolean
to the bytes message stream as a 1-byte value.void
writeByte(byte value)
Writes abyte
to the bytes message stream as a 1-byte value.void
writeBytes(byte[] value)
Writes a byte array to the bytes message stream.void
writeBytes(byte[] value, int offset, int length)
Writes a portion of a byte array to the bytes message stream.void
writeChar(char value)
Writes achar
to the bytes message stream as a 2-byte value, high byte first.void
writeDouble(double value)
Converts thedouble
argument to along
using thedoubleToLongBits
method in classDouble
, and then writes thatlong
value to the bytes message stream as an 8-byte quantity, high byte first.void
writeFloat(float value)
Converts thefloat
argument to anint
using thefloatToIntBits
method in classFloat
, and then writes thatint
value to the bytes message stream as a 4-byte quantity, high byte first.void
writeInt(int value)
Writes anint
to the bytes message stream as four bytes, high byte first.void
writeLong(long value)
Writes along
to the bytes message stream as eight bytes, high byte first.void
writeObject(Object value)
Writes an object to the bytes message stream.void
writeShort(short value)
Writes ashort
to the bytes message stream as two bytes, high byte first.void
writeUTF(String value)
Writes a string to the bytes message stream using UTF-8 encoding in a machine-independent manner.-
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
-
getBodyLength
long getBodyLength() throws 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:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageNotReadableException
- if the message is in write-only mode.- Since:
- JMS 1.1
-
readBoolean
boolean readBoolean() throws JMSException
Reads aboolean
from the bytes message stream.- 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 bytes stream has been reached.MessageNotReadableException
- if the message is in write-only mode.
-
readByte
byte readByte() throws JMSException
Reads a signed 8-bit value from the bytes message stream.- Returns:
- the next byte from the bytes message stream as a signed 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 bytes stream has been reached.MessageNotReadableException
- if the message is in write-only mode.
-
readUnsignedByte
int readUnsignedByte() throws JMSException
Reads an unsigned 8-bit number from the bytes message stream.- Returns:
- the next byte from the bytes message stream, interpreted as an unsigned 8-bit number
- Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageEOFException
- if unexpected end of bytes stream has been reached.MessageNotReadableException
- if the message is in write-only mode.
-
readShort
short readShort() throws JMSException
Reads a signed 16-bit number from the bytes message stream.- Returns:
- the next two bytes from the bytes message stream, interpreted as a signed 16-bit number
- Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageEOFException
- if unexpected end of bytes stream has been reached.MessageNotReadableException
- if the message is in write-only mode.
-
readUnsignedShort
int readUnsignedShort() throws JMSException
Reads an unsigned 16-bit number from the bytes message stream.- Returns:
- the next two bytes from the bytes message stream, interpreted as an unsigned 16-bit integer
- Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageEOFException
- if unexpected end of bytes stream has been reached.MessageNotReadableException
- if the message is in write-only mode.
-
readChar
char readChar() throws JMSException
Reads a Unicode character value from the bytes message stream.- Returns:
- the next two bytes from the bytes message stream as a Unicode character
- Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageEOFException
- if unexpected end of bytes stream has been reached.MessageNotReadableException
- if the message is in write-only mode.
-
readInt
int readInt() throws JMSException
Reads a signed 32-bit integer from the bytes message stream.- Returns:
- the next four bytes from the bytes message stream, 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 bytes stream has been reached.MessageNotReadableException
- if the message is in write-only mode.
-
readLong
long readLong() throws JMSException
Reads a signed 64-bit integer from the bytes message stream.- Returns:
- the next eight bytes from the bytes message stream, 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 bytes stream has been reached.MessageNotReadableException
- if the message is in write-only mode.
-
readFloat
float readFloat() throws JMSException
Reads afloat
from the bytes message stream.- Returns:
- the next four bytes from the bytes message stream, interpreted as a
float
- Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageEOFException
- if unexpected end of bytes stream has been reached.MessageNotReadableException
- if the message is in write-only mode.
-
readDouble
double readDouble() throws JMSException
Reads adouble
from the bytes message stream.- Returns:
- the next eight bytes from the bytes message stream, interpreted as a
double
- Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageEOFException
- if unexpected end of bytes stream has been reached.MessageNotReadableException
- if the message is in write-only mode.
-
readUTF
String readUTF() throws JMSException
Reads a string that has been encoded using a modified UTF-8 format from the bytes message stream.For more information on the UTF-8 format, see "File System Safe UCS Transformation Format (FSS_UTF)", X/Open Preliminary Specification, X/Open Company Ltd., Document Number: P316. This information also appears in ISO/IEC 10646, Annex P.
- Returns:
- a Unicode string from the bytes message stream
- Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageEOFException
- if unexpected end of bytes stream has been reached.MessageNotReadableException
- if the message is in write-only mode.
-
readBytes
int readBytes(byte[] value) throws JMSException
Reads a byte array from the bytes message stream.If the length of array
value
is less than the number of bytes remaining to be read from the stream, the array should be filled. A subsequent call reads the next increment, and so on.If the number of bytes remaining in the stream is less than the length of array
value
, the bytes should be read into the array. The return value of the total number of bytes read will be less than the length of the array, indicating that there are no more bytes left to be read from the stream. The next read of the stream returns -1.- 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:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageNotReadableException
- if the message is in write-only mode.
-
readBytes
int readBytes(byte[] value, int length) throws JMSException
Reads a portion of the bytes message stream.If the length of array
value
is less than the number of bytes remaining to be read from the stream, the array should be filled. A subsequent call reads the next increment, and so on.If the number of bytes remaining in the stream is less than the length of array
value
, the bytes should be read into the array. The return value of the total number of bytes read will be less than the length of the array, indicating that there are no more bytes left to be read from the stream. The next read of the stream returns -1.If
length
is negative, orlength
is greater than the length of the arrayvalue
, then anIndexOutOfBoundsException
is thrown. No bytes will be read from the stream for this exception case.- Parameters:
value
- the buffer into which the data is readlength
- the number of bytes to read; must be less than or equal tovalue.length
- 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:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageNotReadableException
- if the message is in write-only mode.
-
writeBoolean
void writeBoolean(boolean value) throws JMSException
Writes aboolean
to the bytes message stream as a 1-byte value. 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 bytes message stream as a 1-byte value.- 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 bytes message stream as two bytes, high byte first.- Parameters:
value
- theshort
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 bytes message stream as a 2-byte value, high byte first.- 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 bytes message stream as four bytes, high byte first.- Parameters:
value
- theint
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 bytes message stream as eight bytes, high byte first.- Parameters:
value
- thelong
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
Converts thefloat
argument to anint
using thefloatToIntBits
method in classFloat
, and then writes thatint
value to the bytes message stream as a 4-byte quantity, high byte first.- 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
Converts thedouble
argument to along
using thedoubleToLongBits
method in classDouble
, and then writes thatlong
value to the bytes message stream as an 8-byte quantity, high byte first.- 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.
-
writeUTF
void writeUTF(String value) throws JMSException
Writes a string to the bytes message stream using UTF-8 encoding in a machine-independent manner.For more information on the UTF-8 format, see "File System Safe UCS Transformation Format (FSS_UTF)", X/Open Preliminary Specification, X/Open Company Ltd., Document Number: P316. This information also appears in ISO/IEC 10646, Annex P.
- 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 to the bytes message stream.- Parameters:
value
- the byte array 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 to the bytes message stream.- 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 bytes message stream.This method works only for the objectified primitive object types (
Integer
,Double
,Long
...),String
objects, and byte arrays.- Parameters:
value
- the object in the Java programming language ("Java object") to be written; it must not be null- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.MessageFormatException
- if the object is of an invalid type.MessageNotWriteableException
- if the message is in read-only mode.NullPointerException
- if the parametervalue
is null.
-
reset
void reset() throws JMSException
Puts the message body in read-only mode and repositions the stream of bytes 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.
-
-