com.ibm.jms
Class JMSMapMessage

java.lang.Object
  |
  +--com.ibm.jms.JMSMessage
        |
        +--com.ibm.jms.JMSMapMessage
All Implemented Interfaces:
javax.jms.MapMessage, javax.jms.Message, java.io.Serializable

public class JMSMapMessage
extends JMSMessage
implements javax.jms.MapMessage

JMSMapMessage is used to send a set of name/type/value triplets. The entries can be accessed sequentially or randomly by name. The order of the entries is undefined. It adds a map message body.

The primitive types can be read or written explicitly using methods for each type. They can also be read or written generically as objects. For example, the call
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 then be both read from and written to.

Map messages support the following conversion table. The marked cases are supported and the unmarked cases throw a JMSException. The String to primitive conversions might 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      X
 byte[]                                                               X
 --------------------------------------------------------------------------
 

See Also:
Serialized Form

Field Summary
   
Fields inherited from interface javax.jms.Message
DEFAULT_DELIVERY_MODE, DEFAULT_PRIORITY, DEFAULT_TIME_TO_LIVE
 
Method Summary
 void clearBody()
          Clears the message body.
 boolean getBoolean(java.lang.String name)
          Gets the boolean value of the named key.
 byte getByte(java.lang.String name)
          Gets the byte value of the named key.
 byte[] getBytes(java.lang.String name)
          Gets the byte array value of the named key.
 char getChar(java.lang.String name)
          Gets the Unicode char value of the named key.
 double getDouble(java.lang.String name)
          Gets the double value of the named key.
 float getFloat(java.lang.String name)
          Gets the float value of the named key.
 int getInt(java.lang.String name)
          Gets the integer value of the named key.
 long getLong(java.lang.String name)
          Gets the long value of the named key.
 java.util.Enumeration getMapNames()
          Gets an Enumeration of all the MapMessage's names.
 java.lang.Object getObject(java.lang.String name)
          Gets the Java object with the given name.
 short getShort(java.lang.String name)
          Gets the short value of the named key.
 java.lang.String getString(java.lang.String name)
          Gets the String value of the named key.
 boolean itemExists(java.lang.String name)
          Checks whether an item exists in this MapMessage.
 void setBoolean(java.lang.String name, boolean value)
          Sets a boolean value with the given name in the map.
 void setByte(java.lang.String name, byte value)
          Sets a byte value with the given name in the map.
 void setBytes(java.lang.String name, byte[] value)
          Sets a byte array with the given name in the map.
 void setBytes(java.lang.String name, byte[] value, int offset, int length)
          Sets a portion of a byte array in the map with the given name.
 void setChar(java.lang.String name, char value)
          Sets a Unicode character with the given name in the map.
 void setDouble(java.lang.String name, double value)
          Sets a double value with the given name in the map.
 void setFloat(java.lang.String name, float value)
          Sets a floating point value with the given name in the map.
 void setInt(java.lang.String name, int value)
          Sets an integer value with the given name in the map.
 void setLong(java.lang.String name, long value)
          Sets a long value with the given name in the map.
 void setObject(java.lang.String name, java.lang.Object value)
          Sets a Java object with the given name in the map.
 void setShort(java.lang.String name, short value)
          Sets a short value with the given name in the map.
 void setString(java.lang.String name, java.lang.String value)
          Sets a String value with the given name in the map.
 java.lang.String toString()
          Creates a String which contains a formatted version of the Message.
 
