MQTT client programming concepts

MQTT client programming concepts

The concepts described in this section help you to understand the client libraries for the MQTT protocol. The concepts complement the API documentation accompanying the client libraries.
For the latest information and downloads, see the following resources:
The Eclipse Paho project, and MQTT.org, have free downloads of the latest telemetry clients and samples for a range of programming languages. Use these sites to help you develop sample programs for publishing and subscribing IBM MQ Telemetry Transport, and for adding security features.
Early versions of the MA9C: IBM Messaging Telemetry Clients SupportPac included a compiled sample application (mqttv3app.jar) and associated client library (mqttv3.jar). They were provided in the following directories:

ma9c/SDK/clients/java/org.eclipse.paho.sample.mqttv3app.jar
ma9c/SDK/clients/java/org.eclipse.paho.client.mqttv3.jar
In later versions of this SupportPac, the /SDK/ directory and contents is removed:
Only the source for the sample application (mqttv3app.jar) is provided. It is in this directory:
ma9c/clients/java/samples/org/eclipse/paho/sample/mqttv3app/*.java
The compiled client library is still provided. It is in this directory:
ma9c/clients/java/org.eclipse.paho.client.mqttv3-1.0.2.jar
The deprecated MA9B: Mobile Messaging and M2M Client Pack is no longer available.
To develop and run an MQTT client you need to copy or install these resources on the client device. You do not need to install a separate client runtime.

The licensing conditions for clients are associated with the server that you are connecting the clients to.

The MQTT client libraries are reference implementations of the MQTT protocol. We can implement your own clients in different languages suitable for different device platforms. See IBM MQ Telemetry Transport format and protocol.

The API documentation makes no assumptions about which MQTT server the client is connected to. The behavior of the client might differ slightly when connected to different servers. The descriptions that follow describe the behavior of the client when connected to the IBM MQ telemetry service.

Callbacks and synchronization in MQTT client applications
The MQTT client programming model uses threads extensively. The threads decouple an MQTT client application, as much as they can, from delays in transmitting messages to and from the server. Publications, delivery tokens, and connection lost events are delivered to the methods in a callback class that implements MqttCallback.
Clean sessions
The MQTT client, and the telemetry (MQXR) service maintain session state information. The state information is used to ensure at least once and exactly once delivery, and exactly once receipt of publications. Session state also includes subscriptions created by an MQTT client. We can choose to run an MQTT client with or without maintaining state information between sessions. Change the clean session mode by setting MqttConnectOptions.cleanSession before connecting.
Client identifier
The client identifier is a 23 byte string that identifies an MQTT client. Each identifier must be unique to only one connected client at a time. The identifier must contain only characters valid in a queue manager name. Within these constraints, you are able to use any identification string. It is important to have a procedure for allocating client identifiers, and a means of configuring a client with its chosen identifier.
Delivery tokens
When a client publishes on a topic a new delivery token is created. Use the delivery token to monitor the delivery of a publication, or to block the client application until delivery is complete.
Last will and testament publication
If an MQTT client connection unexpectedly ends, we can configure MQ Telemetry to send a "last will and testament" publication. Predefine the content of the publication, and the topic to send it to. The "last will and testament" is a connection property. Create it before connecting the client.
Message persistence in MQTT clients
Publication messages are made persistent if they are sent with a quality of service of at least once, or exactly once. We can implement your own persistence mechanism on the client, or use the default persistence mechanism that is provided with the client. Persistence works in both directions, for publications sent to or from the client.
Publications
Publications are instances of MqttMessage that are associated with a topic string. MQTT clients can create publications to send to IBM MQ, and subscribe to topics on IBM MQ to receive publications.
Qualities of service provided by an MQTT client
An MQTT client provides three qualities of service for delivering publications to IBM MQ and to the MQTT client: "at most once", "at least once" and "exactly once". When an MQTT client sends a request to IBM MQ to create a subscription, the request is sent with the "at least once" quality of service.
Retained publications and MQTT clients
A topic can have one, and only one, retained publication. If you create a subscription to a topic that has a retained publication, the publication is immediately forwarded to you.
Subscriptions
Create subscriptions to register an interest in publication topics using a topic filter. A client can create multiple subscriptions, or a subscription containing a topic filter that uses wildcards, to register an interest in multiple topics. Publications on topics matching the filters are sent to the client. Subscriptions can remain active while a client is disconnected. The publications are sent to the client when it reconnects.
Topic strings and topic filters in MQTT clients
Topic strings and topic filters are used to publish and to subscribe. The syntax of topic strings and filters in MQTT clients is largely the same as topic strings in IBM MQ.
Parent topic: Developing applications for MQ Telemetry