Inherits from KMMessage : KCObject : NSObject
Declared in KMMapMessage.h

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

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