org.eclipse.paho.client.mqttv3
Class MqttAsyncClient

java.lang.Object
  extended by org.eclipse.paho.client.mqttv3.MqttAsyncClient
All Implemented Interfaces:
IMqttAsyncClient

public class MqttAsyncClient
extends Object
implements IMqttAsyncClient

Lightweight client for talking to an MQTT server using non-blocking methods that allow an operation to run in the background.

This class implements the non-blocking IMqttAsyncClient client interface allowing applications to initiate MQTT actions and then carry on working while the MQTT action completes on a background thread. This implementation is compatible with all Java SE runtimes from 1.4.2 and up.

An application can connect to an MQTT server using:

To enable messages to be delivered even across network and client restarts messages need to be safely stored until the message has been delivered at the requested quality of service. A pluggable persistence mechanism is provided to store the messages.

By default MqttDefaultFilePersistence is used to store messages to a file. If persistence is set to null then messages are stored in memory and hence can be lost if the client, Java runtime or device shuts down.

If connecting with MqttConnectOptions.setCleanSession(boolean) set to true it is safe to use memory persistence as all state is cleared when a client disconnects. If connecting with cleanSession set to false in order to provide reliable message delivery then a persistent message store such as the default one should be used.

The message store interface is pluggable. Different stores can be used by implementing the MqttClientPersistence interface and passing it to the clients constructor.

See Also:
IMqttAsyncClient

Field Summary
protected  ClientComms comms
           
 Logger log
           
 
Constructor Summary
MqttAsyncClient(String serverURI, String clientId)
          Create an MqttAsyncClient that is used to communicate with an MQTT server.
MqttAsyncClient(String serverURI, String clientId, MqttClientPersistence persistence)
          Create an MqttAsyncClient that is used to communicate with an MQTT server.
 
Method Summary
protected static boolean Character_isHighSurrogate(char ch)
           
 void close()
          Close the client Releases all resource associated with the client.
 IMqttToken connect()
          Connects to an MQTT server using the default options.
 IMqttToken connect(MqttConnectOptions options)
          Connects to an MQTT server using the provided connect options.
 IMqttToken connect(MqttConnectOptions options, Object userContext, IMqttActionListener callback)
          Connects to an MQTT server using the specified options.
 IMqttToken connect(Object userContext, IMqttActionListener callback)
          Connects to an MQTT server using the default options.
protected  NetworkModule[] createNetworkModules(String address, MqttConnectOptions options)
          Factory method to create an array of network modules, one for each of the supplied URIs
 IMqttToken disconnect()
          Disconnects from the server.
 IMqttToken disconnect(long quiesceTimeout)
          Disconnects from the server.
 IMqttToken disconnect(long quiesceTimeout, Object userContext, IMqttActionListener callback)
          Disconnects from the server.
 IMqttToken disconnect(Object userContext, IMqttActionListener callback)
          Disconnects from the server.
static String generateClientId()
          Returns a randomly generated client identifier based on the current user's login name and the system time.
 String getClientId()
          Returns the client ID used by this client.
 Debug getDebug()
          Return a debug object that can be used to help solve problems.
 IMqttDeliveryToken[] getPendingDeliveryTokens()
          Returns the delivery tokens for any outstanding publish operations.
 String getServerURI()
          Returns the address of the server used by this client.
