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: import java.util.Enumeration;
025:
026: /** A <CODE>MapMessage</CODE> object is used to send a set of name-value pairs.
027: * The names are <CODE>String</CODE> objects, and the values are primitive
028: * data types in the Java programming language. The names must have a value that
029: * is not null, and not an empty string. The entries can be accessed
030: * sequentially or randomly by name. The order of the entries is undefined.
031: * <CODE>MapMessage</CODE> inherits from the <CODE>Message</CODE> interface
032: * and adds a message body that contains a Map.
033: *
034: * <P>The primitive types can be read or written explicitly using methods
035: * for each type. They may also be read or written generically as objects.
036: * For instance, a call to <CODE>MapMessage.setInt("foo", 6)</CODE> is
037: * equivalent to <CODE>MapMessage.setObject("foo", new Integer(6))</CODE>.
038: * Both forms are provided, because the explicit form is convenient for
039: * static programming, and the object form is needed when types are not known
040: * at compile time.
041: *
042: * <P>When a client receives a <CODE>MapMessage</CODE>, it is in read-only
043: * mode. If a client attempts to write to the message at this point, a
044: * <CODE>MessageNotWriteableException</CODE> is thrown. If
045: * <CODE>clearBody</CODE> is called, the message can now be both read from and
046: * written to.
047: *
048: * <P><CODE>MapMessage</CODE> objects support the following conversion table.
049: * 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: * @see javax.jms.Session#createMapMessage()
080: * @see javax.jms.BytesMessage
081: * @see javax.jms.Message
082: * @see javax.jms.ObjectMessage
083: * @see javax.jms.StreamMessage
084: * @see javax.jms.TextMessage
085: */
086:
087: public interface MapMessage extends Message {
088:
089: /** Returns the <CODE>boolean</CODE> value with the specified name.
090: *
091: * @param name the name of the <CODE>boolean</CODE>
092: *
093: * @return the <CODE>boolean</CODE> value with the specified name
094: *
095: * @exception JMSException if the JMS provider fails to read the message
096: * due to some internal error.
097: * @exception MessageFormatException if this type conversion is invalid.
098: */
099:
100: boolean getBoolean(String name) throws JMSException;
101:
102: /** Returns the <CODE>byte</CODE> value with the specified name.
103: *
104: * @param name the name of the <CODE>byte</CODE>
105: *
106: * @return the <CODE>byte</CODE> value with the specified name
107: *
108: * @exception JMSException if the JMS provider fails to read the message
109: * due to some internal error.
110: * @exception MessageFormatException if this type conversion is invalid.
111: */
112:
113: byte getByte(String name) throws JMSException;
114:
115: /** Returns the <CODE>short</CODE> value with the specified name.
116: *
117: * @param name the name of the <CODE>short</CODE>
118: *
119: * @return the <CODE>short</CODE> value with the specified name
120: *
121: * @exception JMSException if the JMS provider fails to read the message
122: * due to some internal error.
123: * @exception MessageFormatException if this type conversion is invalid.
124: */
125:
126: short getShort(String name) throws JMSException;
127:
128: /** Returns the Unicode character value with the specified name.
129: *
130: * @param name the name of the Unicode character
131: *
132: * @return the Unicode character value with the specified name
133: *
134: * @exception JMSException if the JMS provider fails to read the message
135: * due to some internal error.
136: * @exception MessageFormatException if this type conversion is invalid.
137: */
138:
139: char getChar(String name) throws JMSException;
140:
141: /** Returns the <CODE>int</CODE> value with the specified name.
142: *
143: * @param name the name of the <CODE>int</CODE>
144: *
145: * @return the <CODE>int</CODE> value with the specified name
146: *
147: * @exception JMSException if the JMS provider fails to read the message
148: * due to some internal error.
149: * @exception MessageFormatException if this type conversion is invalid.
150: */
151:
152: int getInt(String name) throws JMSException;
153:
154: /** Returns the <CODE>long</CODE> value with the specified name.
155: *
156: * @param name the name of the <CODE>long</CODE>
157: *
158: * @return the <CODE>long</CODE> value with the specified name
159: *
160: * @exception JMSException if the JMS provider fails to read the message
161: * due to some internal error.
162: * @exception MessageFormatException if this type conversion is invalid.
163: */
164:
165: long getLong(String name) throws JMSException;
166:
167: /** Returns the <CODE>float</CODE> value with the specified name.
168: *
169: * @param name the name of the <CODE>float</CODE>
170: *
171: * @return the <CODE>float</CODE> value with the specified name
172: *
173: * @exception JMSException if the JMS provider fails to read the message
174: * due to some internal error.
175: * @exception MessageFormatException if this type conversion is invalid.
176: */
177:
178: float getFloat(String name) throws JMSException;
179:
180: /** Returns the <CODE>double</CODE> value with the specified name.
181: *
182: * @param name the name of the <CODE>double</CODE>
183: *
184: * @return the <CODE>double</CODE> value with the specified name
185: *
186: * @exception JMSException if the JMS provider fails to read the message
187: * due to some internal error.
188: * @exception MessageFormatException if this type conversion is invalid.
189: */
190:
191: double getDouble(String name) throws JMSException;
192:
193: /** Returns the <CODE>String</CODE> value with the specified name.
194: *
195: * @param name the name of the <CODE>String</CODE>
196: *
197: * @return the <CODE>String</CODE> value with the specified name; if there
198: * is no item by this name, a null value is returned
199: *
200: * @exception JMSException if the JMS provider fails to read the message
201: * due to some internal error.
202: * @exception MessageFormatException if this type conversion is invalid.
203: */
204:
205: String getString(String name) throws JMSException;
206:
207: /** Returns the byte array value with the specified name.
208: *
209: * @param name the name of the byte array
210: *
211: * @return a copy of the byte array value with the specified name; if there
212: * is no
213: * item by this name, a null value is returned.
214: *
215: * @exception JMSException if the JMS provider fails to read the message
216: * due to some internal error.
217: * @exception MessageFormatException if this type conversion is invalid.
218: */
219:
220: byte[] getBytes(String name) throws JMSException;
221:
222: /** Returns the value of the object with the specified name.
223: *
224: * <P>This method can be used to return, in objectified format,
225: * an object in the Java programming language ("Java object") that had
226: * been stored in the Map with the equivalent
227: * <CODE>setObject</CODE> method call, or its equivalent primitive
228: * <CODE>set<I>type</I></CODE> method.
229: *
230: * <P>Note that byte values are returned as <CODE>byte[]</CODE>, not
231: * <CODE>Byte[]</CODE>.
232: *
233: * @param name the name of the Java object
234: *
235: * @return a copy of the Java object value with the specified name, in
236: * objectified format (for example, if the object was set as an
237: * <CODE>int</CODE>, an <CODE>Integer</CODE> is returned); if there is no
238: * item by this name, a null value is returned
239: *
240: * @exception JMSException if the JMS provider fails to read the message
241: * due to some internal error.
242: */
243:
244: Object getObject(String name) throws JMSException;
245:
246: /** Returns an <CODE>Enumeration</CODE> of all the names in the
247: * <CODE>MapMessage</CODE> object.
248: *
249: * @return an enumeration of all the names in this <CODE>MapMessage</CODE>
250: *
251: * @exception JMSException if the JMS provider fails to read the message
252: * due to some internal error.
253: */
254:
255: Enumeration getMapNames() throws JMSException;
256:
257: /** Sets a <CODE>boolean</CODE> value with the specified name into the Map.
258: *
259: * @param name the name of the <CODE>boolean</CODE>
260: * @param value the <CODE>boolean</CODE> value to set in the Map
261: *
262: * @exception JMSException if the JMS provider fails to write the message
263: * due to some internal error.
264: * @exception IllegalArgumentException if the name is null or if the name is
265: * an empty string.
266: * @exception MessageNotWriteableException if the message is in read-only
267: * mode.
268: */
269:
270: void setBoolean(String name, boolean value) throws JMSException;
271:
272: /** Sets a <CODE>byte</CODE> value with the specified name into the Map.
273: *
274: * @param name the name of the <CODE>byte</CODE>
275: * @param value the <CODE>byte</CODE> value to set in the Map
276: *
277: * @exception JMSException if the JMS provider fails to write the message
278: * due to some internal error.
279: * @exception IllegalArgumentException if the name is null or if the name is
280: * an empty string.
281: * @exception MessageNotWriteableException if the message is in read-only
282: * mode.
283: */
284:
285: void setByte(String name, byte value) throws JMSException;
286:
287: /** Sets a <CODE>short</CODE> value with the specified name into the Map.
288: *
289: * @param name the name of the <CODE>short</CODE>
290: * @param value the <CODE>short</CODE> value to set in the Map
291: *
292: * @exception JMSException if the JMS provider fails to write the message
293: * due to some internal error.
294: * @exception IllegalArgumentException if the name is null or if the name is
295: * an empty string.
296: * @exception MessageNotWriteableException if the message is in read-only
297: * mode.
298: */
299:
300: void setShort(String name, short value) throws JMSException;
301:
302: /** Sets a Unicode character value with the specified name into the Map.
303: *
304: * @param name the name of the Unicode character
305: * @param value the Unicode character value to set in the Map
306: *
307: * @exception JMSException if the JMS provider fails to write the message
308: * due to some internal error.
309: * @exception IllegalArgumentException if the name is null or if the name is
310: * an empty string.
311: * @exception MessageNotWriteableException if the message is in read-only
312: * mode.
313: */
314:
315: void setChar(String name, char value) throws JMSException;
316:
317: /** Sets an <CODE>int</CODE> value with the specified name into the Map.
318: *
319: * @param name the name of the <CODE>int</CODE>
320: * @param value the <CODE>int</CODE> value to set in the Map
321: *
322: * @exception JMSException if the JMS provider fails to write the message
323: * due to some internal error.
324: * @exception IllegalArgumentException if the name is null or if the name is
325: * an empty string.
326: * @exception MessageNotWriteableException if the message is in read-only
327: * mode.
328: */
329:
330: void setInt(String name, int value) throws JMSException;
331:
332: /** Sets a <CODE>long</CODE> value with the specified name into the Map.
333: *
334: * @param name the name of the <CODE>long</CODE>
335: * @param value the <CODE>long</CODE> value to set in the Map
336: *
337: * @exception JMSException if the JMS provider fails to write the message
338: * due to some internal error.
339: * @exception IllegalArgumentException if the name is null or if the name is
340: * an empty string.
341: * @exception MessageNotWriteableException if the message is in read-only
342: * mode.
343: */
344:
345: void setLong(String name, long value) throws JMSException;
346:
347: /** Sets a <CODE>float</CODE> value with the specified name into the Map.
348: *
349: * @param name the name of the <CODE>float</CODE>
350: * @param value the <CODE>float</CODE> value to set in the Map
351: *
352: * @exception JMSException if the JMS provider fails to write the message
353: * due to some internal error.
354: * @exception IllegalArgumentException if the name is null or if the name is
355: * an empty string.
356: * @exception MessageNotWriteableException if the message is in read-only
357: * mode.
358: */
359:
360: void setFloat(String name, float value) throws JMSException;
361:
362: /** Sets a <CODE>double</CODE> value with the specified name into the Map.
363: *
364: * @param name the name of the <CODE>double</CODE>
365: * @param value the <CODE>double</CODE> value to set in the Map
366: *
367: * @exception JMSException if the JMS provider fails to write the message
368: * due to some internal error.
369: * @exception IllegalArgumentException if the name is null or if the name is
370: * an empty string.
371: * @exception MessageNotWriteableException if the message is in read-only
372: * mode.
373: */
374:
375: void setDouble(String name, double value) throws JMSException;
376:
377: /** Sets a <CODE>String</CODE> value with the specified name into the Map.
378: *
379: * @param name the name of the <CODE>String</CODE>
380: * @param value the <CODE>String</CODE> value to set in the Map
381: *
382: * @exception JMSException if the JMS provider fails to write the message
383: * due to some internal error.
384: * @exception IllegalArgumentException if the name is null or if the name is
385: * an empty string.
386: * @exception MessageNotWriteableException if the message is in read-only
387: * mode.
388: */
389:
390: void setString(String name, String value) throws JMSException;
391:
392: /** Sets a byte array value with the specified name into the Map.
393: *
394: * @param name the name of the byte array
395: * @param value the byte array value to set in the Map; the array
396: * is copied so that the value for <CODE>name</CODE> will
397: * not be altered by future modifications
398: *
399: * @exception JMSException if the JMS provider fails to write the message
400: * due to some internal error.
401: * @exception NullPointerException if the name is null, or if the name is
402: * an empty string.
403: * @exception MessageNotWriteableException if the message is in read-only
404: * mode.
405: */
406:
407: void setBytes(String name, byte[] value) throws JMSException;
408:
409: /** Sets a portion of the byte array value with the specified name into the
410: * Map.
411: *
412: * @param name the name of the byte array
413: * @param value the byte array value to set in the Map
414: * @param offset the initial offset within the byte array
415: * @param length the number of bytes to use
416: *
417: * @exception JMSException if the JMS provider fails to write the message
418: * due to some internal error.
419: * @exception IllegalArgumentException if the name is null or if the name is
420: * an empty string.
421: * @exception MessageNotWriteableException if the message is in read-only
422: * mode.
423: */
424:
425: void setBytes(String name, byte[] value, int offset, int length)
426: throws JMSException;
427:
428: /** Sets an object value with the specified name into the Map.
429: *
430: * <P>This method works only for the objectified primitive
431: * object types (<code>Integer</code>, <code>Double</code>,
432: * <code>Long</code> ...), <code>String</code> objects, and byte
433: * arrays.
434: *
435: * @param name the name of the Java object
436: * @param value the Java object value to set in the Map
437: *
438: * @exception JMSException if the JMS provider fails to write the message
439: * due to some internal error.
440: * @exception IllegalArgumentException if the name is null or if the name is
441: * an empty string.
442: * @exception MessageFormatException if the object is invalid.
443: * @exception MessageNotWriteableException if the message is in read-only
444: * mode.
445: */
446:
447: void setObject(String name, Object value) throws JMSException;
448:
449: /** Indicates whether an item exists in this <CODE>MapMessage</CODE> object.
450: *
451: * @param name the name of the item to test
452: *
453: * @return true if the item exists
454: *
455: * @exception JMSException if the JMS provider fails to determine if the
456: * item exists due to some internal error.
457: */
458:
459: boolean itemExists(String name) throws JMSException;
460: }
|