Package org.ow2.joram.jakarta.jms

Class BytesMessage

java.lang.Object

org.ow2.joram.jakarta.jms.Message

org.ow2.joram.jakarta.jms.BytesMessage

All Implemented Interfaces:

jakarta.jms.BytesMessage, jakarta.jms.Message

public final class BytesMessage
extends Message
implements jakarta.jms.BytesMessage

Implements the jakarta.jms.BytesMessage interface.

A BytesMessage object is used to send a message containing a stream of uninterpreted bytes. It inherits from the Message interface and adds a bytes message body. The BytesMessage methods are based largely on those found in java.io.DataInputStream and java.io.DataOutputStream.

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 to BytesMessage.writeObject(new Integer(6)).

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. 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 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 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.

Field Summary

Fields

Modifier and Type	Field	Description
private DataInputStream	inputStream	The stream for reading the written data.
private ByteArrayOutputStream	outputBuffer	The array in which the written data is buffered.
private DataOutputStream	outputStream	The stream in which body data is written.
private boolean	prepared	true if the message has been sent since its last modif.

Fields inherited from class org.ow2.joram.jakarta.jms.Message

jmsDest, logger, momMsg, propertiesRO, RObody, session

Fields inherited from interface jakarta.jms.Message

DEFAULT_DELIVERY_DELAY, DEFAULT_DELIVERY_MODE, DEFAULT_PRIORITY, DEFAULT_TIME_TO_LIVE

Constructor Summary

Constructors

Constructor	Description
BytesMessage()	Instantiates a bright new BytesMessage.
BytesMessage(Session sess, Message momMsg)	Instantiates a BytesMessage wrapping a consumed MOM message containing a bytes array.

Method Summary

Modifier and Type	Method	Description
void	clearBody()	API method.
<T> T	getBody(Class<T> c)	Returns the message body as an object of the specified type.
long	getBodyLength()	API method.
(package private) byte[]	getBytes()	Get message content as byte array
protected <T> T	getEffectiveBody(Class<T> c)	Get message body
protected void	prepare()	Method actually preparing the message for sending by transfering the local body into the wrapped MOM message.
boolean	readBoolean()	API method.
byte	readByte()	API method.
int	readBytes(byte[] value)	API method.
int	readBytes(byte[] value, int length)	API method.
char	readChar()	API method.
double	readDouble()	API method.
float	readFloat()	API method.
int	readInt()	API method.
long	readLong()	API method.
short	readShort()	API method.
int	readUnsignedByte()	API method.
int	readUnsignedShort()	API method.
String	readUTF()	API method.
void	reset()	API method.
void	writeBoolean(boolean value)	API method.
void	writeByte(byte value)	API method.
void	writeBytes(byte[] value)	API method.
void	writeBytes(byte[] value, int offset, int length)	API method.
void	writeChar(char value)	API method.
void	writeDouble(double value)	API method.
void	writeFloat(float value)	API method.
void	writeInt(int value)	API method.
void	writeLong(long value)	API method.
void	writeObject(Object value)	API method.
void	writeShort(short value)	API method.
void	writeUTF(String value)	API method.

Methods inherited from class org.ow2.joram.jakarta.jms.Message

acknowledge, clearProperties, convertJMSMessage, dumpBody, dumpBody, getBooleanProperty, getByteProperty, getCompressedMinSize, getCompressionLevel, getDoubleProperty, getFloatProperty, getIntProperty, getJMSCorrelationID, getJMSCorrelationIDAsBytes, getJMSDeliveryMode, getJMSDeliveryTime, getJMSDestination, getJMSExpiration, getJMSMessageID, getJMSPriority, getJMSRedelivered, getJMSReplyTo, getJMSTimestamp, getJMSType, getLongProperty, getMomMsg, getObjectProperty, getProperties, getPropertyNames, getRawBody, getShortProperty, getStringProperty, isBodyAssignableTo, isCompressed, prepareJMSMessage, propertyExists, resetPropertiesRO, setBooleanProperty, setByteProperty, setCompressedMinSize, setCompressionLevel, setDoubleProperty, setFloatProperty, setIntProperty, setJMSCorrelationID, setJMSCorrelationIDAsBytes, setJMSDeliveryMode, setJMSDeliveryTime, setJMSDestination, setJMSExpiration, setJMSMessageID, setJMSPriority, setJMSRedelivered, setJMSReplyTo, setJMSTimestamp, setJMSType, setLongProperty, setObjectProperty, setShortProperty, setStringProperty, toString, toString, wrapMomMessage

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface jakarta.jms.Message