protected  MqttTopic getTopic(String topic)
          Get a topic object which can be used to publish messages.
 boolean isConnected()
          Determines if this client is currently connected to the server.
 IMqttDeliveryToken publish(String topic, byte[] payload, int qos, boolean retained)
          Publishes a message to a topic on the server.
 IMqttDeliveryToken publish(String topic, byte[] payload, int qos, boolean retained, Object userContext, IMqttActionListener callback)
          Publishes a message to a topic on the server.
 IMqttDeliveryToken publish(String topic, MqttMessage message)
          Publishes a message to a topic on the server.
 IMqttDeliveryToken publish(String topic, MqttMessage message, Object userContext, IMqttActionListener callback)
          Publishes a message to a topic on the server.
 void setCallback(MqttCallback callback)
          Sets a callback listener to use for events that happen asynchronously.
 IMqttToken subscribe(String[] topicFilters, int[] qos)
          Subscribe to multiple topics, each of which may include wildcards.
 IMqttToken subscribe(String[] topicFilters, int[] qos, Object userContext, IMqttActionListener callback)
          Subscribes to multiple topics, each of which may include wildcards.
 IMqttToken subscribe(String topicFilter, int qos)
          Subscribe to a topic, which may include wildcards.
 IMqttToken subscribe(String topicFilter, int qos, Object userContext, IMqttActionListener callback)
          Subscribe to a topic, which may include wildcards.
 IMqttToken unsubscribe(String topicFilter)
          Requests the server unsubscribe the client from a topic.
 IMqttToken unsubscribe(String[] topicFilters)
          Requests the server unsubscribe the client from one or more topics.
 IMqttToken unsubscribe(String[] topicFilters, Object userContext, IMqttActionListener callback)
          Requests the server unsubscribe the client from one or more topics.
 IMqttToken unsubscribe(String topicFilter, Object userContext, IMqttActionListener callback)
          Requests the server unsubscribe the client from a topics.
static void validateTopic(String topic)
          Checks a topic is valid when publishing a message.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

comms

protected ClientComms comms

log

public Logger log
Constructor Detail

MqttAsyncClient

public MqttAsyncClient(String serverURI,
                       String clientId)
                throws MqttException
Create an MqttAsyncClient that is used to communicate with an MQTT server.

The address of a server can be specified on the constructor. Alternatively a list containing one or more servers can be specified using the setServerURIs method on MqttConnectOptions.

The serverURI parameter is typically used with the the clientId parameter to form a key. The key is used to store and reference messages while they are being delivered. Hence the serverURI specified on the constructor must still be specified even if a list of servers is specified on an MqttConnectOptions object. The serverURI on the constructor must remain the same across restarts of the client for delivery of messages to be maintained from a given client to a given server or set of servers.

The address of the server to connect to is specified as a URI. Two types of connection are supported tcp:// for a TCP connection and ssl:// for a TCP connection secured by SSL/TLS. For example:

If the port is not specified, it will default to 1883 for tcp://" URIs, and 8883 for ssl:// URIs.

A client identifier clientId must be specified and be less that 23 characters. It must be unique across all clients connecting to the same server. The clientId is used by the server to store data related to the client, hence it is important that the clientId remain the same when connecting to a server if durable subscriptions or reliable messaging are required.

A convenience method is provided to generate a random client id that should satisfy this criteria - generateClientId(). As the client identifier is used by the server to identify a client when it reconnects, the client must use the same identifier between connections if durable subscriptions or reliable delivery of messages is required.

In Java SE, SSL can be configured in one of several ways, which the client will use in the following order:

In Java ME, the platform settings are used for SSL connections.

An instance of the default persistence mechanism MqttDefaultFilePersistence is used by the client. To specify a different persistence mechanism or to turn off persistence, use the MqttAsyncClient(String, String, MqttClientPersistence) constructor.

Parameters:
serverURI - the address of the server to connect to, specified as a URI. Can be overridden using MqttConnectOptions.setServerURIs(String[])
clientId - a client identifier that is unique on the server being connected to
Throws:
IllegalArgumentException - if the URI does not start with "tcp://", "ssl://" or "local://".
IllegalArgumentException - if the clientId is null or is greater than 23 characters in length
MqttException - if any other problem was encountered

MqttAsyncClient

public MqttAsyncClient(String serverURI,
                       String clientId,
                       MqttClientPersistence persistence)
                throws MqttException
Create an MqttAsyncClient that is used to communicate with an MQTT server.

The address of a server can be specified on the constructor. Alternatively a list containing one or more servers can be specified using the setServerURIs method on MqttConnectOptions.

