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:
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.
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.
This section describes how the MQ Light service interprets aspects of the AMQP message format.
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:
- 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.
- An amqp-value that is of primitive type string.¬† This is used by the MQ Light client to transfer textual data, including JSON.
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:
–¬†¬†¬†¬†¬†¬†¬†¬†¬† 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.
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.