acknowledge, clearProperties, 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

Field Detail

outputBuffer

private transient ByteArrayOutputStream outputBuffer

The array in which the written data is buffered.

outputStream

private transient DataOutputStream outputStream

The stream in which body data is written.

inputStream

private transient DataInputStream inputStream

The stream for reading the written data.

prepared

private transient boolean prepared

true if the message has been sent since its last modif.

Constructor Detail

BytesMessage

BytesMessage()

Instantiates a bright new BytesMessage.

BytesMessage

BytesMessage(Session sess,
             Message momMsg)
      throws jakarta.jms.JMSException

Instantiates a BytesMessage wrapping a consumed MOM message containing a bytes array.

Parameters:

sess - The consuming session.

momMsg - The MOM message to wrap.

Throws:

jakarta.jms.JMSException - if an error has occurred

Method Detail

getBodyLength

public long getBodyLength()
                   throws jakarta.jms.JMSException

API method. 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.

Specified by:

getBodyLength in interface jakarta.jms.BytesMessage

Returns:

the number of bytes in the message's body.

Throws:

jakarta.jms.MessageNotReadableException - If the message is WRITE-ONLY.

jakarta.jms.JMSException

clearBody

public void clearBody()
               throws jakarta.jms.JMSException

API method. Clears out the message body.

Calling this method leaves the message body in the same state as an empty body in a newly created message.

Specified by:

clearBody in interface jakarta.jms.Message

Overrides:

clearBody in class Message

Throws:

jakarta.jms.JMSException - In case of an error while closing the output or input streams.

writeBoolean

public void writeBoolean(boolean value)
                  throws jakarta.jms.JMSException

API method. Writes a boolean to the bytes message stream as a 1-byte value. The value true is written as the value (byte)1; the value false is written as the value (byte)0.

Specified by:

writeBoolean in interface jakarta.jms.BytesMessage

Parameters:

value - the value to be written.

Throws:

jakarta.jms.MessageNotWriteableException - If the message body is read-only.

jakarta.jms.JMSException - If the value could not be written on the stream.

writeByte

public void writeByte(byte value)
               throws jakarta.jms.JMSException

API method. Writes a byte to the bytes message stream.

Specified by:

writeByte in interface jakarta.jms.BytesMessage

Parameters:

value - the value to be written.

Throws:

jakarta.jms.MessageNotWriteableException - If the message body is read-only.

jakarta.jms.JMSException - If the value could not be written on the stream.

writeBytes

public void writeBytes(byte[] value)
                throws jakarta.jms.JMSException

API method. Writes a byte array to the bytes message stream.

Specified by:

writeBytes in interface jakarta.jms.BytesMessage

Parameters:

value - the byte array to be written.

Throws:

jakarta.jms.MessageNotWriteableException - If the message body is read-only.

jakarta.jms.JMSException - If the value could not be written on the stream.

writeBytes

public void writeBytes(byte[] value,
                       int offset,
                       int length)
                throws jakarta.jms.JMSException

API method. Writes a portion of a byte array to the bytes message stream.

Specified by:

writeBytes in interface jakarta.jms.BytesMessage

Parameters:

value - the byte array to be written.

offset - the initial offset within the byte array

length - the number of bytes to use

Throws:

