org.eclipse.paho.mqttv5.client.IMqttDeliveryToken Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.paho.mqttv5.client
The newest version!
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.
 * 
 * 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
 * 
 
 * 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.
 * 
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. 
 * 
 *  
 * An action is in progress until either:
 * 
 * isComplete() returns true or 
 * 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.
 * 
 * 
 */

public interface IMqttDeliveryToken extends IMqttToken {
	/**
	 * Returns the message associated with this token.
	 * Until the message has been delivered, the message being delivered will
	 * be returned. Once the message has been delivered null 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;
}