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. You 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.

When you connect an MQTT client application using the MqttClient.connect method, the client identifies the connection using the client identifier and the address of the server. The server checks whether session information has been saved from a previous connection to the server. If a previous session still exists, and cleanSession=true, then the previous session information at the client and server is cleared. If cleanSession=false the previous session is resumed. If no previous session exists, a new session is started.

Note: The IBM® MQ Administrator can forcibly close an open session and delete all the session information. If the client reopens the session with cleanSession=false, a new session is started.

Publications

If you use the default MqttConnectOptions, or set MqttConnectOptions.cleanSession to true before connecting the client, all pending publication deliveries for the client are removed when the client connects.

The clean session setting has no effect on publications sent with QoS=0. For QoS=1 and QoS=2, using cleanSession=true might result in losing a publication.

Subscriptions

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.