jakarta.jms.MessageNotWriteableException - If the message body is read-only.

jakarta.jms.JMSException - If the value could not be written on the stream.

writeChar

public void writeChar(char value)
               throws jakarta.jms.JMSException

API method. Writes a char to the bytes message stream.

Specified by:

writeChar in interface jakarta.jms.BytesMessage

Parameters:

value - the value to be written.

Throws:

jakarta.jms.MessageNotWriteableException - If the message body is read-only.

jakarta.jms.JMSException - If the value could not be written on the stream.

writeDouble

public void writeDouble(double value)
                 throws jakarta.jms.JMSException

API method. Writes a double to the bytes message stream.

Specified by:

writeDouble in interface jakarta.jms.BytesMessage

Parameters:

value - the value to be written.

Throws:

jakarta.jms.MessageNotWriteableException - If the message body is read-only.

jakarta.jms.JMSException - If the value could not be written on the stream.

writeFloat

public void writeFloat(float value)
                throws jakarta.jms.JMSException

API method. Writes a float to the bytes message stream.

Specified by:

writeFloat in interface jakarta.jms.BytesMessage

Parameters:

value - the value to be written.

Throws:

jakarta.jms.MessageNotWriteableException - If the message body is read-only.

jakarta.jms.JMSException - If the value could not be written on the stream.

writeInt

public void writeInt(int value)
              throws jakarta.jms.JMSException

API method. Writes an int to the bytes message stream.

Specified by:

writeInt in interface jakarta.jms.BytesMessage

Parameters:

value - the value to be written.

Throws:

jakarta.jms.MessageNotWriteableException - If the message body is read-only.

jakarta.jms.JMSException - If the value could not be written on the stream.

writeLong

public void writeLong(long value)
               throws jakarta.jms.JMSException

API method. Writes a long to the bytes message stream.

Specified by:

writeLong in interface jakarta.jms.BytesMessage

Parameters:

value - the value to be written.

Throws:

jakarta.jms.MessageNotWriteableException - If the message body is read-only.

jakarta.jms.JMSException - If the value could not be written on the stream.

writeShort

public void writeShort(short value)
                throws jakarta.jms.JMSException

API method. Writes a short to the bytes message stream.

Specified by:

writeShort in interface jakarta.jms.BytesMessage

Parameters:

value - the value to be written.

Throws:

jakarta.jms.MessageNotWriteableException - If the message body is read-only.

jakarta.jms.JMSException - If the value could not be written on the stream.

writeUTF

public void writeUTF(String value)
              throws jakarta.jms.JMSException

API method. Writes a string to the bytes message stream using UTF-8 encoding in a machine-independent manner.

Specified by:

writeUTF in interface jakarta.jms.BytesMessage

Parameters:

value - the String value to be written.

Throws:

jakarta.jms.MessageNotWriteableException - If the message body is read-only.

jakarta.jms.JMSException - If the value could not be written on the stream.

writeObject

public void writeObject(Object value)
                 throws jakarta.jms.JMSException

API method. 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.

Specified by:

writeObject in interface jakarta.jms.BytesMessage

Parameters:

value - the primitive Java object to be written; it must not be null.

Throws:

jakarta.jms.MessageNotWriteableException - If the message body is read-only.

jakarta.jms.MessageFormatException - If the value type is invalid.

jakarta.jms.JMSException - If the value could not be written on the stream.

readBoolean

public boolean readBoolean()
                    throws jakarta.jms.JMSException

API method. Reads a boolean from the bytes message stream.

Specified by:

readBoolean in interface jakarta.jms.BytesMessage

Returns:

the value read

Throws:

jakarta.jms.MessageNotReadableException - If the message body is write-only.

jakarta.jms.JMSException - If an exception occurs while reading the bytes.

readByte

public byte readByte()
              throws jakarta.jms.JMSException

API method. Reads a byte from the bytes message stream.

Specified by:

