bytesmessage.java

JAVA 消息服务(JMS)定义了Java 中访问消息中间件的接口,里边有实现消息服务的基础源码,可以开发高级应用

/*
 * @(#)BytesMessage.java	1.31 02/04/09
 *
 * Copyright 1997-2002 Sun Microsystems, Inc. All Rights Reserved.
 *
 *  SUN PROPRIETARY/CONFIDENTIAL.
 * This software is the proprietary information of Sun Microsystems, Inc.  
 * Use is subject to license terms.
 * 
 */

 
package javax.jms;

import java.io.InputStream;
import java.io.OutputStream;

/** A <CODE>BytesMessage</CODE> object is used to send a message containing a 
  * stream of uninterpreted bytes. It inherits from the <CODE>Message</CODE> 
  * interface and adds a bytes
  * message body. The receiver of the message supplies the interpretation
  * of the bytes.
  *
  * <P>The <CODE>BytesMessage</CODE> methods are based largely on those found in
  * <CODE>java.io.DataInputStream</CODE> and
  * <CODE>java.io.DataOutputStream</CODE>.
  *
  * <P>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.
  *
  * <P>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.
  *
  * <P>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 <CODE>BytesMessage.writeInt(6)</CODE> is
  * equivalent to <CODE>BytesMessage.writeObject(new Integer(6))</CODE>.
  * 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.
  *
  * <P>When the message is first created, and when <CODE>clearBody</CODE>
  * is called, the body of the message is in write-only mode. After the 
  * first call to <CODE>reset</CODE> 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 
  * <CODE>reset</CODE> so that the message body is in read-only mode for the client.
  *
  * <P>If <CODE>clearBody</CODE> is called on a message in read-only mode, 
  * the message body is cleared and the message is in write-only mode.
  *
  * <P>If a client attempts to read a message in write-only mode, a 
  * <CODE>MessageNotReadableException</CODE> is thrown.
  *
  * <P>If a client attempts to write a message in read-only mode, a 
  * <CODE>MessageNotWriteableException</CODE> is thrown.
  *
  * @version     1.1 April 2, 2002
  * @author      Mark Hapner
  * @author      Rich Burridge
  * @author      Kate Stout
  *
  * @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
  */

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 number of bytes in the message 
       * @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.
       * @since 1.1 
       */
       
      long getBodyLength() throws JMSException;

    /** Reads a <code>boolean</code> from the bytes message stream.
      *
      * @return the <code>boolean</code> 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 the bytes message stream.
      *
      * @return the next byte from the bytes message stream as a signed 8-bit
      * <code>byte</code>
      *
      * @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 the bytes message stream.
      *  
      * @return the next byte from the bytes message stream, interpreted 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 the bytes message stream.
      *
      * @return the next two bytes from the bytes message stream, interpreted 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 bytes message stream.
      *  
      * @return the next two bytes from the bytes message stream, interpreted 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 bytes stream has 
      *                                been reached.
      * @exception MessageNotReadableException if the message is in write-only 
      *                                        mode.
      */ 
 
    int
    readUnsignedShort() throws JMSException;


    /** Reads a Unicode character value from the bytes message stream.
      *
      * @return the next two bytes from the bytes message stream as a Unicode
      * 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 the bytes message stream.
      *
      * @return the next four bytes from the bytes message stream, interpreted
      * as an <code>int</code>
      *
      * @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 the bytes message stream.
      *
      * @return the next eight bytes from the bytes message stream, interpreted
      * as a <code>long</code>
      *
      * @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</code> from the bytes message stream.
      *
      * @return the next four bytes from the bytes message stream, interpreted
      * as a <code>float</code>
      *
      * @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</code> from the bytes message stream.
      *
      * @return the next eight bytes from the bytes message stream, interpreted
      * as a <code>double</code>
      *
      * @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 the bytes message stream.
      *
      * <P>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.
      *
      * @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;