Mapping JMS messages onto IBM MQ messages

IBM 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 an IBM MQ message.

This topic describes how the JMS message structure that is described in the first part of this section is mapped onto an IBM MQ message. It is of interest to programmers who want to transmit messages between JMS and traditional IBM MQ applications. It is also of interest to people who want to manipulate messages transmitted between two JMS applications, for example, in an IBM Integration Bus 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 IBM MQ queues or messages are involved.

IBM MQ messages are composed of three components:

  • The IBM MQ Message Descriptor (MQMD)
  • An IBM MQ MQRFH2 header
  • The message body.

The MQRFH2 is optional, and its inclusion in an outgoing message is governed by the TARGCLIENT flag in the JMS Destination class. We can set this flag using the IBM 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 IBM 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. We 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 an IBM MQ message and back again:
Figure 1. How messages are transformed between JMS and IBM MQ using the MQRFH2 header

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.