Configure distributed queuing to send messages to MQTT clients
IBM® WebSphere® MQ
applications can send MQTT v3 clients messages by publishing to subscription
created by a client, or by sending a message directly. Whichever method
is used, the message is placed on SYSTEM.MQTT.TRANSMIT.QUEUE
, and sent to the client by the telemetry (MQXR) service. There are
a number of ways to place a message on SYSTEM.MQTT.TRANSMIT.QUEUE
.
Publishing a message in response to an MQTT client subscription
The telemetry (MQXR) service creates a subscription on behalf of the MQTT client. The client is the destination for any publications that match the subscription sent by the client. The telemetry services forwards matching publications back to the client.
An MQTT client is connected to WebSphere MQ as a queue
manager, with its queue manager name set to its ClientIdentifier. The destination for publications to be sent to the client is a
transmission queue, SYSTEM.MQTT.TRANSMIT.QUEUE
. The
telemetry service forwards messages on SYSTEM.MQTT.TRANSMIT.QUEUE
to MQTT clients, using the target queue manager name as the key
to a specific client.
SYSTEM.MQTT.TRANSMIT.QUEUE
. Using standard WebSphere
MQ object name resolution, ClientIdentifier
is resolved as follows; see Table 1. ClientIdentifier
matches nothing.ClientIdentifier
is a remote queue manager name. It does not match the local queue manager name, a queue manager alias, or a transmission queue name.- The queue name is not defined. Currently, the telemetry (MQXR)
service sets
SYSTEM.MQTT.PUBLICATION.QUEUE
as the name of the queue. An MQTT v3 client does not support queues, so the resolved queue name is ignored by the client. - The local queue manager property, Default transmission
queue, name must be set to
SYSTEM.MQTT.TRANSMIT.QUEUE
, so that the publication is put onSYSTEM.MQTT.TRANSMIT.QUEUE
to be sent to the client.
ClientIdentifier
matches a queue manager alias namedClientIdentifier
.ClientIdentifier
is a remote queue manager name. It matches the name of a queue manager alias.- The queue manager alias must be defined with
ClientIdentifier
as the remote queue manager name. - By setting the transmission queue name in the queue manager alias
definition it is not necessary for the default transmission to be
set to
SYSTEM.MQTT.TRANSMIT.QUEUE
.
Input | Output | ||||
---|---|---|---|---|---|
ClientIdentifier |
Queue manager name | Queue name | Queue manager name | Queue name | Transmission queue |
Matches nothing | ClientIdentifier |
undefined | ClientIdentifier |
undefined | Default transmission queue. SYSTEM.MQTT. |
Matches a queue manager alias named ClientIdentifier |
ClientIdentifier |
undefined | ClientIdentifier |
undefined | SYSTEM.MQTT. |
For further information about name resolution, see Name resolution.
Any WebSphere MQ program can publish to the same topic. The publication is sent to its subscribers, including MQTT v3 clients that have a subscription to the topic.
If an
administrative topic is created in a cluster, with the attribute CLUSTER(clusterName)
, any application
in the cluster can publish to the client; for example:
echo DEFINE TOPIC('MQTTExamples') TOPICSTR('MQTT Examples') CLUSTER(MQTT) REPLACE | runmqsc qMgr
SYSTEM.MQTT.TRANSMIT.QUEUE
a cluster attribute.MQTT client subscribers and publishers can connect to different queue managers. The subscribers and publishers can be part of the same cluster, or connected by a publish/subscribe hierarchy. The publication is delivered from the publisher to the subscriber using WebSphere MQ.
Sending a message to a client directly
An alternative to a client creating a subscription and receiving a publication that matches the subscription topic, send a message to an MQTT v3 client directly. MQTT V3 client applications cannot send messages directly, but other application, such as WebSphere MQ applications, can.
The WebSphere MQ application must know the ClientIdentifier of the MQTT v3 client. As MQTT v3 clients do not have queues, the target queue name is passed to the MQTT v3 application client messageArrived method as a topic name. For example, in an MQI program, create an object descriptor with the client as the ObjectQmgrName:
MQOD.ObjectQmgrName = ClientIdentifier;
MQOD.ObjectName = name;
If the application is written using JMS, create a point-to-point destination; for example:
javax.jms.Destination jmsDestination =
(javax.jms.Destination)jmsFactory.createQueue
("queue://ClientIdentifier/name");
SYSTEM.MQTT.TRANSMIT.QUEUE
; see Table 2. The remote
queue name can be anything. The client receives it as a topic string.Input | Output | |||
---|---|---|---|---|
Queue name | Queue manager name | Queue name | Queue manager name | Transmission queue |
Name of remote queue definition | Blank or local queue manager name | Remote queue name used as a topic string | ClientIdentifier |
SYSTEM.MQTT. |
If the client is connected, the message is sent directly to the MQTT client, which calls the messageArrived method; see messageArrived method.
If the client has disconnected with a persistent
session, the message is stored in SYSTEM.MQTT.TRANSMIT.QUEUE
; see MQTT stateless and stateful sessions . It is forwarded to the client when the client reconnects to the
session again.
If you send a non-persistent message it is sent
to the client with "at most once" quality of service, QoS=0
. If you send a persistent message directly to a client, by default,
it is sent with "exactly once" quality of service, QoS=2
. As the client might not have a persistence mechanism, the client
can lower the quality of service it accepts for messages sent directly.
To lower the quality of service for messages sent directly to a client,
make a subscription to the topic DEFAULT.QoS
. Specify
the maximum quality of service the client can support.