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