The serverURI parameter is typically used with the the clientId parameter to form a key. The key is used to store and reference messages while they are being delivered. Hence the serverURI specified on the constructor must still be specified even if a list of servers is specified on an MqttConnectOptions object. The serverURI on the constructor must remain the same across restarts of the client for delivery of messages to be maintained from a given client to a given server or set of servers.

The address of the server to connect to is specified as a URI. Two types of connection are supported tcp:// for a TCP connection and ssl:// for a TCP connection secured by SSL/TLS. For example:

If the port is not specified, it will default to 1883 for tcp://" URIs, and 8883 for ssl:// URIs.

A client identifier clientId must be specified and be less that 23 characters. It must be unique across all clients connecting to the same server. The clientId is used by the server to store data related to the client, hence it is important that the clientId remain the same when connecting to a server if durable subscriptions or reliable messaging are required.

A convenience method is provided to generate a random client id that should satisfy this criteria - generateClientId(). As the client identifier is used by the server to identify a client when it reconnects, the client must use the same identifier between connections if durable subscriptions or reliable delivery of messages is required.

In Java SE, SSL can be configured in one of several ways, which the client will use in the following order:

In Java ME, the platform settings are used for SSL connections.

A persistence mechanism is used to enable reliable messaging. For messages sent at qualities of service (QoS) 1 or 2 to be reliably delivered, messages must be stored (on both the client and server) until the delivery of the message is complete. If messages are not safely stored when being delivered then a failure in the client or server can result in lost messages. A pluggable persistence mechanism is supported via the MqttClientPersistence interface. An implementer of this interface that safely stores messages must be specified in order for delivery of messages to be reliable. In addition MqttConnectOptions.setCleanSession(boolean) must be set to false. In the event that only QoS 0 messages are sent or received or cleanSession is set to true then a safe store is not needed.

An implementation of file-based persistence is provided in class MqttDefaultFilePersistence which will work in all Java SE based systems. If no persistence is needed, the persistence parameter can be explicitly set to null.

Parameters:
serverURI - the address of the server to connect to, specified as a URI. Can be overridden using MqttConnectOptions.setServerURIs(String[])
clientId - a client identifier that is unique on the server being connected to
persistence - the persistence class to use to store in-flight message. If null then the default persistence mechanism is used
Throws:
IllegalArgumentException - if the URI does not start with "tcp://", "ssl://" or "local://"
IllegalArgumentException - if the clientId is null or is greater than 23 characters in length
MqttException - if any other problem was encountered
Method Detail

Character_isHighSurrogate

protected static boolean Character_isHighSurrogate(char ch)
Parameters:
ch -
Returns:
returns 'true' if the character is a high-surrogate code unit

createNetworkModules

protected NetworkModule[] createNetworkModules(String address,
                                               MqttConnectOptions options)
                                        throws MqttException,
                                               MqttSecurityException
Factory method to create an array of network modules, one for each of the supplied URIs

Parameters:
address - the URI for the server.
Returns:
a network module appropriate to the specified address.
Throws:
MqttException
MqttSecurityException

connect

public IMqttToken connect(Object userContext,
                          IMqttActionListener callback)
                   throws MqttException,
                          MqttSecurityException
Description copied from interface: IMqttAsyncClient
Connects to an MQTT server using the default options.

The default options are specified in MqttConnectOptions class.

Specified by:
connect in interface IMqttAsyncClient
Parameters:
userContext - optional object used to pass context to the callback. Use null if not required.
callback - optional listener that will be notified when the connect completes. Use null if not required.
Returns:
token used to track and wait for the connect to complete. The token will be passed to any callback that has been set.
Throws:
MqttSecurityException - for security related problems
MqttException - for non security related problems
See Also:
IMqttAsyncClient.connect(MqttConnectOptions, Object, IMqttActionListener)

connect

public IMqttToken connect()
                   throws MqttException,
                          MqttSecurityException
Description copied from interface: IMqttAsyncClient
Connects to an MQTT server using the default options.

The default options are specified in MqttConnectOptions class.