readByte in interface jakarta.jms.BytesMessage

Returns:

the value read

Throws:

jakarta.jms.MessageNotReadableException - If the message body is write-only.

jakarta.jms.JMSException - If an exception occurs while reading the bytes.

readUnsignedByte

public int readUnsignedByte()
                     throws jakarta.jms.JMSException

API method. Reads an unsigned byte from the bytes message stream.

Specified by:

readUnsignedByte in interface jakarta.jms.BytesMessage

Returns:

the next byte from the bytes message stream, interpreted as an unsigned 8-bit number.

Throws:

jakarta.jms.MessageNotReadableException - If the message body is write-only.

jakarta.jms.JMSException - If an exception occurs while reading the bytes.

readShort

public short readShort()
                throws jakarta.jms.JMSException

API method. Reads a short from the bytes message stream.

Specified by:

readShort in interface jakarta.jms.BytesMessage

Returns:

the value read

Throws:

jakarta.jms.MessageNotReadableException - If the message body is write-only.

jakarta.jms.JMSException - If an exception occurs while reading the bytes.

readUnsignedShort

public int readUnsignedShort()
                      throws jakarta.jms.JMSException

API method. Reads an unsigned short from the bytes message stream.

Specified by:

readUnsignedShort in interface jakarta.jms.BytesMessage

Returns:

the next two bytes from the bytes message stream, interpreted as an unsigned 16-bit integer.

Throws:

jakarta.jms.MessageNotReadableException - If the message body is write-only.

jakarta.jms.JMSException - If an exception occurs while reading the bytes.

readChar

public char readChar()
              throws jakarta.jms.JMSException

API method. Reads a char from the bytes message stream.

Specified by:

readChar in interface jakarta.jms.BytesMessage

Returns:

the value read

Throws:

jakarta.jms.MessageNotReadableException - If the message body is write-only.

jakarta.jms.JMSException - If an exception occurs while reading the bytes.

readInt

public int readInt()
            throws jakarta.jms.JMSException

API method. Reads an int from the bytes message stream.

Specified by:

readInt in interface jakarta.jms.BytesMessage

Returns:

the value read

Throws:

jakarta.jms.MessageNotReadableException - If the message body is write-only.

jakarta.jms.JMSException - If an exception occurs while reading the bytes.

readLong

public long readLong()
              throws jakarta.jms.JMSException

API method. Reads a long from the bytes message stream.

Specified by:

readLong in interface jakarta.jms.BytesMessage

Returns:

the value read

Throws:

jakarta.jms.MessageNotReadableException - If the message body is write-only.

jakarta.jms.JMSException - If an exception occurs while reading the bytes.

readFloat

public float readFloat()
                throws jakarta.jms.JMSException

API method. Reads a float from the bytes message stream.

Specified by:

readFloat in interface jakarta.jms.BytesMessage

Returns:

the value read

Throws:

jakarta.jms.MessageNotReadableException - If the message body is write-only.

jakarta.jms.JMSException - If an exception occurs while reading the bytes.

readDouble

public double readDouble()
                  throws jakarta.jms.JMSException

API method. Reads a double from the bytes message stream.

Specified by:

readDouble in interface jakarta.jms.BytesMessage

Returns:

the value read

Throws:

jakarta.jms.MessageNotReadableException - If the message body is write-only.

jakarta.jms.JMSException - If an exception occurs while reading the bytes.

readBytes

public int readBytes(byte[] value)
              throws jakarta.jms.JMSException

API method. Reads up to value.length bytes from the bytes message stream. A subsequent call reads the next increment, and so on.

A return value of the total number of bytes read less than the length of the array indicates that there are no more bytes left to be read from the stream. The next read of the stream returns -1.

Specified by:

readBytes in interface jakarta.jms.BytesMessage

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:

jakarta.jms.MessageNotReadableException - If the message body is write-only.

jakarta.jms.JMSException - If an exception occurs while reading the bytes.

