| 
 | J2EE1.4 SDK | |||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
A MapMessage object is used to send a set of name-value pairs.
 The names are String objects, and the values are primitive 
 data types in the Java programming language. The names must have a value that
 is not null, and not an empty string. The entries can be accessed 
 sequentially or randomly by name. The order of the entries is undefined. 
 MapMessage inherits from the Message interface
 and adds a message body that contains a Map.
 
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.
Session.createMapMessage(), 
BytesMessage, 
Message, 
ObjectMessage, 
StreamMessage, 
TextMessage| Field Summary | 
| Fields inherited from interface javax.jms.Message | 
| DEFAULT_DELIVERY_MODE, DEFAULT_PRIORITY, DEFAULT_TIME_TO_LIVE | 
| Method Summary | |
|  boolean | getBoolean(java.lang.String name)Returns the booleanvalue with the specified name. | 
|  byte | getByte(java.lang.String name)Returns the bytevalue with the specified name. | 
|  byte[] | getBytes(java.lang.String name)Returns the byte array value with the specified name. | 
|  char | getChar(java.lang.String name)Returns the Unicode character value with the specified name. | 
|  double | getDouble(java.lang.String name)Returns the doublevalue with the specified name. | 
|  float | getFloat(java.lang.String name)Returns the floatvalue with the specified name. | 
|  int | getInt(java.lang.String name)Returns the intvalue with the specified name. | 
|  long | getLong(java.lang.String name)Returns the longvalue with the specified name. | 
|  java.util.Enumeration | getMapNames()Returns an Enumerationof all the names in theMapMessageobject. | 
|  java.lang.Object | getObject(java.lang.String name)Returns the value of the object with the specified name. | 
|  short | getShort(java.lang.String name)Returns the shortvalue with the specified name. | 
|  java.lang.String | getString(java.lang.String name)Returns the Stringvalue with the specified name. | 
|  boolean | itemExists(java.lang.String name)Indicates whether an item exists in this MapMessageobject. | 
|  void | setBoolean(java.lang.String name,
           boolean value)Sets a booleanvalue with the specified name into the Map. | 
|  void | setByte(java.lang.String name,
        byte value)Sets a bytevalue with the specified name into the Map. | 
|  void | setBytes(java.lang.String name,
         byte[] value)Sets a byte array value with the specified name into the Map. | 
|  void | setBytes(java.lang.String name,
         byte[] value,
         int offset,
         int length)Sets a portion of the byte array value with the specified name into the Map. | 
|  void | setChar(java.lang.String name,
        char value)Sets a Unicode character value with the specified name into the Map. | 
|  void | setDouble(java.lang.String name,
          double value)Sets a doublevalue with the specified name into the Map. | 
|  void | setFloat(java.lang.String name,
         float value)Sets a floatvalue with the specified name into the Map. | 
|  void | setInt(java.lang.String name,
       int value)Sets an intvalue with the specified name into the Map. | 
|  void | setLong(java.lang.String name,
        long value)Sets a longvalue with the specified name into the Map. | 
|  void | setObject(java.lang.String name,
          java.lang.Object value)Sets an object value with the specified name into the Map. | 
|  void | setShort(java.lang.String name,
         short value)Sets a shortvalue with the specified name into the Map. | 
|  void | setString(java.lang.String name,
          java.lang.String value)Sets a Stringvalue with the specified name into the Map. | 
| Method Detail | 
public boolean getBoolean(java.lang.String name)
                   throws JMSException
boolean value with the specified name.
name - the name of the boolean
boolean value with the specified name
JMSException - if the JMS provider fails to read the message
                         due to some internal error.
MessageFormatException - if this type conversion is invalid.
public byte getByte(java.lang.String name)
             throws JMSException
byte value with the specified name.
name - the name of the byte
byte value with the specified name
JMSException - if the JMS provider fails to read the message
                         due to some internal error.
MessageFormatException - if this type conversion is invalid.
public short getShort(java.lang.String name)
               throws JMSException
short value with the specified name.
name - the name of the short
short value with the specified name
JMSException - if the JMS provider fails to read the message
                         due to some internal error.
MessageFormatException - if this type conversion is invalid.
public char getChar(java.lang.String name)
             throws JMSException
name - the name of the Unicode character
JMSException - if the JMS provider fails to read the message
                         due to some internal error.
MessageFormatException - if this type conversion is invalid.
public int getInt(java.lang.String name)
           throws JMSException
int value with the specified name.
name - the name of the int
int value with the specified name
JMSException - if the JMS provider fails to read the message
                         due to some internal error.
MessageFormatException - if this type conversion is invalid.
public long getLong(java.lang.String name)
             throws JMSException
long value with the specified name.
name - the name of the long
long value with the specified name
JMSException - if the JMS provider fails to read the message
                         due to some internal error.
MessageFormatException - if this type conversion is invalid.
public float getFloat(java.lang.String name)
               throws JMSException
float value with the specified name.
name - the name of the float
float value with the specified name
JMSException - if the JMS provider fails to read the message
                         due to some internal error.
