Mapping JMS messages onto WebSphere MQ messages

WebSphere® MQ messages are composed of a Message Descriptor, an optional MQRFH2 header, and a body. The contents of a JMS message are partly mapped and partly copied to a WebSphere MQ message.

This topic describes how the JMS message structure that is described in the first part of this section is mapped onto a WebSphere MQ message. It is of interest to programmers who want to transmit messages between JMS and traditional WebSphere MQ applications. It is also of interest to people who want to manipulate messages transmitted between two JMS applications, for example, in a WebSphere Message Broker implementation.

This section does not apply if an application uses a real-time connection to a broker. When an application uses a real-time connection, all communication is performed directly over TCP/IP; no WebSphere MQ queues or messages are involved.

WebSphere MQ messages are composed of three components:
  • The WebSphere MQ Message Descriptor (MQMD)
  • A WebSphere MQ MQRFH2 header
  • The message body.

The MQRFH2 is optional, and its inclusion in an outgoing message is governed by a flag in the JMS Destination class. You can set this flag using the WebSphere MQ JMS administration tool. Because the MQRFH2 carries JMS-specific information, always include it in the message when the sender knows that the receiving destination is a JMS application. Normally, omit the MQRFH2 when sending a message directly to a non-JMS application. This is because such an application does not expect an MQRFH2 in its WebSphere MQ message.

If an incoming message does not have an MQRFH2 header, the Queue or Topic object derived from the JMSReplyTo header field of the message, by default, has this flag set so that a reply message sent to the queue or topic also does not have an MQRFH2 header. You can switch off this behavior of including an MQRFH2 header in a reply message only if the original message has an MQRFH2 header, by setting the TARGCLIENTMATCHING property of the connection factory to NO.

Figure 1 shows how the structure of a JMS message is transformed to a WebSphere MQ message and back again:
Figure 1. How messages are transformed between JMS and WebSphere MQ using the MQRFH2 header
This diagram shows how messages in JMS are partly mapped and partly copied to a WebSphere MQ message when the MQRFH2 header is used. It also shows the transformation from a WebSphere MQ message to a JMS message. The details of the transformation are in the text following the figure.
The structures are transformed in two ways:
Mapping
Where the MQMD includes a field that is equivalent to the JMS field, the JMS field is mapped onto the MQMD field. Additional MQMD fields are exposed as JMS properties, because a JMS application might need to get or set these fields when communicating with a non-JMS application.
Copying
Where there is no MQMD equivalent, a JMS header field or property is passed, possibly transformed, as a field inside the MQRFH2.