public interface IMqttAsyncClient
It provides applications a simple programming interface to all features of the MQTT version 3.1 specification including:
There are two styles of MQTT client, this one and IMqttClient
.
An application is not restricted to using one style if an IMqttAsyncClient based client is used as both blocking and
non-blocking methods can be used in the same application. If an IMqttClient based client is used then only blocking
methods are available to the application. For more details on the blocking client see IMqttClient
There are two forms of non-blocking method:
IMqttToken token = asyncClient.method(parms)
In this form the method returns a token that can be used to track the progress of the action (method). The method
provides a waitForCompletion() method that once invoked will block until the action completes. Once completed there
are method on the token that can be used to check if the action completed successfully or not. For example to wait
until a connect completes:
IMqttToken conToken;
conToken = asyncClient.client.connect(conToken);
... do some work...
conToken.waitForCompletion();
To turn a method into a blocking invocation the following form can be used:
IMqttToken token;
token = asyncClient.method(parms).waitForCompletion();
IMqttToken token method(parms, Object userContext, IMqttActionListener callback)
In this form a callback is registered with the method. The callback will be notified when the action succeeds or
fails. The callback is invoked on the thread managed by the MQTT client so it is important that processing is
minimised in the callback. If not the operation of the MQTT client will be inhibited. For example to be notified
(called back) when a connect completes:
IMqttToken conToken;
conToken = asyncClient.connect("some context",new new MqttAsyncActionListener() {
public void onSuccess(IMqttToken asyncActionToken) {
log("Connected");
}
public void onFailure(IMqttToken asyncActionToken, Throwable exception) {
log ("connect failed" +exception);
}
});
An optional context object can be passed into the method which will then be made available in the
callback. The context is stored by the MQTT client) in the token which is then returned to the invoker. The token is
provided to the callback methods where the context can then be accessed.
To understand when the delivery of a message is complete either of the two methods above can be used to either wait
on or be notified when the publish completes. An alternative is to use the
MqttCallback.deliveryComplete(IMqttDeliveryToken)
method which will also be notified when a message has been
delivered to the requested quality of service.
Modifier and Type | Method and Description |
---|---|
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,
java.lang.Object userContext,
IMqttActionListener callback)
Connects to an MQTT server using the specified options.
|
IMqttToken |
connect(java.lang.Object userContext,
IMqttActionListener callback)
Connects to an MQTT server using the default options.
|
IMqttToken |
disconnect()
Disconnects from the server.
|
IMqttToken |
disconnect(long quiesceTimeout)
Disconnects from the server.
|
IMqttToken |
disconnect(long quiesceTimeout,
java.lang.Object userContext,
IMqttActionListener callback)
Disconnects from the server.
|
IMqttToken |
disconnect(java.lang.Object userContext,
IMqttActionListener callback)
Disconnects from the server.
|
void |
disconnectForcibly()
Disconnects from the server forcibly to reset all the states.
|
void |
disconnectForcibly(long disconnectTimeout)
Disconnects from the server forcibly to reset all the states.
|
void |
disconnectForcibly(long quiesceTimeout,
long disconnectTimeout)
Disconnects from the server forcibly to reset all the states.
|
java.lang.String |
getClientId()
Returns the client ID used by this client.
|
IMqttDeliveryToken[] |
getPendingDeliveryTokens()
Returns the delivery tokens for any outstanding publish operations.
|
java.lang.String |
getServerURI()
Returns the address of the server used by this client.
|
boolean |
isConnected()
Determines if this client is currently connected to the server.
|
IMqttDeliveryToken |
publish(java.lang.String topic,
byte[] payload,
int qos,
boolean retained)
Publishes a message to a topic on the server.
|
IMqttDeliveryToken |
publish(java.lang.String topic,
byte[] payload,
int qos,
boolean retained,
java.lang.Object userContext,
IMqttActionListener callback)
Publishes a message to a topic on the server.
|
IMqttDeliveryToken |
publish(java.lang.String topic,
MqttMessage message)
Publishes a message to a topic on the server.
|
IMqttDeliveryToken |
publish(java.lang.String topic,
MqttMessage message,
java.lang.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(java.lang.String[] topicFilters,
int[] qos)
Subscribe to multiple topics, each of which may include wildcards.
|
IMqttToken |
subscribe(java.lang.String[] topicFilters,
int[] qos,
java.lang.Object userContext,
IMqttActionListener callback)
Subscribes to multiple topics, each of which may include wildcards.
|
IMqttToken |
subscribe(java.lang.String topicFilter,
int qos)
Subscribe to a topic, which may include wildcards.
|
IMqttToken |
subscribe(java.lang.String topicFilter,
int qos,
java.lang.Object userContext,
IMqttActionListener callback)
Subscribe to a topic, which may include wildcards.
|
IMqttToken |
unsubscribe(java.lang.String topicFilter)
Requests the server unsubscribe the client from a topic.
|
IMqttToken |
unsubscribe(java.lang.String[] topicFilters)
Requests the server unsubscribe the client from one or more topics.
|
IMqttToken |
unsubscribe(java.lang.String[] topicFilters,
java.lang.Object userContext,
IMqttActionListener callback)
Requests the server unsubscribe the client from one or more topics.
|
IMqttToken |
unsubscribe(java.lang.String topicFilter,
java.lang.Object userContext,
IMqttActionListener callback)
Requests the server unsubscribe the client from a topics.
|
IMqttToken connect() throws MqttException, MqttSecurityException
The default options are specified in MqttConnectOptions
class.
MqttSecurityException
- for security related problemsMqttException
- for non security related problemsconnect(MqttConnectOptions, Object, IMqttActionListener)
IMqttToken connect(MqttConnectOptions options) throws MqttException, MqttSecurityException
The connection will be established using the options specified in the MqttConnectOptions
parameter.
options
- a set of connection parameters that override the defaults.MqttSecurityException
- for security related problemsMqttException
- for non security related problemsconnect(MqttConnectOptions, Object, IMqttActionListener)
IMqttToken connect(java.lang.Object userContext, IMqttActionListener callback) throws MqttException, MqttSecurityException
The default options are specified in MqttConnectOptions
class.
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.MqttSecurityException
- for security related problemsMqttException
- for non security related problemsconnect(MqttConnectOptions, Object, IMqttActionListener)
IMqttToken connect(MqttConnectOptions options, java.lang.Object userContext, IMqttActionListener callback) throws MqttException, MqttSecurityException
The server to connect to is specified on the constructor. It is recommended to call
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:
IMqttToken.waitForCompletion()
orIMqttActionListener
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.MqttSecurityException
- for security related problemsMqttException
- for non security related problems including communication errorsIMqttToken disconnect() throws MqttException
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.
MqttException
- for problems encountered while disconnectingdisconnect(long, Object, IMqttActionListener)
IMqttToken disconnect(long quiesceTimeout) throws MqttException
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.
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.MqttException
- for problems encountered while disconnectingdisconnect(long, Object, IMqttActionListener)
IMqttToken disconnect(java.lang.Object userContext, IMqttActionListener callback) throws MqttException
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.
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.MqttException
- for problems encountered while disconnectingdisconnect(long, Object, IMqttActionListener)
IMqttToken disconnect(long quiesceTimeout, java.lang.Object userContext, IMqttActionListener callback) throws MqttException
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:
IMqttToken.waitForCompletion()
orIMqttActionListener
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.MqttException
- for problems encountered while disconnectingvoid disconnectForcibly() throws MqttException
Because the client is able to establish the TCP/IP connection to a none MQTT server and it will certainly fail to send the disconnect packet. It will wait for a maximum of 30 seconds for work to quiesce before disconnecting and wait for a maximum of 10 seconds for sending the disconnect packet to server.
MqttException
- if any unexpected errorvoid disconnectForcibly(long disconnectTimeout) throws MqttException
Because the client is able to establish the TCP/IP connection to a none MQTT server and it will certainly fail to send the disconnect packet. It will wait for a maximum of 30 seconds for work to quiesce before disconnecting.
disconnectTimeout
- the amount of time in milliseconds to allow send disconnect packet to server.MqttException
- if any unexpected errorvoid disconnectForcibly(long quiesceTimeout, long disconnectTimeout) throws MqttException
Because the client is able to establish the TCP/IP connection to a none MQTT server and it will certainly fail to send the disconnect packet.
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.disconnectTimeout
- the amount of time in milliseconds to allow send disconnect packet to server.MqttException
- if any unexpected errorboolean isConnected()
true
if connected, false
otherwise.java.lang.String getClientId()
All clients connected to the same server or server farm must have a unique ID.
java.lang.String getServerURI()
The format of the returned String is the same as that used on the constructor.
MqttAsyncClient.MqttAsyncClient(String, String)
IMqttDeliveryToken publish(java.lang.String topic, byte[] payload, int qos, boolean retained) throws MqttException, MqttPersistenceException
A convenience method, which will create a new MqttMessage
object with a byte array payload and the
specified QoS, and then publish it.
topic
- to deliver the message to, for example "finance/stock/ibm".payload
- the byte array to use as the payloadqos
- 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.MqttPersistenceException
- when a problem occurs storing the messagejava.lang.IllegalArgumentException
- if value of QoS is not 0, 1 or 2.MqttException
- for other errors encountered while publishing the message. For instance if too many messages are
being processed.publish(String, MqttMessage, Object, IMqttActionListener)
,
MqttMessage.setQos(int)
,
MqttMessage.setRetained(boolean)
IMqttDeliveryToken publish(java.lang.String topic, byte[] payload, int qos, boolean retained, java.lang.Object userContext, IMqttActionListener callback) throws MqttException, MqttPersistenceException
A convenience method, which will create a new MqttMessage
object with a byte array payload and the
specified QoS, and then publish it.
topic
- to deliver the message to, for example "finance/stock/ibm".payload
- the byte array to use as the payloadqos
- 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 serviceMqttPersistenceException
- when a problem occurs storing the messagejava.lang.IllegalArgumentException
- if value of QoS is not 0, 1 or 2.MqttException
- for other errors encountered while publishing the message. For instance client not connected.publish(String, MqttMessage, Object, IMqttActionListener)
,
MqttMessage.setQos(int)
,
MqttMessage.setRetained(boolean)
IMqttDeliveryToken publish(java.lang.String topic, MqttMessage message) throws MqttException, MqttPersistenceException
MqttMessage
message and delivers it to the server
at the requested quality of service.topic
- to deliver the message to, for example "finance/stock/ibm".message
- to deliver to the serverMqttPersistenceException
- when a problem occurs storing the messagejava.lang.IllegalArgumentException
- if value of QoS is not 0, 1 or 2.MqttException
- for other errors encountered while publishing the message. For instance client not connected.publish(String, MqttMessage, Object, IMqttActionListener)
IMqttDeliveryToken publish(java.lang.String topic, MqttMessage message, java.lang.Object userContext, IMqttActionListener callback) throws MqttException, MqttPersistenceException
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:
setCallback(MqttCallback)
where the
MqttCallback.deliveryComplete(IMqttDeliveryToken)
method will be called.MqttToken.waitForCompletion()
orIMqttActionListener
to this methodtopic
- to deliver the message to, for example "finance/stock/ibm".message
- to deliver to the serveruserContext
- 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 serviceMqttPersistenceException
- when a problem occurs storing the messagejava.lang.IllegalArgumentException
- if value of QoS is not 0, 1 or 2.MqttException
- for other errors encountered while publishing the message. For instance client not connected.MqttMessage
IMqttToken subscribe(java.lang.String topicFilter, int qos) throws MqttException
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.MqttException
- if there was an error registering the subscription.subscribe(String[], int[], Object, IMqttActionListener)
IMqttToken subscribe(java.lang.String topicFilter, int qos, java.lang.Object userContext, IMqttActionListener callback) throws MqttException
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 completedMqttException
- if there was an error registering the subscription.subscribe(String[], int[], Object, IMqttActionListener)
IMqttToken subscribe(java.lang.String[] topicFilters, int[] qos) throws MqttException
Provides an optimized way to subscribe to multiple topics compared to subscribing to each one individually.
topicFilters
- one or more topics to subscribe to, which can include wildcardsqos
- 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.MqttException
- if there was an error registering the subscription.subscribe(String[], int[], Object, IMqttActionListener)
IMqttToken subscribe(java.lang.String[] topicFilters, int[] qos, java.lang.Object userContext, IMqttActionListener callback) throws MqttException
Provides an optimized way to subscribe to multiple topics compared to subscribing to each one individually.
The 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:
The "topic filter" string used when subscribing may contain special characters, which allow you to subscribe to multiple topics at once.
The topic level separator is used to introduce structure into the topic, and can therefore be specified within the topic for that purpose. The multi-level wildcard and single-level wildcard can be used for subscriptions, but they cannot be used within a topic by the publisher of a message.
The number sign (#) is a wildcard character that matches any number of levels within a topic. For example, if you
subscribe to finance/stock/ibm/#, you receive messages on these
topics:
finance / stock / ibm
finance / stock / ibm / closingprice
finance / stock / ibm / currentprice
The multi-level wildcard can represent zero or more levels. Therefore, finance/# can also match the singular finance, where # represents zero levels. The topic level separator is meaningless in this context, because there are no levels to separate.
The multi-level wildcard can be specified only on its own or next to the topic level separator character. Therefore, # and finance/# are both valid, but finance# is not valid. The multi-level wildcard must be the last character used within the topic tree. For example, finance/# is valid but finance/#/closingprice is not valid.
The plus sign (+) is a wildcard character that matches only one topic level. For example, finance/stock/+ matches finance/stock/ibm and finance/stock/xyz, but not finance/stock/ibm/closingprice. Also, because the single-level wildcard matches only a single level, finance/+ does not match finance.
Use the single-level wildcard at any level in the topic tree, and in conjunction with the multilevel wildcard. Specify the single-level wildcard next to the topic level separator, except when it is specified on its own. Therefore, + and finance/+ are both valid, but finance+ is not valid. The single-level wildcard can be used at the end of the topic tree or within the topic tree. For example, finance/+ and finance/+/ibm are both valid.
The method returns control before the subscribe completes. Completion can be tracked by:
MqttToken.waitForCompletion()
orIMqttActionListener
to this methodtopicFilters
- one or more topics to subscribe to, which can include wildcardsqos
- the maximum quality of service to subscribe each topic at.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 completedMqttException
- if there was an error registering the subscription.java.lang.IllegalArgumentException
- if the two supplied arrays are not the same size.IMqttToken unsubscribe(java.lang.String topicFilter) throws MqttException
topicFilter
- the topic to unsubscribe from. It must match a topicFilter specified on an earlier subscribe.MqttException
- if there was an error unregistering the subscription.unsubscribe(String[], Object, IMqttActionListener)
IMqttToken unsubscribe(java.lang.String[] topicFilters) throws MqttException
topicFilters
- one or more topics to unsubscribe from. Each topicFilter must match one specified on an earlier
subscribe. *MqttException
- if there was an error unregistering the subscription.unsubscribe(String[], Object, IMqttActionListener)
IMqttToken unsubscribe(java.lang.String topicFilter, java.lang.Object userContext, IMqttActionListener callback) throws MqttException
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 completedMqttException
- if there was an error unregistering the subscription.unsubscribe(String[], Object, IMqttActionListener)
IMqttToken unsubscribe(java.lang.String[] topicFilters, java.lang.Object userContext, IMqttActionListener callback) throws MqttException
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:
MqttToken.waitForCompletion()
orIMqttActionListener
to this methodtopicFilters
- 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 completedMqttException
- if there was an error unregistering the subscription.void setCallback(MqttCallback callback)
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.
callback
- which will be invoked for certain asynchronous eventsMqttCallback
IMqttDeliveryToken[] getPendingDeliveryTokens()
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
void close() throws MqttException
MqttException
- if the client is not disconnected.