javax.jms.BytesMessage Maven / Gradle / Ivy
Show all versions of ow2-jms-2.0-spec Show documentation
/**
* Copyright 2013 ScalAgent Distributed Technologies
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
* ---------------------------------------------------------------------
* $Id: BytesMessage.java 6347 2013-03-13 08:52:02Z tachker $
* ---------------------------------------------------------------------
*/
package javax.jms;
/**
* A {@code BytesMessage} object is used to send a message containing an a
* stream of bytes which can be compressed. It inherits from the {@code Message}
* interface and set to message body this stream. The receiver of the message
* has to supply the interpretation of the bytes.
*
*
* The {@code BytesMessage} methods are mainly wider than those found in
* {@code java.io.DataInputStream} and {@code 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)).
*
* 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.
*
* @see javax.jms.Session#createBytesMessage()
* @see javax.jms.MapMessage
* @see javax.jms.Message
* @see javax.jms.ObjectMessage
* @see javax.jms.StreamMessage
* @see javax.jms.TextMessage
*
* @version JMS 2.0
* @since JMS 1.0
*
*/
public interface BytesMessage extends Message {
/**
* 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.
*
* @return the number of bytes in the message's body.
*
* @exception MessageNotReadableException
* If the message is WRITE-ONLY.
*
* @since JMS 1.0
*/
long getBodyLength() throws JMSException;
/**
* Reads a {@code boolean} from the bytes message body.
*
* @return the {@code boolean} value read
*
* @exception JMSException
* if the JMS provider fails to read the message due to some
* internal error.
* @exception MessageEOFException
* if unexpected end of bytes stream has been reached.
* @exception MessageNotReadableException
* if the message is in write-only mode.
*/
boolean readBoolean() throws JMSException;
/**
* Reads a signed 8-bit value from message body.
*
* @return the next byte from the bytes message stream as a signed 8-bit
* {@code byte}
*
* @exception JMSException
* if the JMS provider fails to read the message due to some
* internal error.
* @exception MessageEOFException
* if unexpected end of bytes stream has been reached.
* @exception MessageNotReadableException
* if the message is in write-only mode.
*/
byte readByte() throws JMSException;
/**
* Reads an unsigned 8-bit number from message body.
*
* @return the next byte from the bytes message stream, treated as an unsigned
* 8-bit number
*
* @exception JMSException
* if the JMS provider fails to read the message due to some
* internal error.
* @exception MessageEOFException
* if unexpected end of bytes stream has been reached.
* @exception MessageNotReadableException
* if the message is in write-only mode.
*/
int readUnsignedByte() throws JMSException;
/**
* Reads a signed 16-bit number from message body.
*
* @return the next two bytes from the bytes message stream, read as a signed
* 16-bit number
*
* @exception JMSException
* if the JMS provider fails to read the message due to some
* internal error.
* @exception MessageEOFException
* if unexpected end of bytes stream has been reached.
* @exception MessageNotReadableException
* if the message is in write-only mode.
*/
short readShort() throws JMSException;
/**
* Reads an unsigned 16-bit number from the message body.
*
* @return the next two bytes from the bytes message stream, read as an
* unsigned 16-bit integer
*
* @exception JMSException
* if the JMS provider fails to read the message due to some
* internal error.
* @exception MessageEOFException
* if unexpected end of body has been reached.
* @exception MessageNotReadableException
* if the message is in write-only mode.
*/
int readUnsignedShort() throws JMSException;
/**
* Reads a Unicode character value from the message body.
*
* @return the next two bytes from the bytes message as character
*
* @exception JMSException
* if the JMS provider fails to read the message due to some
* internal error.
* @exception MessageEOFException
* if unexpected end of bytes stream has been reached.
* @exception MessageNotReadableException
* if the message is in write-only mode.
*/
char readChar() throws JMSException;
/**
* Reads a signed 32-bit integer from message body.
*
* @return the next four bytes from message body, read as an {@code int}
*
* @exception JMSException
* if the JMS provider fails to read the message due to some
* internal error.
* @exception MessageEOFException
* if unexpected end of bytes stream has been reached.
* @exception MessageNotReadableException
* if the message is in write-only mode.
*/
int readInt() throws JMSException;
/**
* Reads a signed 64-bit integer from message body.
*
* @return the next eight bytes from message body, read as a {@code long}
*
* @exception JMSException
* if the JMS provider fails to read the message due to some
* internal error.
* @exception MessageEOFException
* if unexpected end of bytes stream has been reached.
* @exception MessageNotReadableException
* if the message is in write-only mode.
*/
long readLong() throws JMSException;
/**
* Reads a {@code float} from message body .
*
* @return the next four bytes from message body, read as a {@code float}
*
* @exception JMSException
* if the JMS provider fails to read the message due to some
* internal error.
* @exception MessageEOFException
* if unexpected end of bytes stream has been reached.
* @exception MessageNotReadableException
* if the message is in write-only mode.
*/
float readFloat() throws JMSException;
/**
* Reads a {@code double} from message body.
*
* @return the next eight bytes from message body, read as a {@code double}
*
* @exception JMSException
* if the JMS provider fails to read the message due to some
* internal error.
* @exception MessageEOFException
* if unexpected end of bytes stream has been reached.
* @exception MessageNotReadableException
* if the message is in write-only mode.
*/
double readDouble() throws JMSException;
/**
* Reads a string that has been encoded using a modified UTF-8 format from
* message body.
*
*
* @return a Unicode string from the bytes message stream
*
* @exception JMSException
* if the JMS provider fails to read the message due to some
* internal error.
* @exception MessageEOFException
* if unexpected end of bytes stream has been reached.
* @exception MessageNotReadableException
* if the message is in write-only mode.
*/
String readUTF() throws JMSException;
/**
* Reads a byte array from message body.
*
*
* @param value
* the buffer into which the data is read
*
* @return 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
*
* @exception JMSException
* if the JMS provider fails to read the message due to some
* internal error.
* @exception MessageNotReadableException
* if the message is in write-only mode.
*/
int readBytes(byte[] value) throws JMSException;
/**
* Reads a portion of message body.
*
*
* If the length of array {@code 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.
*
* @param value
* the buffer into which the data is read
* @param length
* the number of bytes to read; must be less than or equal to
* {@code value.length}
*
* @return 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
*
* @exception JMSException
* if the JMS provider fails to read the message due to some
* internal error.
* @exception MessageNotReadableException
* if the message is in write-only mode.
*/
int readBytes(byte[] value, int length) throws JMSException;
/**
* Writes a {@code boolean} into message body as a 1-byte value. The value
* {@code true} is written as the value {@code (byte)1}; the value
* {@code false} is written as the value {@code (byte)0}.
*
* @param value
* the {@code boolean} value to be written
*
* @exception JMSException
* if the JMS provider fails to write the message due to some
* internal error.
* @exception MessageNotWriteableException
* if the message is in read-only mode.
*/
void writeBoolean(boolean value) throws JMSException;
/**
* Writes a {@code byte} into message body as a 1-byte value.
*
* @param value
* the {@code byte} value to be written
*
* @exception JMSException
* if the JMS provider fails to write the message due to some
* internal error.
* @exception MessageNotWriteableException
* if the message is in read-only mode.
*/
void writeByte(byte value) throws JMSException;
/**
* Writes a {@code short} into message body as two bytes, high byte first.
*
* @param value
* the {@code short} to be written
*
* @exception JMSException
* if the JMS provider fails to write the message due to some
* internal error.
* @exception MessageNotWriteableException
* if the message is in read-only mode.
*/
void writeShort(short value) throws JMSException;
/**
* Writes a {@code char} into message body a 2-byte value, high byte first.
*
* @param value
* the {@code char} value to be written
*
* @exception JMSException
* if the JMS provider fails to write the message due to some
* internal error.
* @exception MessageNotWriteableException
* if the message is in read-only mode.
*/
void writeChar(char value) throws JMSException;
/**
* Writes an {@code int} into message body as four bytes, high byte first.
*
* @param value
* the {@code int} to be written
*
* @exception JMSException
* if the JMS provider fails to write the message due to some
* internal error.
* @exception MessageNotWriteableException
* if the message is in read-only mode.
*/
void writeInt(int value) throws JMSException;
/**
* Writes a {@code long}into message body as eight bytes, high byte first.
*
* @param value
* the {@code long} to be written
*
* @exception JMSException
* if the JMS provider fails to write the message due to some
* internal error.
* @exception MessageNotWriteableException
* if the message is in read-only mode.
*/
void writeLong(long value) throws JMSException;
/**
* Writes a {@code float} by converting the {@code float} argument to an
* {@code int} into message body as a 4-byte quantity, high byte first.
*
* @param value
* the {@code float} value to be written
*
* @exception JMSException
* if the JMS provider fails to write the message due to some
* internal error.
* @exception MessageNotWriteableException
* if the message is in read-only mode.
*/
void writeFloat(float value) throws JMSException;
/**
* Writes a code by converting {@code double} argument to a {@code long} into
* message body as an 8-byte quantity, high byte first.
*
* @param value
* the {@code double} value to be written
*
* @exception JMSException
* if the JMS provider fails to write the message due to some
* internal error.
* @exception MessageNotWriteableException
* if the message is in read-only mode.
*/
void writeDouble(double value) throws JMSException;
/**
* Writes a string into message body using UTF-8 encoding in a
* machine-independent manner.
*
* @param value
* the {@code String} value to be written
*
* @exception JMSException
* if the JMS provider fails to write the message due to some
* internal error.
* @exception MessageNotWriteableException
* if the message is in read-only mode.
*/
void writeUTF(String value) throws JMSException;
/**
* Writes a byte array into message body.
*
* @param value
* the byte array to be written
*
* @exception JMSException
* if the JMS provider fails to write the message due to some
* internal error.
* @exception MessageNotWriteableException
* if the message is in read-only mode.
*/
void writeBytes(byte[] value) throws JMSException;
/**
* Writes a portion of a byte array to the bytes message stream.
*
* @param value
* the byte array value to be written
* @param offset
* the initial offset within the byte array
* @param length
* the number of bytes to use
*
* @exception JMSException
* if the JMS provider fails to write the message due to some
* internal error.
* @exception MessageNotWriteableException
* if the message is in read-only mode.
*/
void writeBytes(byte[] value, int offset, int length) throws JMSException;
/**
* Writes an array of bytes into message body.
*
*
* This method works only for the objectified primitive object types, and byte
* arrays.
*
* @param value
* the object in the Java programming language ("Java object") to be
* written; it must not be null
*
* @exception JMSException
* if the JMS provider fails to write the message due to some
* internal error.
* @exception MessageFormatException
* if the object is of an invalid type.
* @exception MessageNotWriteableException
* if the message is in read-only mode.
* @exception java.lang.NullPointerException
* if the parameter {@code value} is null.
*/
void writeObject(Object value) throws JMSException;
/**
* Puts the message body in read-only mode and repositions the pointer at the
* beginning.
*
* @exception JMSException
* if the JMS provider fails to reset the message due to some
* internal error.
* @exception MessageFormatException
* if the message has an invalid format.
*/
void reset() throws JMSException;
}