Methods inherited from class com.ibm.jms.JMSMessage
acknowledge, clearProperties, getBooleanProperty, getByteProperty, getDoubleProperty, getFloatProperty, getIntProperty, getJMSCorrelationID, getJMSCorrelationIDAsBytes, getJMSDeliveryMode, getJMSDestination, getJMSExpiration, getJMSMessageID, getJMSPriority, getJMSRedelivered, getJMSReplyTo, getJMSTimestamp, getJMSType, getLongProperty, getObjectProperty, getPropertyNames, getShortProperty, getStringProperty, propertyExists, setBooleanProperty, setByteProperty, setDoubleProperty, setFloatProperty, setIntProperty, setJMSCorrelationID, setJMSCorrelationIDAsBytes, setJMSDeliveryMode, setJMSDestination, setJMSExpiration, setJMSMessageID, setJMSPriority, setJMSRedelivered, setJMSReplyTo, setJMSTimestamp, setJMSType, setLongProperty, setObjectProperty, setShortProperty, setStringProperty
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface javax.jms.Message
acknowledge, clearProperties, getBooleanProperty, getByteProperty, getDoubleProperty, getFloatProperty, getIntProperty, getJMSCorrelationID, getJMSCorrelationIDAsBytes, getJMSDeliveryMode, getJMSDestination, getJMSExpiration, getJMSMessageID, getJMSPriority, getJMSRedelivered, getJMSReplyTo, getJMSTimestamp, getJMSType, getLongProperty, getObjectProperty, getPropertyNames, getShortProperty, getStringProperty, propertyExists, setBooleanProperty, setByteProperty, setDoubleProperty, setFloatProperty, setIntProperty, setJMSCorrelationID, setJMSCorrelationIDAsBytes, setJMSDeliveryMode, setJMSDestination, setJMSExpiration, setJMSMessageID, setJMSPriority, setJMSRedelivered, setJMSReplyTo, setJMSTimestamp, setJMSType, setLongProperty, setObjectProperty, setShortProperty, setStringProperty
 

Method Detail

clearBody

public void clearBody()
               throws javax.jms.JMSException
Clears the message body. All other parts of the message are left untouched.

Specified by:
clearBody in interface javax.jms.Message
Specified by:
clearBody in class JMSMessage
Throws:
javax.jms.JMSException - if there is an internal JMS error.

getBoolean

public boolean getBoolean(java.lang.String name)
                   throws javax.jms.JMSException
Gets the boolean value of the named key.

Specified by:
getBoolean in interface javax.jms.MapMessage
Parameters:
name - the name of the key
Returns:
the boolean value.
Throws:
javax.jms.JMSException - if JMS fails to read the message due to an internal error.
javax.jms.MessageFormatException - if this type conversion is not valid.

getByte

public byte getByte(java.lang.String name)
             throws javax.jms.JMSException
Gets the byte value of the named key.

Specified by:
getByte in interface javax.jms.MapMessage
Parameters:
name - the name of the key
Returns:
the byte value.
Throws:
javax.jms.JMSException - if JMS fails to read the message due to an internal error.
javax.jms.MessageFormatException - if this type conversion is not valid.

getBytes

public byte[] getBytes(java.lang.String name)
                throws javax.jms.JMSException
Gets the byte array value of the named key.

Specified by:
getBytes in interface javax.jms.MapMessage
Parameters:
name - the name of the key
Returns:
the byte array.
Throws:
javax.jms.JMSException - if JMS fails to read the message due to an internal error.
javax.jms.MessageFormatException - if this type conversion is not valid.

getChar

public char getChar(java.lang.String name)
             throws javax.jms.JMSException
Gets the Unicode char value of the named key.

Specified by:
getChar in interface javax.jms.MapMessage
Parameters:
name - the name of the boolean key
Returns:
the char.
Throws:
javax.jms.JMSException - if JMS fails to read the message due to an internal error.
javax.jms.MessageFormatException - if this type conversion is not valid.

getDouble

public double getDouble(java.lang.String name)
                 throws javax.jms.JMSException
Gets the double value of the named key.

Specified by:
getDouble in interface javax.jms.MapMessage
Parameters:
name - the name of the key
Returns:
the double value.
Throws:
javax.jms.JMSException - if JMS fails to read the message due to an internal error.
javax.jms.MessageFormatException - if this type conversion is not valid.

getFloat

public float getFloat(java.lang.String name)
               throws javax.jms.JMSException
Gets the float value of the named key.

Specified by:
getFloat in interface javax.jms.MapMessage
Parameters:
name - the name of the key
Returns:
the float value.
Throws:
javax.jms.JMSException - if JMS fails to read the message due to an internal error.
javax.jms.MessageFormatException - if this type conversion is not valid.

getInt

public int getInt(java.lang.String name)
           throws javax.jms.JMSException
Gets the integer value of the named key.

