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 * @(#)StreamMessage.java 1.42 07/02/07
37 */
38
39 package javax.jms;
40
41 /** A <CODE>StreamMessage</CODE> object is used to send a stream of primitive
42 * types in the Java programming language. It is filled and read sequentially.
43 * It inherits from the <CODE>Message</CODE> interface
44 * and adds a stream message body. Its methods are based largely on those
45 * found in <CODE>java.io.DataInputStream</CODE> and
46 * <CODE>java.io.DataOutputStream</CODE>.
47 *
48 * <P>The primitive types can be read or written explicitly using methods
49 * for each type. They may also be read or written generically as objects.
50 * For instance, a call to <CODE>StreamMessage.writeInt(6)</CODE> is
51 * equivalent to <CODE>StreamMessage.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 body 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 * <P><CODE>StreamMessage</CODE> objects support the following conversion
76 * table. The marked cases must be supported. The unmarked cases must throw a
77 * <CODE>JMSException</CODE>. The <CODE>String</CODE>-to-primitive conversions
78 * may throw a runtime exception if the primitive's <CODE>valueOf()</CODE>
79 * method does not accept it as a valid <CODE>String</CODE> representation of
80 * the primitive.
81 *
82 * <P>A value written as the row type can be read as the column type.
83 *
84 * <PRE>
85 * | | boolean byte short char int long float double String byte[]
86 * |----------------------------------------------------------------------
87 * |boolean | X X
88 * |byte | X X X X X
89 * |short | X X X X
90 * |char | X X
91 * |int | X X X
92 * |long | X X
93 * |float | X X X
94 * |double | X X
95 * |String | X X X X X X X X
96 * |byte[] | X
97 * |----------------------------------------------------------------------
98 * </PRE>
99 *
100 * <P>Attempting to read a null value as a primitive type must be treated
101 * as calling the primitive's corresponding <code>valueOf(String)</code>
102 * conversion method with a null value. Since <code>char</code> does not
103 * support a <code>String</code> conversion, attempting to read a null value
104 * as a <code>char</code> must throw a <code>NullPointerException</code>.
105 *
106 * @see javax.jms.BytesMessage
107 * @see javax.jms.MapMessage
108 * @see javax.jms.Message
109 * @see javax.jms.ObjectMessage
110 * @see javax.jms.TextMessage
111 */
112
113 public interface StreamMessage extends Message {
114
115
116 /** Reads a <code>boolean</code> from the stream message.
117 *
118 * @return the <code>boolean</code> value read
119 *
120 * @exception JMSException if the JMS provider fails to read the message
121 * due to some internal error.
122 * @exception MessageEOFException if unexpected end of message stream has
123 * been reached.
124 * @exception MessageFormatException if this type conversion is invalid.
125 * @exception MessageNotReadableException if the message is in write-only
126 * mode.
127 */
128
129 boolean
130 readBoolean() throws JMSException;
131
132
133 /** Reads a <code>byte</code> value from the stream message.
134 *
135 * @return the next byte from the stream message as a 8-bit
136 * <code>byte</code>
137 *
138 * @exception JMSException if the JMS provider fails to read the message
139 * due to some internal error.
140 * @exception MessageEOFException if unexpected end of message stream has
141 * been reached.
142 * @exception MessageFormatException if this type conversion is invalid.
143 * @exception MessageNotReadableException if the message is in write-only
144 * mode.
145 */
146
147 byte
148 readByte() throws JMSException;
149
150
151 /** Reads a 16-bit integer from the stream message.
152 *
153 * @return a 16-bit integer from the stream message
154 *
155 * @exception JMSException if the JMS provider fails to read the message
156 * due to some internal error.
157 * @exception MessageEOFException if unexpected end of message stream has
158 * been reached.
159 * @exception MessageFormatException if this type conversion is invalid.
160 * @exception MessageNotReadableException if the message is in write-only
161 * mode.
162 */
163
164 short
165 readShort() throws JMSException;
166
167
168 /** Reads a Unicode character value from the stream message.
169 *
170 * @return a Unicode character from the stream message
171 *
172 * @exception JMSException if the JMS provider fails to read the message
173 * due to some internal error.
174 * @exception MessageEOFException if unexpected end of message stream has
175 * been reached.
176 * @exception MessageFormatException if this type conversion is invalid
177 * @exception MessageNotReadableException if the message is in write-only
178 * mode.
179 */
180
181 char
182 readChar() throws JMSException;
183
184
185 /** Reads a 32-bit integer from the stream message.
186 *
187 * @return a 32-bit integer value from the stream message, interpreted
188 * as an <code>int</code>
189 *
190 * @exception JMSException if the JMS provider fails to read the message
191 * due to some internal error.
192 * @exception MessageEOFException if unexpected end of message stream has
193 * been reached.
194 * @exception MessageFormatException if this type conversion is invalid.
195 * @exception MessageNotReadableException if the message is in write-only
196 * mode.
197 */
198
199 int
200 readInt() throws JMSException;
201
202
203 /** Reads a 64-bit integer from the stream message.
204 *
205 * @return a 64-bit integer value from the stream message, interpreted as
206 * a <code>long</code>
207 *
208 * @exception JMSException if the JMS provider fails to read the message
209 * due to some internal error.
210 * @exception MessageEOFException if unexpected end of message stream has
211 * been reached.
212 * @exception MessageFormatException if this type conversion is invalid.
213 * @exception MessageNotReadableException if the message is in write-only
214 * mode.
215 */
216
217 long
218 readLong() throws JMSException;
219
220
221 /** Reads a <code>float</code> from the stream message.
222 *
223 * @return a <code>float</code> value from the stream message
224 *
225 * @exception JMSException if the JMS provider fails to read the message
226 * due to some internal error.
227 * @exception MessageEOFException if unexpected end of message stream has
228 * been reached.
229 * @exception MessageFormatException if this type conversion is invalid.
230 * @exception MessageNotReadableException if the message is in write-only
231 * mode.
232 */
233
234 float
235 readFloat() throws JMSException;
236
237
238 /** Reads a <code>double</code> from the stream message.
239 *
240 * @return a <code>double</code> value from the stream message
241 *
242 * @exception JMSException if the JMS provider fails to read the message
243 * due to some internal error.
244 * @exception MessageEOFException if unexpected end of message stream has
245 * been reached.
246 * @exception MessageFormatException if this type conversion is invalid.
247 * @exception MessageNotReadableException if the message is in write-only
248 * mode.
249 */
250
251 double
252 readDouble() throws JMSException;
253
254
255 /** Reads a <CODE>String</CODE> from the stream message.
256 *
257 * @return a Unicode string from the stream message
258 *
259 * @exception JMSException if the JMS provider fails to read the message
260 * due to some internal error.
261 * @exception MessageEOFException if unexpected end of message stream has
262 * been reached.
263 * @exception MessageFormatException if this type conversion is invalid.
264 * @exception MessageNotReadableException if the message is in write-only
265 * mode.
266 */
267
268 String
269 readString() throws JMSException;
270
271
272 /** Reads a byte array field from the stream message into the
273 * specified <CODE>byte[]</CODE> object (the read buffer).
274 *
275 * <P>To read the field value, <CODE>readBytes</CODE> should be
276 * successively called
277 * until it returns a value less than the length of the read buffer.
278 * The value of the bytes in the buffer following the last byte
279 * read is undefined.
280 *
281 * <P>If <CODE>readBytes</CODE> returns a value equal to the length of the
282 * buffer, a subsequent <CODE>readBytes</CODE> call must be made. If there
283 * are no more bytes to be read, this call returns -1.
284 *
285 * <P>If the byte array field value is null, <CODE>readBytes</CODE>
286 * returns -1.
287 *
288 * <P>If the byte array field value is empty, <CODE>readBytes</CODE>
289 * returns 0.
290 *
291 * <P>Once the first <CODE>readBytes</CODE> call on a <CODE>byte[]</CODE>
292 * field value has been made,
293 * the full value of the field must be read before it is valid to read
294 * the next field. An attempt to read the next field before that has
295 * been done will throw a <CODE>MessageFormatException</CODE>.
296 *
297 * <P>To read the byte field value into a new <CODE>byte[]</CODE> object,
298 * use the <CODE>readObject</CODE> method.
299 *
300 * @param value the buffer into which the data is read
301 *
302 * @return the total number of bytes read into the buffer, or -1 if
303 * there is no more data because the end of the byte field has been
304 * reached
305 *
306 * @exception JMSException if the JMS provider fails to read the message
307 * due to some internal error.
308 * @exception MessageEOFException if unexpected end of message stream has
309 * been reached.
310 * @exception MessageFormatException if this type conversion is invalid.
311 * @exception MessageNotReadableException if the message is in write-only
312 * mode.
313 *
314 * @see #readObject()
315 */
316
317 int
318 readBytes(byte[] value) throws JMSException;
319
320
321 /** Reads an object from the stream message.
322 *
323 * <P>This method can be used to return, in objectified format,
324 * an object in the Java programming language ("Java object") that has
325 * been written to the stream with the equivalent
326 * <CODE>writeObject</CODE> method call, or its equivalent primitive
327 * <CODE>write<I>type</I></CODE> method.
328 *
329 * <P>Note that byte values are returned as <CODE>byte[]</CODE>, not
330 * <CODE>Byte[]</CODE>.
331 *
332 * <P>An attempt to call <CODE>readObject</CODE> to read a byte field
333 * value into a new <CODE>byte[]</CODE> object before the full value of the
334 * byte field has been read will throw a
335 * <CODE>MessageFormatException</CODE>.
336 *
337 * @return a Java object from the stream message, in objectified
338 * format (for example, if the object was written as an <CODE>int</CODE>,
339 * an <CODE>Integer</CODE> is returned)
340 *
341 * @exception JMSException if the JMS provider fails to read the message
342 * due to some internal error.
343 * @exception MessageEOFException if unexpected end of message stream has
344 * been reached.
345 * @exception MessageFormatException if this type conversion is invalid.
346 * @exception MessageNotReadableException if the message is in write-only
347 * mode.
348 *
349 * @see #readBytes(byte[] value)
350 */
351
352 Object
353 readObject() throws JMSException;
354
355
356
357 /** Writes a <code>boolean</code> to the stream message.
358 * The value <code>true</code> is written as the value
359 * <code>(byte)1</code>; the value <code>false</code> is written as
360 * the value <code>(byte)0</code>.
361 *
362 * @param value the <code>boolean</code> value to be written
363 *
364 * @exception JMSException if the JMS provider fails to write the message
365 * due to some internal error.
366 * @exception MessageNotWriteableException if the message is in read-only
367 * mode.
368 */
369
370 void
371 writeBoolean(boolean value)
372 throws JMSException;
373
374
375 /** Writes a <code>byte</code> to the stream message.
376 *
377 * @param value the <code>byte</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 writeByte(byte value) throws JMSException;
387
388
389 /** Writes a <code>short</code> to the stream message.
390 *
391 * @param value the <code>short</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 writeShort(short value) throws JMSException;
401
402
403 /** Writes a <code>char</code> to the stream message.
404 *
405 * @param value the <code>char</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 writeChar(char value) throws JMSException;
415
416
417 /** Writes an <code>int</code> to the stream message.
418 *
419 * @param value the <code>int</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 writeInt(int value) throws JMSException;
429
430
431 /** Writes a <code>long</code> to the stream message.
432 *
433 * @param value the <code>long</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 writeLong(long value) throws JMSException;
443
444
445 /** Writes a <code>float</code> to the stream message.
446 *
447 * @param value the <code>float</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 writeFloat(float value) throws JMSException;
457
458
459 /** Writes a <code>double</code> to the stream message.
460 *
461 * @param value the <code>double</code> value to be written
462 *
463 * @exception JMSException if the JMS provider fails to write the message
464 * due to some internal error.
465 * @exception MessageNotWriteableException if the message is in read-only
466 * mode.
467 */
468
469 void
470 writeDouble(double value) throws JMSException;
471
472
473 /** Writes a <code>String</code> to the stream message.
474 *
475 * @param value the <code>String</code> value to be written
476 *
477 * @exception JMSException if the JMS provider fails to write the message
478 * due to some internal error.
479 * @exception MessageNotWriteableException if the message is in read-only
480 * mode.
481 */
482
483 void
484 writeString(String value) throws JMSException;
485
486
487 /** Writes a byte array field to the stream message.
488 *
489 * <P>The byte array <code>value</code> is written to the message
490 * as a byte array field. Consecutively written byte array fields are
491 * treated as two distinct fields when the fields are read.
492 *
493 * @param value the byte array value to be written
494 *
495 * @exception JMSException if the JMS provider fails to write the message
496 * due to some internal error.
497 * @exception MessageNotWriteableException if the message is in read-only
498 * mode.
499 */
500
501 void
502 writeBytes(byte[] value) throws JMSException;
503
504
505 /** Writes a portion of a byte array as a byte array field to the stream
506 * message.
507 *
508 * <P>The a portion of the byte array <code>value</code> is written to the
509 * message as a byte array field. Consecutively written byte
510 * array fields are treated as two distinct fields when the fields are
511 * read.
512 *
513 * @param value the byte array value to be written
514 * @param offset the initial offset within the byte array
515 * @param length the number of bytes to use
516 *
517 * @exception JMSException if the JMS provider fails to write the message
518 * due to some internal error.
519 * @exception MessageNotWriteableException if the message is in read-only
520 * mode.
521 */
522
523 void
524 writeBytes(byte[] value, int offset, int length)
525 throws JMSException;
526
527
528 /** Writes an object to the stream message.
529 *
530 * <P>This method works only for the objectified primitive
531 * object types (<code>Integer</code>, <code>Double</code>,
532 * <code>Long</code> ...), <code>String</code> objects, and byte
533 * arrays.
534 *
535 * @param value the Java object to be written
536 *
537 * @exception JMSException if the JMS provider fails to write the message
538 * due to some internal error.
539 * @exception MessageFormatException if the object is invalid.
540 * @exception MessageNotWriteableException if the message is in read-only
541 * mode.
542 */
543
544 void
545 writeObject(Object value) throws JMSException;
546
547
548 /** Puts the message body in read-only mode and repositions the stream
549 * to the beginning.
550 *
551 * @exception JMSException if the JMS provider fails to reset the message
552 * due to some internal error.
553 * @exception MessageFormatException if the message has an invalid
554 * format.
555 */
556
557 void
558 reset() throws JMSException;
559 }
Save This Page