Specified by:
connect in interface IMqttAsyncClient
Returns:
token used to track and wait for the connect to complete. The token will be passed to the callback methods if a callback is set.
Throws:
MqttSecurityException - for security related problems
MqttException - for non security related problems
See Also:
IMqttAsyncClient.connect(MqttConnectOptions, Object, IMqttActionListener)

connect

public IMqttToken connect(MqttConnectOptions options)
                   throws MqttException,
                          MqttSecurityException
Description copied from interface: IMqttAsyncClient
Connects to an MQTT server using the provided connect options.

The connection will be established using the options specified in the MqttConnectOptions parameter.

Specified by:
connect in interface IMqttAsyncClient
Parameters:
options - a set of connection parameters that override the defaults.
Returns:
token used to track and wait for the connect to complete. The token will be passed to any callback that has been set.
Throws:
MqttSecurityException - for security related problems
MqttException - for non security related problems
See Also:
IMqttAsyncClient.connect(MqttConnectOptions, Object, IMqttActionListener)

connect

public IMqttToken connect(MqttConnectOptions options,
                          Object userContext,
                          IMqttActionListener callback)
                   throws MqttException,
                          MqttSecurityException
Description copied from interface: IMqttAsyncClient
Connects to an MQTT server using the specified options.

The server to connect to is specified on the constructor. It is recommended to call IMqttAsyncClient.setCallback(MqttCallback) prior to connecting in order that messages destined for the client can be accepted as soon as the client is connected.

The method returns control before the connect completes. Completion can be tracked by:

Specified by:
connect in interface IMqttAsyncClient
Parameters:
options - a set of connection parameters that override the defaults.
userContext - optional object for used to pass context to the callback. Use null if not required.
callback - optional listener that will be notified when the connect completes. Use null if not required.
Returns:
token used to track and wait for the connect to complete. The token will be passed to any callback that has been set.
Throws:
MqttSecurityException - for security related problems
MqttException - for non security related problems including communication errors

disconnect

public IMqttToken disconnect(Object userContext,
                             IMqttActionListener callback)
                      throws MqttException
Description copied from interface: IMqttAsyncClient
Disconnects from the server.

An attempt is made to quiesce the client allowing outstanding work to complete before disconnecting. It will wait for a maximum of 30 seconds for work to quiesce before disconnecting. This method must not be called from inside MqttCallback methods.

Specified by:
disconnect in interface IMqttAsyncClient
Parameters:
userContext - optional object used to pass context to the callback. Use null if not required.
callback - optional listener that will be notified when the disconnect completes. Use null if not required.
Returns:
token used to track and wait for the disconnect to complete. The token will be passed to any callback that has been set.
Throws:
MqttException - for problems encountered while disconnecting
See Also:
IMqttAsyncClient.disconnect(long, Object, IMqttActionListener)

disconnect

public IMqttToken disconnect()
                      throws MqttException
Description copied from interface: IMqttAsyncClient
Disconnects from the server.

An attempt is made to quiesce the client allowing outstanding work to complete before disconnecting. It will wait for a maximum of 30 seconds for work to quiesce before disconnecting. This method must not be called from inside MqttCallback methods.

Specified by:
disconnect in interface IMqttAsyncClient
Returns:
token used to track and wait for disconnect to complete. The token will be passed to any callback that has been set.
Throws:
MqttException - for problems encountered while disconnecting
See Also:
IMqttAsyncClient.disconnect(long, Object, IMqttActionListener)

disconnect

public IMqttToken disconnect(long quiesceTimeout)
                      throws MqttException
Description copied from interface: IMqttAsyncClient
Disconnects from the server.

An attempt is made to quiesce the client allowing outstanding work to complete before disconnecting. It will wait for a maximum of the specified quiesce time for work to complete before disconnecting. This method must not be called from inside MqttCallback methods.

Specified by:
disconnect in interface IMqttAsyncClient
Parameters:
quiesceTimeout - the amount of time in milliseconds to allow for existing work to finish before disconnecting. A value of zero or less means the client will not quiesce.
Returns:
token used to track and wait for disconnect to complete. The token will be passed to the callback methods if a callback is set.
Throws:
MqttException - for problems encountered while disconnecting
See Also:
IMqttAsyncClient.disconnect(long, Object, IMqttActionListener)

