As I mentioned before, MQ Light uses the OASIS Standard AMQP 1.0 wire protocol.   The Node.JS client we have published at npmjs.org is based on the Qpid Proton project.

What we have not yet documented is exactly how do we use the AMQP protocol. These details are needed in order to use the Proton language clients in other languages to interact with MQ Light.

Using this information it is possible to use the qpid clients to send and receive messages using MQ light and the following languages:  Java, Python, Ruby, Perl, PHP, C.   Details of that will be in subsequent posts.

The details are:

AMQP Connections

The container-id field, flowed as part the client’s open performative, is interpreted by MQ Light as the client’s identifier.¬† This identifier is shown in the MQ Light GUI.¬† Note that client identifiers must be unique across an instance of the MQ Light Service. In the future we intend to implement a “connection stealing” behaviour if a client ID is re-used but right now what will happen is that the second client to attempt to use a client ID will fail to connect.

AMQP Links

MQ Light expects the client to originate all attach performatives, and will never attempt to send attach performatives to the client.  When a client sends an attach performative to the MQ Light Service the role fields is used to determine the client will use the link to send messages to the MQ Light Service (role set to false), or receive messages from the MQ Light Service (role set to true).

When a client is sending messages to the MQ Light Service (a producer) then the “MQLight topic” to which messages are sent is based on the AMQP “to” property of the message.

When a client is receiving messages from the MQ Light Service (a consumer) then the address field, present in the source field of the attach performative, is used to specify both the topic pattern of the destination to subscribe to, as well as whether the destination is shared or private.

Clients wishing to subscribe to a private destination must format the address field to start with the string private:, followed by the topic pattern to use for the destination.  For example: private:mytopic would subscribe to a private destination using the topic pattern mytopic.

Clients wishing to subscribe to a shared destination must format the address to start with the string share:, followed by the share name, a colon, and then the topic pattern.  For example: share:myshare:mytopic would subscribe to a shared destination using the share name myshare and the topic pattern mytopic.

Messaging

This section describes how the MQ Light service interprets aspects of the AMQP message format.

Application Data

Whiles the MQ Light Service has been designed to permit the round-tripping of messages with any valid application-data section – the MQ Light client will only send (and expect to receive) a limited number of message bodies:

  1. An amqp-value that is of primitive type binary.  This is used by the MQ Light client to transfer binary data, such as that supplied in a Node.js Buffer object.
  2. An amqp-value that is of primitive type string.  This is used by the MQ Light client to transfer textual data, including JSON.

Properties

When a client sends a message to the MQ Light Service, the value present in the to field of the message’s properties section is interpreted as the name of the topic to send the message to.¬† This is formatted as a URL:

amqp://host:port/topic

Where:

–¬†¬†¬†¬†¬†¬†¬†¬†¬† host is the hostname of the MQ Light Service (this is ignored by the MQ Light Service)

–¬†¬†¬†¬†¬†¬†¬†¬†¬† port is the port number that the MQ Light Service is listening on (again, this is ignored)

–¬†¬†¬†¬†¬†¬†¬†¬†¬† topic is the name of the topic to send the message to.

The content-type field of the message’s properties section is used, by the MQ Light client, to determine how to present the data when it receives a message with payload which consists of a primitive string.¬†¬† If a content type of application/json is specified then the client will interpret the message payload as containing JSON.

NOTE:

If you are using the Apache QPID proton 0.7 client then you may hit issue PROTON-516 in which case you will need to patch your code with the one line (deletion) change committed to fix that issue in proton 0.8. You may also hit PROTON-610 in which case you will need to apply the patch for that issue.

<

p align=”left”>

5 comments on"Using MQ Light with AMQP 1.0 Clients"

  1. SundarVenkat August 07, 2016

    Dear Rob,
    Do we have a MQ Light Client for .Net?
    Thanks.

    • LaurenceBonney August 16, 2016

      Hi there, to date we have completed MQ Light Node, Java and Ruby clients, with a Python client still in development.

  2. Dear Rob,

    Great article! The AMQP standard will change middle tier landscape as USB did to PCs. Since the standard is still young, the AMQP clients still need time to become a battle tested and mature technology.

    Since AQMP should interoperate, using MQ Light’s sample of send.js and recv.js should be able to talk to Apache MQ. The send.js works just fine, but recv.js hangs. Is there something that needs to modify in order to get recv.js to work with Apache MQ?

    The MQ Light samples were tested on Windows 7 (x64).

    Thanks

    • Rob Nicholson December 12, 2014

      Hi Fred,
      Thanks for your comment. We have not tried using the MQ Light node.js client against other brokers. Which one are you using since there are several projects you could be describing as Apache MQ (qpid, active MQ, Apollo….). The problem might be related to the particular format of the address field that we use and which is coded into the samples as described here https://developer.ibm.com/messaging/2014/06/06/using-mq-light-amqp-1-0-clients/ or it may be due to something else. One way to perhaps drill down would be to trace the connection with a recent wireshark (has amqp support) or to turn on the mqlight client side logging as follows:

      Set the environment variable MQLIGHT_NODE_LOG= and re-run the node client to get logging output.
      Some useful levels are:
      entry_exit – log function entry and exit (with return codes).
      parms – as above, but with function parameters logged as well.
      data – as above, but with additional data logging.
      debug – as above, but with additional debug entries.
      detail – as above, but with higher-detail data logging (including the output from qpid-proton when PN_TRACE_FRM is set).
      raw – as above, but including the output from qpid-proton when PN_TRACE_RAW is set.
      all – log everything, include frequently called functions which will quickly output a lot of data!
      ‘debug’ is the most likely starting point.

      Log output goes to stderr by default. This can be changed to stdout by setting MQLIGHT_NODE_LOG_STREAM=stdout.

      • Hi Rob,

        Thanks for the reply. The UI Workout sample works perfectly with Apache MQ version 5.10. Once I finished testing the new Ruby Client on MQ light, I will turn my attention back to recv.js.

        Thanks for the information on logging.

Join The Discussion

Your email address will not be published.