Package org.objectweb.joram.client.jms

Class BytesMessage

  • All Implemented Interfaces:
    BytesMessage, Message
    public final class BytesMessage
extends Message
implements BytesMessage
    Implements the javax.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 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,
             org.objectweb.joram.shared.messages.Message momMsg)
      throws 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:
        JMSException - if an error has occurred

    • Method Detail

      • getBodyLength

        public long getBodyLength()
                   throws 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 BytesMessage
        Returns:
        the number of bytes in the message's body.
        Throws:
        MessageNotReadableException - If the message is WRITE-ONLY.
        JMSException

      • clearBody

        public void clearBody()
               throws 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 Message
        Overrides:
        clearBody in class Message
        Throws:
        JMSException - In case of an error while closing the output or input streams.

      • writeBoolean

        public void writeBoolean​(boolean value)
                  throws 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 BytesMessage
        Parameters:
        value - the value to be written.
        Throws:
        MessageNotWriteableException - If the message body is read-only.
        JMSException - If the value could not be written on the stream.

      • writeBytes

        public void writeBytes​(byte[] value)
                throws JMSException
        API method. Writes a byte array to the bytes message stream.
        Specified by:
        writeBytes in interface BytesMessage
        Parameters:
        value - the byte array to be written.
        Throws:
        MessageNotWriteableException - If the message body is read-only.
        JMSException - If the value could not be written on the stream.

      • writeBytes

        public void writeBytes​(byte[] value,
                       int offset,
                       int length)
                throws JMSException
        API method. Writes a portion of a byte array to the bytes message stream.
        Specified by:
        writeBytes in interface 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:
        MessageNotWriteableException - If the message body is read-only.
        JMSException - If the value could not be written on the stream.

      • writeUTF

        public void writeUTF​(String value)
              throws 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 BytesMessage
        Parameters:
        value - the String value to be written.
        Throws:
        MessageNotWriteableException - If the message body is read-only.
        JMSException - If the value could not be written on the stream.

      • writeObject

        public void writeObject​(Object value)
                 throws 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 BytesMessage
        Parameters:
        value - the primitive Java object to be written; it must not be null.
        Throws:
        MessageNotWriteableException - If the message body is read-only.
        MessageFormatException - If the value type is invalid.
        JMSException - If the value could not be written on the stream.

      • readUnsignedByte

        public int readUnsignedByte()
                     throws JMSException
        API method. Reads an unsigned byte from the bytes message stream.
        Specified by:
        readUnsignedByte in interface BytesMessage
        Returns:
        the next byte from the bytes message stream, interpreted as an unsigned 8-bit number.
        Throws:
        MessageNotReadableException - If the message body is write-only.
        JMSException - If an exception occurs while reading the bytes.

      • readUnsignedShort

        public int readUnsignedShort()
                      throws JMSException
        API method. Reads an unsigned short from the bytes message stream.
        Specified by:
        readUnsignedShort in interface BytesMessage
        Returns:
        the next two bytes from the bytes message stream, interpreted as an unsigned 16-bit integer.
        Throws:
        MessageNotReadableException - If the message body is write-only.
        JMSException - If an exception occurs while reading the bytes.

      • readBytes

        public int readBytes​(byte[] value)
              throws 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 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:
        MessageNotReadableException - If the message body is write-only.
        JMSException - If an exception occurs while reading the bytes.

      • readBytes

        public int readBytes​(byte[] value,
                     int length)
              throws 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 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:
        MessageNotReadableException - If the message body is write-only.
        JMSException - If an exception occurs while reading the bytes.

      • readUTF

        public String readUTF()
               throws 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 BytesMessage
        Returns:
        a Unicode string from the bytes message stream.
        Throws:
        MessageNotReadableException - If the message body is write-only.
        JMSException - If an exception occurs while reading the bytes.

      • reset

        public void reset()
           throws 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 BytesMessage
        Throws:
        JMSException - If an error occurs while closing the output stream.

      • getBytes

        byte[] getBytes()
         throws JMSException
        Get message content as byte array
        Returns:
        byte[] the message content as byte array
        Throws:
        JMSException - If an error occurs while closing the output stream.

      • getBody

        public <T> T getBody​(Class<T> c)
              throws 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 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:
        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.
        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 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:
        JMSException - if the JMS provider fails to return a value due to some internal error.