disconnect

public IMqttToken disconnect(long quiesceTimeout,
                             Object userContext,
                             IMqttActionListener callback)
                      throws MqttException
Description copied from interface: IMqttAsyncClient
Disconnects from the server.

The client will wait for MqttCallback methods to complete. It will then wait for up to the quiesce timeout to allow for work which has already been initiated to complete. For instance when a QoS 2 message has started flowing to the server but the QoS 2 flow has not completed.It prevents new messages being accepted and does not send any messages that have been accepted but not yet started delivery across the network to the server. When work has completed or after the quiesce timeout, the client will disconnect from the server. If the cleanSession flag was set to false and is set to false the next time a connection is made QoS 1 and 2 messages that were not previously delivered will be delivered.

This method must not be called from inside MqttCallback methods.

The method returns control before the disconnect completes. Completion can be tracked by:

Specified by:
disconnect in interface IMqttAsyncClient
Parameters:
quiesceTimeout - the amount of time in milliseconds to allow for existing work to finish before disconnecting. A value of zero or less means the client will not quiesce.
userContext - optional object used to pass context to the callback. Use null if not required.
callback - optional listener that will be notified when the disconnect completes. Use null if not required.
Returns:
token used to track and wait for the connect to complete. The token will be passed to any callback that has been set.
Throws:
MqttException - for problems encountered while disconnecting

isConnected

public boolean isConnected()
Description copied from interface: IMqttAsyncClient
Determines if this client is currently connected to the server.

Specified by:
isConnected in interface IMqttAsyncClient
Returns:
true if connected, false otherwise.

getClientId

public String getClientId()
Description copied from interface: IMqttAsyncClient
Returns the client ID used by this client.

All clients connected to the same server or server farm must have a unique ID.

Specified by:
getClientId in interface IMqttAsyncClient
Returns:
the client ID used by this client.

getServerURI

public String getServerURI()
Description copied from interface: IMqttAsyncClient
Returns the address of the server used by this client.

The format of the returned String is the same as that used on the constructor.

Specified by:
getServerURI in interface IMqttAsyncClient
Returns:
the server's address, as a URI String.
See Also:
MqttAsyncClient(String, String)

getTopic

protected MqttTopic getTopic(String topic)
Get a topic object which can be used to publish messages.

There are two alternative methods that should be used in preference to this one when publishing a message:

When you build an application, the design of the topic tree should take into account the following principles of topic name syntax and semantics:

The following principles apply to the construction and content of a topic tree:

Parameters:
topic - the topic to use, for example "finance/stock/ibm".
Returns:
an MqttTopic object, which can be used to publish messages to the topic.
Throws:
IllegalArgumentException - if the topic contains a '+' or '#' wildcard character.

subscribe

public IMqttToken subscribe(String topicFilter,
                            int qos,
                            Object userContext,
                            IMqttActionListener callback)
                     throws MqttException
Description copied from interface: IMqttAsyncClient
Subscribe to a topic, which may include wildcards.

Specified by:
subscribe in interface IMqttAsyncClient
Parameters:
topicFilter - the topic to subscribe to, which can include wildcards.
qos - the maximum quality of service at which to subscribe. Messages published at a lower quality of service will be received at the published QoS. Messages published at a higher quality of service will be received using the QoS specified on the subscribe.
userContext - optional object used to pass context to the callback. Use null if not required.
callback - optional listener that will be notified when subscribe has completed
Returns:
token used to track and wait for the subscribe to complete. The token will be passed to callback methods if set.
Throws:
MqttException - if there was an error registering the subscription.
See Also:
IMqttAsyncClient.subscribe(String[], int[], Object, IMqttActionListener)

subscribe

public IMqttToken subscribe(String topicFilter,
                            int qos)
                     throws MqttException