MessageFormatException - if this type conversion is invalid.
public double getDouble(java.lang.String name)
                 throws JMSException
double value with the specified name.
name - the name of the double
double value with the specified name
JMSException - if the JMS provider fails to read the message
                         due to some internal error.
MessageFormatException - if this type conversion is invalid.
public java.lang.String getString(java.lang.String name)
                           throws JMSException
String value with the specified name.
name - the name of the String
String value with the specified name; if there 
 is no item by this name, a null value is returned
JMSException - if the JMS provider fails to read the message
                         due to some internal error.
MessageFormatException - if this type conversion is invalid.
public byte[] getBytes(java.lang.String name)
                throws JMSException
name - the name of the byte array
JMSException - if the JMS provider fails to read the message
                         due to some internal error.
MessageFormatException - if this type conversion is invalid.
public java.lang.Object getObject(java.lang.String name)
                           throws JMSException
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[].
name - the name of the Java object
int, an Integer is returned); if there is no 
 item by this name, a null value is returned
JMSException - if the JMS provider fails to read the message
                         due to some internal error.
public java.util.Enumeration getMapNames()
                                  throws JMSException
Enumeration of all the names in the 
 MapMessage object.
MapMessage
JMSException - if the JMS provider fails to read the message
                         due to some internal error.
public void setBoolean(java.lang.String name,
                       boolean value)
                throws JMSException
boolean value with the specified name into the Map.
name - the name of the booleanvalue - the boolean value to set in the Map
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
java.lang.IllegalArgumentException - if the name is null or if the name is
                          an empty string.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void setByte(java.lang.String name,
                    byte value)
             throws JMSException
byte value with the specified name into the Map.
name - the name of the bytevalue - the byte value to set in the Map
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
java.lang.IllegalArgumentException - if the name is null or if the name is
                          an empty string.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void setShort(java.lang.String name,
                     short value)
              throws JMSException
short value with the specified name into the Map.
name - the name of the shortvalue - the short value to set in the Map
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
java.lang.IllegalArgumentException - if the name is null or if the name is
                          an empty string.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void setChar(java.lang.String name,
                    char value)
             throws JMSException
name - the name of the Unicode charactervalue - the Unicode character value to set in the Map
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
java.lang.IllegalArgumentException - if the name is null or if the name is
                          an empty string.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void setInt(java.lang.String name,
                   int value)
            throws JMSException
int value with the specified name into the Map.
name - the name of the intvalue - the int value to set in the Map
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
java.lang.IllegalArgumentException - if the name is null or if the name is
                          an empty string.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void setLong(java.lang.String name,
                    long value)
             throws JMSException
long value with the specified name into the Map.
name - the name of the longvalue - the long value to set in the Map
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
java.lang.IllegalArgumentException - if the name is null or if the name is
                          an empty string.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void setFloat(java.lang.String name,
                     float value)
              throws JMSException
float value with the specified name into the Map.
name - the name of the floatvalue - the float value to set in the Map
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
java.lang.IllegalArgumentException - if the name is null or if the name is
                          an empty string.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void setDouble(java.lang.String name,
                      double value)
               throws JMSException
double value with the specified name into the Map.
name - the name of the doublevalue - the double value to set in the Map
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
java.lang.IllegalArgumentException - if the name is null or if the name is
                          an empty string.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void setString(java.lang.String name,
                      java.lang.String value)
               throws JMSException
String value with the specified name into the Map.
name - the name of the Stringvalue - the String value to set in the Map
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
java.lang.IllegalArgumentException - if the name is null or if the name is
                          an empty string.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void setBytes(java.lang.String name,
                     byte[] value)
              throws JMSException
name - the name of the byte arrayvalue - the byte array value to set in the Map; the array
              is copied so that the value for name will
              not be altered by future modifications
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
java.lang.NullPointerException - if the name is null, or if the name is
                          an empty string.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void setBytes(java.lang.String name,
                     byte[] value,
                     int offset,
                     int length)
              throws JMSException
name - the name of the byte arrayvalue - the byte array value to set in the Mapoffset - the initial offset within the byte arraylength - the number of bytes to use
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
java.lang.IllegalArgumentException - if the name is null or if the name is
                          an empty string.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public void setObject(java.lang.String name,
                      java.lang.Object value)
               throws JMSException
This method works only for the objectified primitive
 object types (Integer, Double, 
 Long ...), String objects, and byte 
 arrays.
name - the name of the Java objectvalue - the Java object value to set in the Map
JMSException - if the JMS provider fails to write the message
                         due to some internal error.
java.lang.IllegalArgumentException - if the name is null or if the name is
                          an empty string.
MessageFormatException - if the object is invalid.
MessageNotWriteableException - if the message is in read-only 
                                         mode.
public boolean itemExists(java.lang.String name)
                   throws JMSException
MapMessage object.
name - the name of the item to test
JMSException - if the JMS provider fails to determine if the 
                         item exists due to some internal error.| 
 | J2EE1.4 SDK | |||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
Copyright 2003 Sun Microsystems, Inc. All rights reserved.