45 lines
2.0 KiB
Java
45 lines
2.0 KiB
Java
package org.eclipse.paho.mqttv5.client;
|
|
|
|
import org.eclipse.paho.mqttv5.common.MqttException;
|
|
import org.eclipse.paho.mqttv5.common.MqttMessage;
|
|
|
|
/**
|
|
* Provides a mechanism for tracking the delivery of a message.
|
|
*
|
|
* <p>A subclass of IMqttToken that allows the delivery of a message to be tracked.
|
|
* Unlike instances of IMqttToken delivery tokens can be used across connection
|
|
* and client restarts. This enables the delivery of a messages to be tracked
|
|
* after failures. There are two approaches
|
|
* <ul>
|
|
* <li>A list of delivery tokens for in-flight messages can be obtained using
|
|
* {@link IMqttAsyncClient#getPendingTokens()}. The waitForCompletion
|
|
* method can then be used to block until the delivery is complete.
|
|
* <li>A {@link MqttCallback} can be set on the client. Once a message has been
|
|
* delivered the {@link MqttCallback#deliveryComplete(IMqttToken)} method will
|
|
* be called withe delivery token being passed as a parameter.
|
|
* </ul>
|
|
* <p>
|
|
* An action is in progress until either:</p>
|
|
* <ul>
|
|
* <li>isComplete() returns true or </li>
|
|
* <li>getException() is not null. If a client shuts down before delivery is complete
|
|
* an exception is returned. As long as the Java Runtime is not stopped a delivery token
|
|
* is valid across a connection disconnect and reconnect. In the event the client
|
|
* is shut down the getPendingTokens method can be used once the client is
|
|
* restarted to obtain a list of delivery tokens for inflight messages.</li>
|
|
* </ul>
|
|
*
|
|
*/
|
|
|
|
public interface IMqttDeliveryToken extends IMqttToken {
|
|
/**
|
|
* Returns the message associated with this token.
|
|
* <p>Until the message has been delivered, the message being delivered will
|
|
* be returned. Once the message has been delivered <code>null</code> will be
|
|
* returned.
|
|
* @return the message associated with this token or null if already delivered.
|
|
* @throws MqttException if there was a problem completing retrieving the message
|
|
*/
|
|
MqttMessage getMessage() throws MqttException;
|
|
}
|