Package jakarta.jms

Interface BytesMessage

  • All Superinterfaces:
    Message

    public interface BytesMessage
    extends Message
    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 receiver of the message supplies the interpretation of the bytes.

    The BytesMessage methods are based largely on those found in java.io.DataInputStream and java.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 to BytesMessage.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 BytesMessage is sent asynchronously, the provider must call reset on the BytesMessage passed to the CompletionListener. This means that the CompletionListener can read the message body without needing to call reset. 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.

    Since:
    JMS 1.0
    Version:
    Jakarta Messaging 2.0
    See Also:
    Session.createBytesMessage(), MapMessage, Message, ObjectMessage, StreamMessage, TextMessage
    • 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 a boolean 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 a float 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 a double 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, 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.

        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:
        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 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.
        Parameters:
        value - the boolean 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 a byte to the bytes message stream as a 1-byte value.
        Parameters:
        value - the byte 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 a short to the bytes message stream as two bytes, high byte first.
        Parameters:
        value - the short 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 a char to the bytes message stream as a 2-byte value, high byte first.
        Parameters:
        value - the char 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 an int to the bytes message stream as four bytes, high byte first.
        Parameters:
        value - the int 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 a long to the bytes message stream as eight bytes, high byte first.
        Parameters:
        value - the long 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 the float argument to an int using the floatToIntBits method in class Float, and then writes that int value to the bytes message stream as a 4-byte quantity, high byte first.
        Parameters:
        value - the float 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 the double argument to a long using the doubleToLongBits method in class Double, and then writes that long value to the bytes message stream as an 8-byte quantity, high byte first.
        Parameters:
        value - the double 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 - the String 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 written
        offset - the initial offset within the byte array
        length - 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 parameter value 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.