001: /*
002: * @(#)BytesMessage.java 1.31 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: import java.io.InputStream;
015: import java.io.OutputStream;
016:
017: /** A <CODE>BytesMessage</CODE> object is used to send a message containing a
018: * stream of uninterpreted bytes. It inherits from the <CODE>Message</CODE>
019: * interface and adds a bytes
020: * message body. The receiver of the message supplies the interpretation
021: * of the bytes.
022: *
023: * <P>The <CODE>BytesMessage</CODE> methods are based largely on those found in
024: * <CODE>java.io.DataInputStream</CODE> and
025: * <CODE>java.io.DataOutputStream</CODE>.
026: *
027: * <P>This message type is for client encoding of existing message formats.
028: * If possible, one of the other self-defining message types should be used
029: * instead.
030: *
031: * <P>Although the JMS API allows the use of message properties with byte
032: * messages, they are typically not used, since the inclusion of properties
033: * may affect the format.
034: *
035: * <P>The primitive types can be written explicitly using methods
036: * for each type. They may also be written generically as objects.
037: * For instance, a call to <CODE>BytesMessage.writeInt(6)</CODE> is
038: * equivalent to <CODE>BytesMessage.writeObject(new Integer(6))</CODE>.
039: * Both forms are provided, because the explicit form is convenient for
040: * static programming, and the object form is needed when types are not known
041: * at compile time.
042: *
043: * <P>When the message is first created, and when <CODE>clearBody</CODE>
044: * is called, the body of the message is in write-only mode. After the
045: * first call to <CODE>reset</CODE> has been made, the message body is in
046: * read-only mode.
047: * After a message has been sent, the client that sent it can retain and
048: * modify it without affecting the message that has been sent. The same message
049: * object can be sent multiple times.
050: * When a message has been received, the provider has called
051: * <CODE>reset</CODE> so that the message body is in read-only mode for the client.
052: *
053: * <P>If <CODE>clearBody</CODE> is called on a message in read-only mode,
054: * the message body is cleared and the message is in write-only mode.
055: *
056: * <P>If a client attempts to read a message in write-only mode, a
057: * <CODE>MessageNotReadableException</CODE> is thrown.
058: *
059: * <P>If a client attempts to write a message in read-only mode, a
060: * <CODE>MessageNotWriteableException</CODE> is thrown.
061: *
062: * @version 1.1 April 2, 2002
063: * @author Mark Hapner
064: * @author Rich Burridge
065: * @author Kate Stout
066: *
067: * @see javax.jms.Session#createBytesMessage()
068: * @see javax.jms.MapMessage
069: * @see javax.jms.Message
070: * @see javax.jms.ObjectMessage
071: * @see javax.jms.StreamMessage
072: * @see javax.jms.TextMessage
073: */
074:
075: public interface BytesMessage extends Message {
076:
077: /** Gets the number of bytes of the message body when the message
078: * is in read-only mode. The value returned can be used to allocate
079: * a byte array. The value returned is the entire length of the message
080: * body, regardless of where the pointer for reading the message
081: * is currently located.
082: *
083: * @return number of bytes in the message
084: * @exception JMSException if the JMS provider fails to read the message
085: * due to some internal error.
086: * @exception MessageNotReadableException if the message is in write-only
087: * mode.
088: * @since 1.1
089: */
090:
091: long getBodyLength() throws JMSException;
092:
093: /** Reads a <code>boolean</code> from the bytes message stream.
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 bytes stream has
100: * been reached.
101: * @exception MessageNotReadableException if the message is in write-only
102: * mode.
103: */
104:
105: boolean readBoolean() throws JMSException;
106:
107: /** Reads a signed 8-bit value from the bytes message stream.
108: *
109: * @return the next byte from the bytes message stream as a signed 8-bit
110: * <code>byte</code>
111: *
112: * @exception JMSException if the JMS provider fails to read the message
113: * due to some internal error.
114: * @exception MessageEOFException if unexpected end of bytes stream has
115: * been reached.
116: * @exception MessageNotReadableException if the message is in write-only
117: * mode.
118: */
119:
120: byte readByte() throws JMSException;
121:
122: /** Reads an unsigned 8-bit number from the bytes message stream.
123: *
124: * @return the next byte from the bytes message stream, interpreted as an
125: * unsigned 8-bit number
126: *
127: * @exception JMSException if the JMS provider fails to read the message
128: * due to some internal error.
129: * @exception MessageEOFException if unexpected end of bytes stream has
130: * been reached.
131: * @exception MessageNotReadableException if the message is in write-only
132: * mode.
133: */
134:
135: int readUnsignedByte() throws JMSException;
136:
137: /** Reads a signed 16-bit number from the bytes message stream.
138: *
139: * @return the next two bytes from the bytes message stream, interpreted as
140: * a signed 16-bit number
141: *
142: * @exception JMSException if the JMS provider fails to read the message
143: * due to some internal error.
144: * @exception MessageEOFException if unexpected end of bytes stream has
145: * been reached.
146: * @exception MessageNotReadableException if the message is in write-only
147: * mode.
148: */
149:
150: short readShort() throws JMSException;
151:
152: /** Reads an unsigned 16-bit number from the bytes message stream.
153: *
154: * @return the next two bytes from the bytes message stream, interpreted as
155: * an unsigned 16-bit integer
156: *
157: * @exception JMSException if the JMS provider fails to read the message
158: * due to some internal error.
159: * @exception MessageEOFException if unexpected end of bytes stream has
160: * been reached.
161: * @exception MessageNotReadableException if the message is in write-only
162: * mode.
163: */
164:
165: int readUnsignedShort() throws JMSException;
166:
167: /** Reads a Unicode character value from the bytes message stream.
168: *
169: * @return the next two bytes from the bytes message stream as a Unicode
170: * character
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 bytes stream has
175: * been reached.
176: * @exception MessageNotReadableException if the message is in write-only
177: * mode.
178: */
179:
180: char readChar() throws JMSException;
181:
182: /** Reads a signed 32-bit integer from the bytes message stream.
183: *
184: * @return the next four bytes from the bytes message stream, interpreted
185: * as an <code>int</code>
186: *
187: * @exception JMSException if the JMS provider fails to read the message
188: * due to some internal error.
189: * @exception MessageEOFException if unexpected end of bytes stream has
190: * been reached.
191: * @exception MessageNotReadableException if the message is in write-only
192: * mode.
193: */
194:
195: int readInt() throws JMSException;
196:
197: /** Reads a signed 64-bit integer from the bytes message stream.
198: *
199: * @return the next eight bytes from the bytes message stream, interpreted
200: * as a <code>long</code>
201: *
202: * @exception JMSException if the JMS provider fails to read the message
203: * due to some internal error.
204: * @exception MessageEOFException if unexpected end of bytes stream has
205: * been reached.
206: * @exception MessageNotReadableException if the message is in write-only
207: * mode.
208: */
209:
210: long readLong() throws JMSException;
211:
212: /** Reads a <code>float</code> from the bytes message stream.
213: *
214: * @return the next four bytes from the bytes message stream, interpreted
215: * as a <code>float</code>
216: *
217: * @exception JMSException if the JMS provider fails to read the message
218: * due to some internal error.
219: * @exception MessageEOFException if unexpected end of bytes stream has
220: * been reached.
221: * @exception MessageNotReadableException if the message is in write-only
222: * mode.
223: */
224:
225: float readFloat() throws JMSException;
226:
227: /** Reads a <code>double</code> from the bytes message stream.
228: *
229: * @return the next eight bytes from the bytes message stream, interpreted
230: * as a <code>double</code>
231: *
232: * @exception JMSException if the JMS provider fails to read the message
233: * due to some internal error.
234: * @exception MessageEOFException if unexpected end of bytes stream has
235: * been reached.
236: * @exception MessageNotReadableException if the message is in write-only
237: * mode.
238: */
239:
240: double readDouble() throws JMSException;
241:
242: /** Reads a string that has been encoded using a modified UTF-8
243: * format from the bytes message stream.
244: *
245: * <P>For more information on the UTF-8 format, see "File System Safe
246: * UCS Transformation Format (FSS_UTF)", X/Open Preliminary Specification,
247: * X/Open Company Ltd., Document Number: P316. This information also
248: * appears in ISO/IEC 10646, Annex P.
249: *
250: * @return a Unicode string from the bytes message stream
251: *
252: * @exception JMSException if the JMS provider fails to read the message
253: * due to some internal error.
254: * @exception MessageEOFException if unexpected end of bytes stream has
255: * been reached.
256: * @exception MessageNotReadableException if the message is in write-only
257: * mode.
258: */
259:
260: String readUTF() throws JMSException;
261:
262: /** Reads a byte array from the bytes message stream.
263: *
264: * <P>If the length of array <code>value</code> is less than the number of
265: * bytes remaining to be read from the stream, the array should
266: * be filled. A subsequent call reads the next increment, and so on.
267: *
268: * <P>If the number of bytes remaining in the stream is less than the
269: * length of
270: * array <code>value</code>, the bytes should be read into the array.
271: * The return value of the total number of bytes read will be less than
272: * the length of the array, indicating that there are no more bytes left
273: * to be read from the stream. The next read of the stream returns -1.
274: *
275: * @param value the buffer into which the data is read
276: *
277: * @return the total number of bytes read into the buffer, or -1 if
278: * there is no more data because the end of the stream has been reached
279: *
280: * @exception JMSException if the JMS provider fails to read the message
281: * due to some internal error.
282: * @exception MessageNotReadableException if the message is in write-only
283: * mode.
284: */
285:
286: int readBytes(byte[] value) throws JMSException;
287:
288: /** Reads a portion of the bytes message stream.
289: *
290: * <P>If the length of array <code>value</code> is less than the number of
291: * bytes remaining to be read from the stream, the array should
292: * be filled. A subsequent call reads the next increment, and so on.
293: *
294: * <P>If the number of bytes remaining in the stream is less than the
295: * length of
296: * array <code>value</code>, the bytes should be read into the array.
297: * The return value of the total number of bytes read will be less than
298: * the length of the array, indicating that there are no more bytes left
299: * to be read from the stream. The next read of the stream returns -1.
300: *
301: * <p> If <code>length</code> is negative, or
302: * <code>length</code> is greater than the length of the array
303: * <code>value</code>, then an <code>IndexOutOfBoundsException</code> is
304: * thrown. No bytes will be read from the stream for this exception case.
305: *
306: * @param value the buffer into which the data is read
307: * @param length the number of bytes to read; must be less than or equal to
308: * <code>value.length</code>
309: *
310: * @return the total number of bytes read into the buffer, or -1 if
311: * there is no more data because the end of the stream has been reached
312: *
313: * @exception JMSException if the JMS provider fails to read the message
314: * due to some internal error.
315: * @exception MessageNotReadableException if the message is in write-only
316: * mode.
317: */
318:
319: int readBytes(byte[] value, int length) throws JMSException;
320:
321: /** Writes a <code>boolean</code> to the bytes message stream as a 1-byte
322: * value.
323: * The value <code>true</code> is written as the value
324: * <code>(byte)1</code>; the value <code>false</code> is written as
325: * the value <code>(byte)0</code>.
326: *
327: * @param value the <code>boolean</code> value to be written
328: *
329: * @exception JMSException if the JMS provider fails to write the message
330: * due to some internal error.
331: * @exception MessageNotWriteableException if the message is in read-only
332: * mode.
333: */
334:
335: void writeBoolean(boolean value) throws JMSException;
336:
337: /** Writes a <code>byte</code> to the bytes message stream as a 1-byte
338: * value.
339: *
340: * @param value the <code>byte</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 writeByte(byte value) throws JMSException;
349:
350: /** Writes a <code>short</code> to the bytes message stream as two bytes,
351: * high byte first.
352: *
353: * @param value the <code>short</code> to be written
354: *
355: * @exception JMSException if the JMS provider fails to write the message
356: * due to some internal error.
357: * @exception MessageNotWriteableException if the message is in read-only
358: * mode.
359: */
360:
361: void writeShort(short value) throws JMSException;
362:
363: /** Writes a <code>char</code> to the bytes message stream as a 2-byte
364: * value, high byte first.
365: *
366: * @param value the <code>char</code> value to be written
367: *
368: * @exception JMSException if the JMS provider fails to write the message
369: * due to some internal error.
370: * @exception MessageNotWriteableException if the message is in read-only
371: * mode.
372: */
373:
374: void writeChar(char value) throws JMSException;
375:
376: /** Writes an <code>int</code> to the bytes message stream as four bytes,
377: * high byte first.
378: *
379: * @param value the <code>int</code> to be written
380: *
381: * @exception JMSException if the JMS provider fails to write the message
382: * due to some internal error.
383: * @exception MessageNotWriteableException if the message is in read-only
384: * mode.
385: */
386:
387: void writeInt(int value) throws JMSException;
388:
389: /** Writes a <code>long</code> to the bytes message stream as eight bytes,
390: * high byte first.
391: *
392: * @param value the <code>long</code> to be written
393: *
394: * @exception JMSException if the JMS provider fails to write the message
395: * due to some internal error.
396: * @exception MessageNotWriteableException if the message is in read-only
397: * mode.
398: */
399:
400: void writeLong(long value) throws JMSException;
401:
402: /** Converts the <code>float</code> argument to an <code>int</code> using
403: * the
404: * <code>floatToIntBits</code> method in class <code>Float</code>,
405: * and then writes that <code>int</code> value to the bytes message
406: * stream as a 4-byte quantity, high byte first.
407: *
408: * @param value the <code>float</code> value 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 writeFloat(float value) throws JMSException;
417:
418: /** Converts the <code>double</code> argument to a <code>long</code> using
419: * the
420: * <code>doubleToLongBits</code> method in class <code>Double</code>,
421: * and then writes that <code>long</code> value to the bytes message
422: * stream as an 8-byte quantity, high byte first.
423: *
424: * @param value the <code>double</code> value to be written
425: *
426: * @exception JMSException if the JMS provider fails to write the message
427: * due to some internal error.
428: * @exception MessageNotWriteableException if the message is in read-only
429: * mode.
430: */
431:
432: void writeDouble(double value) throws JMSException;
433:
434: /** Writes a string to the bytes message stream using UTF-8 encoding in a
435: * machine-independent manner.
436: *
437: * <P>For more information on the UTF-8 format, see "File System Safe
438: * UCS Transformation Format (FSS_UTF)", X/Open Preliminary Specification,
439: * X/Open Company Ltd., Document Number: P316. This information also
440: * appears in ISO/IEC 10646, Annex P.
441: *
442: * @param value the <code>String</code> value to be written
443: *
444: * @exception JMSException if the JMS provider fails to write the message
445: * due to some internal error.
446: * @exception MessageNotWriteableException if the message is in read-only
447: * mode.
448: */
449:
450: void writeUTF(String value) throws JMSException;
451:
452: /** Writes a byte array to the bytes message stream.
453: *
454: * @param value the byte array to be written
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) throws JMSException;
463:
464: /** Writes a portion of a byte array to the bytes message stream.
465: *
466: * @param value the byte array value to be written
467: * @param offset the initial offset within the byte array
468: * @param length the number of bytes to use
469: *
470: * @exception JMSException if the JMS provider fails to write the message
471: * due to some internal error.
472: * @exception MessageNotWriteableException if the message is in read-only
473: * mode.
474: */
475:
476: void writeBytes(byte[] value, int offset, int length)
477: throws JMSException;
478:
479: /** Writes an object to the bytes message stream.
480: *
481: * <P>This method works only for the objectified primitive
482: * object types (<code>Integer</code>, <code>Double</code>,
483: * <code>Long</code> ...), <code>String</code> objects, and byte
484: * arrays.
485: *
486: * @param value the object in the Java programming language ("Java
487: * object") to be written; it must not be null
488: *
489: * @exception JMSException if the JMS provider fails to write the message
490: * due to some internal error.
491: * @exception MessageFormatException if the object is of an invalid type.
492: * @exception MessageNotWriteableException if the message is in read-only
493: * mode.
494: * @exception java.lang.NullPointerException if the parameter
495: * <code>value</code> is null.
496: */
497:
498: void writeObject(Object value) throws JMSException;
499:
500: /** Puts the message body in read-only mode and repositions the stream of
501: * bytes to the beginning.
502: *
503: * @exception JMSException if the JMS provider fails to reset the message
504: * due to some internal error.
505: * @exception MessageFormatException if the message has an invalid
506: * format.
507: */
508:
509: void reset() throws JMSException;
510: }
|