readBytes

public int readBytes(byte[] value,
                     int length)
              throws jakarta.jms.JMSException

API method. Reads up to length bytes of the bytes message stream. A subsequent call reads the next increment, and so on.

A return value of the total number of bytes read less than the length parameter indicates 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, or length is greater than the length of the array value, then an IndexOutOfBoundsException is thrown. No bytes will be read from the stream for this exception case.

Specified by:

readBytes in interface jakarta.jms.BytesMessage

Parameters:

value - the buffer into which the data is read.

length - the number of bytes to read; must be less than or equal to value.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:

jakarta.jms.MessageNotReadableException - If the message body is write-only.

jakarta.jms.JMSException - If an exception occurs while reading the bytes.

readUTF

public String readUTF()
               throws jakarta.jms.JMSException

API method. Reads a string that has been encoded using a modified UTF-8 format from the bytes message stream.

Specified by:

readUTF in interface jakarta.jms.BytesMessage

Returns:

a Unicode string from the bytes message stream.

Throws:

jakarta.jms.MessageNotReadableException - If the message body is write-only.

jakarta.jms.JMSException - If an exception occurs while reading the bytes.

reset

public void reset()
           throws jakarta.jms.JMSException

API method. Puts the message body in read-only mode and repositions the stream of bytes to the beginning.

Specified by:

reset in interface jakarta.jms.BytesMessage

Throws:

jakarta.jms.JMSException - If an error occurs while closing the output stream.

prepare

protected void prepare()
                throws jakarta.jms.JMSException

Method actually preparing the message for sending by transfering the local body into the wrapped MOM message.

Overrides:

prepare in class Message

Throws:

jakarta.jms.MessageFormatException - If an error occurs while serializing.

jakarta.jms.JMSException

getBytes

byte[] getBytes()
         throws jakarta.jms.JMSException

Get message content as byte array

Returns:

byte[] the message content as byte array

Throws:

jakarta.jms.JMSException - If an error occurs while closing the output stream.

getBody

public <T> T getBody(Class<T> c)
              throws jakarta.jms.JMSException

Description copied from class: Message

Returns the message body as an object of the specified type. This method may be called on any type of message except for StreamMessage. The message body must be capable of being assigned to the specified type. This means that the specified class or interface must be either the same as, or a superclass or superinterface of, the class of the message body.

Specified by:

getBody in interface jakarta.jms.Message

Overrides:

getBody in class Message

Parameters:

c - The type to which the message body will be assigned. If the message has no body then any type may be specified and null is returned.
If the message is a TextMessage then this parameter must be set to String.class or another type to which a String is assignable.
If the message is a ObjectMessage then parameter must be set to java.io.Serializable.class or another type to which the body is assignable.
If the message is a MapMessage then this parameter must be set to java.util.Map.class (or java.lang.Object.class).
If the message is a BytesMessage then this parameter must be set to byte[].class (or java.lang.Object.class). This method will reset the BytesMessage before and after use.
If the message is a TextMessage, ObjectMessage, MapMessage or BytesMessage and the message has no body, then the above does not apply and this parameter may be set to any type; the returned value will always be null.
If the message is a Message (but not one of its subtypes) then this parameter may be set to any type; the returned value will always be null.

Returns:

the message body

Throws:

jakarta.jms.MessageFormatException - if the message is a StreamMessage, if the message body cannot be assigned to the specified type, or if the message is an ObjectMessage and object deserialization fails.

jakarta.jms.JMSException - if the JMS provider fails to get the message body due to some internal error.

getEffectiveBody

protected <T> T getEffectiveBody(Class<T> c)
                          throws jakarta.jms.JMSException

Description copied from class: Message

Get message body

Overrides:

getEffectiveBody in class Message

Parameters:

c - The type to which the message body will be assigned.

Returns:

message body

Throws:

jakarta.jms.JMSException - if the JMS provider fails to return a value due to some internal error.