-
- All Superinterfaces:
Message
public interface MapMessage extends Message
AMapMessage
object is used to send a set of name-value pairs. The names areString
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 theMessage
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 toMapMessage.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, aMessageNotWriteableException
is thrown. IfclearBody
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 aJMSException
. TheString
-to-primitive conversions may throw a runtime exception if the primitive'svalueOf()
method does not accept it as a validString
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. Sincechar
does not support aString
conversion, attempting to read a null value as achar
must throw aNullPointerException
.- Since:
- JMS 1.0
- Version:
- Jakarta Messaging 2.0
- See Also:
Session.createMapMessage()
,BytesMessage
,Message
,ObjectMessage
,StreamMessage
,TextMessage
-
-
Field Summary
-
Fields inherited from interface jakarta.jms.Message
DEFAULT_DELIVERY_DELAY, DEFAULT_DELIVERY_MODE, DEFAULT_PRIORITY, DEFAULT_TIME_TO_LIVE
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description boolean
getBoolean(String name)
Returns theboolean
value with the specified name.byte
getByte(String name)
Returns thebyte
value with the specified name.byte[]
getBytes(String name)
Returns the byte array value with the specified name.char
getChar(String name)
Returns the Unicode character value with the specified name.double
getDouble(String name)
Returns thedouble
value with the specified name.float
getFloat(String name)
Returns thefloat
value with the specified name.int
getInt(String name)
Returns theint
value with the specified name.long
getLong(String name)
Returns thelong
value with the specified name.Enumeration
getMapNames()
Returns anEnumeration
of all the names in theMapMessage
object.Object
getObject(String name)
Returns the value of the object with the specified name.short
getShort(String name)
Returns theshort
value with the specified name.String
getString(String name)
Returns theString
value with the specified name.boolean
itemExists(String name)
Indicates whether an item exists in thisMapMessage
object.void
setBoolean(String name, boolean value)
Sets aboolean
value with the specified name into the Map.void
setByte(String name, byte value)
Sets abyte
value with the specified name into the Map.void
setBytes(String name, byte[] value)
Sets a byte array value with the specified name into the Map.void
setBytes(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(String name, char value)
Sets a Unicode character value with the specified name into the Map.void
setDouble(String name, double value)
Sets adouble
value with the specified name into the Map.void
setFloat(String name, float value)
Sets afloat
value with the specified name into the Map.void
setInt(String name, int value)
Sets anint
value with the specified name into the Map.void
setLong(String name, long value)
Sets along
value with the specified name into the Map.void
setObject(String name, Object value)
Sets an object value with the specified name into the Map.void
setShort(String name, short value)
Sets ashort
value with the specified name into the Map.void
setString(String name, String value)
Sets aString
value with the specified name into the Map.-
Methods inherited from interface jakarta.jms.Message
acknowledge, clearBody, clearProperties, getBody, getBooleanProperty, getByteProperty, getDoubleProperty, getFloatProperty, getIntProperty, getJMSCorrelationID, getJMSCorrelationIDAsBytes, getJMSDeliveryMode, getJMSDeliveryTime, getJMSDestination, getJMSExpiration, getJMSMessageID, getJMSPriority, getJMSRedelivered, getJMSReplyTo, getJMSTimestamp, getJMSType, getLongProperty, getObjectProperty, getPropertyNames, getShortProperty, getStringProperty, isBodyAssignableTo, propertyExists, setBooleanProperty, setByteProperty, setDoubleProperty, setFloatProperty, setIntProperty, setJMSCorrelationID, setJMSCorrelationIDAsBytes, setJMSDeliveryMode, setJMSDeliveryTime, setJMSDestination, setJMSExpiration, setJMSMessageID, setJMSPriority, setJMSRedelivered, setJMSReplyTo, setJMSTimestamp, setJMSType, setLongProperty, setObjectProperty, setShortProperty, setStringProperty
-
-
-
-
Method Detail
-
getBoolean
boolean getBoolean(String name) throws JMSException
Returns theboolean
value with the specified name.- Parameters:
name
- the name of theboolean
- Returns:
- the
boolean
value with the specified name - Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageFormatException
- if this type conversion is invalid.
-
getByte
byte getByte(String name) throws JMSException
Returns thebyte
value with the specified name.- Parameters:
name
- the name of thebyte
- Returns:
- the
byte
value with the specified name - Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageFormatException
- if this type conversion is invalid.
-
getShort
short getShort(String name) throws JMSException
Returns theshort
value with the specified name.- Parameters:
name
- the name of theshort
- Returns:
- the
short
value with the specified name - Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageFormatException
- if this type conversion is invalid.
-
getChar
char getChar(String name) throws JMSException
Returns the Unicode character value with the specified name.- Parameters:
name
- the name of the Unicode character- Returns:
- the Unicode character value with the specified name
- Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageFormatException
- if this type conversion is invalid.
-
getInt
int getInt(String name) throws JMSException
Returns theint
value with the specified name.- Parameters:
name
- the name of theint
- Returns:
- the
int
value with the specified name - Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageFormatException
- if this type conversion is invalid.
-
getLong
long getLong(String name) throws JMSException
Returns thelong
value with the specified name.- Parameters:
name
- the name of thelong
- Returns:
- the
long
value with the specified name - Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageFormatException
- if this type conversion is invalid.
-
getFloat
float getFloat(String name) throws JMSException
Returns thefloat
value with the specified name.- Parameters:
name
- the name of thefloat
- Returns:
- the
float
value with the specified name - Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageFormatException
- if this type conversion is invalid.
-
getDouble
double getDouble(String name) throws JMSException
Returns thedouble
value with the specified name.- Parameters:
name
- the name of thedouble
- Returns:
- the
double
value with the specified name - Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageFormatException
- if this type conversion is invalid.
-
getString
String getString(String name) throws JMSException
Returns theString
value with the specified name.- Parameters:
name
- the name of theString
- Returns:
- the
String
value with the specified name; if there is no item by this name, a null value is returned - Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageFormatException
- if this type conversion is invalid.
-
getBytes
byte[] getBytes(String name) throws JMSException
Returns the byte array value with the specified name.- Parameters:
name
- the name of the byte array- Returns:
- a copy of the byte array value with the specified name; if there is no item by this name, a null value is returned.
- Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.MessageFormatException
- if this type conversion is invalid.
-
getObject
Object getObject(String name) throws JMSException
Returns the value of the object with the specified name.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 primitivesettype
method.Note that byte values are returned as
byte[]
, notByte[]
.- Parameters:
name
- the name of the Java object- Returns:
- a copy of the Java object value with the specified name, in objectified format (for example, if the object
was set as an
int
, anInteger
is returned); if there is no item by this name, a null value is returned - Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.
-
getMapNames
Enumeration getMapNames() throws JMSException
Returns anEnumeration
of all the names in theMapMessage
object.- Returns:
- an enumeration of all the names in this
MapMessage
- Throws:
JMSException
- if the Jakarta Messaging provider fails to read the message due to some internal error.
-
setBoolean
void setBoolean(String name, boolean value) throws JMSException
Sets aboolean
value with the specified name into the Map.- Parameters:
name
- the name of theboolean
value
- theboolean
value to set in the Map- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.IllegalArgumentException
- if the name is null or if the name is an empty string.MessageNotWriteableException
- if the message is in read-only mode.
-
setByte
void setByte(String name, byte value) throws JMSException
Sets abyte
value with the specified name into the Map.- Parameters:
name
- the name of thebyte
value
- thebyte
value to set in the Map- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.IllegalArgumentException
- if the name is null or if the name is an empty string.MessageNotWriteableException
- if the message is in read-only mode.
-
setShort
void setShort(String name, short value) throws JMSException
Sets ashort
value with the specified name into the Map.- Parameters:
name
- the name of theshort
value
- theshort
value to set in the Map- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.IllegalArgumentException
- if the name is null or if the name is an empty string.MessageNotWriteableException
- if the message is in read-only mode.
-
setChar
void setChar(String name, char value) throws JMSException
Sets a Unicode character value with the specified name into the Map.- Parameters:
name
- the name of the Unicode charactervalue
- the Unicode character value to set in the Map- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.IllegalArgumentException
- if the name is null or if the name is an empty string.MessageNotWriteableException
- if the message is in read-only mode.
-
setInt
void setInt(String name, int value) throws JMSException
Sets anint
value with the specified name into the Map.- Parameters:
name
- the name of theint
value
- theint
value to set in the Map- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.IllegalArgumentException
- if the name is null or if the name is an empty string.MessageNotWriteableException
- if the message is in read-only mode.
-
setLong
void setLong(String name, long value) throws JMSException
Sets along
value with the specified name into the Map.- Parameters:
name
- the name of thelong
value
- thelong
value to set in the Map- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.IllegalArgumentException
- if the name is null or if the name is an empty string.MessageNotWriteableException
- if the message is in read-only mode.
-
setFloat
void setFloat(String name, float value) throws JMSException
Sets afloat
value with the specified name into the Map.- Parameters:
name
- the name of thefloat
value
- thefloat
value to set in the Map- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.IllegalArgumentException
- if the name is null or if the name is an empty string.MessageNotWriteableException
- if the message is in read-only mode.
-
setDouble
void setDouble(String name, double value) throws JMSException
Sets adouble
value with the specified name into the Map.- Parameters:
name
- the name of thedouble
value
- thedouble
value to set in the Map- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.IllegalArgumentException
- if the name is null or if the name is an empty string.MessageNotWriteableException
- if the message is in read-only mode.
-
setString
void setString(String name, String value) throws JMSException
Sets aString
value with the specified name into the Map.- Parameters:
name
- the name of theString
value
- theString
value to set in the Map- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.IllegalArgumentException
- if the name is null or if the name is an empty string.MessageNotWriteableException
- if the message is in read-only mode.
-
setBytes
void setBytes(String name, byte[] value) throws JMSException
Sets a byte array value with the specified name into the Map.- Parameters:
name
- the name of the byte arrayvalue
- the byte array value to set in the Map; the array is copied so that the value forname
will not be altered by future modifications- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.IllegalArgumentException
- if the name is null, or if the name is an empty string.MessageNotWriteableException
- if the message is in read-only mode.
-
setBytes
void setBytes(String name, byte[] value, int offset, int length) throws JMSException
Sets a portion of the byte array value with the specified name into the Map.- Parameters:
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- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.IllegalArgumentException
- if the name is null or if the name is an empty string.MessageNotWriteableException
- if the message is in read-only mode.
-
setObject
void setObject(String name, Object value) throws JMSException
Sets an object value with the specified name into the Map.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 objectvalue
- the Java object value to set in the Map- Throws:
JMSException
- if the Jakarta Messaging provider fails to write the message due to some internal error.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.
-
itemExists
boolean itemExists(String name) throws JMSException
Indicates whether an item exists in thisMapMessage
object.- Parameters:
name
- the name of the item to test- Returns:
- true if the item exists
- Throws:
JMSException
- if the Jakarta Messaging provider fails to determine if the item exists due to some internal error.
-
-