The ESB JMS Encoder and Decoder Components

Some integration solutions involve JMS and SOAP messages sent to or from IBM WebSphere MQ Series messaging systems. The Microsoft ESB Guidance includes two JMS pipeline components for use in these situations. The components read or write the JMS portion of the MQ message header using the values of context properties associated with the message. However, there are more than 60 different types of JMS headers in use with WebSphere MQ Series systems. The ESB JMS components work only with MQRFH2 headers.

Installation

Installing the ESB Core automatically installs the JMS Encoder and JMS Decoder components** **in the pipeline components folder. To install the components for design-time use, see the instructions about how to add the components to the Visual Studio Toolbox palette in the topic Installing Services and Components.

How They Work

The JMS pipeline components inspect the message headers and operate only on messages that have the MQMD_Format header set to RFH (MQRFH2). However, even when this property is set, the components inspect the headers to confirm that they do conform to the IBM RFH2 format. If they do not, the components generate a parse error that indicates the MQMD_Format parameter was set to RFH (MQRFH2), but the structure of the header did not comply with the RFH2 standard. If inbound message header parsing fails, the decoder component allows the message to pass, but it sets a message context property named MQRFH2_ParseError to True.

The MQRFH2 property schema deployed in BizTalk with the JMS components exposes all of the MQRFH2 header properties. After demoting the headers of an incoming message, the data from the headers resides in an XML document stored in the MQRFH2_NameValueData context property of the message. To understand the usage of these headers, and the impact when changing the values, review the appropriate IBM documentation.

Using the JMS Encoder and Decoder Components

To use the JMS Encoder and Decoder components, developers add them to pipelines in a BizTalk application. For a send pipeline, the JMS Encoder component should reside in the Encode stage. For a receive pipeline, the JMS Decoder component should reside in the Decode stage. The JMS components will not install in any other stages of a pipeline.

When installed in the Encode stage, the JMS Encoder component reads the values in the JMS MQRFH2 headers and writes (promotes) them into the message context properties. When installed in the Decode stage, the JMS Decoder component reads (demotes) the context property values and inserts them into the JMS MQRFH2 headers. This means that all the MQ header values are available as context properties of the message within the pipeline.

To detect and manage header-parsing errors, developers can include code that examines the value of the MQRFH2_ParseError property. They can implement a recovery process that subscribes to failed messages, or they can specify send ports that filter on the MQRFH2_ParseError property to persist the message. Subscribers that work with JMS messages should include a filter condition that specifies the value False for the MQRFH2_ParseError property to prevent the subscriber from receiving messages that failed the header parsing process.

Developers can also update the context property values (for example, change the MQRFH2_Encoding property value), and the component will reflect these changes in the MQ message headers so that they are set when the message arrives at its ultimate destination. The component automatically ignores invalid values and sets "safe" default values where required headers are missing. For example, if the developer specifies an invalid value for MQRFH2_Encoding property, the outbound message will have the MQRFH2_Encoding header set to UNKNOWN. If the developer removes a value from a context property, but the MQMD_Format property is still set to "RFH", the component will add a header containing the default value as per the IBM specification.

For an example of how to use these components, see Installing and Running the JMS MQRFH2 Component Sample.