MapMessage


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  
25  package javax.jms;
26  
27  import java.util.Enumeration  ;
28  
29  /** A <CODE>MapMessage</CODE> object is used to send a set of name-value pairs.
30    * The names are <CODE>String</CODE> objects, and the values are primitive 
31    * data types in the Java programming language. The names must have a value that
32    * is not null, and not an empty string. The entries can be accessed 
33    * sequentially or randomly by name. The order of the entries is undefined. 
34    * <CODE>MapMessage</CODE> inherits from the <CODE>Message</CODE> interface
35    * and adds a message body that contains a Map.
36    *
37    * <P>The primitive types can be read or written explicitly using methods
38    * for each type. They may also be read or written generically as objects.
39    * For instance, a call to <CODE>MapMessage.setInt("foo", 6)</CODE> is 
40    * equivalent to <CODE>MapMessage.setObject("foo", new Integer(6))</CODE>.
41    * Both forms are provided, because the explicit form is convenient for
42    * static programming, and the object form is needed when types are not known
43    * at compile time.
44    *
45    * <P>When a client receives a <CODE>MapMessage</CODE>, it is in read-only 
46    * mode. If a client attempts to write to the message at this point, a 
47    * <CODE>MessageNotWriteableException</CODE> is thrown. If 
48    * <CODE>clearBody</CODE> is called, the message can now be both read from and 
49    * written to.
50    *
51    * <P><CODE>MapMessage</CODE> objects support the following conversion table. 
52    * The marked cases must be supported. The unmarked cases must throw a 
53    * <CODE>JMSException</CODE>. The <CODE>String</CODE>-to-primitive conversions 
54    * may throw a runtime exception if the primitive's <CODE>valueOf()</CODE> 
55    * method does not accept it as a valid <CODE>String</CODE> representation of 
56    * the primitive.
57    *
58    * <P>A value written as the row type can be read as the column type.
59    *
60    * <PRE>
61    * |        | boolean byte short char int long float double String byte[]
62    * |----------------------------------------------------------------------
63    * |boolean |    X                                            X
64    * |byte    |          X     X         X   X                  X
65    * |short   |                X         X   X                  X
66    * |char    |                     X                           X
67    * |int     |                          X   X                  X
68    * |long    |                              X                  X
69    * |float   |                                    X     X      X
70    * |double  |                                          X      X
71    * |String  |    X     X     X         X   X     X     X      X
72    * |byte[]  |                                                        X
73    * |----------------------------------------------------------------------
74    * </PRE>
75    *
76    * <P>Attempting to read a null value as a primitive type must be treated
77    * as calling the primitive's corresponding <code>valueOf(String)</code> 
78    * conversion method with a null value. Since <code>char</code> does not 
79    * support a <code>String</code> conversion, attempting to read a null value 
80    * as a <code>char</code> must throw a <code>NullPointerException</code>.
81    *
82    * @version     1.1 February 2, 002
83    * @author      Mark Hapner
84    * @author      Rich Burridge
85    *
86    * @see         javax.jms.Session#createMapMessage()
87    * @see         javax.jms.BytesMessage
88    * @see         javax.jms.Message
89    * @see         javax.jms.ObjectMessage
90    * @see         javax.jms.StreamMessage
91    * @see         javax.jms.TextMessage
92    */
93   
94  public interface MapMessage extends Message   { 
95  
96  
97      /** Returns the <CODE>boolean</CODE> value with the specified name.
98        *
99        * @param name the name of the <CODE>boolean</CODE>
100       *
101       * @return the <CODE>boolean</CODE> value with the specified name
102       *
103       * @exception JMSException if the JMS provider fails to read the message
104       *                         due to some internal error.
105       * @exception MessageFormatException if this type conversion is invalid.      
106       */
107 
108     boolean 
109     getBoolean(String   name) throws JMSException  ;
110 
111 
112     /** Returns the <CODE>byte</CODE> value with the specified name.
113       *
114       * @param name the name of the <CODE>byte</CODE>
115       *
116       * @return the <CODE>byte</CODE> value with the specified name
117       *
118       * @exception JMSException if the JMS provider fails to read the message
119       *                         due to some internal error.
120       * @exception MessageFormatException if this type conversion is invalid.
121       */ 
122 
123     byte 
124     getByte(String   name) throws JMSException  ;
125 
126 
127     /** Returns the <CODE>short</CODE> value with the specified name.
128       *
129       * @param name the name of the <CODE>short</CODE>
130       *
131       * @return the <CODE>short</CODE> value with the specified name
132       *
133       * @exception JMSException if the JMS provider fails to read the message
134       *                         due to some internal error.
135       * @exception MessageFormatException if this type conversion is invalid.      
136       */ 
137 
138     short 
139     getShort(String   name) throws JMSException  ;
140 
141 
142     /** Returns the Unicode character value with the specified name.
143       *
144       * @param name the name of the Unicode character
145       *
146       * @return the Unicode character value with the specified name
147       *
148       * @exception JMSException if the JMS provider fails to read the message
149       *                         due to some internal error.
150       * @exception MessageFormatException if this type conversion is invalid.     
151       */ 
152 
153     char 
154     getChar(String   name) throws JMSException  ;
155 
156 
157     /** Returns the <CODE>int</CODE> value with the specified name.
158       *
159       * @param name the name of the <CODE>int</CODE>
160       *
161       * @return the <CODE>int</CODE> value with the specified name
162       *
163       * @exception JMSException if the JMS provider fails to read the message
164       *                         due to some internal error.
165       * @exception MessageFormatException if this type conversion is invalid.      
166       */ 
167 
168     int 
169     getInt(String   name) throws JMSException  ;
170 
171 
172     /** Returns the <CODE>long</CODE> value with the specified name.
173       *
174       * @param name the name of the <CODE>long</CODE>
175       *
176       * @return the <CODE>long</CODE> value with the specified name
177       *
178       * @exception JMSException if the JMS provider fails to read the message
179       *                         due to some internal error.
180       * @exception MessageFormatException if this type conversion is invalid.      
181       */ 
182 
183     long 
184     getLong(String   name) throws JMSException  ;
185 
186 
187     /** Returns the <CODE>float</CODE> value with the specified name.
188       *
189       * @param name the name of the <CODE>float</CODE>
190       *
191       * @return the <CODE>float</CODE> value with the specified name
192       *
193       * @exception JMSException if the JMS provider fails to read the message
194       *                         due to some internal error.
195       * @exception MessageFormatException if this type conversion is invalid.     
196       */ 
197 
198     float 
199     getFloat(String   name) throws JMSException  ;
200 
201 
202     /** Returns the <CODE>double</CODE> value with the specified name.
203       *
204       * @param name the name of the <CODE>double</CODE>
205       *
206       * @return the <CODE>double</CODE> value with the specified name
207       *
208       * @exception JMSException if the JMS provider fails to read the message
209       *                         due to some internal error.
210       * @exception MessageFormatException if this type conversion is invalid.      
211       */ 
212 
213     double 
214     getDouble(String   name) throws JMSException  ;
215 
216 
217     /** Returns the <CODE>String</CODE> value with the specified name.
218       *
219       * @param name the name of the <CODE>String</CODE>
220       *
221       * @return the <CODE>String</CODE> value with the specified name; if there 
222       * is no item by this name, a null value is returned
223       *
224       * @exception JMSException if the JMS provider fails to read the message
225       *                         due to some internal error.
226       * @exception MessageFormatException if this type conversion is invalid.      
227       */ 
228 
229     String   
230     getString(String   name) throws JMSException  ;
231 
232 
233     /** Returns the byte array value with the specified name.
234       *
235       * @param name the name of the byte array
236       *
237       * @return a copy of the byte array value with the specified name; if there
238       * is no
239       * item by this name, a null value is returned.
240       *
241       * @exception JMSException if the JMS provider fails to read the message
242       *                         due to some internal error.
243       * @exception MessageFormatException if this type conversion is invalid.      
244       */ 
245 
246     byte[] 
247     getBytes(String   name) throws JMSException  ;
248 
249 
250     /** Returns the value of the object with the specified name.
251       *
252       * <P>This method can be used to return, in objectified format,
253       * an object in the Java programming language ("Java object") that had 
254       * been stored in the Map with the equivalent
255       * <CODE>setObject</CODE> method call, or its equivalent primitive
256       * <CODE>set<I>type</I></CODE> method.
257       *
258       * <P>Note that byte values are returned as <CODE>byte[]</CODE>, not 
259       * <CODE>Byte[]</CODE>.
260       *
261       * @param name the name of the Java object
262       *
263       * @return a copy of the Java object value with the specified name, in 
264       * objectified format (for example, if the object was set as an 
265       * <CODE>int</CODE>, an <CODE>Integer</CODE> is returned); if there is no 
266       * item by this name, a null value is returned
267       *
268       * @exception JMSException if the JMS provider fails to read the message
269       *                         due to some internal error.
270       */ 
271 
272     Object   
273     getObject(String   name) throws JMSException  ;
274 
275 
276 
277     /** Returns an <CODE>Enumeration</CODE> of all the names in the 
278       * <CODE>MapMessage</CODE> object.
279       *
280       * @return an enumeration of all the names in this <CODE>MapMessage</CODE>
281       *
282       * @exception JMSException if the JMS provider fails to read the message
283       *                         due to some internal error.
284       */
285 
286     Enumeration  
287     getMapNames() throws JMSException  ;
288 
289 
290     /** Sets a <CODE>boolean</CODE> value with the specified name into the Map.
291       *
292       * @param name the name of the <CODE>boolean</CODE>
293       * @param value the <CODE>boolean</CODE> value to set in the Map
294       *
295       * @exception JMSException if the JMS provider fails to write the message
296       *                         due to some internal error.
297       * @exception IllegalArgumentException if the name is null or if the name is
298       *                          an empty string.
299       * @exception MessageNotWriteableException if the message is in read-only 
300       *                                         mode.
301       */
302 
303     void 
304     setBoolean(String   name, boolean value) throws JMSException  ;
305 
306 
307     /** Sets a <CODE>byte</CODE> value with the specified name into the Map.
308       *
309       * @param name the name of the <CODE>byte</CODE>
310       * @param value the <CODE>byte</CODE> value to set in the Map
311       *
312       * @exception JMSException if the JMS provider fails to write the message
313       *                         due to some internal error.
314      * @exception IllegalArgumentException if the name is null or if the name is
315       *                          an empty string.
316       * @exception MessageNotWriteableException if the message is in read-only 
317       *                                         mode.
318       */ 
319 
320     void 
321     setByte(String   name, byte value) 
322             throws JMSException  ;
323 
324 
325     /** Sets a <CODE>short</CODE> value with the specified name into the Map.
326       *
327       * @param name the name of the <CODE>short</CODE>
328       * @param value the <CODE>short</CODE> value to set in the Map
329       *
330       * @exception JMSException if the JMS provider fails to write the message
331       *                         due to some internal error.
332        * @exception IllegalArgumentException if the name is null or if the name is
333       *                          an empty string.
334       * @exception MessageNotWriteableException if the message is in read-only 
335       *                                         mode.
336       */ 
337 
338     void 
339     setShort(String   name, short value) 
340             throws JMSException  ;
341 
342 
343     /** Sets a Unicode character value with the specified name into the Map.
344       *
345       * @param name the name of the Unicode character
346       * @param value the Unicode character value to set in the Map
347       *
348       * @exception JMSException if the JMS provider fails to write the message
349       *                         due to some internal error.
350        * @exception IllegalArgumentException if the name is null or if the name is
351       *                          an empty string.
352       * @exception MessageNotWriteableException if the message is in read-only 
353       *                                         mode.
354       */ 
355 
356     void 
357     setChar(String   name, char value) 
358             throws JMSException  ;
359 
360 
361     /** Sets an <CODE>int</CODE> value with the specified name into the Map.
362       *
363       * @param name the name of the <CODE>int</CODE>
364       * @param value the <CODE>int</CODE> value to set in the Map
365       *
366       * @exception JMSException if the JMS provider fails to write the message
367       *                         due to some internal error.
368       * @exception IllegalArgumentException if the name is null or if the name is
369       *                          an empty string.
370       * @exception MessageNotWriteableException if the message is in read-only 
371       *                                         mode.
372       */ 
373 
374     void 
375     setInt(String   name, int value) 
376             throws JMSException  ;
377 
378 
379     /** Sets a <CODE>long</CODE> value with the specified name into the Map.
380       *
381       * @param name the name of the <CODE>long</CODE>
382       * @param value the <CODE>long</CODE> value to set in the Map
383       *
384       * @exception JMSException if the JMS provider fails to write the message
385       *                         due to some internal error.
386       * @exception IllegalArgumentException if the name is null or if the name is
387       *                          an empty string.
388       * @exception MessageNotWriteableException if the message is in read-only 
389       *                                         mode.
390       */ 
391 
392     void 
393     setLong(String   name, long value) 
394             throws JMSException  ;
395 
396 
397     /** Sets a <CODE>float</CODE> value with the specified name into the Map.
398       *
399       * @param name the name of the <CODE>float</CODE>
400       * @param value the <CODE>float</CODE> value to set in the Map
401       *
402       * @exception JMSException if the JMS provider fails to write the message
403       *                         due to some internal error.
404        * @exception IllegalArgumentException if the name is null or if the name is
405       *                          an empty string.
406       * @exception MessageNotWriteableException if the message is in read-only 
407       *                                         mode.
408       */ 
409 
410     void 
411     setFloat(String   name, float value) 
412             throws JMSException  ;
413 
414 
415     /** Sets a <CODE>double</CODE> value with the specified name into the Map.
416       *
417       * @param name the name of the <CODE>double</CODE>
418       * @param value the <CODE>double</CODE> value to set in the Map
419       *
420       * @exception JMSException if the JMS provider fails to write the message
421       *                         due to some internal error.
422       * @exception IllegalArgumentException if the name is null or if the name is
423       *                          an empty string.
424       * @exception MessageNotWriteableException if the message is in read-only 
425       *                                         mode.
426       */ 
427 
428     void 
429     setDouble(String   name, double value) 
430             throws JMSException  ;
431 
432 
433     /** Sets a <CODE>String</CODE> value with the specified name into the Map.
434       *
435       * @param name the name of the <CODE>String</CODE>
436       * @param value the <CODE>String</CODE> 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 MessageNotWriteableException if the message is in read-only 
443       *                                         mode.
444       */ 
445 
446     void 
447     setString(String   name, String   value) 
448             throws JMSException  ;
449 
450 
451     /** Sets a byte array value with the specified name into the Map.
452       *
453       * @param name the name of the byte array
454       * @param value the byte array value to set in the Map; the array
455       *              is copied so that the value for <CODE>name</CODE> will
456       *              not be altered by future modifications
457       *
458       * @exception JMSException if the JMS provider fails to write the message
459       *                         due to some internal error.
460       * @exception NullPointerException if the name is null, or if the name is
461       *                          an empty string.
462       * @exception MessageNotWriteableException if the message is in read-only 
463       *                                         mode.
464       */ 
465 
466     void
467     setBytes(String   name, byte[] value) 
468             throws JMSException  ;
469 
470 
471     /** Sets a portion of the byte array value with the specified name into the 
472       * Map.
473       *  
474       * @param name the name of the byte array
475       * @param value the byte array value to set in the Map
476       * @param offset the initial offset within the byte array
477       * @param length the number of bytes to use
478       *
479       * @exception JMSException if the JMS provider fails to write the message
480       *                         due to some internal error.
481        * @exception IllegalArgumentException if the name is null or if the name is
482       *                          an empty string.
483       * @exception MessageNotWriteableException if the message is in read-only 
484       *                                         mode.
485       */ 
486  
487     void
488     setBytes(String   name, byte[] value, 
489          int offset, int length) 
490             throws JMSException  ;
491 
492 
493     /** Sets an object value with the specified name into the Map.
494       *
495       * <P>This method works only for the objectified primitive
496       * object types (<code>Integer</code>, <code>Double</code>, 
497       * <code>Long</code>&nbsp;...), <code>String</code> objects, and byte 
498       * arrays.
499       *
500       * @param name the name of the Java object
501       * @param value the Java object value to set in the Map
502       *
503       * @exception JMSException if the JMS provider fails to write the message
504       *                         due to some internal error.
505       * @exception IllegalArgumentException if the name is null or if the name is
506       *                          an empty string.
507       * @exception MessageFormatException if the object is invalid.
508       * @exception MessageNotWriteableException if the message is in read-only 
509       *                                         mode.
510       */ 
511 
512     void 
513     setObject(String   name, Object   value) 
514             throws JMSException  ;
515 
516 
517     /** Indicates whether an item exists in this <CODE>MapMessage</CODE> object.
518       *
519       * @param name the name of the item to test
520       *
521       * @return true if the item exists
522       *
523       * @exception JMSException if the JMS provider fails to determine if the 
524       *                         item exists due to some internal error.
525       */ 
526  
527     boolean
528     itemExists(String   name) throws JMSException  ;
529 }
530
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags