Java Doc for MapMessage.java in  » 6.0-JDK-Modules » JMS » javax » jms » Java Source Code / Java DocumentationJava Source Code and Java Documentation

The primitive types can be read or written explicitly using methods for each type. They may also be read or written generically as objects. For instance, a call to MapMessage.setInt("foo", 6) is equivalent to MapMessage.setObject("foo", new Integer(6)). Both forms are provided, because the explicit form is convenient for static programming, and the object form is needed when types are not known at compile time.

When a client receives a MapMessage, it is in read-only mode. If a client attempts to write to the message at this point, a MessageNotWriteableException is thrown. If clearBody is called, the message can now be both read from and written to.

MapMessage objects support the following conversion table. The marked cases must be supported. The unmarked cases must throw a JMSException. The String-to-primitive conversions may throw a runtime exception if the primitive's valueOf() method does not accept it as a valid String representation of the primitive.

A value written as the row type can be read as the column type.

 |        | boolean byte short char int long float double String byte[]
 |----------------------------------------------------------------------
 |boolean |    X                                            X
 |byte    |          X     X         X   X                  X
 |short   |                X         X   X                  X
 |char    |                     X                           X
 |int     |                          X   X                  X
 |long    |                              X                  X
 |float   |                                    X     X      X
 |double  |                                          X      X
 |String  |    X     X     X         X   X     X     X      X
 |byte[]  |                                                        X
 |----------------------------------------------------------------------
 

Attempting to read a null value as a primitive type must be treated as calling the primitive's corresponding valueOf(String) conversion method with a null value. Since char does not support a String conversion, attempting to read a null value as a char must throw a NullPointerException.
version:
   1.1 February 2, 002
author:
   Mark Hapner
author:
   Rich Burridge
See Also:   javax.jms.Session.createMapMessage
See Also:   javax.jms.BytesMessage
See Also:   javax.jms.Message
See Also:   javax.jms.ObjectMessage
See Also:   javax.jms.StreamMessage
See Also:   javax.jms.TextMessage

This method can be used to return, in objectified format, an object in the Java programming language ("Java object") that had been stored in the Map with the equivalent setObject method call, or its equivalent primitive settype method.

Note that byte values are returned as byte[], not Byte[].
Parameters:
  name - the name of the Java object a copy of the Java object value with the specified name, in objectified format (for example, if the object was set as an int, an Integer is returned); if there is no item by this name, a null value is returned
exception:
  JMSException - if the JMS provider fails to read the messagedue to some internal error.

This method works only for the objectified primitive object types (Integer, Double, Long ...), String objects, and byte arrays.
Parameters:
  name - the name of the Java object
Parameters:
  value - the Java object value to set in the Map
exception:
  JMSException - if the JMS provider fails to write the messagedue to some internal error.
exception:
  IllegalArgumentException - if the name is null or if the name isan empty string.
exception:
  MessageFormatException - if the object is invalid.
exception:
  MessageNotWriteableException - if the message is in read-only mode.