JMS Message payload

How payload is extracted from the JMS message for each of the JMS Message types.

The payload for some of the JMS message types can be extracted as a whole from the message object by using the JMS API. The payload is passed as a bit stream to an integration node parser. This is true for the following message types:

BytesMessage
TextMessage
ObjectMessage
Additional processing is required to deal with the ObjectMessage payload because the JMS ObjectMessage payload is a serialized Java™ Object.

The JMSInput node obtains the payload by calling getObject( ) on the message. getObject( ) returns a de-serialized object of the original class. This class definition must be made available to the JMSInput node, and you should ensure that it is accessible through the integration node's Java class path. (The class path is defined in the mqsiprofile batch file, which is in the integration node's executable directory; for example, on Windows, this is mqsiprofile.cmd in the install_dir/bin directory.) The JMSInput node invokes the BLOB parser, which creates the message body by using a bit stream that is created from the object.

The Java Object can be subsequently re-serialized in a JavaCompute node or a user-defined extension, and is updated by using its method calls.

The payload for MapMessage and StreamMessage can be extracted only as individual elements and must be reformatted by the JMSInput node before it can be used to create the message body.

MapMessage payload
The JMSMap domain is a synonym for the integration node XML parser, which expects a stream of XML data. MapMessage payload data however, is extracted as sets of name-value pairs from the message object. The JMS API is used to obtain the name-value pairs.

The JMSInput node appends each name-value pair to a bit stream as an XML element and value, and preserves the type of the value by using the dt= attribute.
The following example shows the XML that is generated by the JMSInput node for the MapMessage payload:
```
	<map>
	    <Item_8_of_10_Char dt='char'>A</Item_8_of_10_Char>
 	    <Item_5_of_10_Double dt='r8'>999999.0</Item_5_of_10_Double>
 	    <Item_10_of_10_String>Last Map Item</Item_10_of_10_String>
 	    <Item_9_of_10_Boolean dt='boolean'>0</Item_9_of_10_Boolean>
 	    <Item_2_of_10_Integrer dt='i4'>999</Item_2_of_10_Integrer>
 	    <Item_3_of_10_Short dt='i2'>9999</Item_3_of_10_Short>
 	    <Item_7_of_10_Byte dt='i1'>9</Item_7_of_10_Byte>
 	    <Item_6_of_10_Float dt='r4'>2.24</Item_6_of_10_Float>
 	    <Item_1_of_10_String>P2P Map Msg Number:1</Item_1_of_10_String>
 	    <Item_4_of_10_Long dt='i8'>99999</Item_4_of_10_Long>
           </map>
```
In this example, the message contains 10 fields. The field names have been generated by a JMS Client application, and take the form item_n_of_x_t, where:
- n is the sequence number in which the item was added to the message,
- x is the total number of items in the map,
- t is the type of the value.
The map data is not returned from the JMS API the order in which it was received.
If a JMSInput node receives a JMS MapMessage that contains characters that would be invalid in an XML tag, it escapes the names as follows:
1. The XML tag of the name element is formed by truncating the JMS message name element up to the location of the first invalid character.
2. The original name from the JMS name element is preserved in an attribute of the XML tag.
3. The closing XML tag matches the opening tag, without the tag attribute.
For example, a name-value pair of <ORDER_ITEM[5]><WIDGET> in a JMS MapMessage would be converted to XML and written to the message tree as <ORDER_ITEM ibm_original_name="ORDER_ITEM[5]">WIDGET</ORDER_ITEM>
StreamMessage payload
The StreamMessage payload data is a sequence of fields, where each field has a specific type. The fields do not have associated names and so a default element name elt is used to generate the XML elements. Similar to the MapMessage, the JMS API allows for fields only to be retrieved individually. The JMSInput node extracts fields from the JMS message and appends each to a bit stream in XML format.
The following is an example of the XML that is generated by the JMSInput node for the StreamMessage payload:
```
<stream>
     <elt>P2P Stream Message  Number :7</elt>
     <elt dt='i4'>999</elt>
     <elt dt='i2'>9999</elt>
     <elt dt='i8'>99999</elt>
     <elt dt='r8'>999999.0</elt>
     <elt dt='r4'>2.24</elt>
     <elt dt='i1'>9</elt>
     <elt dt='char'>A</elt>
     <elt dt='boolean'>0</elt>
     <elt>Last Stream Item</elt>
</stream>
```
In this example, 10 typed values are added to the StreamMessage by a JMS client application.