JMS provides five forms of message body. Each form is defined by a message interface: • StreamMessage - a message whose body contains a stream of Java primitive values. It is filled and read sequentially. • MapMessage - a message whose body contains a set of name-value pairs where names are String objects and values are Java primitive types. The entries can be accessed sequentially by enumerator or randomly by name. The order of the entries is undefined. • TextMessage - a message whose body contains a java.lang.String. The inclusion of this message type is based on our presumption that String messages will be used extensively. One reason for this is that XML will likely become a popular mechanism for representing the content of JMS messages. • ObjectMessage - a message that contains a serializable Java object. If a collection of Java objects is needed, one of the collection classes provided in JDK 1.2 can be used. • BytesMessage - a message that contains a stream of uninterpreted bytes. This message type is for literally encoding a body to match an existing message format. In many cases, it will be possible to use one of 44 Java Message Service Version 2.0
the other, self-defining, message types instead. Although JMS allows the use of message properties with byte messages it is typically not done since the inclusion of properties may affect the format.
3.11.1. Clearing a message body The clearBody method of Message resets the value of the message body to the ‘empty’ initial message value as set by the message type’s create method provided by Session. Clearing a message’s body does not clear its property entries. 3.11.2. Read-only message body When a message is received, its body is read only. If an attempt is made to change the body a MessageNotWriteableException must be thrown. If its body is subsequently cleared, the body is in the same state as an empty body in a newly created message. 3.11.3. Conversions provided by StreamMessage and MapMessage Both StreamMessage and MapMessage support the same set of primitive data types. The 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 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. Both StreamMessage and MapMessage support the following conversion table. The marked cases must be supported. The unmarked cases must throw a JMS MessageFormatException. The String to numeric conversions must throw a java.lang.NumberFormatException if the numeric’s valueOf() method does not accept the String value as a valid representation. StreamMessage and MapMessage must implement the String to boolean conversion as specified by the valueOf(String) method of Boolean as defined by the Java language. Attempting to read a null value as a Java 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 NullPointerException. Getting a MapMessage field for a field name that has not been set is handled as if the field exists with a null value. If a read method of StreamMessage or BytesMessage throws a MessageFormatException or NumberFormatException, the current position of the read pointer must not be incremented. A subsequent read must be capable of recovering from the exception by rereading the data as a different type. A value written as the row type can be read as the column type Table 3-7 Conversions for StreamMessage and MapMessage boolean byte short char int long float double String byte[]