001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common Development
008: * and Distribution License("CDDL") (collectively, the "License"). You
009: * may not use this file except in compliance with the License. You can obtain
010: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
011: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
012: * language governing permissions and limitations under the License.
013: *
014: * When distributing the software, include this License Header Notice in each
015: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
016: * Sun designates this particular file as subject to the "Classpath" exception
017: * as provided by Sun in the GPL Version 2 section of the License file that
018: * accompanied this code. If applicable, add the following below the License
019: * Header, with the fields enclosed by brackets [] replaced by your own
020: * identifying information: "Portions Copyrighted [year]
021: * [name of copyright owner]"
022: *
023: * Contributor(s):
024: *
025: * If you wish your version of this file to be governed by only the CDDL or
026: * only the GPL Version 2, indicate your decision by adding "[Contributor]
027: * elects to include this software in this distribution under the [CDDL or GPL
028: * Version 2] license." If you don't indicate a single choice of license, a
029: * recipient has the option to distribute your version of this file under
030: * either the CDDL, the GPL Version 2 or to extend the choice of license to
031: * its licensees as provided above. However, if you add GPL Version 2 code
032: * and therefore, elected the GPL Version 2 license, then the option applies
033: * only if the new code is made subject to such option by the copyright
034: * holder.
035: */
036:
037: package javax.jms;
038:
039: import java.util.Enumeration;
040:
041: /** A <CODE>MapMessage</CODE> object is used to send a set of name-value pairs.
042: * The names are <CODE>String</CODE> objects, and the values are primitive
043: * data types in the Java programming language. The names must have a value that
044: * is not null, and not an empty string. The entries can be accessed
045: * sequentially or randomly by name. The order of the entries is undefined.
046: * <CODE>MapMessage</CODE> inherits from the <CODE>Message</CODE> interface
047: * and adds a message body that contains a Map.
048: *
049: * <P>The primitive types can be read or written explicitly using methods
050: * for each type. They may also be read or written generically as objects.
051: * For instance, a call to <CODE>MapMessage.setInt("foo", 6)</CODE> is
052: * equivalent to <CODE>MapMessage.setObject("foo", new Integer(6))</CODE>.
053: * Both forms are provided, because the explicit form is convenient for
054: * static programming, and the object form is needed when types are not known
055: * at compile time.
056: *
057: * <P>When a client receives a <CODE>MapMessage</CODE>, it is in read-only
058: * mode. If a client attempts to write to the message at this point, a
059: * <CODE>MessageNotWriteableException</CODE> is thrown. If
060: * <CODE>clearBody</CODE> is called, the message can now be both read from and
061: * written to.
062: *
063: * <P><CODE>MapMessage</CODE> objects support the following conversion table.
064: * The marked cases must be supported. The unmarked cases must throw a
065: * <CODE>JMSException</CODE>. The <CODE>String</CODE>-to-primitive conversions
066: * may throw a runtime exception if the primitive's <CODE>valueOf()</CODE>
067: * method does not accept it as a valid <CODE>String</CODE> representation of
068: * the primitive.
069: *
070: * <P>A value written as the row type can be read as the column type.
071: *
072: * <PRE>
073: * | | boolean byte short char int long float double String byte[]
074: * |----------------------------------------------------------------------
075: * |boolean | X X
076: * |byte | X X X X X
077: * |short | X X X X
078: * |char | X X
079: * |int | X X X
080: * |long | X X
081: * |float | X X X
082: * |double | X X
083: * |String | X X X X X X X X
084: * |byte[] | X
085: * |----------------------------------------------------------------------
086: * </PRE>
087: *
088: * <P>Attempting to read a null value as a primitive type must be treated
089: * as calling the primitive's corresponding <code>valueOf(String)</code>
090: * conversion method with a null value. Since <code>char</code> does not
091: * support a <code>String</code> conversion, attempting to read a null value
092: * as a <code>char</code> must throw a <code>NullPointerException</code>.
093: *
094: * @version 1.1 February 2, 002
095: * @author Mark Hapner
096: * @author Rich Burridge
097: *
098: * @see javax.jms.Session#createMapMessage()
099: * @see javax.jms.BytesMessage
100: * @see javax.jms.Message
101: * @see javax.jms.ObjectMessage
102: * @see javax.jms.StreamMessage
103: * @see javax.jms.TextMessage
104: */
105:
106: public interface MapMessage extends Message {
107:
108: /** Returns the <CODE>boolean</CODE> value with the specified name.
109: *
110: * @param name the name of the <CODE>boolean</CODE>
111: *
112: * @return the <CODE>boolean</CODE> value with the specified name
113: *
114: * @exception JMSException if the JMS provider fails to read the message
115: * due to some internal error.
116: * @exception MessageFormatException if this type conversion is invalid.
117: */
118:
119: boolean getBoolean(String name) throws JMSException;
120:
121: /** Returns the <CODE>byte</CODE> value with the specified name.
122: *
123: * @param name the name of the <CODE>byte</CODE>
124: *
125: * @return the <CODE>byte</CODE> value with the specified name
126: *
127: * @exception JMSException if the JMS provider fails to read the message
128: * due to some internal error.
129: * @exception MessageFormatException if this type conversion is invalid.
130: */
131:
132: byte getByte(String name) throws JMSException;
133:
134: /** Returns the <CODE>short</CODE> value with the specified name.
135: *
136: * @param name the name of the <CODE>short</CODE>
137: *
138: * @return the <CODE>short</CODE> value with the specified name
139: *
140: * @exception JMSException if the JMS provider fails to read the message
141: * due to some internal error.
142: * @exception MessageFormatException if this type conversion is invalid.
143: */
144:
145: short getShort(String name) throws JMSException;
146:
147: /** Returns the Unicode character value with the specified name.
148: *
149: * @param name the name of the Unicode character
150: *
151: * @return the Unicode character value with the specified name
152: *
153: * @exception JMSException if the JMS provider fails to read the message
154: * due to some internal error.
155: * @exception MessageFormatException if this type conversion is invalid.
156: */
157:
158: char getChar(String name) throws JMSException;
159:
160: /** Returns the <CODE>int</CODE> value with the specified name.
161: *
162: * @param name the name of the <CODE>int</CODE>
163: *
164: * @return the <CODE>int</CODE> value with the specified name
165: *
166: * @exception JMSException if the JMS provider fails to read the message
167: * due to some internal error.
168: * @exception MessageFormatException if this type conversion is invalid.
169: */
170:
171: int getInt(String name) throws JMSException;
172:
173: /** Returns the <CODE>long</CODE> value with the specified name.
174: *
175: * @param name the name of the <CODE>long</CODE>
176: *
177: * @return the <CODE>long</CODE> value with the specified name
178: *
179: * @exception JMSException if the JMS provider fails to read the message
180: * due to some internal error.
181: * @exception MessageFormatException if this type conversion is invalid.
182: */
183:
184: long getLong(String name) throws JMSException;
185:
186: /** Returns the <CODE>float</CODE> value with the specified name.
187: *
188: * @param name the name of the <CODE>float</CODE>
189: *
190: * @return the <CODE>float</CODE> value with the specified name
191: *
192: * @exception JMSException if the JMS provider fails to read the message
193: * due to some internal error.
194: * @exception MessageFormatException if this type conversion is invalid.
195: */
196:
197: float getFloat(String name) throws JMSException;
198:
199: /** Returns the <CODE>double</CODE> value with the specified name.
200: *
201: * @param name the name of the <CODE>double</CODE>
202: *
203: * @return the <CODE>double</CODE> value with the specified name
204: *
205: * @exception JMSException if the JMS provider fails to read the message
206: * due to some internal error.
207: * @exception MessageFormatException if this type conversion is invalid.
208: */
209:
210: double getDouble(String name) throws JMSException;
211:
212: /** Returns the <CODE>String</CODE> value with the specified name.
213: *
214: * @param name the name of the <CODE>String</CODE>
215: *
216: * @return the <CODE>String</CODE> value with the specified name; if there
217: * is no item by this name, a null value is returned
218: *
219: * @exception JMSException if the JMS provider fails to read the message
220: * due to some internal error.
221: * @exception MessageFormatException if this type conversion is invalid.
222: */
223:
224: String getString(String name) throws JMSException;
225:
226: /** Returns the byte array value with the specified name.
227: *
228: * @param name the name of the byte array
229: *
230: * @return a copy of the byte array value with the specified name; if there
231: * is no
232: * item by this name, a null value is returned.
233: *
234: * @exception JMSException if the JMS provider fails to read the message
235: * due to some internal error.
236: * @exception MessageFormatException if this type conversion is invalid.
237: */
238:
239: byte[] getBytes(String name) throws JMSException;
240:
241: /** Returns the value of the object with the specified name.
242: *
243: * <P>This method can be used to return, in objectified format,
244: * an object in the Java programming language ("Java object") that had
245: * been stored in the Map with the equivalent
246: * <CODE>setObject</CODE> method call, or its equivalent primitive
247: * <CODE>set<I>type</I></CODE> method.
248: *
249: * <P>Note that byte values are returned as <CODE>byte[]</CODE>, not
250: * <CODE>Byte[]</CODE>.
251: *
252: * @param name the name of the Java object
253: *
254: * @return a copy of the Java object value with the specified name, in
255: * objectified format (for example, if the object was set as an
256: * <CODE>int</CODE>, an <CODE>Integer</CODE> is returned); if there is no
257: * item by this name, a null value is returned
258: *
259: * @exception JMSException if the JMS provider fails to read the message
260: * due to some internal error.
261: */
262:
263: Object getObject(String name) throws JMSException;
264:
265: /** Returns an <CODE>Enumeration</CODE> of all the names in the
266: * <CODE>MapMessage</CODE> object.
267: *
268: * @return an enumeration of all the names in this <CODE>MapMessage</CODE>
269: *
270: * @exception JMSException if the JMS provider fails to read the message
271: * due to some internal error.
272: */
273:
274: Enumeration getMapNames() throws JMSException;
275:
276: /** Sets a <CODE>boolean</CODE> value with the specified name into the Map.
277: *
278: * @param name the name of the <CODE>boolean</CODE>
279: * @param value the <CODE>boolean</CODE> value to set in the Map
280: *
281: * @exception JMSException if the JMS provider fails to write the message
282: * due to some internal error.
283: * @exception IllegalArgumentException if the name is null or if the name is
284: * an empty string.
285: * @exception MessageNotWriteableException if the message is in read-only
286: * mode.
287: */
288:
289: void setBoolean(String name, boolean value) throws JMSException;
290:
291: /** Sets a <CODE>byte</CODE> value with the specified name into the Map.
292: *
293: * @param name the name of the <CODE>byte</CODE>
294: * @param value the <CODE>byte</CODE> value to set in the Map
295: *
296: * @exception JMSException if the JMS provider fails to write the message
297: * due to some internal error.
298: * @exception IllegalArgumentException if the name is null or if the name is
299: * an empty string.
300: * @exception MessageNotWriteableException if the message is in read-only
301: * mode.
302: */
303:
304: void setByte(String name, byte value) throws JMSException;
305:
306: /** Sets a <CODE>short</CODE> value with the specified name into the Map.
307: *
308: * @param name the name of the <CODE>short</CODE>
309: * @param value the <CODE>short</CODE> value to set in the Map
310: *
311: * @exception JMSException if the JMS provider fails to write the message
312: * due to some internal error.
313: * @exception IllegalArgumentException if the name is null or if the name is
314: * an empty string.
315: * @exception MessageNotWriteableException if the message is in read-only
316: * mode.
317: */
318:
319: void setShort(String name, short value) throws JMSException;
320:
321: /** Sets a Unicode character value with the specified name into the Map.
322: *
323: * @param name the name of the Unicode character
324: * @param value the Unicode character value to set in the Map
325: *
326: * @exception JMSException if the JMS provider fails to write the message
327: * due to some internal error.
328: * @exception IllegalArgumentException if the name is null or if the name is
329: * an empty string.
330: * @exception MessageNotWriteableException if the message is in read-only
331: * mode.
332: */
333:
334: void setChar(String name, char value) throws JMSException;
335:
336: /** Sets an <CODE>int</CODE> value with the specified name into the Map.
337: *
338: * @param name the name of the <CODE>int</CODE>
339: * @param value the <CODE>int</CODE> value to set in the Map
340: *
341: * @exception JMSException if the JMS provider fails to write the message
342: * due to some internal error.
343: * @exception IllegalArgumentException if the name is null or if the name is
344: * an empty string.
345: * @exception MessageNotWriteableException if the message is in read-only
346: * mode.
347: */
348:
349: void setInt(String name, int value) throws JMSException;
350:
351: /** Sets a <CODE>long</CODE> value with the specified name into the Map.
352: *
353: * @param name the name of the <CODE>long</CODE>
354: * @param value the <CODE>long</CODE> value to set in the Map
355: *
356: * @exception JMSException if the JMS provider fails to write the message
357: * due to some internal error.
358: * @exception IllegalArgumentException if the name is null or if the name is
359: * an empty string.
360: * @exception MessageNotWriteableException if the message is in read-only
361: * mode.
362: */
363:
364: void setLong(String name, long value) throws JMSException;
365:
366: /** Sets a <CODE>float</CODE> value with the specified name into the Map.
367: *
368: * @param name the name of the <CODE>float</CODE>
369: * @param value the <CODE>float</CODE> value to set in the Map
370: *
371: * @exception JMSException if the JMS provider fails to write the message
372: * due to some internal error.
373: * @exception IllegalArgumentException if the name is null or if the name is
374: * an empty string.
375: * @exception MessageNotWriteableException if the message is in read-only
376: * mode.
377: */
378:
379: void setFloat(String name, float value) throws JMSException;
380:
381: /** Sets a <CODE>double</CODE> value with the specified name into the Map.
382: *
383: * @param name the name of the <CODE>double</CODE>
384: * @param value the <CODE>double</CODE> value to set in the Map
385: *
386: * @exception JMSException if the JMS provider fails to write the message
387: * due to some internal error.
388: * @exception IllegalArgumentException if the name is null or if the name is
389: * an empty string.
390: * @exception MessageNotWriteableException if the message is in read-only
391: * mode.
392: */
393:
394: void setDouble(String name, double value) throws JMSException;
395:
396: /** Sets a <CODE>String</CODE> value with the specified name into the Map.
397: *
398: * @param name the name of the <CODE>String</CODE>
399: * @param value the <CODE>String</CODE> value to set in the Map
400: *
401: * @exception JMSException if the JMS provider fails to write the message
402: * due to some internal error.
403: * @exception IllegalArgumentException if the name is null or if the name is
404: * an empty string.
405: * @exception MessageNotWriteableException if the message is in read-only
406: * mode.
407: */
408:
409: void setString(String name, String value) throws JMSException;
410:
411: /** Sets a byte array value with the specified name into the Map.
412: *
413: * @param name the name of the byte array
414: * @param value the byte array value to set in the Map; the array
415: * is copied so that the value for <CODE>name</CODE> will
416: * not be altered by future modifications
417: *
418: * @exception JMSException if the JMS provider fails to write the message
419: * due to some internal error.
420: * @exception NullPointerException if the name is null, or if the name is
421: * an empty string.
422: * @exception MessageNotWriteableException if the message is in read-only
423: * mode.
424: */
425:
426: void setBytes(String name, byte[] value) throws JMSException;
427:
428: /** Sets a portion of the byte array value with the specified name into the
429: * Map.
430: *
431: * @param name the name of the byte array
432: * @param value the byte array value to set in the Map
433: * @param offset the initial offset within the byte array
434: * @param length the number of bytes to use
435: *
436: * @exception JMSException if the JMS provider fails to write the message
437: * due to some internal error.
438: * @exception IllegalArgumentException if the name is null or if the name is
439: * an empty string.
440: * @exception MessageNotWriteableException if the message is in read-only
441: * mode.
442: */
443:
444: void setBytes(String name, byte[] value, int offset, int length)
445: throws JMSException;
446:
447: /** Sets an object value with the specified name into the Map.
448: *
449: * <P>This method works only for the objectified primitive
450: * object types (<code>Integer</code>, <code>Double</code>,
451: * <code>Long</code> ...), <code>String</code> objects, and byte
452: * arrays.
453: *
454: * @param name the name of the Java object
455: * @param value the Java object value to set in the Map
456: *
457: * @exception JMSException if the JMS provider fails to write the message
458: * due to some internal error.
459: * @exception IllegalArgumentException if the name is null or if the name is
460: * an empty string.
461: * @exception MessageFormatException if the object is invalid.
462: * @exception MessageNotWriteableException if the message is in read-only
463: * mode.
464: */
465:
466: void setObject(String name, Object value) throws JMSException;
467:
468: /** Indicates whether an item exists in this <CODE>MapMessage</CODE> object.
469: *
470: * @param name the name of the item to test
471: *
472: * @return true if the item exists
473: *
474: * @exception JMSException if the JMS provider fails to determine if the
475: * item exists due to some internal error.
476: */
477:
478: boolean itemExists(String name) throws JMSException;
479: }
|