Description copied from interface: IMqttAsyncClient
Subscribe to a topic, which may include wildcards.

Specified by:
subscribe in interface IMqttAsyncClient
Parameters:
topicFilter - the topic to subscribe to, which can include wildcards.
qos - the maximum quality of service at which to subscribe. Messages published at a lower quality of service will be received at the published QoS. Messages published at a higher quality of service will be received using the QoS specified on the subscribe.
Returns:
token used to track and wait for the subscribe to complete. The token will be passed to callback methods if set.
Throws:
MqttException - if there was an error registering the subscription.
See Also:
IMqttAsyncClient.subscribe(String[], int[], Object, IMqttActionListener)

subscribe

public IMqttToken subscribe(String[] topicFilters,
                            int[] qos)
                     throws MqttException
Description copied from interface: IMqttAsyncClient
Subscribe to multiple topics, each of which may include wildcards.

Provides an optimized way to subscribe to multiple topics compared to subscribing to each one individually.

Specified by:
subscribe in interface IMqttAsyncClient
Parameters:
topicFilters - one or more topics to subscribe to, which can include wildcards
qos - the maximum quality of service at which to subscribe. Messages published at a lower quality of service will be received at the published QoS. Messages published at a higher quality of service will be received using the QoS specified on the subscribe.
Returns:
token used to track and wait for the subscribe to complete. The token will be passed to callback methods if set.
Throws:
MqttException - if there was an error registering the subscription.
See Also:
IMqttAsyncClient.subscribe(String[], int[], Object, IMqttActionListener)

subscribe

public IMqttToken subscribe(String[] topicFilters,
                            int[] qos,
                            Object userContext,
                            IMqttActionListener callback)
                     throws MqttException
Description copied from interface: IMqttAsyncClient
Subscribes to multiple topics, each of which may include wildcards.

Provides an optimized way to subscribe to multiple topics compared to subscribing to each one individually.

The IMqttAsyncClient.setCallback(MqttCallback) method should be called before this method, otherwise any received messages will be discarded.

