Conversion between MQTT and JMS

When messages are converted between MQTT and JMS, there is a set of rules that are applied to the conversion.

If the source and destination protocols are the same, then no conversion occurs. For MQTT to JMS message conversion, when the content is ambiguous, the property ConvertMessageType is used to decide what action to take. Eclipse Amlen sets the message type when a message is received from IBM® MQ. Messages are treated as JMS messages when received from Eclipse Amlen.

The following table shows the six message types that define the type of content in JMS, and two message types that defines the type of content in MQTT:

Table 1. The message types that define the type of content in JMS and MQTT.
Message type To MQTT From MQTT
Message Zero length payload Never created
BytesMessage The byte array content is used as the payload. Use the payload as a byte content if one of the following is true:
  • The ConvertMessageType property is 'bytes'
  • The convert type is automatic and the payload contains any byte sequence that is not a valid UTF-8 encoded string, or contains any byte less than 0x20 except 0x09, 0x0a, or 0x0d.
MapMessage The map is converted to JSON in a UTF-8 encoding. Never created
ObjectMessage The serialized form of the object is used as the payload. If the object is null, a zero length payload is used. Never created
StreamMessage The stream is converted to JSON in a UTF-8 encoding. Never created
TextMessage The UTF-8 encoding of the text is used as the payload. If the text is null, a zero length payload is used. Interpret the payload as a UTF-8 encoded string if the convert type is text, or the convert type is automatic and the payload contains only valid UTF-8 characters and only the control characters NL, CR, and HT.

Differences exist in the implementation of common concepts between the MQTT and JMS protocols. If you are planning to interchange messages between the two protocols, restrict your messages to functionality that is supported by both. Before you convert your messages, familiarize yourself with the following implementation characteristics of MQTT and JMS protocols and with the mapping information.

  • Named user properties are mapped in both directions.
  • JMS user properties must start with JMSX and cannot start with JMS. When you convert from MQTT to JMS, ensure user properties start with JMSX.
  • Differences exist in how property values are handled:
    • MQTT allows a string only as a property type.
    • JMS allows a string, integers of various sizes, a floating value, a Boolean, and a byte array as a property type.
    • When you convert a JMS property value to an MQTT property value, covert the JMS property value to a string, where possible.
    • When you convert a JMS byte array, convert the value to a string. If the value cannot be converted to a valid UTF-8 string, the property value is not written.
    • When you convert from MQTT to JMS, all property values are converted to strings.
  • MQTT Content Type maps to JMSType in both directions.
  • MQTT Response Topic maps to JMSReplyTo in both directions
  • MQTT Correlation Identifier maps to JMSCorrelationID in both directions. Use valid UTF-8 strings as correlation IDs when you interchange messages between protocols. For JMS, the correlation identifier must be a string. To use request and response between JMS and MQTT, you must update to the new version of the MQTT client.
  • JMSMessageID maps to the MQTT user property JMSMessageID in both directions.
  • JMSTimestamp maps to the MQTT user property JMSTimestamp in both directions. In MQTT, JMSTimestamp is an ISO8601 formatted string that starts with year.
  • JMS places more stringent restrictions on the names of properties than MQTT. Use property names that meet both sets of requirements.
  • MQTT allows multiple instances of the same key. However, JMS allows only one instance of each key. If multiple instances of a key exist when you send properties from MQTT to JMS, the client sees one key only . It is not possible to determine which key the client sees.

For information about other considerations when MQTT applications interact with JMS applications, see Developing MQTT applications.