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.

The token is an MqttDeliveryToken object. It is created by calling the MqttTopic.publish() method and is retained by the MQTT client until the client session is disconnected and the delivery is completed.

The normal use of the token is to check whether delivery is complete. Block the client application until delivery is complete by using the returned token to call token.waitForCompletion. Alternatively, provide a MqttCallBack handler. When the MQTT client has received all the acknowledgments it expects as part of delivering the publication, it calls MqttCallBack.deliveryComplete passing the delivery token as a parameter.

Until delivery is complete, we can inspect the publication using the returned delivery token by calling token.getMessage.


Completed deliveries

The completion of deliveries is asynchronous and depends on the quality of service associated with the publication.

    At most once

    • QoS=0
    • Delivery is complete immediately on return from MqttTopic.publish. MqttCallback.deliveryComplete is called immediately.

    At least once

    • QoS=1
    • Delivery is complete when an acknowledgment to the publication has been received from the queue manager. MqttCallback.deliveryComplete is called when the acknowledgment is received. The message might be delivered more than once before MqttCallback.deliveryComplete is called, if communications are slow or unreliable.

    Exactly once

    • QoS=2
    • Delivery is complete when the client receives a completion message that the publication has been published to subscribers. MqttCallback.deliveryComplete is called as soon as the publication message is received. It does not wait for the completion message.

In rare circumstances, your client application might not return to the MQTT client from MqttCallback.deliveryComplete normally. You know that delivery has completed, because the MqttCallback.deliveryComplete was called. If the client restarts the same session, MqttCallback.deliveryComplete does not get called again.


Incomplete deliveries

If the delivery is not complete after the client session is disconnected we can connect the client again and complete the delivery. We can only complete the delivery of a message if the message was published in a session with the MqttConnectionOptions attribute set to false.

Create the client using the same client identifier and server address, and then connect, setting the cleanSession MqttConnectionOptions attribute to false again. If you set cleanSession to true, pending delivery tokens are thrown away.

We can check if there are any pending deliveries by calling MqttClient.getPendingDeliveryTokens. We can call MqttClient.getPendingDeliveryTokens before connecting the client.

Parent topic: MQTT client programming concepts


Related concepts