BytesMessage


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  import java.io.InputStream  ;
28  import java.io.OutputStream  ;
29  
30  /** A <CODE>BytesMessage</CODE> object is used to send a message containing a 
31    * stream of uninterpreted bytes. It inherits from the <CODE>Message</CODE> 
32    * interface and adds a bytes
33    * message body. The receiver of the message supplies the interpretation
34    * of the bytes.
35    *
36    * <P>The <CODE>BytesMessage</CODE> methods are based largely on those found in
37    * <CODE>java.io.DataInputStream</CODE> and
38    * <CODE>java.io.DataOutputStream</CODE>.
39    *
40    * <P>This message type is for client encoding of existing message formats. 
41    * If possible, one of the other self-defining message types should be used 
42    * instead.
43    *
44    * <P>Although the JMS API allows the use of message properties with byte 
45    * messages, they are typically not used, since the inclusion of properties 
46    * may affect the format.
47    *
48    * <P>The primitive types can be written explicitly using methods
49    * for each type. They may also be written generically as objects.
50    * For instance, a call to <CODE>BytesMessage.writeInt(6)</CODE> is
51    * equivalent to <CODE>BytesMessage.writeObject(new Integer(6))</CODE>.
52    * Both forms are provided, because the explicit form is convenient for
53    * static programming, and the object form is needed when types are not known
54    * at compile time.
55    *
56    * <P>When the message is first created, and when <CODE>clearBody</CODE>
57    * is called, the body of the message is in write-only mode. After the 
58    * first call to <CODE>reset</CODE> has been made, the message body is in 
59    * read-only mode. 
60    * After a message has been sent, the client that sent it can retain and 
61    * modify it without affecting the message that has been sent. The same message
62    * object can be sent multiple times.
63    * When a message has been received, the provider has called 
64    * <CODE>reset</CODE> so that the message body is in read-only mode for the client.
65    *
66    * <P>If <CODE>clearBody</CODE> is called on a message in read-only mode, 
67    * the message body is cleared and the message is in write-only mode.
68    *
69    * <P>If a client attempts to read a message in write-only mode, a 
70    * <CODE>MessageNotReadableException</CODE> is thrown.
71    *
72    * <P>If a client attempts to write a message in read-only mode, a 
73    * <CODE>MessageNotWriteableException</CODE> is thrown.
74    *
75    * @version     1.1 April 2, 2002
76    * @author      Mark Hapner
77    * @author      Rich Burridge
78    * @author      Kate Stout
79    *
80    * @see         javax.jms.Session#createBytesMessage()
81    * @see         javax.jms.MapMessage
82    * @see         javax.jms.Message
83    * @see         javax.jms.ObjectMessage
84    * @see         javax.jms.StreamMessage
85    * @see         javax.jms.TextMessage
86    */
87  
88  public interface BytesMessage extends Message   {
89      
90       /** Gets the number of bytes of the message body when the message
91         * is in read-only mode. The value returned can be used to allocate 
92         * a byte array. The value returned is the entire length of the message
93         *  body, regardless of where the pointer for reading the message 
94         * is currently located.
95         * 
96         * @return number of bytes in the message 
97         * @exception JMSException if the JMS provider fails to read the message 
98         *                         due to some internal error.
99         * @exception MessageNotReadableException if the message is in write-only
100        *                         mode.
101        * @since 1.1 
102        */
103        
104       long getBodyLength() throws JMSException  ;
105 
106     /** Reads a <code>boolean</code> from the bytes message stream.
107       *
108       * @return the <code>boolean</code> value read
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 bytes stream has 
113       *                                been reached.
114       * @exception MessageNotReadableException if the message is in write-only 
115       *                                        mode.
116       */
117     
118  
119     boolean 
120     readBoolean() throws JMSException  ;
121 
122 
123     /** Reads a signed 8-bit value from the bytes message stream.
124       *
125       * @return the next byte from the bytes message stream as a signed 8-bit
126       * <code>byte</code>
127       *
128       * @exception JMSException if the JMS provider fails to read the message 
129       *                         due to some internal error.
130       * @exception MessageEOFException if unexpected end of bytes stream has 
131       *                                been reached.
132       * @exception MessageNotReadableException if the message is in write-only 
133       *                                        mode.
134       */ 
135 
136     byte 
137     readByte() throws JMSException  ;
138 
139 
140     /** Reads an unsigned 8-bit number from the bytes message stream.
141       *  
142       * @return the next byte from the bytes message stream, interpreted as an
143       * unsigned 8-bit number
144       *
145       * @exception JMSException if the JMS provider fails to read the message 
146       *                         due to some internal error.
147       * @exception MessageEOFException if unexpected end of bytes stream has 
148       *                                been reached.
149       * @exception MessageNotReadableException if the message is in write-only 
150       *                                        mode.
151       */
152 
153     int
154     readUnsignedByte() throws JMSException  ;
155 
156 
157     /** Reads a signed 16-bit number from the bytes message stream.
158       *
159       * @return the next two bytes from the bytes message stream, interpreted as
160       * a signed 16-bit number
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 bytes stream has 
165       *                                been reached.
166       * @exception MessageNotReadableException if the message is in write-only 
167       *                                        mode.
168       */ 
169 
170     short 
171     readShort() throws JMSException  ;
172 
173 
174     /** Reads an unsigned 16-bit number from the bytes message stream.
175       *  
176       * @return the next two bytes from the bytes message stream, interpreted as
177       * an unsigned 16-bit integer
178       *
179       * @exception JMSException if the JMS provider fails to read the message 
180       *                         due to some internal error.
181       * @exception MessageEOFException if unexpected end of bytes stream has 
182       *                                been reached.
183       * @exception MessageNotReadableException if the message is in write-only 
184       *                                        mode.
185       */ 
186  
187     int
188     readUnsignedShort() throws JMSException  ;
189 
190 
191     /** Reads a Unicode character value from the bytes message stream.
192       *
193       * @return the next two bytes from the bytes message stream as a Unicode
194       * character
195       *
196       * @exception JMSException if the JMS provider fails to read the message 
197       *                         due to some internal error.
198       * @exception MessageEOFException if unexpected end of bytes stream has 
199       *                                been reached.
200       * @exception MessageNotReadableException if the message is in write-only 
201       *                                        mode.
202       */ 
203 
204     char 
205     readChar() throws JMSException  ;
206 
207 
208     /** Reads a signed 32-bit integer from the bytes message stream.
209       *
210       * @return the next four bytes from the bytes message stream, interpreted
211       * as an <code>int</code>
212       *
213       * @exception JMSException if the JMS provider fails to read the message 
214       *                         due to some internal error.
215       * @exception MessageEOFException if unexpected end of bytes stream has 
216       *                                been reached.
217       * @exception MessageNotReadableException if the message is in write-only 
218       *                                        mode.
219       */ 
220 
221     int 
222     readInt() throws JMSException  ;
223 
224 
225     /** Reads a signed 64-bit integer from the bytes message stream.
226       *
227       * @return the next eight bytes from the bytes message stream, interpreted
228       * as a <code>long</code>
229       *
230       * @exception JMSException if the JMS provider fails to read the message 
231       *                         due to some internal error.
232       * @exception MessageEOFException if unexpected end of bytes stream has 
233       *                                been reached.
234       * @exception MessageNotReadableException if the message is in write-only 
235       *                                        mode.
236       */ 
237 
238     long 
239     readLong() throws JMSException  ;
240 
241 
242     /** Reads a <code>float</code> from the bytes message stream.
243       *
244       * @return the next four bytes from the bytes message stream, interpreted
245       * as a <code>float</code>
246       *
247       * @exception JMSException if the JMS provider fails to read the message 
248       *                         due to some internal error.
249       * @exception MessageEOFException if unexpected end of bytes stream has 
250       *                                been reached.
251       * @exception MessageNotReadableException if the message is in write-only 
252       *                                        mode.
253       */ 
254 
255     float 
256     readFloat() throws JMSException  ;
257 
258 
259     /** Reads a <code>double</code> from the bytes message stream.
260       *
261       * @return the next eight bytes from the bytes message stream, interpreted
262       * as a <code>double</code>
263       *
264       * @exception JMSException if the JMS provider fails to read the message 
265       *                         due to some internal error.
266       * @exception MessageEOFException if unexpected end of bytes stream has 
267       *                                been reached.
268       * @exception MessageNotReadableException if the message is in write-only 
269       *                                        mode.
270       */ 
271 
272     double 
273     readDouble() throws JMSException  ;
274 
275 
276     /** Reads a string that has been encoded using a modified UTF-8
277       * format from the bytes message stream.
278       *
279       * <P>For more information on the UTF-8 format, see "File System Safe
280       * UCS Transformation Format (FSS_UTF)", X/Open Preliminary Specification,
281       * X/Open Company Ltd., Document Number: P316. This information also
282       * appears in ISO/IEC 10646, Annex P.
283       *
284       * @return a Unicode string from the bytes message stream
285       *
286       * @exception JMSException if the JMS provider fails to read the message 
287       *                         due to some internal error.
288       * @exception MessageEOFException if unexpected end of bytes stream has 
289       *                                been reached.
290       * @exception MessageNotReadableException if the message is in write-only 
291       *                                        mode.
292       */ 
293 
294     String   
295     readUTF() throws JMSException  ;
296 
297 
298     /** Reads a byte array from the bytes message stream.
299       *
300       * <P>If the length of array <code>value</code> is less than the number of 
301       * bytes remaining to be read from the stream, the array should 
302       * be filled. A subsequent call reads the next increment, and so on.
303       * 
304       * <P>If the number of bytes remaining in the stream is less than the 
305       * length of 
306       * array <code>value</code>, the bytes should be read into the array. 
307       * The return value of the total number of bytes read will be less than
308       * the length of the array, indicating that there are no more bytes left 
309       * to be read from the stream. The next read of the stream returns -1.
310       *
311       * @param value the buffer into which the data is read
312       *
313       * @return the total number of bytes read into the buffer, or -1 if 
314       * there is no more data because the end of the stream has been reached
315       *
316       * @exception JMSException if the JMS provider fails to read the message 
317       *                         due to some internal error.
318       * @exception MessageNotReadableException if the message is in write-only 
319       *                                        mode.
320       */ 
321 
322     int
323     readBytes(byte[] value) throws JMSException  ;
324 
325 
326     /** Reads a portion of the bytes message stream.
327       *
328       * <P>If the length of array <code>value</code> is less than the number of
329       * bytes remaining to be read from the stream, the array should 
330       * be filled. A subsequent call reads the next increment, and so on.
331       * 
332       * <P>If the number of bytes remaining in the stream is less than the 
333       * length of 
334       * array <code>value</code>, the bytes should be read into the array. 
335       * The return value of the total number of bytes read will be less than
336       * the length of the array, indicating that there are no more bytes left 
337       * to be read from the stream. The next read of the stream returns -1.
338       *
339       * <p> If <code>length</code> is negative, or
340       * <code>length</code> is greater than the length of the array
341       * <code>value</code>, then an <code>IndexOutOfBoundsException</code> is
342       * thrown. No bytes will be read from the stream for this exception case.
343       *  
344       * @param value the buffer into which the data is read
345       * @param length the number of bytes to read; must be less than or equal to
346       *        <code>value.length</code>
347       * 
348       * @return the total number of bytes read into the buffer, or -1 if
349       * there is no more data because the end of the stream has been reached
350       *  
351       * @exception JMSException if the JMS provider fails to read the message 
352       *                         due to some internal error.
353       * @exception MessageNotReadableException if the message is in write-only 
354       *                                        mode.
355       */ 
356 
357     int
358     readBytes(byte[] value, int length) 
359             throws JMSException  ;
360 
361 
362     /** Writes a <code>boolean</code> to the bytes message stream as a 1-byte 
363       * value.
364       * The value <code>true</code> is written as the value 
365       * <code>(byte)1</code>; the value <code>false</code> is written as 
366       * the value <code>(byte)0</code>.
367       *
368       * @param value the <code>boolean</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     writeBoolean(boolean value) 
378             throws JMSException  ;
379 
380 
381     /** Writes a <code>byte</code> to the bytes message stream as a 1-byte 
382       * value.
383       *
384       * @param value the <code>byte</code> value to be written
385       *
386       * @exception JMSException if the JMS provider fails to write the message
387       *                         due to some internal error.
388       * @exception MessageNotWriteableException if the message is in read-only 
389       *                                         mode.
390       */ 
391 
392     void 
393     writeByte(byte value) throws JMSException  ;
394 
395 
396     /** Writes a <code>short</code> to the bytes message stream as two bytes,
397       * high byte first.
398       *
399       * @param value the <code>short</code> to be written
400       *
401       * @exception JMSException if the JMS provider fails to write the message
402       *                         due to some internal error.
403       * @exception MessageNotWriteableException if the message is in read-only 
404       *                                         mode.
405       */ 
406 
407     void 
408     writeShort(short value) throws JMSException  ;
409 
410 
411     /** Writes a <code>char</code> to the bytes message stream as a 2-byte
412       * value, high byte first.
413       *
414       * @param value the <code>char</code> value to be written
415       *
416       * @exception JMSException if the JMS provider fails to write the message
417       *                         due to some internal error.
418       * @exception MessageNotWriteableException if the message is in read-only 
419       *                                         mode.
420       */ 
421 
422     void 
423     writeChar(char value) throws JMSException  ;
424 
425 
426     /** Writes an <code>int</code> to the bytes message stream as four bytes, 
427       * high byte first.
428       *
429       * @param value the <code>int</code> to be written
430       *
431       * @exception JMSException if the JMS provider fails to write the message
432       *                         due to some internal error.
433       * @exception MessageNotWriteableException if the message is in read-only 
434       *                                         mode.
435       */ 
436 
437     void 
438     writeInt(int value) throws JMSException  ;
439 
440 
441     /** Writes a <code>long</code> to the bytes message stream as eight bytes, 
442       * high byte first.
443       *
444       * @param value the <code>long</code> to be written
445       *
446       * @exception JMSException if the JMS provider fails to write the message
447       *                         due to some internal error.
448       * @exception MessageNotWriteableException if the message is in read-only 
449       *                                         mode.
450       */ 
451 
452     void 
453     writeLong(long value) throws JMSException  ;
454 
455 
456     /** Converts the <code>float</code> argument to an <code>int</code> using 
457       * the
458       * <code>floatToIntBits</code> method in class <code>Float</code>,
459       * and then writes that <code>int</code> value to the bytes message
460       * stream as a 4-byte quantity, high byte first.
461       *
462       * @param value the <code>float</code> value to be written
463       *
464       * @exception JMSException if the JMS provider fails to write the message
465       *                         due to some internal error.
466       * @exception MessageNotWriteableException if the message is in read-only 
467       *                                         mode.
468       */ 
469 
470     void 
471     writeFloat(float value) throws JMSException  ;
472 
473 
474     /** Converts the <code>double</code> argument to a <code>long</code> using 
475       * the
476       * <code>doubleToLongBits</code> method in class <code>Double</code>,
477       * and then writes that <code>long</code> value to the bytes message
478       * stream as an 8-byte quantity, high byte first.
479       *
480       * @param value the <code>double</code> value to be written
481       *
482       * @exception JMSException if the JMS provider fails to write the message
483       *                         due to some internal error.
484       * @exception MessageNotWriteableException if the message is in read-only 
485       *                                         mode.
486       */ 
487 
488     void 
489     writeDouble(double value) throws JMSException  ;
490 
491 
492     /** Writes a string to the bytes message stream using UTF-8 encoding in a 
493       * machine-independent manner.
494       *
495       * <P>For more information on the UTF-8 format, see "File System Safe 
496       * UCS Transformation Format (FSS_UTF)", X/Open Preliminary Specification,       
497       * X/Open Company Ltd., Document Number: P316. This information also 
498       * appears in ISO/IEC 10646, Annex P. 
499       *
500       * @param value the <code>String</code> value to be written
501       *
502       * @exception JMSException if the JMS provider fails to write the message
503       *                         due to some internal error.
504       * @exception MessageNotWriteableException if the message is in read-only 
505       *                                         mode.
506       */ 
507 
508     void 
509     writeUTF(String   value) throws JMSException  ;
510 
511 
512     /** Writes a byte array to the bytes message stream.
513       *
514       * @param value the byte array to be written
515       *
516       * @exception JMSException if the JMS provider fails to write the message
517       *                         due to some internal error.
518       * @exception MessageNotWriteableException if the message is in read-only 
519       *                                         mode.
520       */ 
521 
522     void
523     writeBytes(byte[] value) throws JMSException  ;
524 
525 
526     /** Writes a portion of a byte array to the bytes message stream.
527       *  
528       * @param value the byte array value to be written
529       * @param offset the initial offset within the byte array
530       * @param length the number of bytes to use
531       *
532       * @exception JMSException if the JMS provider fails to write the message
533       *                         due to some internal error.
534       * @exception MessageNotWriteableException if the message is in read-only 
535       *                                         mode.
536       */ 
537  
538     void
539     writeBytes(byte[] value, int offset, int length) 
540             throws JMSException  ;
541 
542 
543     /** Writes an object to the bytes message stream.
544       *
545       * <P>This method works only for the objectified primitive
546       * object types (<code>Integer</code>, <code>Double</code>, 
547       * <code>Long</code>&nbsp;...), <code>String</code> objects, and byte 
548       * arrays.
549       *
550       * @param value the object in the Java programming language ("Java 
551       *              object") to be written; it must not be null
552       *
553       * @exception JMSException if the JMS provider fails to write the message
554       *                         due to some internal error.
555       * @exception MessageFormatException if the object is of an invalid type.
556       * @exception MessageNotWriteableException if the message is in read-only 
557       *                                         mode.
558       * @exception java.lang.NullPointerException if the parameter 
559       *                                           <code>value</code> is null.
560       */ 
561 
562     void 
563     writeObject(Object   value) throws JMSException  ;
564 
565 
566     /** Puts the message body in read-only mode and repositions the stream of 
567       * bytes to the beginning.
568       *  
569       * @exception JMSException if the JMS provider fails to reset the message
570       *                         due to some internal error.
571       * @exception MessageFormatException if the message has an invalid
572       *                         format.
573       */ 
574 
575     void
576     reset() throws JMSException  ;
577 }
578
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags