Mapping JMS messages onto WebSphere MQ messages

 

This section describes how the JMS message structure that is described in the first part of this chapter 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 message broker implementation.

This section does not apply when you use a direct connection to WebSphere MQ Event Broker.

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.

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.

 

The MQRFH2 header

This section describes the MQRFH Version 2 header, which carries JMS-specific data that is associated with the message content. The MQRFH2 Version 2 is an extensible header, and can also carry additional information that is not directly associated with JMS. However, this section covers only its use by JMS.

There are two parts of the header, a fixed portion and a variable portion.

Fixed portion
The fixed portion is modelled on the standard WebSphere MQ header pattern and consists of the following fields:

StrucId (MQCHAR4)
Structure identifier.

Must be MQRFH_STRUC_ID (value: "RFH ") (initial value).

MQRFH_STRUC_ID_ARRAY (value: "R","F","H"," ") is also defined in the usual way.

Version (MQLONG)
Structure version number.

Must be MQRFH_VERSION_2 (value: 2) (initial value).

StrucLength (MQLONG)
Total length of MQRFH2, including the NameValueData fields.

The value set into StrucLength must be a multiple of 4 (the data in the NameValueData fields can be padded with space characters to achieve this).

Encoding (MQLONG)
Data encoding.

Encoding of any numeric data in the portion of the message following the MQRFH2 (the next header, or the message data following this header).

CodedCharSetId (MQLONG)
Coded character set identifier.

Representation of any character data in the portion of the message following the MQRFH2 (the next header, or the message data following this header).

Format (MQCHAR8)
Format name.

Format name for the portion of the message following the MQRFH2.

Flags (MQLONG)
Flags.

MQRFH_NO_FLAGS =0. No flags set.

NameValueCCSID (MQLONG)
The coded character set identifier (CCSID) for the NameValueData character strings contained in this header. The NameValueData can be coded in a character set that differs from the other character strings that are contained in the header (StrucID and Format).

If the NameValueCCSID is a 2-byte Unicode CCSID (1200, 13488, or 17584), the byte order of the Unicode is the same as the byte ordering of the numeric fields in the MQRFH2. (For example, Version, StrucLength, and NameValueCCSID itself.)

The NameValueCCSID takes values from the following table:

Table 17. Possible values for NameValueCCSID field

Value Meaning
1200 UCS2 open-ended
1208 UTF8
13488 UCS2 2.0 subset
17584 UCS2 2.1 subset (includes Euro symbol)

Variable portion
The variable portion follows the fixed portion. The variable portion contains a variable number of MQRFH2 folders. Each folder contains a variable number of elements or properties. Folders group together related properties. The MQRFH2 headers created by JMS can contain up to three folders:

The <mcd> folder
This contains properties that describe the shape or format of the message. For example, the Msd property identifies the message as being Text, Bytes, Stream, Map, Object, or null. This folder is always present in a JMS MQRFH2.

The <jms> folder
This is used to transport JMS header fields, and JMSX properties that cannot be fully expressed in the MQMD. This folder is always present in a JMS MQRFH2.

The <usr> folder
This is used to transport any application-defined properties associated with the message. This folder is only present if the application has set some application-defined properties.

Table 18 shows a full list of property names.

Table 18. MQRFH2 folders and properties used by JMS

JMS field name Java type MQRFH2 folder name Property name Type/values
JMSDestination Destination jms Dst string
JMSExpiration long jms Exp i8
JMSPriority int jms Pri i4
JMSDeliveryMode int jms Dlv i4
JMSCorrelationID String jms Cid string
JMSReplyTo Destination jms Rto string
JMSTimestamp long jms Tms i8
JMSType String mcd Type, Set, Fmt string
JMSXGroupID String jms Gid string
JMSXGroupSeq int jms Seq i4
xxx (user defined) Any usr xxx any
mcd Msd jms_none
jms_text
jms_bytes
jms_map
jms_stream
jms_object

The syntax used to express the properties in the variable portion is as follows:

NameValueLength (MQLONG)
Length in bytes of the NameValueData string that immediately follows this length field (it does not include its own length). The value set into NameValueLength is always a multiple of 4 (the NameValueData field is padded with space characters to achieve this).

NameValueData (MQCHARn)
A single character string, whose length in bytes is given by the preceding NameValueLength field. It contains a folder holding a sequence of properties. Each property is a name/type/value triplet, contained within an XML element whose name is the folder name, as follows: 
 <foldername> triplet1 triplet2 .....   tripletn </foldername>

The closing </foldername> tag can be followed by spaces as padding characters. Each triplet is encoded using an XML-like syntax: 

   <name dt='datatype'>value</name>

The dt='datatype' element is optional and is omitted for many properties, because the datatype is predefined. If it is included, one or more space characters must be included before the dt= tag.

name
is the name of the property; see Table 18.

datatype
must match, after folding, one of the literal datatype values in Table 19.

value
is a string representation of the value to be conveyed, using the definitions in Table 19.

A null value is encoded using the following syntax: 

<name dt="DataType" xsi:nil="true"></name>

Do not use xsi:nil="false".

Table 19. Property datatype values and definitions

Datatype value Definition
string Any sequence of characters excluding < and &
boolean The character 0 or 1 (1 = "true")
bin.hex Hexadecimal digits representing octets
i1 A number, expressed using digits 0..9, with optional sign (no fractions or exponent). Must lie in the range -128 to 127 inclusive
i2 A number, expressed using digits 0..9, with optional sign (no fractions or exponent). Must lie in the range -32768 to 32767 inclusive
i4 A number, expressed using digits 0..9, with optional sign (no fractions or exponent). Must lie in the range -2147483648 to 2147483647 inclusive
i8 A number, expressed using digits 0..9, with optional sign (no fractions or exponent). Must lie in the range -9223372036854775808 to 92233720368547750807 inclusive
int A number, expressed using digits 0..9, with optional sign (no fractions or exponent). Must lie in the same range as i8. This can be used in place of one of the i* types if the sender does not want to associate a particular precision with the property
r4 Floating point number, magnitude <= 3.40282347E+38, >= 1.175E-37 expressed using digits 0..9, optional sign, optional fractional digits, optional exponent
r8 Floating point number, magnitude <= 1.7976931348623E+308, >= 2.225E-307 expressed using digits 0..9, optional sign, optional fractional digits, optional exponent

A string value can contain spaces. You must use the following escape sequences in a string value:

&amp; for the & character
&lt; for the < character

You can use the following escape sequences, but they are not required:

&gt; for the > character
&apos; for the ' character
&quot; for the " character

 

JMS fields and properties with corresponding MQMD fields

Table 20 lists the JMS header fields and Table 21 lists the JMS properties that are mapped directly to MQMD fields. Table 22 lists the provider specific properties and the MQMD fields that they are mapped to.

Table 20. JMS header fields mapping to MQMD fields

JMS header field Java type MQMD field C type
JMSDeliveryMode int Persistence MQLONG
JMSExpiration long Expiry MQLONG
JMSPriority int Priority MQLONG
JMSMessageID String MessageID MQBYTE24
JMSTimestamp long PutDate
PutTime
 MQCHAR8
MQCHAR8
JMSCorrelationID String CorrelId MQBYTE24

Table 21. JMS properties mapping to MQMD fields

JMS property Java type MQMD field C type
JMSXUserID String UserIdentifier MQCHAR12
JMSXAppID String PutApplName MQCHAR28
JMSXDeliveryCount int BackoutCount MQLONG
JMSXGroupID String GroupId MQBYTE24
JMSXGroupSeq int MsgSeqNumber MQLONG

Table 22. JMS provider specific properties mapping to MQMD fields

JMS provider specific property Java type MQMD field C type
JMS_IBM_Report_Exception int Report MQLONG
JMS_IBM_Report_Expiration int Report MQLONG
JMS_IBM_Report_COA int Report MQLONG
JMS_IBM_Report_COD int Report MQLONG
JMS_IBM_Report_PAN int Report MQLONG
JMS_IBM_Report_NAN int Report MQLONG
JMS_IBM_Report_Pass_Msg_ID int Report MQLONG
JMS_IBM_Report_Pass_Correl_ID int Report MQLONG
JMS_IBM_Report_Discard_Msg int Report MQLONG
JMS_IBM_MsgType int MsgType MQLONG
JMS_IBM_Feedback int Feedback MQLONG
JMS_IBM_Format String Format MQCHAR8
JMS_IBM_PutApplType int PutApplType MQLONG
JMS_IBM_Encoding int Encoding MQLONG
JMS_IBM_Character_Set String CodedCharacterSetId MQLONG
JMS_IBM_PutDate String PutDate MQCHAR8
JMS_IBM_PutTime String PutTime MQCHAR8
JMS_IBM_Last_Msg_In_Group boolean MsgFlags MQLONG

 

Mapping JMS fields onto WebSphere MQ fields (outgoing messages)

Table 23 shows how the JMS header fields are mapped into MQMD/RFH2 fields at send() or publish() time. Table 24 shows how JMS properties and Table 25 shows how JMS provider specific properties are mapped to MQMD fields at send() or publish() time,

For fields marked Set by Message Object, the value transmitted is the value held in the JMS message immediately before the send() or publish() operation. The value in the JMS message is left unchanged by the operation.

For fields marked Set by Send Method, a value is assigned when the send() or publish() is performed (any value held in the JMS message is ignored). The value in the JMS message is updated to show the value used.

Fields marked as Receive-only are not transmitted and are left unchanged in the message by send() or publish().

Table 23. Outgoing message field mapping

JMS header field name MQMD field used for transmission Header Set by
JMSDestination MQRFH2 Send Method
JMSDeliveryMode Persistence MQRFH2 Send Method
JMSExpiration Expiry MQRFH2 Send Method
JMSPriority Priority MQRFH2 Send Method
JMSMessageID MessageID Send Method
JMSTimestamp PutDate/PutTime Send Method
JMSCorrelationID CorrelId MQRFH2 Message Object
JMSReplyTo ReplyToQ/ReplyToQMgr MQRFH2 Message Object
JMSType MQRFH2 Message Object
JMSRedelivered Receive-only

Table 24. Outgoing message JMS property mapping

JMS property name MQMD field used for transmission Header Set by
JMSXUserID UserIdentifier Send Method
JMSXAppID PutApplName Send Method
JMSXDeliveryCount Receive-only
JMSXGroupID GroupId MQRFH2 Message Object
JMSXGroupSeq MsgSeqNumber MQRFH2 Message Object

Table 25. Outgoing message JMS provider specific property mapping

JMS provider specific property name MQMD field used for transmission Header Set by
JMS_IBM_Report_Exception Report Message Object
JMS_IBM_Report_Expiration Report Message Object
JMS_IBM_Report_COA/COD Report Message Object
JMS_IBM_Report_NAN/PAN Report Message Object
JMS_IBM_Report_Pass_Msg_ID Report Message Object
JMS_IBM_Report_Pass_Correl_ID Report Message Object
JMS_IBM_Report_Discard_Msg Report Message Object
JMS_IBM_MsgType MsgType Message Object
JMS_IBM_Feedback Feedback Message Object
JMS_IBM_Format Format Message Object
JMS_IBM_PutApplType PutApplType Send Method
JMS_IBM_Encoding Encoding Message Object
JMS_IBM_Character_Set CodedCharacterSetId Message Object
JMS_IBM_PutDate PutDate Send Method
JMS_IBM_PutTime PutTime Send Method
JMS_IBM_Last_Msg_In_Group MsgFlags Message Object

 

Mapping JMS header fields at send() or publish()

The following notes relate to the mapping of JMS fields at send() or publish():

JMSDestination to MQRFH2
This is stored as a string that serializes the salient characteristics of the destination object, so that a receiving JMS can reconstitute an equivalent destination object. The MQRFH2 field is encoded as URI (see (JMSURI) for details of the URI notation).

JMSReplyTo to MQMD ReplyToQ, ReplyToQMgr, MQRFH2
The queue and queue manager name are copied to the MQMD ReplyToQ and ReplyToQMgr fields respectively. The destination extension information (other useful details that are kept in the destination object) is copied into the MQRFH2 field. The MQRFH2 field is encoded as a URI (see (JMSURI) for details of the URI notation).

JMSDeliveryMode to MQMD Persistence
The JMSDeliveryMode value is set by the send() or publish() Method or MessageProducer, unless the Destination Object overrides it. The JMSDeliveryMode value is mapped to the MQMD Persistence field as follows:

  • JMS value PERSISTENT is equivalent to MQPER_PERSISTENT

  • JMS value NON_PERSISTENT is equivalent to MQPER_NOT_PERSISTENT

If the MQQueue persistence property is not set to JMSC.MQJMS_PER_QDEF, the delivery mode value is also encoded in the MQRFH2.

JMSExpiration to/from MQMD Expiry, MQRFH2
JMSExpiration stores the time to expire (the sum of the current time and the time to live), whereas MQMD stores the time to live. Also, JMSExpiration is in milliseconds, but MQMD.expiry is in centiseconds.

  • If the send() method sets an unlimited time to live, MQMD Expiry is set to MQEI_UNLIMITED, and no JMSExpiration is encoded in the MQRFH2.

  • If the send() method sets a time to live that is less than 214748364.7 seconds (about 7 years), the time to live is stored in MQMD. Expiry, and the expiration time (in milliseconds), are encoded as an i8 value in the MQRFH2.

  • If the send() method sets a time to live greater than 214748364.7 seconds, MQMD.Expiry is set to MQEI_UNLIMITED. The true expiration time in milliseconds is encoded as an i8 value in the MQRFH2.

JMSPriority to MQMD Priority
Directly map JMSPriority value (0-9) onto MQMD priority value (0-9). If JMSPriority is set to a non-default value, the priority level is also encoded in the MQRFH2.

JMSMessageID from MQMD MessageID
All messages sent from JMS have unique message identifiers assigned by WebSphere MQ. The value assigned is returned in the MQMD messageId field after the MQPUT call, and is passed back to the application in the JMSMessageID field. The WebSphere MQ messageId is a 24-byte binary value, whereas the JMSMessageID is a string. The JMSMessageID is composed of the binary messageId value converted to a sequence of 48 hexadecimal characters, prefixed with the characters ID:. JMS provides a hint that can be set to disable the production of message identifiers. This hint is ignored, and a unique identifier is assigned in all cases. Any value that is set into the JMSMessageId field before a send() is overwritten.

JMSTimestamp to MQRFH2
During a send, the JMSTimestamp field is set according to the JVM's clock. This value is set into the MQRFH2. Any value that is set into the JMSTimestamp field before a send() is overwritten. See also the JMS_IBM_PutDate and JMS_IBM_PutTime properties.

JMSType to MQRFH2
This string is set into the MQRFH2 mcd.Type field. If it is in URI format, it can also affect mcd.Set and mcd.Fmt fields. See also Appendix D, Connecting with other products.

JMSCorrelationID to MQMD CorrelId, MQRFH2
The JMSCorrelationID can hold one of the following:

A provider specific message ID
This is a message identifier from a message previously sent or received, and so should be a string of 48 hexadecimal digits that are prefixed with ID:. The prefix is removed, the remaining characters are converted into binary, and then they are set into the MQMD CorrelId field. No CorrelId value is encoded in the MQRFH2.

A provider-native byte[] value
The value is copied into the MQMD CorrelId field - padded with nulls, or truncated to 24 bytes if necessary. No CorrelId value is encoded in the MQRFH2.

An application-specific string
The value is copied into the MQRFH2. The first 24 bytes of the string, in UTF8 format, are written into the MQMD CorrelID.

 

Mapping JMS property fields

These notes refer to the mapping of JMS property fields in WebSphere MQ messages:

JMSXUserID from MQMD UserIdentifier
JMSXUserID is set on return from send call.

JMSXAppID from MQMD PutApplName
JSMXAppID is set on return from send call.

JMSXGroupID to MQRFH2 (point-to-point)
For point-to-point messages, the JMSXGroupID is copied into the MQMD GroupID field. If the JMSXGroupID starts with the prefix ID:, it is converted into binary. Otherwise, it is encoded as a UTF8 string. The value is padded or truncated if necessary to a length of 24 bytes. The MQMF_MSG_IN_GROUP flag is set.

JMSXGroupID to MQRFH2 (publish/subscribe)
For publish/subscribe messages, the JMSXGroupID is copied into the MQRFH2 as a string.

JMSXGroupSeq MQMD MsgSeqNumber (point-to-point)
For point-to-point messages, the JMSXGroupSeq is copied into the MQMD MsgSeqNumber field. The MQMF_MSG_IN_GROUP flag is set.

JMSXGroupSeq MQMD MsgSeqNumber (publish/subscribe)
For publish/subscribe messages, the JMSXGroupSeq is copied into the MQRFH2 as an i4.

 

Mapping JMS provider-specific fields

The following notes refer to the mapping of JMS Provider specific fields into WebSphere MQ messages:

JMS_IBM_Report_<name> to MQMD Report
A JMS application can set the MQMD Report options, using the following JMS_IBM_Report_XXX properties. The single MQMD is mapped to several JMS_IBM_Report_XXX properties. The application must set the value of these properties to the standard WebSphere MQ MQRO_ constants (included in com.ibm.mq.MQC). So, for example, to request COD with full Data, the application must set JMS_IBM_Report_COD to the value MQC.MQRO_COD_WITH_FULL_DATA.

JMS_IBM_Report_Exception

MQRO_EXCEPTION or
MQRO_EXCEPTION_WITH_DATA or
MQRO_EXCEPTION_WITH_FULL_DATA

JMS_IBM_Report_Expiration

MQRO_EXPIRATION or
MQRO_EXPIRATION_WITH_DATA or
MQRO_EXPIRATION_WITH_FULL_DATA

JMS_IBM_Report_COA

MQRO_COA or
MQRO_COA_WITH_DATA or
MQRO_COA_WITH_FULL_DATA

JMS_IBM_Report_COD

MQRO_COD or
MQRO_COD_WITH_DATA or
MQRO_COD_WITH_FULL_DATA

JMS_IBM_Report_PAN
MQRO_PAN

JMS_IBM_Report_NAN
MQRO_NAN

JMS_IBM_Report_Pass_Msg_ID
MQRO_PASS_MSG_ID

JMS_IBM_Report_Pass_Correl_ID
MQRO_PASS_CORREL_ID

JMS_IBM_Report_Discard_Msg
MQRO_DISCARD_MSG

JMS_IBM_MsgType to MQMD MsgType
Value maps directly onto MQMD MsgType. If the application has not set an explicit value of JMS_IBM_MsgType, a default value is used. This default value is determined as follows:

  • If JMSReplyTo is set to a WebSphere MQ queue destination, MSGType is set to the value MQMT_REQUEST

  • If JMSReplyTo is not set, or is set to anything other than a WebSphere MQ queue destination, MsgType is set to the value MQMT_DATAGRAM

JMS_IBM_Feedback to MQMD Feedback
Value maps directly onto MQMD Feedback.

JMS_IBM_Format to MQMD Format
Value maps directly onto MQMD Format.

JMS_IBM_Encoding to MQMD Encoding
If set, this property overrides the numeric encoding of the Destination Queue or Topic.

JMS_IBM_Character_Set to MQMD CodedCharacterSetId
If set, this property overrides the coded character set property of the Destination Queue or Topic.

JMS_IBM_PutDate from MQMD PutDate
The value of this property is set, during send, directly from the PutDate field in the MQMD. Any value that is set into the JMS_IBM_PutDate property before a send is overwritten. This field is a String of eight characters, in the WebSphere MQ Date format of YYYYMMDD. This property can be used in conjunction with the JMS_IBM_PutTime property to determine the time the message was put according to the queue manager.

JMS_IBM_PutTime from MQMD PutTime
The value of this property is set, during send, directly from the PutTime field in the MQMD. Any value that is set into the JMS_IBM_PutTime property before a send is overwritten. This field is a String of eight characters, in the WebSphere MQ Time format of HHMMSSTH. This property can be used in conjunction with the JMS_IBM_PutDate property to determine the time the message was put according to the queue manager.

JMS_IBM_Last_Msg_In_Group to MQMD MsgFlags
For point-to-point messaging, this boolean value maps to the MQMF_LAST_MSG_IN_GROUP flag in the MQMD MsgFlags field. It is normally used in conjunction with the JMSXGroupID and JMSXGroupSeq properties to indicate to a legacy WebSphere MQ application that this is the last message in a group. This property is ignored for publish/subscribe messaging.

 

Mapping WebSphere MQ fields onto JMS fields (incoming messages)

Table 26 shows how JMS header fields and Table 27 shows how JMS property fields are mapped into MQMD/MQRFH2 fields at send() or publish() time. Table 28 shows how JMS provider specific properties are mapped.

Table 26. Incoming message JMS header field mapping

JMS header field name MQMD field retrieved from MQRFH2 field retrieved from
JMSDestination jms.Dst
JMSDeliveryMode Persistence(JMSDLVN) jms.Dlv(JMSDLVN)
JMSExpiration jms.Exp
JMSPriority Priority
JMSMessageID MessageID
JMSTimestamp PutDate(JMSDLVN)
PutTime(JMSDLVN)
 jms.Tms(JMSDLVN)
JMSCorrelationID CorrelId(JMSDLVN) jms.Cid(JMSDLVN)
JMSReplyTo ReplyToQ(JMSDLVN)
ReplyToQMgr(JMSDLVN)
 jms.Rto(JMSDLVN)
JMSType mcd.Type, mcd.Set, mcd.Fmt
JMSRedelivered BackoutCount
HEADERS="COL1 COL2 COL3" COLSPAN="3"

Notes:

  1. For properties that can have values retrieved from the MQRFH2 or the MQMD, if both are available, the setting in the MQRFH2 is used.

Table 27. Incoming message property mapping

JMS property name MQMD field retrieved from MQRFH2 field retrieved from
JMSXUserID UserIdentifier
JMSXAppID PutApplName
JMSXDeliveryCount BackoutCount
JMSXGroupID GroupId(JMSDN2) jms.Gid(JMSDN2)
JMSXGroupSeq MsgSeqNumber(JMSDN2) jms.Seq(JMSDN2)
HEADERS="COL1 COL2 COL3" COLSPAN="3"

Notes:

  1. For properties that can have values retrieved from the MQRFH2 or the MQMD, if both are available, the setting in the MQRFH2 is used.

Table 28. Incoming message provider specific JMS property mapping

JMS property name MQMD field retrieved from MQRFH2 field retrieved from
JMS_IBM_Report_Exception Report
JMS_IBM_Report_Expiration Report
JMS_IBM_Report_COA Report
JMS_IBM_Report_COD Report
JMS_IBM_Report_PAN Report
JMS_IBM_Report_NAN Report
JMS_IBM_Report_ Pass_Msg_ID Report
JMS_IBM_Report_Pass_Correl_ID Report
JMS_IBM_Report_Discard_Msg Report
JMS_IBM_MsgType MsgType
JMS_IBM_Feedback Feedback
JMS_IBM_Format Format
JMS_IBM_PutApplType PutApplType
JMS_IBM_Encoding 1 Encoding
JMS_IBM_Character_Set 1 CodedCharacterSetId
JMS_IBM_PutDate PutDate
JMS_IBM_PutTime PutTime
JMS_IBM_Last_Msg_In_Group MsgFlags
HEADERS="COL1 COL2 COL3" COLSPAN="3"

  1. Only set if the incoming message is a Bytes Message.

 

Mapping JMS to a native WebSphere MQ application

This section describes what happens if you send a message from a JMS client application to a traditional WebSphere MQ application with no knowledge of MQRFH2 headers. Figure 5 shows the mapping.

The administrator indicates that the JMS client is communicating with such an application by setting the WebSphere MQ destination's TargetClient value to JMSC.MQJMS_CLIENT_NONJMS_MQ. This indicates that no MQRFH2 field is to be produced. Note that if this is not done, the receiving application must be able to handle the MQRFH2 field.

The mapping from JMS to MQMD targeted at a native WebSphere MQ application is the same as mapping from JMS to MQMD targeted at a true JMS client. If JMS receives a WebSphere MQ message with the MQMD format field set to other than MQFMT_RFH2, data is being received from a non-JMS application. If the format is MQFMT_STRING, the message is received as a JMS text message. Otherwise, it is received as a JMS bytes message. Because there is no MQRFH2, only those JMS properties that are transmitted in the MQMD can be restored.

 

Message body

This section discusses the encoding of the message body itself. The encoding depends on the type of JMS message:

ObjectMessage
is an object serialized by the Java Runtime in the normal way.

TextMessage
is an encoded string. For an outgoing message, the string is encoded in the character set given by the destination object. This defaults to UTF8 encoding (the UTF8 encoding starts with the first character of the message; there is no length field at the start). It is, however, possible to specify any other character set supported by WebSphere MQ Java. Such character sets are used mainly when you send a message to a non-JMS application.

If the character set is a double-byte set (including UTF16), the destination object's integer encoding specification determines the order of the bytes.

An incoming message is interpreted using the character set and encoding that are specified in the message itself. These specifications are in the last WebSphere MQ header (or MQMD if there are no headers). For JMS messages, the last header is usually the MQRFH2.

BytesMessage
is, by default, a sequence of bytes as defined by the JMS 1.0.2 specification and associated Java documentation.

For an outgoing message that was assembled by the application itself, the destination object's encoding property can be used to override the encodings of integer and floating point fields contained in the message. For example, you can request that floating point values are stored in S/390 rather than IEEE format).

An incoming message is interpreted using the numeric encoding specified in the message itself. This specification is in the rightmost WebSphere MQ header (or MQMD if there are no headers). For JMS messages, the rightmost header is usually the MQRFH2.

If a BytesMessage is received, and is re-sent without modification, its body is transmitted byte for byte, as it was received. The destination object's encoding property has no effect on the body. The only string-like entity that can be sent explicitly in a BytesMessage is a UTF8 string. This is encoded in Java UTF8 format, and starts with a 2-byte length field. The destination object's character set property has no effect on the encoding of an outgoing BytesMessage. The character set value in an incoming WebSphere MQ message has no effect on the interpretation of that message as a JMS BytesMessage.

Non-Java applications are unlikely to recognize the Java UTF8 encoding. Therefore, for a JMS application to send a BytesMessage that contains text data, the application itself must convert its strings to byte arrays, and write these byte arrays into the BytesMessage.

MapMessage
is a string containing a set of XML name/type/value triplets, encoded as: 
<map><elementName1 dt='datatype'>value</elementName1>
<elementName2 dt='datatype'>value</elementName2>.....
</map>

where datatype can take one of the values described in Table 19, and string is the default datatype, so dt='string' is omitted.

The character set used to encode or interpret the XML string that makes up the MapMessage body is determined following the rules that apply to a TextMessage.

StreamMessage
is like a map, but without element names: 
<stream><elt dt='datatype'>value</elt>
<elt dt='datatype'>value</elt>.....</stream>

Every element is sent using the same tag name (elt). The default type is string, so dt='string' is omitted for string elements.

The character set used to encode or interpret the XML string that makes up the StreamMessage body is determined following the rules that apply to a TextMessage.

The MQRFH2.format field is set as follows:

MQFMT_NONE
for ObjectMessage, BytesMessage, or messages with no body.

MQFMT_STRING
for TextMessage, StreamMessage, or MapMessage.

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.