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