JMSMapMessage
public class JMSMapMessage
extends JMSMessage
implements MapMessage
java.lang.Object
|
+----com.ibm.jms.JMSMessage
|
+----com.ibm.jms.JMSMapMessage
JMSMapMessage is used to send a set of name-value pairs where
names are Strings and values are Java primitive types. 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 primitives
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
--------------------------------------------------------------------------
Methods
clearBody
public void clearBody() throws JMSException;
Clears the message body. All other parts of the message are left untouched.
- Exceptions
-
- JMSException - if there is an internal JMS error.
getBoolean
public boolean getBoolean(String name) throws JMSException;
Gets the boolean value of the named key.
- Parameters
-
- name - the name of the key
- Returns
-
- Exceptions
-
- JMSException - if JMS fails to read the message due to an internal error.
- MessageFormatException - if this type conversion is not valid.
getByte
public byte getByte(String name) throws JMSException;
Gets the byte value of the named key.
- Parameters
-
- name - the name of the key
- Returns
-
- Exceptions
-
- JMSException - if JMS fails to read the message due to an internal error.
- MessageFormatException - if this type conversion is not valid.
getBytes
public byte[] getBytes(String name) throws JMSException;
Gets the byte array value of the named key.
- Parameters
-
- name - the name of the key
- Returns
-
- Exceptions
-
- JMSException - if JMS fails to read the message due to an internal error.
- MessageFormatException - if this type conversion is not valid.
getChar
public char getChar(String name) throws JMSException;
Gets the Unicode char value of the named key.
- Parameters
-
- name - the name of the boolean key
- Returns
-
- Exceptions
-
- JMSException - if JMS fails to read the message due to an internal error.
- MessageFormatException - if this type conversion is not valid.
getDouble
public double getDouble(String name) throws JMSException;
Gets the double value of the named key.
- Parameters
-
- name - the name of the key
- Returns
-
- Exceptions
-
- JMSException - if JMS fails to read the message due to an internal error.
- MessageFormatException - if this type conversion is not valid.
getFloat
public float getFloat(String name) throws JMSException;
Gets the float value of the named key.
- Parameters
-
- name - the name of the key
- Returns
-
- Exceptions
-
- JMSException - if JMS fails to read the message due to an internal error.
- MessageFormatException - if this type conversion is not valid.
getInt
public int getInt(String name) throws JMSException;
Gets the integer value of the named key.
- Parameters
-
- name - the name of the key
- Returns
-
- Exceptions
-
- JMSException - if JMS fails to read the message due to an internal error.
- MessageFormatException - if this type conversion is not valid.
getLong
public long getLong(String name) throws JMSException;
Gets the long value of the named key.
- Parameters
-
- name - the name of the key
- Returns
-
- Exceptions
-
- JMSException - if JMS fails to read the message due to an internal error.
- MessageFormatException - if this type conversion is not valid.
getMapNames
public Enumeration getMapNames() throws JMSException;
Gets an Enumeration of all the MapMessage's names.
- Returns
-
- an enumeration of all the names in this MapMessage.
- Exceptions
-
- JMSException - if JMS fails to read message due to an internal error.
getObject
public Object getObject(String name) throws 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.
- 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.
- Exceptions
-
- JMSException - if JMS fails to read message due to an internal error.
getShort
public short getShort(String name) throws JMSException;
Gets the short value of the named key.
- Parameters
-
- name - the name of the key
- Returns
-
- Exceptions
-
- JMSException - if JMS fails to read the message due to an internal error.
- MessageFormatException - if this type conversion is not valid.
getString
public String getString(String name) throws JMSException;
Gets the String value of the named key.
- Parameters
-
- name - the name of the key
- Returns
-
- Exceptions
-
- JMSException - if JMS fails to read the message due to an internal error.
- MessageFormatException - if this type conversion is not valid.
itemExists
public boolean itemExists(String name) throws JMSException;
Checks whether an item exists in this MapMessage.
- Parameters
-
- name - the name of the item to test
- Returns
-
- trueif the item does exist.
- Exceptions
-
- JMSException - if a JMS error occurs.
setBoolean
public void setBoolean(String name, boolean value) throws JMSException;
Sets a boolean value with the given name in the map.
- Parameters
-
- name - the name of the boolean
- value - the boolean value to set in the map.
- Exceptions
-
- JMSException - if JMS fails to write the message due to an internal error.
- MessageNotWriteableException - if the message in read-only mode.
setByte
public void setByte(String name, byte value) throws JMSException;
Sets a byte value with the given name in the map.
- Parameters
-
- name - the name of the byte
- value - the byte value to set in the map.
- Exceptions
-
- JMSException - if JMS fails to write the message due to an internal error.
- MessageNotWriteableException - if the message in read-only mode.
setBytes
public void setBytes(String name, byte[] value) throws JMSException;
Sets a byte array with the given name in the map.
- Parameters
-
- name - the name of the array
- value - the byte array to set in the map.
- Exceptions
-
- JMSException - if JMS fails to write the message due to an internal error.
- MessageNotWriteableException - if the message in read-only mode.
setBytes
public void setBytes(String name, byte[] value, int offset, int length)
throws JMSException;
Sets a portion of a byte array in the map with the given name.
- 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.
- Exceptions
-
- JMSException - if JMS fails to write the message due to an internal error.
- MessageNotWriteableException - if the message in read-only mode.
setChar
public void setChar(String name, char value) throws JMSException;
Sets a Unicode character with the given name in the map.
- Parameters
-
- name - the name of the character
- value - the value to set in the Map.
- Exceptions
-
- JMSException - if JMS fails to write the message due to an internal error.
- MessageNotWriteableException - if the message in read-only mode.
setDouble
public void setDouble(String name, double value) throws JMSException;
Sets a double value with the given name in the map.
- Parameters
-
- name - the name of the double
- value - the value to set in the Map.
- Exceptions
-
- JMSException - if JMS fails to write the message due to an internal error.
- MessageNotWriteableException - if the message is in read-only mode.
setFloat
public void setFloat(String name, float value) throws JMSException;
Sets a floating point variable with the given name in the map.
- Parameters
-
- name - the name of the float
- value - the value to set in the map.
- Exceptions
-
- JMSException - if JMS fails to write the message due to an internal error.
- MessageNotWriteableException - if the message in read-only mode.
setInt
public void setInt(String name, int value) throws JMSException;
Sets an integer with the given name in the map.
- Parameters
-
- name - the name of the integer
- value - the value to set in the Map.
- Exceptions
-
- JMSException - if JMS fails to write the message due to an internal error.
- MessageNotWriteableException - if the message in read-only mode.
setLong
public void setLong(String name, long value) throws JMSException;
Sets a long with the given name in the map.
- Parameters
-
- name - the name of the long
- value - the value to set in the Map.
- Exceptions
-
- JMSException - if JMS fails to write the message due to an internal error.
- MessageNotWriteableException - if the message in read-only mode.
setObject
public void setObject(String name, Object value) throws 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.
- Parameters
-
- name - the name of the object
- value - the value to set in the Map.
- Exceptions
-
- JMSException - if JMS fails to write the message due to an internal error.
- MessageNotWriteableException - if the message in read-only mode.
setShort
public void setShort(String name, short value) throws JMSException;
Sets a short value with the given name in the map.
- Parameters
-
- name - the name of the short
- value - the short value to set in the map.
- Exceptions
-
- JMSException - if JMS fails to write the message due to an internal error.
- MessageNotWriteableException - if the message in read-only mode.
setString
public void setString(String name, String value) throws JMSException;
Sets a String value with the given name in the map.
- Parameters
-
- name - the name of the String
- value - the String value to set in the Map.
- Exceptions
-
- JMSException - if JMS fails to write the message due to an internal error.
- MessageNotWriteableException - if the message in read-only mode.
toString
public String toString();
Creates a String which contains a formatted version of the Message.
- Returns
-
- the formatted version of the Message.