If (@link MqttConnectOptions#setCleanSession(boolean)} was set to true when when connecting to the server then the subscription remains in place until either:


unsubscribe

public IMqttToken unsubscribe(String topicFilter,
                              Object userContext,
                              IMqttActionListener callback)
                       throws MqttException
Description copied from interface: IMqttAsyncClient
Requests the server unsubscribe the client from a topics.

Specified by:
unsubscribe in interface IMqttAsyncClient
Parameters:
topicFilter - the topic to unsubscribe from. It must match a topicFilter specified on an earlier subscribe.
userContext - optional object used to pass context to the callback. Use null if not required.
callback - optional listener that will be notified when unsubscribe has completed
Returns:
token used to track and wait for the unsubscribe to complete. The token will be passed to callback methods if set.
Throws:
MqttException - if there was an error unregistering the subscription.
See Also:
IMqttAsyncClient.unsubscribe(String[], Object, IMqttActionListener)

unsubscribe

public IMqttToken unsubscribe(String topicFilter)
                       throws MqttException
Description copied from interface: IMqttAsyncClient
Requests the server unsubscribe the client from a topic.

Specified by:
unsubscribe in interface IMqttAsyncClient
Parameters:
topicFilter - the topic to unsubscribe from. It must match a topicFilter specified on an earlier subscribe.
Returns:
token used to track and wait for the unsubscribe to complete. The token will be passed to callback methods if set.
Throws:
MqttException - if there was an error unregistering the subscription.
See Also:
IMqttAsyncClient.unsubscribe(String[], Object, IMqttActionListener)

unsubscribe

public IMqttToken unsubscribe(String[] topicFilters)
                       throws MqttException
Description copied from interface: IMqttAsyncClient
Requests the server unsubscribe the client from one or more topics.

Specified by:
unsubscribe in interface IMqttAsyncClient
Parameters:
topicFilters - one or more topics to unsubscribe from. Each topicFilter must match one specified on an earlier subscribe. *
Returns:
token used to track and wait for the unsubscribe to complete. The token will be passed to callback methods if set.
Throws:
MqttException - if there was an error unregistering the subscription.
See Also:
IMqttAsyncClient.unsubscribe(String[], Object, IMqttActionListener)

unsubscribe

public IMqttToken unsubscribe(String[] topicFilters,
                              Object userContext,
                              IMqttActionListener callback)
                       throws MqttException
Description copied from interface: IMqttAsyncClient
Requests the server unsubscribe the client from one or more topics.

Unsubcribing is the opposite of subscribing. When the server receives the unsubscribe request it looks to see if it can find a matching subscription for the client and then removes it. After this point the server will send no more messages to the client for this subscription.

The topic(s) specified on the unsubscribe must match the topic(s) specified in the original subscribe request for the unsubscribe to succeed

The method returns control before the unsubscribe completes. Completion can be tracked by:

Specified by:
unsubscribe in interface IMqttAsyncClient
Parameters:
topicFilters - one or more topics to unsubscribe from. Each topicFilter must match one specified on an earlier subscribe.
userContext - optional object used to pass context to the callback. Use null if not required.
callback - optional listener that will be notified when unsubscribe has completed
Returns:
token used to track and wait for the unsubscribe to complete. The token will be passed to callback methods if set.
Throws:
MqttException - if there was an error unregistering the subscription.

setCallback

public void setCallback(MqttCallback callback)
Description copied from interface: IMqttAsyncClient
Sets a callback listener to use for events that happen asynchronously.

There are a number of events that the listener will be notified about. These include:

Other events that track the progress of an individual operation such as connect and subscribe can be tracked using the MqttToken returned from each non-blocking method or using setting a IMqttActionListener on the non-blocking method.

Specified by:
setCallback in interface IMqttAsyncClient
Parameters:
callback - which will be invoked for certain asynchronous events
See Also:
MqttCallback

generateClientId

public static String generateClientId()
Returns a randomly generated client identifier based on the current user's login name and the system time.

When cleanSession is set to false, an application must ensure it uses the same client identifier when it reconnects to the server to resume state and maintain assured message delivery.

Returns:
a generated client identifier
See Also:
MqttConnectOptions.setCleanSession(boolean)

getPendingDeliveryTokens

public IMqttDeliveryToken[] getPendingDeliveryTokens()
Description copied from interface: IMqttAsyncClient
Returns the delivery tokens for any outstanding publish operations.

If a client has been restarted and there are messages that were in the process of being delivered when the client stopped this method returns a token for each in-flight message enabling the delivery to be tracked Alternately the MqttCallback.deliveryComplete(IMqttDeliveryToken) callback can be used to track the delivery of outstanding messages.

If a client connects with cleanSession true then there will be no delivery tokens as the cleanSession option deletes all earlier state. For state to be remembered the client must connect with cleanSession set to false

Specified by:
getPendingDeliveryTokens in interface IMqttAsyncClient
Returns:
zero or more delivery tokens

publish

public IMqttDeliveryToken publish(String topic,
                                  byte[] payload,
                                  int qos,
                                  boolean retained,
                                  Object userContext,
                                  IMqttActionListener callback)
                           throws MqttException,
                                  MqttPersistenceException
Description copied from interface: IMqttAsyncClient
Publishes a message to a topic on the server.

A convenience method, which will create a new MqttMessage object with a byte array payload and the specified QoS, and then publish it.

Specified by:
publish in interface IMqttAsyncClient
Parameters:
topic - to deliver the message to, for example "finance/stock/ibm".
payload - the byte array to use as the payload
qos - the Quality of Service to deliver the message at. Valid values are 0, 1 or 2.
retained - whether or not this message should be retained by the server.
userContext - optional object used to pass context to the callback. Use null if not required.
callback - optional listener that will be notified when message delivery hsa completed to the requested quality of service
Returns:
token used to track and wait for the publish to complete. The token will be passed to any callback that has been set.
Throws:
MqttPersistenceException - when a problem occurs storing the message
MqttException - for other errors encountered while publishing the message. For instance client not connected.
See Also:
IMqttAsyncClient.publish(String, MqttMessage, Object, IMqttActionListener), MqttMessage.setQos(int), MqttMessage.setRetained(boolean)

publish

public IMqttDeliveryToken publish(String topic,
                                  byte[] payload,
                                  int qos,
                                  boolean retained)
                           throws MqttException,
                                  MqttPersistenceException
Description copied from interface: IMqttAsyncClient
Publishes a message to a topic on the server.

A convenience method, which will create a new MqttMessage object with a byte array payload and the specified QoS, and then publish it.

Specified by:
publish in interface IMqttAsyncClient
Parameters:
topic - to deliver the message to, for example "finance/stock/ibm".
payload - the byte array to use as the payload
qos - the Quality of Service to deliver the message at. Valid values are 0, 1 or 2.
retained - whether or not this message should be retained by the server.
Returns:
token used to track and wait for the publish to complete. The token will be passed to any callback that has been set.
Throws:
MqttPersistenceException - when a problem occurs storing the message
MqttException - for other errors encountered while publishing the message. For instance if too many messages are being processed.
See Also:
IMqttAsyncClient.publish(String, MqttMessage, Object, IMqttActionListener), MqttMessage.setQos(int), MqttMessage.setRetained(boolean)

publish

public IMqttDeliveryToken publish(String topic,
                                  MqttMessage message)
                           throws MqttException,
                                  MqttPersistenceException
Description copied from interface: IMqttAsyncClient
Publishes a message to a topic on the server. Takes an MqttMessage message and delivers it to the server at the requested quality of service.

Specified by:
publish in interface IMqttAsyncClient
Parameters:
topic - to deliver the message to, for example "finance/stock/ibm".
message - to deliver to the server
Returns:
token used to track and wait for the publish to complete. The token will be passed to any callback that has been set.
Throws:
MqttPersistenceException - when a problem occurs storing the message
MqttException - for other errors encountered while publishing the message. For instance client not connected.
See Also:
IMqttAsyncClient.publish(String, MqttMessage, Object, IMqttActionListener)

publish

public IMqttDeliveryToken publish(String topic,
                                  MqttMessage message,
                                  Object userContext,
                                  IMqttActionListener callback)
                           throws MqttException,
                                  MqttPersistenceException
Description copied from interface: IMqttAsyncClient
Publishes a message to a topic on the server.

Once this method has returned cleanly, the message has been accepted for publication by the client and will be delivered on a background thread. In the event the connection fails or the client stops. Messages will be delivered to the requested quality of service once the connection is re-established to the server on condition that:

When building an application, the design of the topic tree should take into account the following principles of topic name syntax and semantics:

The following principles apply to the construction and content of a topic tree:

The method returns control before the publish completes. Completion can be tracked by:

Specified by:
publish in interface IMqttAsyncClient
Parameters:
topic - to deliver the message to, for example "finance/stock/ibm".
message - to deliver to the server
userContext - optional object used to pass context to the callback. Use null if not required.
callback - optional listener that will be notified when message delivery has completed to the requested quality of service
Returns:
token used to track and wait for the publish to complete. The token will be passed to callback methods if set.
Throws:
MqttPersistenceException - when a problem occurs storing the message
MqttException - for other errors encountered while publishing the message. For instance client not connected.
See Also:
MqttMessage

close

public void close()
           throws MqttException
Description copied from interface: IMqttAsyncClient
Close the client Releases all resource associated with the client. After the client has been closed it cannot be reused. For instance attempts to connect will fail.

Specified by:
close in interface IMqttAsyncClient
Throws:
MqttException - if the client is not disconnected.

getDebug

public Debug getDebug()
Return a debug object that can be used to help solve problems.


validateTopic

public static void validateTopic(String topic)
Checks a topic is valid when publishing a message.

Checks the topic does not contain a wild card character.

Parameters:
topic - to validate
Throws:
IllegalArgumentException - if the topic is not valid


Copyright © 2013. All Rights Reserved.