Specified by:
getInt in interface javax.jms.MapMessage
Parameters:
name - the name of the key
Returns:
the integer value.
Throws:
javax.jms.JMSException - if JMS fails to read the message due to an internal error.
javax.jms.MessageFormatException - if this type conversion is not valid.

getLong

public long getLong(java.lang.String name)
             throws javax.jms.JMSException
Gets the long value of the named key.

Specified by:
getLong in interface javax.jms.MapMessage
Parameters:
name - the name of the key
Returns:
the long value.
Throws:
javax.jms.JMSException - if JMS fails to read the message due to an internal error.
javax.jms.MessageFormatException - if this type conversion is not valid.

getMapNames

public java.util.Enumeration getMapNames()
                                  throws javax.jms.JMSException
Gets an Enumeration of all the MapMessage's names.

Specified by:
getMapNames in interface javax.jms.MapMessage
Returns:
an enumeration of all the names in this MapMessage.
Throws:
javax.jms.JMSException - if JMS fails to read message due to an internal error.

getObject

public java.lang.Object getObject(java.lang.String name)
                           throws javax.jms.JMSException
Gets the Java object with the given name.

This method can be used to return, as a class instance, an object that had been stored in the Map with the equivalent setObject() method call, or its equivalent primitive setter method.

Specified by:
getObject in interface javax.jms.MapMessage
Parameters:
name - the name of the Java object
Returns:
a class which represents the object referred to by the given name. If there is no item by this name, a null value is returned.
Throws:
javax.jms.JMSException - if JMS fails to read message due to an internal error.

getShort

public short getShort(java.lang.String name)
               throws javax.jms.JMSException
Gets the short value of the named key.

Specified by:
getShort in interface javax.jms.MapMessage
Parameters:
name - the name of the key
Returns:
the short value.
Throws:
javax.jms.JMSException - if JMS fails to read the message due to an internal error.
javax.jms.MessageFormatException - if this type conversion is not valid.

getString

public java.lang.String getString(java.lang.String name)
                           throws javax.jms.JMSException
Gets the String value of the named key.

Specified by:
getString in interface javax.jms.MapMessage
Parameters:
name - the name of the key
Returns:
the String value.
Throws:
javax.jms.JMSException - if JMS fails to read the message due to an internal error.
javax.jms.MessageFormatException - if this type conversion is not valid.

itemExists

public boolean itemExists(java.lang.String name)
                   throws javax.jms.JMSException
Checks whether an item exists in this MapMessage.

Specified by:
itemExists in interface javax.jms.MapMessage
Parameters:
name - the name of the item to test
Returns:
true if the item does exist.
Throws:
javax.jms.JMSException - if a JMS error occurs.

setBoolean

public void setBoolean(java.lang.String name,
                       boolean value)
                throws javax.jms.JMSException
Sets a boolean value with the given name in the map.

Specified by:
setBoolean in interface javax.jms.MapMessage
Parameters:
name - the name of the boolean
value - the boolean value to set in the map.
Throws:
javax.jms.JMSException - if JMS fails to write the message due to an internal error.
javax.jms.MessageNotWriteableException - if the message in read-only mode.

setByte

public void setByte(java.lang.String name,
                    byte value)
             throws javax.jms.JMSException
Sets a byte value with the given name in the map.

Specified by:
setByte in interface javax.jms.MapMessage
Parameters:
name - the name of the byte
value - the byte value to set in the map.
Throws:
javax.jms.JMSException - if JMS fails to write the message due to an internal error.
javax.jms.MessageNotWriteableException - if the message in read-only mode.

setBytes

public void setBytes(java.lang.String name,
                     byte[] value)
              throws javax.jms.JMSException
Sets a byte array with the given name in the map.

Specified by:
setBytes in interface javax.jms.MapMessage
Parameters:
name - the name of the array
value - the byte array to set in the map.
Throws:
javax.jms.JMSException - if JMS fails to write the message due to an internal error.
javax.jms.MessageNotWriteableException - if the message in read-only mode.

setBytes

public void setBytes(java.lang.String name,
                     byte[] value,
                     int offset,
                     int length)
              throws javax.jms.JMSException
