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.

Create subscriptions using the MqttClient.subscribe methods, passing one or more topic filters and quality of service parameters. The quality of service parameter sets the maximum quality of service that the subscriber is prepared to use to receive a message. Messages sent to this client cannot be delivered with a higher quality of service. The quality of service is set to the lower of the original value when the message was published and the level specified for the subscription. The default quality of service for receiving messages is QoS=1, at least once.

The subscription request itself is sent with QoS=1.

Publications are received by a subscriber when the MQTT client calls the MqttCallback.messageArrived method. The messageArrived method also passes the topic string with which the message was published to the subscriber.

You can remove a subscription, or a set or subscriptions, using the MqttClient.unsubscribe methods.

An IBM® MQ command can remove a subscription. List subscriptions using MQ Explorer, or by using runmqsc or PCF commands. All MQTT client subscriptions are named. They are given a name of the form: ClientIdentifier:Topic name

If you use the default MqttConnectOptions, or set MqttConnectOptions.cleanSession to true before connecting the client, any old subscriptions for the client are removed when the client connects. Any new subscriptions the client makes during the session are removed when it disconnects.

If you set MqttConnectOptions.cleanSession to false before connecting, any subscriptions the client creates are added to all the subscriptions that existed for the client before it connected. All the subscriptions remain active when the client disconnects.

Another way of understanding the way the cleanSession attribute affects subscriptions is to think of it as a modal attribute. In its default mode, cleanSession=true, the client creates subscriptions and receives publications only within the scope of the session. In the alternative mode, cleanSession=false, subscriptions are durable. The client can connect and disconnect and its subscriptions remain active. When the client reconnects, it receives any undelivered publications. While it is connected, it can modify the set of subscriptions that are active on its behalf.

You must set the cleanSession mode before connecting; the mode lasts for the whole session. To change its setting, you must disconnect and reconnect the client. If you change modes from using cleanSession=false to cleanSession=true, all previous subscriptions for the client, and any publications that have not been received, are discarded.

Publications that match active subscriptions are sent to the client as soon as they are published. If the client is disconnected, they are sent to the client if it reconnects to the same server with the same client identifier and MqttConnectOptions.cleanSession set to false.

Subscriptions for a particular client are identified by the client identifier. You can reconnect the client from a different client device to the same server, and continue with the same subscriptions and receive undelivered publications.