MQTT client utility

The MQTT client utility is a Java application with which we can explore the features of MQTT, that is, connecting to a queue manager, and publishing and subscribing to topics.

We can use the client utility to verify your telemetry setup (for example, when you create a telemetry channel), or the client might serve as an aid when we are developing and debugging applications. For more information about the features and properties of the MQTT client utility, see the following descriptions:

    Publish
    Publish a message to a topic which is then distributed to interested subscribers.

    Subscribe
    Clients and the MQXR listener can register their interest in a topic by subscribing to it and thus receive messages published to that topic.

    Topic
    A topic is the key that identifies the information channel to which messages are published. Subscribers use the topic name to identify the information channels on which they want to receive published messages.
    Topic wildcards

    A subscription might contain special characters, and we can subscribe to multiple topics at once. A topic level separator uses the forward slash (/) to separate each level within a topic, creating a hierarchical structure. For example, ibm/qmgr/apple. Topic level separators allow more flexibility and simplifies management of topics.

    For subscriptions, two wildcard characters are supported:

    • The number sign (#) is used to match any number of levels within a topic. For example, if you subscribe to the topic ibm/qmgr/#, you receive messages on the topics ibm/qmgr/apple and ibm/qmgr/orange.

    • The plus sign (+) matches only one topic level. For example, ibm/qmgr/+ matches ibm/qmgr/apple but not ibm/qmgr/apple/queue.

      We can use the + at the end of the topic tree or within the topic tree. For example, ibm/+ and ibm/+/orange are both valid.

    Publication topics are not allowed to contain either the + or #.

    Message
    A message, in the context of an MQTT client utility, refers to the message payload distributed to subscribers that show interest in a topic. Messages can consist of alphanumeric characters.

    Quality of service (QoS)
    The MQTT client utility provides three qualities of service, as follows:
    At most once (QoS = 0)

    • The message is delivered at most once, or it is not delivered at all. There is no acknowledgment on receipt of the message.
    • The message might be lost if the client is disconnected, or if the server fails.

    At least once (QoS = 1)

    • The message is delivered at least once. It might be delivered multiple times if no acknowledgment is received after a period of time, or if a failure is detected and the communication session is restarted.
    • The message must be stored locally at the sender until an acknowledgment is received, in case the message must be sent again. Messages might be duplicated at the receiving application.

    Exactly once (QoS = 2)

    • This is the highest level of delivery where a message is delivered once and only once. Delivery is assumed, but duplicate messages are not delivered to the receiving application.

    Retained
    This option is only used when publishing messages. It determines whether a message, from a publication on a topic, is retained by the MQTT server (in IBM MQ, the queue manager) after it is delivered to the current subscribers. If you create a subscription to a topic that has a retained publication, you immediately receive the most recent retained publication on that topic.

    Last will and testament
    This is a connection option which determines the message that is sent to IBM MQ, in the event of the MQTT client being disconnected unexpectedly. This option includes a topic, message, QoS, and the option to retain the publication. Consider setting the QoS to 1 or 2 to guarantee delivery.

    Clean session
    Starting an MQTT client with a clean session removes all pending publications, and all old subscriptions that existed on the client before connection. If no previous session exists, the client utility starts with a new session.

    Client history
    The client history provides information about events that occur while using the MQTT client utility. Examples of events include: Connected, Disonnected, Published, or Subscribed.

    View the full details of an entry by selecting the entry and pressing Enter. Alternatively, double-click the entry.

    Reorder the columns in the client history by dragging the column names and placing them in any order of our choice.

  • Running the MQTT client utility
    We can run the MQTT client utility in several ways. We can run it when you create a new telemetry channel, when you run the Define sample configuration wizard, from an already existing telemetry channel, or from the MQ Telemetry welcome page.
  • Use the MQTT client utility
    Use one or more MQTT client utilities to test your telemetry setup. Within the scope of this task, one client utility is used to publish and subscribe to messages.

Parent topic: Use MQ Telemetry


Related tasks