Sets a portion of a byte array in the map with the given name.

Specified by:
setBytes in interface javax.jms.MapMessage
Parameters:
name - the name of the byte array
value - the byte array to set in the Map.
offset - the initial offset within the byte array.
length - the number of bytes to use.
Throws:
javax.jms.JMSException - if JMS fails to write the message due to an internal error.
javax.jms.MessageNotWriteableException - if the message in read-only mode.

setChar

public void setChar(java.lang.String name,
                    char value)
             throws javax.jms.JMSException
Sets a Unicode character with the given name in the map.

Specified by:
setChar in interface javax.jms.MapMessage
Parameters:
name - the name of the character
value - the value to set in the Map.
Throws:
javax.jms.JMSException - if JMS fails to write the message due to an internal error.
javax.jms.MessageNotWriteableException - if the message in read-only mode.

setDouble

public void setDouble(java.lang.String name,
                      double value)
               throws javax.jms.JMSException
Sets a double value with the given name in the map.

Specified by:
setDouble in interface javax.jms.MapMessage
Parameters:
name - the name of the double
value - the value to set in the Map.
Throws:
javax.jms.JMSException - if JMS fails to write the message due to an internal error.
javax.jms.MessageNotWriteableException - if the message is in read-only mode.

setFloat

public void setFloat(java.lang.String name,
                     float value)
              throws javax.jms.JMSException
Sets a floating point value with the given name in the map.

Specified by:
setFloat in interface javax.jms.MapMessage
Parameters:
name - the name of the float
value - the value to set in the map.
Throws:
javax.jms.JMSException - if JMS fails to write the message due to an internal error.
javax.jms.MessageNotWriteableException - if the message in read-only mode.

setInt

public void setInt(java.lang.String name,
                   int value)
            throws javax.jms.JMSException
Sets an integer value with the given name in the map.

Specified by:
setInt in interface javax.jms.MapMessage
Parameters:
name - the name of the integer
value - the value to set in the Map.
Throws:
javax.jms.JMSException - if JMS fails to write the message due to an internal error.
javax.jms.MessageNotWriteableException - if the message in read-only mode.

setLong

public void setLong(java.lang.String name,
                    long value)
             throws javax.jms.JMSException
Sets a long value with the given name in the map.

Specified by:
setLong in interface javax.jms.MapMessage
Parameters:
name - the name of the long
value - the value to set in the Map.
Throws:
javax.jms.JMSException - if JMS fails to write the message due to an internal error.
javax.jms.MessageNotWriteableException - if the message in read-only mode.

setObject

public void setObject(java.lang.String name,
                      java.lang.Object value)
               throws javax.jms.JMSException
Sets a Java object with the given name in the map.

This method only works for the 'objectified' primitive object types (Integer, Double, Long ...), String, and byte arrays.

Specified by:
setObject in interface javax.jms.MapMessage
Parameters:
name - the name of the object
value - the value to set in the Map.
Throws:
javax.jms.JMSException - if JMS fails to write the message due to an internal error.
javax.jms.MessageNotWriteableException - if the message in read-only mode.

setShort

public void setShort(java.lang.String name,
                     short value)
              throws javax.jms.JMSException
Sets a short value with the given name in the map.

Specified by:
setShort in interface javax.jms.MapMessage
Parameters:
name - the name of the short
value - the short value to set in the map.
Throws:
javax.jms.JMSException - if JMS fails to write the message due to an internal error.
javax.jms.MessageNotWriteableException - if the message in read-only mode.

setString

public void setString(java.lang.String name,
                      java.lang.String value)
               throws javax.jms.JMSException
Sets a String value with the given name in the map.

Specified by:
setString in interface javax.jms.MapMessage
Parameters:
name - the name of the String
value - the String value to set in the Map.
Throws:
javax.jms.JMSException - if JMS fails to write the message due to an internal error.
javax.jms.MessageNotWriteableException - if the message in read-only mode.

toString

public java.lang.String toString()
Creates a String which contains a formatted version of the Message.

Overrides:
toString in class JMSMessage
Returns:
the formatted version of the Message.

(c) Copyright IBM Corp. 2005. All Rights Reserved.