1. /*

  2.  * Copyright 2002 Sun Microsystems, Inc. All rights reserved.

  3.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  4.  */

  5. 

  6. package javax.jms;

  7. 

  8. /** A <CODE>StreamMessage</CODE> object is used to send a stream of primitive

  9.   * types in the Java programming language. It is filled and read sequentially.

  10.   * It inherits from the <CODE>Message</CODE> interface

  11.   * and adds a stream message body. Its methods are based largely on those

  12.   * found in <CODE>java.io.DataInputStream</CODE> and

  13.   * <CODE>java.io.DataOutputStream</CODE>.

  14.   *

  15.   * <P>The primitive types can be read or written explicitly using methods

  16.   * for each type. They may also be read or written generically as objects.

  17.   * For instance, a call to <CODE>StreamMessage.writeInt(6)</CODE> is

  18.   * equivalent to <CODE>StreamMessage.writeObject(new Integer(6))</CODE>.

  19.   * Both forms are provided, because the explicit form is convenient for

  20.   * static programming, and the object form is needed when types are not known

  21.   * at compile time.

  22.   *

  23.   * <P>When the message is first created, and when <CODE>clearBody</CODE>

  24.   * is called, the body of the message is in write-only mode. After the 

  25.   * first call to <CODE>reset</CODE> has been made, the message body is in 

  26.   * read-only mode. 

  27.   * After a message has been sent, the client that sent it can retain and 

  28.   * modify it without affecting the message that has been sent. The same message

  29.   * object can be sent multiple times.

  30.   * When a message has been received, the provider has called 

  31.   * <CODE>reset</CODE> so that the message body is in read-only mode for the client.

  32.   * 

  33.   * <P>If <CODE>clearBody</CODE> is called on a message in read-only mode, 

  34.   * the message body is cleared and the message body is in write-only mode.

  35.   * 

  36.   * <P>If a client attempts to read a message in write-only mode, a 

  37.   * <CODE>MessageNotReadableException</CODE> is thrown.

  38.   * 

  39.   * <P>If a client attempts to write a message in read-only mode, a 

  40.   * <CODE>MessageNotWriteableException</CODE> is thrown.

  41.   *

  42.   * <P><CODE>StreamMessage</CODE> objects support the following conversion 

  43.   * table. The marked cases must be supported. The unmarked cases must throw a 

  44.   * <CODE>JMSException</CODE>. The <CODE>String</CODE>-to-primitive conversions 

  45.   * may throw a runtime exception if the primitive's <CODE>valueOf()</CODE> 

  46.   * method does not accept it as a valid <CODE>String</CODE> representation of 

  47.   * the primitive.

  48.   *

  49.   * <P>A value written as the row type can be read as the column type.

  50.   *

  51.   * <PRE>

  52.   * |        | boolean byte short char int long float double String byte[]

  53.   * |----------------------------------------------------------------------

  54.   * |boolean |    X                                            X

  55.   * |byte    |          X     X         X   X                  X   

  56.   * |short   |                X         X   X                  X   

  57.   * |char    |                     X                           X

  58.   * |int     |                          X   X                  X   

  59.   * |long    |                              X                  X   

  60.   * |float   |                                    X     X      X   

  61.   * |double  |                                          X      X   

  62.   * |String  |    X     X     X         X   X     X     X      X   

  63.   * |byte[]  |                                                        X

  64.   * |----------------------------------------------------------------------

  65.   * </PRE>

  66.   *

  67.   * <P>Attempting to read a null value as a primitive type must be treated

  68.   * as calling the primitive's corresponding <code>valueOf(String)</code> 

  69.   * conversion method with a null value. Since <code>char</code> does not 

  70.   * support a <code>String</code> conversion, attempting to read a null value 

  71.   * as a <code>char</code> must throw a <code>NullPointerException</code>.

  72.   *

  73.   * @version     1.0 - 6 August 1998

  74.   * @author      Mark Hapner

  75.   * @author      Rich Burridge

  76.   *

  77.   * @see         javax.jms.Session#createStreamMessage()

  78.   * @see         javax.jms.BytesMessage

  79.   * @see         javax.jms.MapMessage

  80.   * @see         javax.jms.Message

  81.   * @see         javax.jms.ObjectMessage

  82.   * @see         javax.jms.TextMessage

  83.   */

  84. 

  85. public interface StreamMessage extends Message {

  86. 

  87. 

  88.     /** Reads a <code>boolean</code> from the stream message.

  89.       *

  90.       * @return the <code>boolean</code> value read

  91.       *

  92.       * @exception JMSException if the JMS provider fails to read the message

  93.       *                         due to some internal error.

  94.       * @exception MessageEOFException if unexpected end of message stream has

  95.       *                                been reached.     

  96.       * @exception MessageFormatException if this type conversion is invalid.

  97.       * @exception MessageNotReadableException if the message is in write-only 

  98.       *                                        mode.

  99.       */

  100. 

  101.     boolean 

  102.     readBoolean() throws JMSException;

  103. 

  104. 

  105.     /** Reads a <code>byte</code> value from the stream message.

  106.       *

  107.       * @return the next byte from the stream message as a 8-bit

  108.       * <code>byte</code>

  109.       *

  110.       * @exception JMSException if the JMS provider fails to read the message

  111.       *                         due to some internal error.

  112.       * @exception MessageEOFException if unexpected end of message stream has

  113.       *                                been reached.     

  114.       * @exception MessageFormatException if this type conversion is invalid.

  115.       * @exception MessageNotReadableException if the message is in write-only 

  116.       *                                        mode.

  117.       */ 

  118. 

  119.     byte 

  120.     readByte() throws JMSException;

  121. 

  122. 

  123.     /** Reads a 16-bit integer from the stream message.

  124.       *

  125.       * @return a 16-bit integer from the stream message

  126.       *

  127.       * @exception JMSException if the JMS provider fails to read the message

  128.       *                         due to some internal error.

  129.       * @exception MessageEOFException if unexpected end of message stream has

  130.       *                                been reached.     

  131.       * @exception MessageFormatException if this type conversion is invalid.

  132.       * @exception MessageNotReadableException if the message is in write-only 

  133.       *                                        mode.

  134.       */ 

  135. 

  136.     short 

  137.     readShort() throws JMSException;

  138. 

  139. 

  140.     /** Reads a Unicode character value from the stream message.

  141.       *

  142.       * @return a Unicode character from the stream message

  143.       *

  144.       * @exception JMSException if the JMS provider fails to read the message

  145.       *                         due to some internal error.

  146.       * @exception MessageEOFException if unexpected end of message stream has

  147.       *                                been reached.     

  148.       * @exception MessageFormatException if this type conversion is invalid      

  149.       * @exception MessageNotReadableException if the message is in write-only 

  150.       *                                        mode.

  151.       */ 

  152. 

  153.     char 

  154.     readChar() throws JMSException;

  155. 

  156. 

  157.     /** Reads a 32-bit integer from the stream message.

  158.       *

  159.       * @return a 32-bit integer value from the stream message, interpreted

  160.       * as an <code>int</code>

  161.       *

  162.       * @exception JMSException if the JMS provider fails to read the message

  163.       *                         due to some internal error.

  164.       * @exception MessageEOFException if unexpected end of message stream has

  165.       *                                been reached.     

  166.       * @exception MessageFormatException if this type conversion is invalid.

  167.       * @exception MessageNotReadableException if the message is in write-only 

  168.       *                                        mode.

  169.       */ 

  170. 

  171.     int 

  172.     readInt() throws JMSException;

  173. 

  174. 

  175.     /** Reads a 64-bit integer from the stream message.

  176.       *

  177.       * @return a 64-bit integer value from the stream message, interpreted as

  178.       * a <code>long</code>

  179.       *

  180.       * @exception JMSException if the JMS provider fails to read the message

  181.       *                         due to some internal error.

  182.       * @exception MessageEOFException if unexpected end of message stream has

  183.       *                                been reached.     

  184.       * @exception MessageFormatException if this type conversion is invalid.

  185.       * @exception MessageNotReadableException if the message is in write-only 

  186.       *                                        mode.

  187.       */ 

  188. 

  189.     long 

  190.     readLong() throws JMSException;

  191. 

  192. 

  193.     /** Reads a <code>float</code> from the stream message.

  194.       *

  195.       * @return a <code>float</code> value from the stream message

  196.       *

  197.       * @exception JMSException if the JMS provider fails to read the message

  198.       *                         due to some internal error.

  199.       * @exception MessageEOFException if unexpected end of message stream has

  200.       *                                been reached.     

  201.       * @exception MessageFormatException if this type conversion is invalid.

  202.       * @exception MessageNotReadableException if the message is in write-only 

  203.       *                                        mode.

  204.       */ 

  205. 

  206.     float 

  207.     readFloat() throws JMSException;

  208. 

  209. 

  210.     /** Reads a <code>double</code> from the stream message.

  211.       *

  212.       * @return a <code>double</code> value from the stream message

  213.       *

  214.       * @exception JMSException if the JMS provider fails to read the message

  215.       *                         due to some internal error.

  216.       * @exception MessageEOFException if unexpected end of message stream has

  217.       *                                been reached.     

  218.       * @exception MessageFormatException if this type conversion is invalid.

  219.       * @exception MessageNotReadableException if the message is in write-only 

  220.       *                                        mode.

  221.       */ 

  222. 

  223.     double 

  224.     readDouble() throws JMSException;

  225. 

  226. 

  227.     /** Reads a <CODE>String</CODE> from the stream message.

  228.       *

  229.       * @return a Unicode string from the stream message

  230.       *

  231.       * @exception JMSException if the JMS provider fails to read the message

  232.       *                         due to some internal error.

  233.       * @exception MessageEOFException if unexpected end of message stream has

  234.       *                                been reached.     

  235.       * @exception MessageFormatException if this type conversion is invalid.

  236.       * @exception MessageNotReadableException if the message is in write-only 

  237.       *                                        mode.

  238.       */ 

  239. 

  240.     String 

  241.     readString() throws JMSException;

  242. 

  243. 

  244.     /** Reads a byte array field from the stream message into the 

  245.       * specified <CODE>byte[]</CODE> object (the read buffer). 

  246.       * 

  247.       * <P>To read the field value, <CODE>readBytes</CODE> should be 

  248.       * successively called 

  249.       * until it returns a value less than the length of the read buffer.

  250.       * The value of the bytes in the buffer following the last byte 

  251.       * read is undefined.

  252.       * 

  253.       * <P>If <CODE>readBytes</CODE> returns a value equal to the length of the 

  254.       * buffer, a subsequent <CODE>readBytes</CODE> call must be made. If there 

  255.       * are no more bytes to be read, this call returns -1.

  256.       * 

  257.       * <P>If the byte array field value is null, <CODE>readBytes</CODE> 

  258.       * returns -1.

  259.       *

  260.       * <P>If the byte array field value is empty, <CODE>readBytes</CODE> 

  261.       * returns 0.

  262.       * 

  263.       * <P>Once the first <CODE>readBytes</CODE> call on a <CODE>byte[]</CODE>

  264.       * field value has been made,

  265.       * the full value of the field must be read before it is valid to read 

  266.       * the next field. An attempt to read the next field before that has 

  267.       * been done will throw a <CODE>MessageFormatException</CODE>.

  268.       * 

  269.       * <P>To read the byte field value into a new <CODE>byte[]</CODE> object, 

  270.       * use the <CODE>readObject</CODE> method.

  271.       *

  272.       * @param value the buffer into which the data is read

  273.       *

  274.       * @return the total number of bytes read into the buffer, or -1 if 

  275.       * there is no more data because the end of the byte field has been 

  276.       * reached

  277.       *

  278.       * @exception JMSException if the JMS provider fails to read the message

  279.       *                         due to some internal error.

  280.       * @exception MessageEOFException if unexpected end of message stream has

  281.       *                                been reached.     

  282.       * @exception MessageFormatException if this type conversion is invalid.

  283.       * @exception MessageNotReadableException if the message is in write-only 

  284.       *                                        mode.

  285.       * 

  286.       * @see #readObject()

  287.       */ 

  288. 

  289.     int

  290.     readBytes(byte[] value) throws JMSException;

  291. 

  292. 

  293.     /** Reads an object from the stream message.

  294.       *

  295.       * <P>This method can be used to return, in objectified format,

  296.       * an object in the Java programming language ("Java object") that has 

  297.       * been written to the stream with the equivalent

  298.       * <CODE>writeObject</CODE> method call, or its equivalent primitive

  299.       * <CODE>write<I>type</I></CODE> method.

  300.       *  

  301.       * <P>Note that byte values are returned as <CODE>byte[]</CODE>, not 

  302.       * <CODE>Byte[]</CODE>.

  303.       *

  304.       * <P>An attempt to call <CODE>readObject</CODE> to read a byte field 

  305.       * value into a new <CODE>byte[]</CODE> object before the full value of the

  306.       * byte field has been read will throw a 

  307.       * <CODE>MessageFormatException</CODE>.

  308.       *

  309.       * @return a Java object from the stream message, in objectified

  310.       * format (for example, if the object was written as an <CODE>int</CODE>, 

  311.       * an <CODE>Integer</CODE> is returned)

  312.       *

  313.       * @exception JMSException if the JMS provider fails to read the message

  314.       *                         due to some internal error.

  315.       * @exception MessageEOFException if unexpected end of message stream has

  316.       *                                been reached.     

  317.       * @exception MessageFormatException if this type conversion is invalid.

  318.       * @exception MessageNotReadableException if the message is in write-only 

  319.       *                                        mode.

  320.       * 

  321.       * @see #readBytes(byte[] value)

  322.       */ 

  323. 

  324.     Object 

  325.     readObject() throws JMSException;

  326. 

  327. 

  328. 

  329.     /** Writes a <code>boolean</code> to the stream message.

  330.       * The value <code>true</code> is written as the value 

  331.       * <code>(byte)1</code> the value <code>false</code> is written as 

  332.       * the value <code>(byte)0</code>.

  333.       *

  334.       * @param value the <code>boolean</code> value to be written

  335.       *

  336.       * @exception JMSException if the JMS provider fails to write the message

  337.       *                         due to some internal error.

  338.       * @exception MessageNotWriteableException if the message is in read-only 

  339.       *                                         mode.

  340.       */

  341. 

  342.     void 

  343.     writeBoolean(boolean value) 

  344. 			throws JMSException;

  345. 

  346. 

  347.     /** Writes a <code>byte</code> to the stream message.

  348.       *

  349.       * @param value the <code>byte</code> value to be written

  350.       *

  351.       * @exception JMSException if the JMS provider fails to write the message

  352.       *                         due to some internal error.

  353.       * @exception MessageNotWriteableException if the message is in read-only 

  354.       *                                         mode.

  355.       */ 

  356. 

  357.     void 

  358.     writeByte(byte value) throws JMSException;

  359. 

  360. 

  361.     /** Writes a <code>short</code> to the stream message.

  362.       *

  363.       * @param value the <code>short</code> value to be written

  364.       *

  365.       * @exception JMSException if the JMS provider fails to write the message

  366.       *                         due to some internal error.

  367.       * @exception MessageNotWriteableException if the message is in read-only 

  368.       *                                         mode.

  369.       */ 

  370. 

  371.     void 

  372.     writeShort(short value) throws JMSException;

  373. 

  374. 

  375.     /** Writes a <code>char</code> to the stream message.

  376.       *

  377.       * @param value the <code>char</code> value to be written

  378.       *

  379.       * @exception JMSException if the JMS provider fails to write the message

  380.       *                         due to some internal error.

  381.       * @exception MessageNotWriteableException if the message is in read-only 

  382.       *                                         mode.

  383.       */ 

  384. 

  385.     void 

  386.     writeChar(char value) throws JMSException;

  387. 

  388. 

  389.     /** Writes an <code>int</code> to the stream message.

  390.       *

  391.       * @param value the <code>int</code> value to be written

  392.       *

  393.       * @exception JMSException if the JMS provider fails to write the message

  394.       *                         due to some internal error.

  395.       * @exception MessageNotWriteableException if the message is in read-only 

  396.       *                                         mode.

  397.       */ 

  398. 

  399.     void 

  400.     writeInt(int value) throws JMSException;

  401. 

  402. 

  403.     /** Writes a <code>long</code> to the stream message.

  404.       *

  405.       * @param value the <code>long</code> value to be written

  406.       *

  407.       * @exception JMSException if the JMS provider fails to write the message

  408.       *                         due to some internal error.

  409.       * @exception MessageNotWriteableException if the message is in read-only 

  410.       *                                         mode.

  411.       */ 

  412. 

  413.     void 

  414.     writeLong(long value) throws JMSException;

  415. 

  416. 

  417.     /** Writes a <code>float</code> to the stream message.

  418.       *

  419.       * @param value the <code>float</code> value to be written

  420.       *

  421.       * @exception JMSException if the JMS provider fails to write the message

  422.       *                         due to some internal error.

  423.       * @exception MessageNotWriteableException if the message is in read-only 

  424.       *                                         mode.

  425.       */ 

  426. 

  427.     void 

  428.     writeFloat(float value) throws JMSException;

  429. 

  430. 

  431.     /** Writes a <code>double</code> to the stream message.

  432.       *

  433.       * @param value the <code>double</code> value to be written

  434.       *

  435.       * @exception JMSException if the JMS provider fails to write the message

  436.       *                         due to some internal error.

  437.       * @exception MessageNotWriteableException if the message is in read-only 

  438.       *                                         mode.

  439.       */ 

  440. 

  441.     void 

  442.     writeDouble(double value) throws JMSException;

  443. 

  444. 

  445.     /** Writes a <code>String</code> to the stream message.

  446.       *

  447.       * @param value the <code>String</code> value to be written

  448.       *

  449.       * @exception JMSException if the JMS provider fails to write the message

  450.       *                         due to some internal error.

  451.       * @exception MessageNotWriteableException if the message is in read-only 

  452.       *                                         mode.

  453.       */ 

  454. 

  455.     void 

  456.     writeString(String value) throws JMSException;

  457. 

  458. 

  459.     /** Writes a byte array field to the stream message.

  460.       *

  461.       * <P>The byte array <code>value</code> is written to the message

  462.       * as a byte array field. Consecutively written byte array fields are 

  463.       * treated as two distinct fields when the fields are read.

  464.       * 

  465.       * @param value the byte array value to be written

  466.       *

  467.       * @exception JMSException if the JMS provider fails to write the message

  468.       *                         due to some internal error.

  469.       * @exception MessageNotWriteableException if the message is in read-only 

  470.       *                                         mode.

  471.       */ 

  472. 

  473.     void

  474.     writeBytes(byte[] value) throws JMSException;

  475. 

  476. 

  477.     /** Writes a portion of a byte array as a byte array field to the stream 

  478.       * message.

  479.       *  

  480.       * <P>The a portion of the byte array <code>value</code> is written to the

  481.       * message as a byte array field. Consecutively written byte 

  482.       * array fields are treated as two distinct fields when the fields are 

  483.       * read.

  484.       *

  485.       * @param value the byte array value to be written

  486.       * @param offset the initial offset within the byte array

  487.       * @param length the number of bytes to use

  488.       *

  489.       * @exception JMSException if the JMS provider fails to write the message

  490.       *                         due to some internal error.

  491.       * @exception MessageNotWriteableException if the message is in read-only 

  492.       *                                         mode.

  493.       */ 

  494.  

  495.     void

  496.     writeBytes(byte[] value, int offset, int length) 

  497. 			throws JMSException;

  498. 

  499. 

  500.     /** Writes an object to the stream message.

  501.       *

  502.       * <P>This method works only for the objectified primitive

  503.       * object types (<code>Integer</code>, <code>Double</code>, 

  504.       * <code>Long</code> ...), <code>String</code> objects, and byte 

  505.       * arrays.

  506.       *

  507.       * @param value the Java object to be written

  508.       *

  509.       * @exception JMSException if the JMS provider fails to write the message

  510.       *                         due to some internal error.

  511.       * @exception MessageFormatException if the object is invalid.

  512.       * @exception MessageNotWriteableException if the message is in read-only 

  513.       *                                         mode.

  514.       */ 

  515. 

  516.     void 

  517.     writeObject(Object value) throws JMSException;

  518. 

  519. 

  520.     /** Puts the message body in read-only mode and repositions the stream

  521.       * to the beginning.

  522.       *  

  523.       * @exception JMSException if the JMS provider fails to reset the message

  524.       *                         due to some internal error.

  525.       * @exception MessageFormatException if the message has an invalid

  526.       *                                   format.

  527.       */ 

  528.  

  529.     void

  530.     reset() throws JMSException;

  531. }