KMMapMessage Class Reference
Overview
A KMMapMessage object is used to send a set of name-value pairs. The names are String objects, and the values are primitive data types. 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. KMMapMessage 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 KMMapMessage.setInt(“foo”, 6) is equivalent to KMMapMessage.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 KMMapMessage, it is in read-only mode. If a client attempts to write to the message at this point, a KMMessageNotWriteableException is thrown. If clearBody is called, the message can now be both read from and written to.
KMMapMessage objects support the following conversion table. The marked cases must be supported. The unmarked cases must throw a KMJMSException. 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 an exception.
Tasks
-
– getBoolean:
Returns the boolean value with the specified name.
-
– getByte:
Returns the byte value with the specified name.
-
– getShort:
Returns the short value with the specified name.
-
– getChar:
Returns the Unicode character value with the specified name.
-
– getInt:
Returns the int value with the specified name.
-
– getLong:
Returns the long value with the specified name.
-
– getFloat:
Returns the float value with the specified name.
-
– getDouble:
Returns the double value with the specified name.
-
– getString:
Returns the String value with the specified name.
-
– getBytes:
Returns the byte array value with the specified name.
-
– getObject:
Returns the value of the object with the specified name.
-
– mapNames
Returns an Enumeration of all the names in the KMMapMessage object.
-
– setBoolean:value:
Sets a boolean value with the specified name into the Map.
-
– setByte:value:
Sets a byte value with the specified name into the Map.
-
– setShort:value:
Sets a short value with the specified name into the Map.
-
– setChar:value:
Sets a Unicode character value with the specified name into the Map.
-
– setInt:value:
Sets an int value with the specified name into the Map.
-
– setLong:value:
Sets a long value with the specified name into the Map.
-
– setFloat:value:
Sets a float value with the specified name into the Map.
-
– setDouble:value:
Sets a double value with the specified name into the Map.
-
– setString:value:
Sets a String value with the specified name into the Map.
-
– setBytes:value:
Sets a byte array value with the specified name into the Map.
-
– setBytes:value:offset:length:
Sets a portion of the byte array value with the specified name into the Map.
-
– setObject:value:
Sets an object value with the specified name into the Map.
-
– itemExists:
Indicates whether an item exists in this KMMapMessage object.
Instance Methods
getBoolean:
Returns the boolean value with the specified name.
- (BOOL)getBoolean:(NSString *)name
Parameters
- name
the name of the boolean
Return Value
the boolean value with the specified name
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageFormatException
if this type conversion is invalid.
Declared In
KMMapMessage.h
getByte:
Returns the byte value with the specified name.
- (Byte)getByte:(NSString *)name
Parameters
- name
the name of the byte
Return Value
the byte value with the specified name
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageFormatException
if this type conversion is invalid.
Declared In
KMMapMessage.h
getBytes:
Returns the byte array value with the specified name.
- (NSData *)getBytes:(NSString *)name
Parameters
- name
the name of the byte array
Return Value
a copy of the byte array value with the specified name; if there is no item by this name, a null value is returned.
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageFormatException
if this type conversion is invalid.
Declared In
KMMapMessage.h
getChar:
Returns the Unicode character value with the specified name.
- (char)getChar:(NSString *)name
Parameters
- name
the name of the Unicode character
Return Value
the Unicode character value with the specified name
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageFormatException
if this type conversion is invalid.
Declared In
KMMapMessage.h
getDouble:
Returns the double value with the specified name.
- (double)getDouble:(NSString *)name
Parameters
- name
the name of the double
Return Value
the double value with the specified name
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageFormatException
if this type conversion is invalid.
Declared In
KMMapMessage.h
getFloat:
Returns the float value with the specified name.
- (float)getFloat:(NSString *)name
Parameters
- name
the name of the float
Return Value
the float value with the specified name
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageFormatException
if this type conversion is invalid.
Declared In
KMMapMessage.h
getInt:
Returns the int value with the specified name.
- (int)getInt:(NSString *)name
Parameters
- name
the name of the int
Return Value
the int value with the specified name
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageFormatException
if this type conversion is invalid.
Declared In
KMMapMessage.h
getLong:
Returns the long value with the specified name.
- (long long)getLong:(NSString *)name
Parameters
- name
the name of the long
Return Value
the long value with the specified name
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageFormatException
if this type conversion is invalid.
Declared In
KMMapMessage.h
getObject:
Returns the value of the object with the specified name.
- (NSObject *)getObject:(NSString *)name
Parameters
- name
the name of the object
Return Value
The return value is one of NSString, NSData, or NSNumber types depending on the type of value matching the key. nil is returned if there is no matching key, or if the value itself is empty (null). If the map message entry contains a string or byte array, then getObject returns NSString or NSData respectively. Numeric values, as well as byte and boolean are returned as NSNumber. The application developer may prefer to use the appropriate getter methods to retrieve the value when the data type is known to retrieve a specific data type.
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
Declared In
KMMapMessage.h
getShort:
Returns the short value with the specified name.
- (short)getShort:(NSString *)name
Parameters
- name
the name of the short
Return Value
the short value with the specified name
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageFormatException
if this type conversion is invalid.
Declared In
KMMapMessage.h
getString:
Returns the String value with the specified name.
- (NSString *)getString:(NSString *)name
Parameters
- name
the name of the String
Return Value
the String value with the specified name; if there is no item by this name, a null value is returned
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
- KMMessageFormatException
if this type conversion is invalid.
Declared In
KMMapMessage.h
itemExists:
Indicates whether an item exists in this KMMapMessage object.
- (BOOL)itemExists:(NSString *)name
Parameters
- name
the name of the item to test
Return Value
true if the item exists
Exceptions
- KMJMSException
if the JMS provider fails to determine if the item exists due to some internal error.
Declared In
KMMapMessage.h
mapNames
Returns an Enumeration of all the names in the KMMapMessage object.
- (NSEnumerator *)mapNames
Return Value
an enumeration of all the names in this KMMapMessage
Exceptions
- KMJMSException
if the JMS provider fails to read the message due to some internal error.
Declared In
KMMapMessage.h
setBoolean:value:
Sets a boolean value with the specified name into the Map.
- (void)setBoolean:(NSString *)name value:(BOOL)value
Parameters
- name
the name of the boolean
- value
the boolean value to set in the Map
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- NSException
if the name is null or if the name is an empty string.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMMapMessage.h
setByte:value:
Sets a byte value with the specified name into the Map.
- (void)setByte:(NSString *)name value:(Byte)value
Parameters
- name
the name of the byte
- value
the byte value to set in the Map
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- NSException
if the name is null or if the name is an empty string.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMMapMessage.h
setBytes:value:
Sets a byte array value with the specified name into the Map.
- (void)setBytes:(NSString *)name value:(NSData *)value
Parameters
- name
the name of the byte array
- value
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
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- NSException
if the name is null, or if the name is an empty string.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMMapMessage.h
setBytes:value:offset:length:
Sets a portion of the byte array value with the specified name into the Map.
- (void)setBytes:(NSString *)name value:(NSData *)value offset:(int)offset length:(int)length
Parameters
- name
the name of the byte array
- value
the byte array value to set in the Map
- offset
the initial offset within the byte array
- length
the number of bytes to use
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- NSException
if the name is null or if the name is an empty string.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMMapMessage.h
setChar:value:
Sets a Unicode character value with the specified name into the Map.
- (void)setChar:(NSString *)name value:(char)value
Parameters
- name
the name of the Unicode character
- value
the Unicode character value to set in the Map
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- NSException
if the name is null or if the name is an empty string.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMMapMessage.h
setDouble:value:
Sets a double value with the specified name into the Map.
- (void)setDouble:(NSString *)name value:(double)value
Parameters
- name
the name of the double
- value
the double value to set in the Map
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- NSException
if the name is null or if the name is an empty string.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMMapMessage.h
setFloat:value:
Sets a float value with the specified name into the Map.
- (void)setFloat:(NSString *)name value:(float)value
Parameters
- name
the name of the float
- value
the float value to set in the Map
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- NSException
if the name is null or if the name is an empty string.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMMapMessage.h
setInt:value:
Sets an int value with the specified name into the Map.
- (void)setInt:(NSString *)name value:(int)value
Parameters
- name
the name of the int
- value
the int value to set in the Map
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- NSException
if the name is null or if the name is an empty string.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMMapMessage.h
setLong:value:
Sets a long value with the specified name into the Map.
- (void)setLong:(NSString *)name value:(long long)value
Parameters
- name
the name of the long
- value
the long value to set in the Map
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- NSException
if the name is null or if the name is an empty string.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMMapMessage.h
setObject:value:
Sets an object value with the specified name into the Map.
- (void)setObject:(NSString *)name value:(NSObject *)value
Parameters
- name
the name of the object
- value
the object value to set in the Map
Discussion
This method works only for NSNumber, NSString, and NSData.
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- NSException
if the name is null or if the name is an empty string.
- KMMessageFormatException
if the object is invalid.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMMapMessage.h
setShort:value:
Sets a short value with the specified name into the Map.
- (void)setShort:(NSString *)name value:(short)value
Parameters
- name
the name of the short
- value
the short value to set in the Map
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- NSException
if the name is null or if the name is an empty string.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMMapMessage.h
setString:value:
Sets a String value with the specified name into the Map.
- (void)setString:(NSString *)name value:(NSString *)value
Parameters
- name
the name of the String
- value
the String value to set in the Map
Exceptions
- KMJMSException
if the JMS provider fails to write the message due to some internal error.
- NSException
if the name is null or if the name is an empty string.
- KMMessageNotWriteableException
if the message is in read-only mode.
Declared In
KMMapMessage.h