StreamMessage


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  
25  package javax.jms;
26  
27  /** A <CODE>StreamMessage</CODE> object is used to send a stream of primitive
28    * types in the Java programming language. It is filled and read sequentially.
29    * It inherits from the <CODE>Message</CODE> interface
30    * and adds a stream message body. Its methods are based largely on those
31    * found in <CODE>java.io.DataInputStream</CODE> and
32    * <CODE>java.io.DataOutputStream</CODE>.
33    *
34    * <P>The primitive types can be read or written explicitly using methods
35    * for each type. They may also be read or written generically as objects.
36    * For instance, a call to <CODE>StreamMessage.writeInt(6)</CODE> is
37    * equivalent to <CODE>StreamMessage.writeObject(new Integer(6))</CODE>.
38    * Both forms are provided, because the explicit form is convenient for
39    * static programming, and the object form is needed when types are not known
40    * at compile time.
41    *
42    * <P>When the message is first created, and when <CODE>clearBody</CODE>
43    * is called, the body of the message is in write-only mode. After the 
44    * first call to <CODE>reset</CODE> has been made, the message body is in 
45    * read-only mode. 
46    * After a message has been sent, the client that sent it can retain and 
47    * modify it without affecting the message that has been sent. The same message
48    * object can be sent multiple times.
49    * When a message has been received, the provider has called 
50    * <CODE>reset</CODE> so that the message body is in read-only mode for the client.
51    * 
52    * <P>If <CODE>clearBody</CODE> is called on a message in read-only mode, 
53    * the message body is cleared and the message body is in write-only mode.
54    * 
55    * <P>If a client attempts to read a message in write-only mode, a 
56    * <CODE>MessageNotReadableException</CODE> is thrown.
57    * 
58    * <P>If a client attempts to write a message in read-only mode, a 
59    * <CODE>MessageNotWriteableException</CODE> is thrown.
60    *
61    * <P><CODE>StreamMessage</CODE> objects support the following conversion 
62    * table. The marked cases must be supported. The unmarked cases must throw a 
63    * <CODE>JMSException</CODE>. The <CODE>String</CODE>-to-primitive conversions 
64    * may throw a runtime exception if the primitive's <CODE>valueOf()</CODE> 
65    * method does not accept it as a valid <CODE>String</CODE> representation of 
66    * the primitive.
67    *
68    * <P>A value written as the row type can be read as the column type.
69    *
70    * <PRE>
71    * |        | boolean byte short char int long float double String byte[]
72    * |----------------------------------------------------------------------
73    * |boolean |    X                                            X
74    * |byte    |          X     X         X   X                  X   
75    * |short   |                X         X   X                  X   
76    * |char    |                     X                           X
77    * |int     |                          X   X                  X   
78    * |long    |                              X                  X   
79    * |float   |                                    X     X      X   
80    * |double  |                                          X      X   
81    * |String  |    X     X     X         X   X     X     X      X   
82    * |byte[]  |                                                        X
83    * |----------------------------------------------------------------------
84    * </PRE>
85    *
86    * <P>Attempting to read a null value as a primitive type must be treated
87    * as calling the primitive's corresponding <code>valueOf(String)</code> 
88    * conversion method with a null value. Since <code>char</code> does not 
89    * support a <code>String</code> conversion, attempting to read a null value 
90    * as a <code>char</code> must throw a <code>NullPointerException</code>.
91    *
92    * @version     1.0 - 6 August 1998
93    * @author      Mark Hapner
94    * @author      Rich Burridge
95    *
96    * @see         javax.jms.Session#createStreamMessage()
97    * @see         javax.jms.BytesMessage
98    * @see         javax.jms.MapMessage
99    * @see         javax.jms.Message
100   * @see         javax.jms.ObjectMessage
101   * @see         javax.jms.TextMessage
102   */
103 
104 public interface StreamMessage extends Message   {
105 
106 
107     /** Reads a <code>boolean</code> from the stream message.
108       *
109       * @return the <code>boolean</code> value read
110       *
111       * @exception JMSException if the JMS provider fails to read the message
112       *                         due to some internal error.
113       * @exception MessageEOFException if unexpected end of message stream has
114       *                                been reached.     
115       * @exception MessageFormatException if this type conversion is invalid.
116       * @exception MessageNotReadableException if the message is in write-only 
117       *                                        mode.
118       */
119 
120     boolean 
121     readBoolean() throws JMSException  ;
122 
123 
124     /** Reads a <code>byte</code> value from the stream message.
125       *
126       * @return the next byte from the stream message as a 8-bit
127       * <code>byte</code>
128       *
129       * @exception JMSException if the JMS provider fails to read the message
130       *                         due to some internal error.
131       * @exception MessageEOFException if unexpected end of message stream has
132       *                                been reached.     
133       * @exception MessageFormatException if this type conversion is invalid.
134       * @exception MessageNotReadableException if the message is in write-only 
135       *                                        mode.
136       */ 
137 
138     byte 
139     readByte() throws JMSException  ;
140 
141 
142     /** Reads a 16-bit integer from the stream message.
143       *
144       * @return a 16-bit integer from the stream message
145       *
146       * @exception JMSException if the JMS provider fails to read the message
147       *                         due to some internal error.
148       * @exception MessageEOFException if unexpected end of message stream has
149       *                                been reached.     
150       * @exception MessageFormatException if this type conversion is invalid.
151       * @exception MessageNotReadableException if the message is in write-only 
152       *                                        mode.
153       */ 
154 
155     short 
156     readShort() throws JMSException  ;
157 
158 
159     /** Reads a Unicode character value from the stream message.
160       *
161       * @return a Unicode character from the stream message
162       *
163       * @exception JMSException if the JMS provider fails to read the message
164       *                         due to some internal error.
165       * @exception MessageEOFException if unexpected end of message stream has
166       *                                been reached.     
167       * @exception MessageFormatException if this type conversion is invalid      
168       * @exception MessageNotReadableException if the message is in write-only 
169       *                                        mode.
170       */ 
171 
172     char 
173     readChar() throws JMSException  ;
174 
175 
176     /** Reads a 32-bit integer from the stream message.
177       *
178       * @return a 32-bit integer value from the stream message, interpreted
179       * as an <code>int</code>
180       *
181       * @exception JMSException if the JMS provider fails to read the message
182       *                         due to some internal error.
183       * @exception MessageEOFException if unexpected end of message stream has
184       *                                been reached.     
185       * @exception MessageFormatException if this type conversion is invalid.
186       * @exception MessageNotReadableException if the message is in write-only 
187       *                                        mode.
188       */ 
189 
190     int 
191     readInt() throws JMSException  ;
192 
193 
194     /** Reads a 64-bit integer from the stream message.
195       *
196       * @return a 64-bit integer value from the stream message, interpreted as
197       * a <code>long</code>
198       *
199       * @exception JMSException if the JMS provider fails to read the message
200       *                         due to some internal error.
201       * @exception MessageEOFException if unexpected end of message stream has
202       *                                been reached.     
203       * @exception MessageFormatException if this type conversion is invalid.
204       * @exception MessageNotReadableException if the message is in write-only 
205       *                                        mode.
206       */ 
207 
208     long 
209     readLong() throws JMSException  ;
210 
211 
212     /** Reads a <code>float</code> from the stream message.
213       *
214       * @return a <code>float</code> value from the stream message
215       *
216       * @exception JMSException if the JMS provider fails to read the message
217       *                         due to some internal error.
218       * @exception MessageEOFException if unexpected end of message stream has
219       *                                been reached.     
220       * @exception MessageFormatException if this type conversion is invalid.
221       * @exception MessageNotReadableException if the message is in write-only 
222       *                                        mode.
223       */ 
224 
225     float 
226     readFloat() throws JMSException  ;
227 
228 
229     /** Reads a <code>double</code> from the stream message.
230       *
231       * @return a <code>double</code> value from the stream message
232       *
233       * @exception JMSException if the JMS provider fails to read the message
234       *                         due to some internal error.
235       * @exception MessageEOFException if unexpected end of message stream has
236       *                                been reached.     
237       * @exception MessageFormatException if this type conversion is invalid.
238       * @exception MessageNotReadableException if the message is in write-only 
239       *                                        mode.
240       */ 
241 
242     double 
243     readDouble() throws JMSException  ;
244 
245 
246     /** Reads a <CODE>String</CODE> from the stream message.
247       *
248       * @return a Unicode string from the stream message
249       *
250       * @exception JMSException if the JMS provider fails to read the message
251       *                         due to some internal error.
252       * @exception MessageEOFException if unexpected end of message stream has
253       *                                been reached.     
254       * @exception MessageFormatException if this type conversion is invalid.
255       * @exception MessageNotReadableException if the message is in write-only 
256       *                                        mode.
257       */ 
258 
259     String   
260     readString() throws JMSException  ;
261 
262 
263     /** Reads a byte array field from the stream message into the 
264       * specified <CODE>byte[]</CODE> object (the read buffer). 
265       * 
266       * <P>To read the field value, <CODE>readBytes</CODE> should be 
267       * successively called 
268       * until it returns a value less than the length of the read buffer.
269       * The value of the bytes in the buffer following the last byte 
270       * read is undefined.
271       * 
272       * <P>If <CODE>readBytes</CODE> returns a value equal to the length of the 
273       * buffer, a subsequent <CODE>readBytes</CODE> call must be made. If there 
274       * are no more bytes to be read, this call returns -1.
275       * 
276       * <P>If the byte array field value is null, <CODE>readBytes</CODE> 
277       * returns -1.
278       *
279       * <P>If the byte array field value is empty, <CODE>readBytes</CODE> 
280       * returns 0.
281       * 
282       * <P>Once the first <CODE>readBytes</CODE> call on a <CODE>byte[]</CODE>
283       * field value has been made,
284       * the full value of the field must be read before it is valid to read 
285       * the next field. An attempt to read the next field before that has 
286       * been done will throw a <CODE>MessageFormatException</CODE>.
287       * 
288       * <P>To read the byte field value into a new <CODE>byte[]</CODE> object, 
289       * use the <CODE>readObject</CODE> method.
290       *
291       * @param value the buffer into which the data is read
292       *
293       * @return the total number of bytes read into the buffer, or -1 if 
294       * there is no more data because the end of the byte field has been 
295       * reached
296       *
297       * @exception JMSException if the JMS provider fails to read the message
298       *                         due to some internal error.
299       * @exception MessageEOFException if unexpected end of message stream has
300       *                                been reached.     
301       * @exception MessageFormatException if this type conversion is invalid.
302       * @exception MessageNotReadableException if the message is in write-only 
303       *                                        mode.
304       * 
305       * @see #readObject()
306       */ 
307 
308     int
309     readBytes(byte[] value) throws JMSException  ;
310 
311 
312     /** Reads an object from the stream message.
313       *
314       * <P>This method can be used to return, in objectified format,
315       * an object in the Java programming language ("Java object") that has 
316       * been written to the stream with the equivalent
317       * <CODE>writeObject</CODE> method call, or its equivalent primitive
318       * <CODE>write<I>type</I></CODE> method.
319       *  
320       * <P>Note that byte values are returned as <CODE>byte[]</CODE>, not 
321       * <CODE>Byte[]</CODE>.
322       *
323       * <P>An attempt to call <CODE>readObject</CODE> to read a byte field 
324       * value into a new <CODE>byte[]</CODE> object before the full value of the
325       * byte field has been read will throw a 
326       * <CODE>MessageFormatException</CODE>.
327       *
328       * @return a Java object from the stream message, in objectified
329       * format (for example, if the object was written as an <CODE>int</CODE>, 
330       * an <CODE>Integer</CODE> is returned)
331       *
332       * @exception JMSException if the JMS provider fails to read the message
333       *                         due to some internal error.
334       * @exception MessageEOFException if unexpected end of message stream has
335       *                                been reached.     
336       * @exception MessageFormatException if this type conversion is invalid.
337       * @exception MessageNotReadableException if the message is in write-only 
338       *                                        mode.
339       * 
340       * @see #readBytes(byte[] value)
341       */ 
342 
343     Object   
344     readObject() throws JMSException  ;
345 
346 
347 
348     /** Writes a <code>boolean</code> to the stream message.
349       * The value <code>true</code> is written as the value 
350       * <code>(byte)1</code>; the value <code>false</code> is written as 
351       * the value <code>(byte)0</code>.
352       *
353       * @param value the <code>boolean</code> value to be written
354       *
355       * @exception JMSException if the JMS provider fails to write the message
356       *                         due to some internal error.
357       * @exception MessageNotWriteableException if the message is in read-only 
358       *                                         mode.
359       */
360 
361     void 
362     writeBoolean(boolean value) 
363             throws JMSException  ;
364 
365 
366     /** Writes a <code>byte</code> to the stream message.
367       *
368       * @param value the <code>byte</code> value to be written
369       *
370       * @exception JMSException if the JMS provider fails to write the message
371       *                         due to some internal error.
372       * @exception MessageNotWriteableException if the message is in read-only 
373       *                                         mode.
374       */ 
375 
376     void 
377     writeByte(byte value) throws JMSException  ;
378 
379 
380     /** Writes a <code>short</code> to the stream message.
381       *
382       * @param value the <code>short</code> value to be written
383       *
384       * @exception JMSException if the JMS provider fails to write the message
385       *                         due to some internal error.
386       * @exception MessageNotWriteableException if the message is in read-only 
387       *                                         mode.
388       */ 
389 
390     void 
391     writeShort(short value) throws JMSException  ;
392 
393 
394     /** Writes a <code>char</code> to the stream message.
395       *
396       * @param value the <code>char</code> value to be written
397       *
398       * @exception JMSException if the JMS provider fails to write the message
399       *                         due to some internal error.
400       * @exception MessageNotWriteableException if the message is in read-only 
401       *                                         mode.
402       */ 
403 
404     void 
405     writeChar(char value) throws JMSException  ;
406 
407 
408     /** Writes an <code>int</code> to the stream message.
409       *
410       * @param value the <code>int</code> value to be written
411       *
412       * @exception JMSException if the JMS provider fails to write the message
413       *                         due to some internal error.
414       * @exception MessageNotWriteableException if the message is in read-only 
415       *                                         mode.
416       */ 
417 
418     void 
419     writeInt(int value) throws JMSException  ;
420 
421 
422     /** Writes a <code>long</code> to the stream message.
423       *
424       * @param value the <code>long</code> value to be written
425       *
426       * @exception JMSException if the JMS provider fails to write the message
427       *                         due to some internal error.
428       * @exception MessageNotWriteableException if the message is in read-only 
429       *                                         mode.
430       */ 
431 
432     void 
433     writeLong(long value) throws JMSException  ;
434 
435 
436     /** Writes a <code>float</code> to the stream message.
437       *
438       * @param value the <code>float</code> value to be written
439       *
440       * @exception JMSException if the JMS provider fails to write the message
441       *                         due to some internal error.
442       * @exception MessageNotWriteableException if the message is in read-only 
443       *                                         mode.
444       */ 
445 
446     void 
447     writeFloat(float value) throws JMSException  ;
448 
449 
450     /** Writes a <code>double</code> to the stream message.
451       *
452       * @param value the <code>double</code> value to be written
453       *
454       * @exception JMSException if the JMS provider fails to write the message
455       *                         due to some internal error.
456       * @exception MessageNotWriteableException if the message is in read-only 
457       *                                         mode.
458       */ 
459 
460     void 
461     writeDouble(double value) throws JMSException  ;
462 
463 
464     /** Writes a <code>String</code> to the stream message.
465       *
466       * @param value the <code>String</code> value to be written
467       *
468       * @exception JMSException if the JMS provider fails to write the message
469       *                         due to some internal error.
470       * @exception MessageNotWriteableException if the message is in read-only 
471       *                                         mode.
472       */ 
473 
474     void 
475     writeString(String   value) throws JMSException  ;
476 
477 
478     /** Writes a byte array field to the stream message.
479       *
480       * <P>The byte array <code>value</code> is written to the message
481       * as a byte array field. Consecutively written byte array fields are 
482       * treated as two distinct fields when the fields are read.
483       * 
484       * @param value the byte array value to be written
485       *
486       * @exception JMSException if the JMS provider fails to write the message
487       *                         due to some internal error.
488       * @exception MessageNotWriteableException if the message is in read-only 
489       *                                         mode.
490       */ 
491 
492     void
493     writeBytes(byte[] value) throws JMSException  ;
494 
495 
496     /** Writes a portion of a byte array as a byte array field to the stream 
497       * message.
498       *  
499       * <P>The a portion of the byte array <code>value</code> is written to the
500       * message as a byte array field. Consecutively written byte 
501       * array fields are treated as two distinct fields when the fields are 
502       * read.
503       *
504       * @param value the byte array value to be written
505       * @param offset the initial offset within the byte array
506       * @param length the number of bytes to use
507       *
508       * @exception JMSException if the JMS provider fails to write the message
509       *                         due to some internal error.
510       * @exception MessageNotWriteableException if the message is in read-only 
511       *                                         mode.
512       */ 
513  
514     void
515     writeBytes(byte[] value, int offset, int length) 
516             throws JMSException  ;
517 
518 
519     /** Writes an object to the stream message.
520       *
521       * <P>This method works only for the objectified primitive
522       * object types (<code>Integer</code>, <code>Double</code>, 
523       * <code>Long</code>&nbsp;...), <code>String</code> objects, and byte 
524       * arrays.
525       *
526       * @param value the Java object to be written
527       *
528       * @exception JMSException if the JMS provider fails to write the message
529       *                         due to some internal error.
530       * @exception MessageFormatException if the object is invalid.
531       * @exception MessageNotWriteableException if the message is in read-only 
532       *                                         mode.
533       */ 
534 
535     void 
536     writeObject(Object   value) throws JMSException  ;
537 
538 
539     /** Puts the message body in read-only mode and repositions the stream
540       * to the beginning.
541       *  
542       * @exception JMSException if the JMS provider fails to reset the message
543       *                         due to some internal error.
544       * @exception MessageFormatException if the message has an invalid
545       *                                   format.
546       */ 
547  
548     void
549     reset() throws JMSException  ;
550 }
551
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags