org.eclipse.paho.client.mqttv3
Class MqttToken

java.lang.Object
  org.eclipse.paho.client.mqttv3.MqttToken

All Implemented Interfaces:

IMqttToken

Direct Known Subclasses:

MqttDeliveryToken

public class MqttToken
extends Object
implements IMqttToken

Provides a mechanism for tracking the completion of an asynchronous action.

A token that implements the ImqttToken interface is returned from all non-blocking method with the exception of publish.

See Also:

IMqttToken

Field Summary

Token

internalTok A reference to the the class that provides most of the implementation of the MqttToken.

Constructor Summary

MqttToken()

MqttToken(String logContext)

Method Summary

IMqttActionListener	getActionCallback() Return the async listener for this token.
IMqttAsyncClient	getClient() Returns the MQTT client that is responsible for processing the asynchronous action
MqttException	getException() Returns an exception providing more detail if an operation failed.
int	getMessageId() Returns the message ID of the message that is associated with the token.
String[]	getTopics() Returns the topic string(s) for the action being tracked by this token.
Object	getUserContext() Retrieve the context associated with an action.
boolean	isComplete() Returns whether or not the action has finished.
void	setActionCallback(IMqttActionListener listener) Register a listener to be notified when an action completes.
void	setUserContext(Object userContext) Store some context associated with an action.
void	waitForCompletion() Blocks the current thread until the action this token is associated with has completed.
void	waitForCompletion(long timeout) Blocks the current thread until the action this token is associated with has completed.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

internalTok

public Token internalTok

A reference to the the class that provides most of the implementation of the MqttToken. MQTT application programs must not use the internal class.

Constructor Detail

MqttToken

public MqttToken()

MqttToken

public MqttToken(String logContext)

Method Detail

getException

public MqttException getException()

Description copied from interface: IMqttToken

Returns an exception providing more detail if an operation failed.

While an action in in progress and when an action completes successfully null will be returned. Certain errors like timeout or shutting down will not set the exception as the action has not failed or completed at that time

Specified by:

getException in interface IMqttToken

Returns:

exception may return an exception if the operation failed. Null will be returned while action is in progress and if action completes successfully.

isComplete

public boolean isComplete()

Description copied from interface: IMqttToken

Returns whether or not the action has finished.

True will be returned both in the case where the action finished successfully and in the case where it failed. If the action failed IMqttToken.getException() will be non null.

Specified by:

isComplete in interface IMqttToken

setActionCallback

public void setActionCallback(IMqttActionListener listener)

Description copied from interface: IMqttToken

Register a listener to be notified when an action completes.

Once a listener is registered it will be invoked when the action the token is associated with either succeeds or fails.

Specified by:

setActionCallback in interface IMqttToken

Parameters:

listener - to be invoked once the action completes

getActionCallback

public IMqttActionListener getActionCallback()

Description copied from interface: IMqttToken

Return the async listener for this token.

Specified by:

getActionCallback in interface IMqttToken

Returns:

listener that is set on the token or null if a listener is not registered.

waitForCompletion

public void waitForCompletion()
                       throws MqttException

Description copied from interface: IMqttToken

Blocks the current thread until the action this token is associated with has completed.

Specified by:

waitForCompletion in interface IMqttToken

Throws:

MqttException - if there was a problem with the action associated with the token.

See Also:

IMqttToken.waitForCompletion(long)

waitForCompletion

public void waitForCompletion(long timeout)
                       throws MqttException

Description copied from interface: IMqttToken

Blocks the current thread until the action this token is associated with has completed.

The timeout specifies the maximum time it will block for. If the action completes before the timeout then control returns immediately, if not it will block until the timeout expires.

If the action being tracked fails or the timeout expires an exception will be thrown. In the event of a timeout the action may complete after timeout.

Specified by:

waitForCompletion in interface IMqttToken

Parameters:

timeout - the maximum amount of time to wait for, in milliseconds.

Throws:

MqttException - if there was a problem with the action associated with the token.

getClient

public IMqttAsyncClient getClient()

Description copied from interface: IMqttToken

Returns the MQTT client that is responsible for processing the asynchronous action

Specified by:

getClient in interface IMqttToken

getTopics

public String[] getTopics()

Description copied from interface: IMqttToken

Returns the topic string(s) for the action being tracked by this token. If the action has not been initiated or the action has not topic associated with it such as connect then null will be returned.

Specified by:

getTopics in interface IMqttToken

Returns:

the topic string(s) for the subscribe being tracked by this token or null

getUserContext

public Object getUserContext()

Description copied from interface: IMqttToken

Retrieve the context associated with an action.

Allows the ActionListener associated with an action to retrieve any context that was associated with the action when the action was invoked. If not context was provided null is returned.

Specified by:

getUserContext in interface IMqttToken

Returns:

Object context associated with an action or null if there is none.

setUserContext

public void setUserContext(Object userContext)

Description copied from interface: IMqttToken

Store some context associated with an action.

Allows the caller of an action to store some context that can be accessed from within the ActionListener associated with the action. This can be useful when the same ActionListener is associated with multiple actions

Specified by:

setUserContext in interface IMqttToken

Parameters:

userContext - to associate with an action

getMessageId

public int getMessageId()

Description copied from interface: IMqttToken

Returns the message ID of the message that is associated with the token. A message id of zero will be returned for tokens associated with connect, disconnect and ping operations as there can only ever be one of these outstanding at a time. For other operations the MQTT message id flowed over the network.

Specified by:

getMessageId in interface IMqttToken