| 
 | J2EE1.4 SDK | |||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
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 JMS 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. 
 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.
Session.createBytesMessage(), 
MapMessage, 
Message, 
ObjectMessage, 
StreamMessage, 
TextMessage| Field Summary | 
| Fields inherited from interface javax.jms.Message | 
| DEFAULT_DELIVERY_MODE, DEFAULT_PRIORITY, DEFAULT_TIME_TO_LIVE | 
| Method Summary | |
|  long | getBodyLength()Gets the number of bytes of the message body when the message is in read-only mode. | 
|  boolean | readBoolean()Reads a booleanfrom 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 a doublefrom the bytes message stream. | 
|  float | readFloat()Reads a floatfrom 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. | 
|  java.lang.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 a booleanto the bytes message stream as a 1-byte 
 value. | 
|  void | writeByte(byte value)Writes a byteto 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 a charto the bytes message stream as a 2-byte
 value, high byte first. | 
|  void | writeDouble(double value)Converts the doubleargument to alongusing 
 thedoubleToLongBitsmethod in classDouble,
 and then writes thatlongvalue to the bytes message
 stream as an 8-byte quantity, high byte first. | 
|  void | writeFloat(float value)Converts the floatargument to anintusing 
 thefloatToIntBitsmethod in classFloat,
 and then writes thatintvalue to the bytes message
 stream as a 4-byte quantity, high byte first. | 
|  void | writeInt(int value)Writes an intto the bytes message stream as four bytes, 
 high byte first. | 
|  void | writeLong(long value)Writes a longto the bytes message stream as eight bytes, 
 high byte first. | 
|  void | writeObject(java.lang.Object value)Writes an object to the bytes message stream. | 
|  void | writeShort(short value)Writes a shortto the bytes message stream as two bytes,
 high byte first. | 
|  void | writeUTF(java.lang.String value)Writes a string to the bytes message stream using UTF-8 encoding in a machine-independent manner. | 
| Method Detail | 
public long getBodyLength()
                   throws JMSException
JMSException - if the JMS provider fails to read the message 
                         due to some internal error.
MessageNotReadableException - if the message is in write-only
                         mode.
public boolean readBoolean()
                    throws JMSException
boolean from the bytes message stream.
boolean value read
JMSException - if the JMS 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.
public byte readByte()
              throws JMSException
byte
JMSException - if the JMS 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.
public int readUnsignedByte()
                     throws JMSException
JMSException - if the JMS 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.
public short readShort()
                throws JMSException
JMSException - if the JMS 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.
public int readUnsignedShort()
                      throws JMSException
JMSException - if the JMS 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.
public char readChar()
              throws JMSException
JMSException - if the JMS 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.
public int readInt()
            throws JMSException
int
JMSException - if the JMS 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.
public long readLong()
              throws JMSException
long
JMSException - if the JMS 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.
public float readFloat()
                throws JMSException
float from the bytes message stream.
float
JMSException - if the JMS 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.
public double readDouble()
                  throws JMSException
double from the bytes message stream.
double
JMSException - if the JMS 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.
public java.lang.String readUTF()
                         throws JMSException
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.
JMSException - if the JMS 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.
public int readBytes(byte[] value)
              throws JMSException
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.
value - the buffer into which the data is read
JMSException - if the JMS provider fails to read the message 
                         due to some internal error.
MessageNotReadableException - if the message is in write-only 
                                        mode.
public int readBytes(byte[] value,
                     int length)
              throws JMSException
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.
value - the buffer into which the data is readlength - the number of bytes to read; must be less than or equal to
        value.length
JMSException - if the JMS provider fails to read the message 
                         due to some internal error.
MessageNotReadableException - if the message is in write-only 
                                        mode.
public void writeBoolean(boolean value)
                  throws JMSException
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.
value - the boolean value to be written
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void writeByte(byte value)
               throws JMSException
byte to the bytes message stream as a 1-byte 
 value.
value - the byte value to be written
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void writeShort(short value)
                throws JMSException
short to the bytes message stream as two bytes,
 high byte first.
value - the short to be written
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void writeChar(char value)
               throws JMSException
char to the bytes message stream as a 2-byte
 value, high byte first.
value - the char value to be written
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void writeInt(int value)
              throws JMSException
int to the bytes message stream as four bytes, 
 high byte first.
value - the int to be written
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void writeLong(long value)
               throws JMSException
long to the bytes message stream as eight bytes, 
 high byte first.
value - the long to be written
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void writeFloat(float value)
                throws JMSException
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.
value - the float value to be written
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void writeDouble(double value)
                 throws JMSException
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.
value - the double value to be written
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void writeUTF(java.lang.String value)
              throws JMSException
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.
value - the String value to be written
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void writeBytes(byte[] value)
                throws JMSException
value - the byte array to be written
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void writeBytes(byte[] value,
                       int offset,
                       int length)
                throws JMSException
value - the byte array value to be writtenoffset - the initial offset within the byte arraylength - the number of bytes to use
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void writeObject(java.lang.Object value)
                 throws JMSException
This method works only for the objectified primitive
 object types (Integer, Double, 
 Long ...), String objects, and byte 
 arrays.
value - the object in the Java programming language ("Java 
              object") to be written; it must not be null
JMSException - if the JMS 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.
java.lang.NullPointerException - if the parameter 
                                           value is null.
public void reset()
           throws JMSException
JMSException - if the JMS provider fails to reset the message
                         due to some internal error.
MessageFormatException - if the message has an invalid
                         format.| 
 | J2EE1.4 SDK | |||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
Copyright 2003 Sun Microsystems, Inc. All rights reserved.