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 MA9C: IBM Messaging Telemetry Clients 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 we 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 we 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, we 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