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