001: /*
002: * @(#)StreamMessage.java 1.40 02/04/09
003: *
004: * Copyright 1997-2002 Sun Microsystems, Inc. All Rights Reserved.
005: *
006: * SUN PROPRIETARY/CONFIDENTIAL.
007: * This software is the proprietary information of Sun Microsystems, Inc.
008: * Use is subject to license terms.
009: *
010: */
011:
012: package javax.jms;
013:
014: /** A <CODE>StreamMessage</CODE> object is used to send a stream of primitive
015: * types in the Java programming language. It is filled and read sequentially.
016: * It inherits from the <CODE>Message</CODE> interface
017: * and adds a stream message body. Its methods are based largely on those
018: * found in <CODE>java.io.DataInputStream</CODE> and
019: * <CODE>java.io.DataOutputStream</CODE>.
020: *
021: * <P>The primitive types can be read or written explicitly using methods
022: * for each type. They may also be read or written generically as objects.
023: * For instance, a call to <CODE>StreamMessage.writeInt(6)</CODE> is
024: * equivalent to <CODE>StreamMessage.writeObject(new Integer(6))</CODE>.
025: * Both forms are provided, because the explicit form is convenient for
026: * static programming, and the object form is needed when types are not known
027: * at compile time.
028: *
029: * <P>When the message is first created, and when <CODE>clearBody</CODE>
030: * is called, the body of the message is in write-only mode. After the
031: * first call to <CODE>reset</CODE> has been made, the message body is in
032: * read-only mode.
033: * After a message has been sent, the client that sent it can retain and
034: * modify it without affecting the message that has been sent. The same message
035: * object can be sent multiple times.
036: * When a message has been received, the provider has called
037: * <CODE>reset</CODE> so that the message body is in read-only mode for the client.
038: *
039: * <P>If <CODE>clearBody</CODE> is called on a message in read-only mode,
040: * the message body is cleared and the message body is in write-only mode.
041: *
042: * <P>If a client attempts to read a message in write-only mode, a
043: * <CODE>MessageNotReadableException</CODE> is thrown.
044: *
045: * <P>If a client attempts to write a message in read-only mode, a
046: * <CODE>MessageNotWriteableException</CODE> is thrown.
047: *
048: * <P><CODE>StreamMessage</CODE> objects support the following conversion
049: * table. The marked cases must be supported. The unmarked cases must throw a
050: * <CODE>JMSException</CODE>. The <CODE>String</CODE>-to-primitive conversions
051: * may throw a runtime exception if the primitive's <CODE>valueOf()</CODE>
052: * method does not accept it as a valid <CODE>String</CODE> representation of
053: * the primitive.
054: *
055: * <P>A value written as the row type can be read as the column type.
056: *
057: * <PRE>
058: * | | boolean byte short char int long float double String byte[]
059: * |----------------------------------------------------------------------
060: * |boolean | X X
061: * |byte | X X X X X
062: * |short | X X X X
063: * |char | X X
064: * |int | X X X
065: * |long | X X
066: * |float | X X X
067: * |double | X X
068: * |String | X X X X X X X X
069: * |byte[] | X
070: * |----------------------------------------------------------------------
071: * </PRE>
072: *
073: * <P>Attempting to read a null value as a primitive type must be treated
074: * as calling the primitive's corresponding <code>valueOf(String)</code>
075: * conversion method with a null value. Since <code>char</code> does not
076: * support a <code>String</code> conversion, attempting to read a null value
077: * as a <code>char</code> must throw a <code>NullPointerException</code>.
078: *
079: * @version 1.0 - 6 August 1998
080: * @author Mark Hapner
081: * @author Rich Burridge
082: *
083: * @see javax.jms.Session#createStreamMessage()
084: * @see javax.jms.BytesMessage
085: * @see javax.jms.MapMessage
086: * @see javax.jms.Message
087: * @see javax.jms.ObjectMessage
088: * @see javax.jms.TextMessage
089: */
090:
091: public interface StreamMessage extends Message {
092:
093: /** Reads a <code>boolean</code> from the stream message.
094: *
095: * @return the <code>boolean</code> value read
096: *
097: * @exception JMSException if the JMS provider fails to read the message
098: * due to some internal error.
099: * @exception MessageEOFException if unexpected end of message stream has
100: * been reached.
101: * @exception MessageFormatException if this type conversion is invalid.
102: * @exception MessageNotReadableException if the message is in write-only
103: * mode.
104: */
105:
106: boolean readBoolean() throws JMSException;
107:
108: /** Reads a <code>byte</code> value from the stream message.
109: *
110: * @return the next byte from the stream message as a 8-bit
111: * <code>byte</code>
112: *
113: * @exception JMSException if the JMS provider fails to read the message
114: * due to some internal error.
115: * @exception MessageEOFException if unexpected end of message stream has
116: * been reached.
117: * @exception MessageFormatException if this type conversion is invalid.
118: * @exception MessageNotReadableException if the message is in write-only
119: * mode.
120: */
121:
122: byte readByte() throws JMSException;
123:
124: /** Reads a 16-bit integer from the stream message.
125: *
126: * @return a 16-bit integer from the stream message
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 message stream has
131: * been reached.
132: * @exception MessageFormatException if this type conversion is invalid.
133: * @exception MessageNotReadableException if the message is in write-only
134: * mode.
135: */
136:
137: short readShort() throws JMSException;
138:
139: /** Reads a Unicode character value from the stream message.
140: *
141: * @return a Unicode character from the stream message
142: *
143: * @exception JMSException if the JMS provider fails to read the message
144: * due to some internal error.
145: * @exception MessageEOFException if unexpected end of message stream has
146: * been reached.
147: * @exception MessageFormatException if this type conversion is invalid
148: * @exception MessageNotReadableException if the message is in write-only
149: * mode.
150: */
151:
152: char readChar() throws JMSException;
153:
154: /** Reads a 32-bit integer from the stream message.
155: *
156: * @return a 32-bit integer value from the stream message, interpreted
157: * as an <code>int</code>
158: *
159: * @exception JMSException if the JMS provider fails to read the message
160: * due to some internal error.
161: * @exception MessageEOFException if unexpected end of message stream has
162: * been reached.
163: * @exception MessageFormatException if this type conversion is invalid.
164: * @exception MessageNotReadableException if the message is in write-only
165: * mode.
166: */
167:
168: int readInt() throws JMSException;
169:
170: /** Reads a 64-bit integer from the stream message.
171: *
172: * @return a 64-bit integer value from the stream message, interpreted as
173: * a <code>long</code>
174: *
175: * @exception JMSException if the JMS provider fails to read the message
176: * due to some internal error.
177: * @exception MessageEOFException if unexpected end of message stream has
178: * been reached.
179: * @exception MessageFormatException if this type conversion is invalid.
180: * @exception MessageNotReadableException if the message is in write-only
181: * mode.
182: */
183:
184: long readLong() throws JMSException;
185:
186: /** Reads a <code>float</code> from the stream message.
187: *
188: * @return a <code>float</code> value from the stream message
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: float readFloat() throws JMSException;
200:
201: /** Reads a <code>double</code> from the stream message.
202: *
203: * @return a <code>double</code> value from the stream message
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 message stream has
208: * been reached.
209: * @exception MessageFormatException if this type conversion is invalid.
210: * @exception MessageNotReadableException if the message is in write-only
211: * mode.
212: */
213:
214: double readDouble() throws JMSException;
215:
216: /** Reads a <CODE>String</CODE> from the stream message.
217: *
218: * @return a Unicode string from the stream message
219: *
220: * @exception JMSException if the JMS provider fails to read the message
221: * due to some internal error.
222: * @exception MessageEOFException if unexpected end of message stream has
223: * been reached.
224: * @exception MessageFormatException if this type conversion is invalid.
225: * @exception MessageNotReadableException if the message is in write-only
226: * mode.
227: */
228:
229: String readString() throws JMSException;
230:
231: /** Reads a byte array field from the stream message into the
232: * specified <CODE>byte[]</CODE> object (the read buffer).
233: *
234: * <P>To read the field value, <CODE>readBytes</CODE> should be
235: * successively called
236: * until it returns a value less than the length of the read buffer.
237: * The value of the bytes in the buffer following the last byte
238: * read is undefined.
239: *
240: * <P>If <CODE>readBytes</CODE> returns a value equal to the length of the
241: * buffer, a subsequent <CODE>readBytes</CODE> call must be made. If there
242: * are no more bytes to be read, this call returns -1.
243: *
244: * <P>If the byte array field value is null, <CODE>readBytes</CODE>
245: * returns -1.
246: *
247: * <P>If the byte array field value is empty, <CODE>readBytes</CODE>
248: * returns 0.
249: *
250: * <P>Once the first <CODE>readBytes</CODE> call on a <CODE>byte[]</CODE>
251: * field value has been made,
252: * the full value of the field must be read before it is valid to read
253: * the next field. An attempt to read the next field before that has
254: * been done will throw a <CODE>MessageFormatException</CODE>.
255: *
256: * <P>To read the byte field value into a new <CODE>byte[]</CODE> object,
257: * use the <CODE>readObject</CODE> method.
258: *
259: * @param value the buffer into which the data is read
260: *
261: * @return the total number of bytes read into the buffer, or -1 if
262: * there is no more data because the end of the byte field has been
263: * reached
264: *
265: * @exception JMSException if the JMS provider fails to read the message
266: * due to some internal error.
267: * @exception MessageEOFException if unexpected end of message stream has
268: * been reached.
269: * @exception MessageFormatException if this type conversion is invalid.
270: * @exception MessageNotReadableException if the message is in write-only
271: * mode.
272: *
273: * @see #readObject()
274: */
275:
276: int readBytes(byte[] value) throws JMSException;
277:
278: /** Reads an object from the stream message.
279: *
280: * <P>This method can be used to return, in objectified format,
281: * an object in the Java programming language ("Java object") that has
282: * been written to the stream with the equivalent
283: * <CODE>writeObject</CODE> method call, or its equivalent primitive
284: * <CODE>write<I>type</I></CODE> method.
285: *
286: * <P>Note that byte values are returned as <CODE>byte[]</CODE>, not
287: * <CODE>Byte[]</CODE>.
288: *
289: * <P>An attempt to call <CODE>readObject</CODE> to read a byte field
290: * value into a new <CODE>byte[]</CODE> object before the full value of the
291: * byte field has been read will throw a
292: * <CODE>MessageFormatException</CODE>.
293: *
294: * @return a Java object from the stream message, in objectified
295: * format (for example, if the object was written as an <CODE>int</CODE>,
296: * an <CODE>Integer</CODE> is returned)
297: *
298: * @exception JMSException if the JMS provider fails to read the message
299: * due to some internal error.
300: * @exception MessageEOFException if unexpected end of message stream has
301: * been reached.
302: * @exception MessageFormatException if this type conversion is invalid.
303: * @exception MessageNotReadableException if the message is in write-only
304: * mode.
305: *
306: * @see #readBytes(byte[] value)
307: */
308:
309: Object readObject() throws JMSException;
310:
311: /** Writes a <code>boolean</code> to the stream message.
312: * The value <code>true</code> is written as the value
313: * <code>(byte)1</code>; the value <code>false</code> is written as
314: * the value <code>(byte)0</code>.
315: *
316: * @param value the <code>boolean</code> value to be written
317: *
318: * @exception JMSException if the JMS provider fails to write the message
319: * due to some internal error.
320: * @exception MessageNotWriteableException if the message is in read-only
321: * mode.
322: */
323:
324: void writeBoolean(boolean value) throws JMSException;
325:
326: /** Writes a <code>byte</code> to the stream message.
327: *
328: * @param value the <code>byte</code> value to be written
329: *
330: * @exception JMSException if the JMS provider fails to write the message
331: * due to some internal error.
332: * @exception MessageNotWriteableException if the message is in read-only
333: * mode.
334: */
335:
336: void writeByte(byte value) throws JMSException;
337:
338: /** Writes a <code>short</code> to the stream message.
339: *
340: * @param value the <code>short</code> value to be written
341: *
342: * @exception JMSException if the JMS provider fails to write the message
343: * due to some internal error.
344: * @exception MessageNotWriteableException if the message is in read-only
345: * mode.
346: */
347:
348: void writeShort(short value) throws JMSException;
349:
350: /** Writes a <code>char</code> to the stream message.
351: *
352: * @param value the <code>char</code> value to be written
353: *
354: * @exception JMSException if the JMS provider fails to write the message
355: * due to some internal error.
356: * @exception MessageNotWriteableException if the message is in read-only
357: * mode.
358: */
359:
360: void writeChar(char value) throws JMSException;
361:
362: /** Writes an <code>int</code> to the stream message.
363: *
364: * @param value the <code>int</code> value to be written
365: *
366: * @exception JMSException if the JMS provider fails to write the message
367: * due to some internal error.
368: * @exception MessageNotWriteableException if the message is in read-only
369: * mode.
370: */
371:
372: void writeInt(int value) throws JMSException;
373:
374: /** Writes a <code>long</code> to the stream message.
375: *
376: * @param value the <code>long</code> value to be written
377: *
378: * @exception JMSException if the JMS provider fails to write the message
379: * due to some internal error.
380: * @exception MessageNotWriteableException if the message is in read-only
381: * mode.
382: */
383:
384: void writeLong(long value) throws JMSException;
385:
386: /** Writes a <code>float</code> to the stream message.
387: *
388: * @param value the <code>float</code> value to be written
389: *
390: * @exception JMSException if the JMS provider fails to write the message
391: * due to some internal error.
392: * @exception MessageNotWriteableException if the message is in read-only
393: * mode.
394: */
395:
396: void writeFloat(float value) throws JMSException;
397:
398: /** Writes a <code>double</code> to the stream message.
399: *
400: * @param value the <code>double</code> value to be written
401: *
402: * @exception JMSException if the JMS provider fails to write the message
403: * due to some internal error.
404: * @exception MessageNotWriteableException if the message is in read-only
405: * mode.
406: */
407:
408: void writeDouble(double value) throws JMSException;
409:
410: /** Writes a <code>String</code> to the stream message.
411: *
412: * @param value the <code>String</code> value to be written
413: *
414: * @exception JMSException if the JMS provider fails to write the message
415: * due to some internal error.
416: * @exception MessageNotWriteableException if the message is in read-only
417: * mode.
418: */
419:
420: void writeString(String value) throws JMSException;
421:
422: /** Writes a byte array field to the stream message.
423: *
424: * <P>The byte array <code>value</code> is written to the message
425: * as a byte array field. Consecutively written byte array fields are
426: * treated as two distinct fields when the fields are read.
427: *
428: * @param value the byte array value to be written
429: *
430: * @exception JMSException if the JMS provider fails to write the message
431: * due to some internal error.
432: * @exception MessageNotWriteableException if the message is in read-only
433: * mode.
434: */
435:
436: void writeBytes(byte[] value) throws JMSException;
437:
438: /** Writes a portion of a byte array as a byte array field to the stream
439: * message.
440: *
441: * <P>The a portion of the byte array <code>value</code> is written to the
442: * message as a byte array field. Consecutively written byte
443: * array fields are treated as two distinct fields when the fields are
444: * read.
445: *
446: * @param value the byte array value to be written
447: * @param offset the initial offset within the byte array
448: * @param length the number of bytes to use
449: *
450: * @exception JMSException if the JMS provider fails to write the message
451: * due to some internal error.
452: * @exception MessageNotWriteableException if the message is in read-only
453: * mode.
454: */
455:
456: void writeBytes(byte[] value, int offset, int length)
457: throws JMSException;
458:
459: /** Writes an object to the stream message.
460: *
461: * <P>This method works only for the objectified primitive
462: * object types (<code>Integer</code>, <code>Double</code>,
463: * <code>Long</code> ...), <code>String</code> objects, and byte
464: * arrays.
465: *
466: * @param value the Java object to be written
467: *
468: * @exception JMSException if the JMS provider fails to write the message
469: * due to some internal error.
470: * @exception MessageFormatException if the object is invalid.
471: * @exception MessageNotWriteableException if the message is in read-only
472: * mode.
473: */
474:
475: void writeObject(Object value) throws JMSException;
476:
477: /** Puts the message body in read-only mode and repositions the stream
478: * to the beginning.
479: *
480: * @exception JMSException if the JMS provider fails to reset the message
481: * due to some internal error.
482: * @exception MessageFormatException if the message has an invalid
483: * format.
484: */
485:
486: void reset() throws JMSException;
487: }
|