public class MqttAsyncClient extends java.lang.Object implements IMqttAsyncClient
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.
IMqttAsyncClient
Constructor and Description |
---|
MqttAsyncClient(java.lang.String serverURI,
java.lang.String clientId)
Create an MqttAsyncClient that is used to communicate with an MQTT server.
|
MqttAsyncClient(java.lang.String serverURI,
java.lang.String clientId,
MqttClientPersistence persistence) |
MqttAsyncClient(java.lang.String serverURI,
java.lang.String clientId,
MqttClientPersistence persistence,
MqttPingSender pingSender)
Create an MqttAsyncClient that is used to communicate with an MQTT server.
|
Modifier and Type | Method and Description |
---|---|
IMqttToken |
checkPing(java.lang.Object userContext,
IMqttActionListener callback) |
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.
|
void |
deleteBufferedMessage(int bufferIndex) |
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.
|
static java.lang.String |
generateClientId()
Returns a randomly generated client identifier based on the the fixed prefix (paho)
and the system time.
|
MqttMessage |
getBufferedMessage(int bufferIndex) |
int |
getBufferedMessageCount() |
java.lang.String |
getClientId()
Returns the client ID used by this client.
|
java.lang.String |
getCurrentServerURI()
Returns the currently connected Server URI
Implemented due to: https://bugs.eclipse.org/bugs/show_bug.cgi?id=481097
Where getServerURI only returns the URI that was provided in
MqttAsyncClient's constructor, getCurrentServerURI returns the URI of the
Server that the client is currently connected to.
|
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.
|
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.
|
void |
messageArrivedComplete(int messageId,
int qos)
Indicate that the application has completed processing the message with id messageId.
|
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 |
reconnect()
User triggered attempt to reconnect
|
void |
setBufferOpts(DisconnectedBufferOptions bufferOpts)
Sets the DisconnectedBufferOptions for this client
|
void |
setCallback(MqttCallback callback)
Sets a callback listener to use for events that happen asynchronously.
|
void |
setManualAcks(boolean manualAcks)
If manualAcks is set to true, then on completion of the messageArrived callback
the MQTT acknowledgements are not sent.
|
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,
IMqttMessageListener[] messageListeners)
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[] topicFilters,
int[] qos,
java.lang.Object userContext,
IMqttActionListener callback,
IMqttMessageListener[] messageListeners)
Subscribe 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,
IMqttMessageListener messageListener)
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 |
subscribe(java.lang.String topicFilter,
int qos,
java.lang.Object userContext,
IMqttActionListener callback,
IMqttMessageListener messageListener)
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.
|
public MqttAsyncClient(java.lang.String serverURI, java.lang.String clientId) throws MqttException
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:
tcp://localhost:1883
ssl://localhost:8883
tcp://
" URIs, and 8883 for ssl://
URIs.
A client identifier clientId
must be specified and be less that 65535 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:
SSLSocketFactory
- applications can
use MqttConnectOptions.setSocketFactory(SocketFactory)
to supply
a factory with the appropriate SSL settings.MqttConnectOptions.setSSLProperties(Properties)
.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.
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 tojava.lang.IllegalArgumentException
- if the URI does not start with
"tcp://", "ssl://" or "local://".java.lang.IllegalArgumentException
- if the clientId is null or is greater than 65535 characters in lengthMqttException
- if any other problem was encounteredpublic MqttAsyncClient(java.lang.String serverURI, java.lang.String clientId, MqttClientPersistence persistence) throws MqttException
MqttException
public MqttAsyncClient(java.lang.String serverURI, java.lang.String clientId, MqttClientPersistence persistence, MqttPingSender pingSender) throws MqttException
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:
tcp://localhost:1883
ssl://localhost:8883
tcp://
" URIs, and 8883 for ssl://
URIs.
A client identifier clientId
must be specified and be less that 65535 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:
SSLSocketFactory
- applications can
use MqttConnectOptions.setSocketFactory(SocketFactory)
to supply
a factory with the appropriate SSL settings.MqttConnectOptions.setSSLProperties(Properties)
.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
.
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 topersistence
- the persistence class to use to store in-flight message. If null then the
default persistence mechanism is usedjava.lang.IllegalArgumentException
- if the URI does not start with
"tcp://", "ssl://" or "local://"java.lang.IllegalArgumentException
- if the clientId is null or is greater than 65535 characters in lengthMqttException
- if any other problem was encounteredpublic IMqttToken connect(java.lang.Object userContext, IMqttActionListener callback) throws MqttException, MqttSecurityException
IMqttAsyncClient
The default options are specified in MqttConnectOptions
class.
connect
in interface IMqttAsyncClient
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 problemsIMqttAsyncClient.connect(MqttConnectOptions, Object, IMqttActionListener)
public IMqttToken connect() throws MqttException, MqttSecurityException
IMqttAsyncClient
The default options are specified in MqttConnectOptions
class.
connect
in interface IMqttAsyncClient
MqttSecurityException
- for security related problemsMqttException
- for non security related problemsIMqttAsyncClient.connect(MqttConnectOptions, Object, IMqttActionListener)
public IMqttToken connect(MqttConnectOptions options) throws MqttException, MqttSecurityException
IMqttAsyncClient
The connection will be established using the options specified in the
MqttConnectOptions
parameter.
connect
in interface IMqttAsyncClient
options
- a set of connection parameters that override the defaults.MqttSecurityException
- for security related problemsMqttException
- for non security related problemsIMqttAsyncClient.connect(MqttConnectOptions, Object, IMqttActionListener)
public IMqttToken connect(MqttConnectOptions options, java.lang.Object userContext, IMqttActionListener callback) throws MqttException, MqttSecurityException
IMqttAsyncClient
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:
IMqttToken.waitForCompletion()
orIMqttActionListener
connect
in interface IMqttAsyncClient
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 errorspublic IMqttToken disconnect(java.lang.Object userContext, IMqttActionListener callback) throws MqttException
IMqttAsyncClient
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.
disconnect
in interface IMqttAsyncClient
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 disconnectingIMqttAsyncClient.disconnect(long, Object, IMqttActionListener)
public IMqttToken disconnect() throws MqttException
IMqttAsyncClient
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.
disconnect
in interface IMqttAsyncClient
MqttException
- for problems encountered while disconnectingIMqttAsyncClient.disconnect(long, Object, IMqttActionListener)
public IMqttToken disconnect(long quiesceTimeout) throws MqttException
IMqttAsyncClient
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.
disconnect
in interface IMqttAsyncClient
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 disconnectingIMqttAsyncClient.disconnect(long, Object, IMqttActionListener)
public IMqttToken disconnect(long quiesceTimeout, java.lang.Object userContext, IMqttActionListener callback) throws MqttException
IMqttAsyncClient
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
disconnect
in interface IMqttAsyncClient
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 disconnectingpublic void disconnectForcibly() throws MqttException
IMqttAsyncClient
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.
disconnectForcibly
in interface IMqttAsyncClient
MqttException
- if any unexpected errorpublic void disconnectForcibly(long disconnectTimeout) throws MqttException
IMqttAsyncClient
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.
disconnectForcibly
in interface IMqttAsyncClient
disconnectTimeout
- the amount of time in milliseconds to allow send disconnect packet to server.MqttException
- if any unexpected errorpublic void disconnectForcibly(long quiesceTimeout, long disconnectTimeout) throws MqttException
IMqttAsyncClient
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.
disconnectForcibly
in interface IMqttAsyncClient
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 errorpublic boolean isConnected()
IMqttAsyncClient
isConnected
in interface IMqttAsyncClient
true
if connected, false
otherwise.public java.lang.String getClientId()
IMqttAsyncClient
All clients connected to the same server or server farm must have a unique ID.
getClientId
in interface IMqttAsyncClient
public java.lang.String getServerURI()
IMqttAsyncClient
The format of the returned String is the same as that used on the constructor.
getServerURI
in interface IMqttAsyncClient
MqttAsyncClient(String, String)
public java.lang.String getCurrentServerURI()
public IMqttToken checkPing(java.lang.Object userContext, IMqttActionListener callback) throws MqttException
MqttException
public IMqttToken subscribe(java.lang.String topicFilter, int qos, java.lang.Object userContext, IMqttActionListener callback) throws MqttException
IMqttAsyncClient
subscribe
in interface IMqttAsyncClient
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.IMqttAsyncClient.subscribe(String[], int[], Object, IMqttActionListener)
public IMqttToken subscribe(java.lang.String topicFilter, int qos) throws MqttException
IMqttAsyncClient
subscribe
in interface IMqttAsyncClient
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.IMqttAsyncClient.subscribe(String[], int[], Object, IMqttActionListener)
public IMqttToken subscribe(java.lang.String[] topicFilters, int[] qos) throws MqttException
IMqttAsyncClient
Provides an optimized way to subscribe to multiple topics compared to subscribing to each one individually.
subscribe
in interface IMqttAsyncClient
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.IMqttAsyncClient.subscribe(String[], int[], Object, IMqttActionListener)
public IMqttToken subscribe(java.lang.String[] topicFilters, int[] qos, java.lang.Object userContext, IMqttActionListener callback) throws MqttException
IMqttAsyncClient
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:
If (@link MqttConnectOptions#setCleanSession(boolean)} was set to false 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 methodsubscribe
in interface IMqttAsyncClient
topicFilters
- 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.public IMqttToken subscribe(java.lang.String topicFilter, int qos, java.lang.Object userContext, IMqttActionListener callback, IMqttMessageListener messageListener) throws MqttException
IMqttAsyncClient
subscribe
in interface IMqttAsyncClient
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 completedmessageListener
- a callback to handle incoming messagesMqttException
- if there was an error registering the subscription.IMqttAsyncClient.subscribe(String[], int[], Object, IMqttActionListener)
public IMqttToken subscribe(java.lang.String topicFilter, int qos, IMqttMessageListener messageListener) throws MqttException
IMqttAsyncClient
subscribe
in interface IMqttAsyncClient
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.messageListener
- a callback to handle incoming messagesMqttException
- if there was an error registering the subscription.IMqttAsyncClient.subscribe(String[], int[], Object, IMqttActionListener)
public IMqttToken subscribe(java.lang.String[] topicFilters, int[] qos, IMqttMessageListener[] messageListeners) throws MqttException
IMqttAsyncClient
Provides an optimized way to subscribe to multiple topics compared to subscribing to each one individually.
subscribe
in interface IMqttAsyncClient
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.messageListeners
- one or more callbacks to handle incoming messagesMqttException
- if there was an error registering the subscription.IMqttAsyncClient.subscribe(String[], int[], Object, IMqttActionListener)
public IMqttToken subscribe(java.lang.String[] topicFilters, int[] qos, java.lang.Object userContext, IMqttActionListener callback, IMqttMessageListener[] messageListeners) throws MqttException
IMqttAsyncClient
Provides an optimized way to subscribe to multiple topics compared to subscribing to each one individually.
subscribe
in interface IMqttAsyncClient
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.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 completedmessageListeners
- one or more callbacks to handle incoming messagesMqttException
- if there was an error registering the subscription.IMqttAsyncClient.subscribe(String[], int[], Object, IMqttActionListener)
public IMqttToken unsubscribe(java.lang.String topicFilter, java.lang.Object userContext, IMqttActionListener callback) throws MqttException
IMqttAsyncClient
unsubscribe
in interface IMqttAsyncClient
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.IMqttAsyncClient.unsubscribe(String[], Object, IMqttActionListener)
public IMqttToken unsubscribe(java.lang.String topicFilter) throws MqttException
IMqttAsyncClient
unsubscribe
in interface IMqttAsyncClient
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.IMqttAsyncClient.unsubscribe(String[], Object, IMqttActionListener)
public IMqttToken unsubscribe(java.lang.String[] topicFilters) throws MqttException
IMqttAsyncClient
unsubscribe
in interface IMqttAsyncClient
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.IMqttAsyncClient.unsubscribe(String[], Object, IMqttActionListener)
public IMqttToken unsubscribe(java.lang.String[] topicFilters, java.lang.Object userContext, IMqttActionListener callback) throws MqttException
IMqttAsyncClient
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 methodunsubscribe
in interface IMqttAsyncClient
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 completedMqttException
- if there was an error unregistering the subscription.public void setCallback(MqttCallback callback)
IMqttAsyncClient
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.
setCallback
in interface IMqttAsyncClient
callback
- which will be invoked for certain asynchronous eventsMqttCallback
public void setManualAcks(boolean manualAcks)
IMqttAsyncClient
setManualAcks
in interface IMqttAsyncClient
public void messageArrivedComplete(int messageId, int qos) throws MqttException
IMqttAsyncClient
messageArrivedComplete
in interface IMqttAsyncClient
messageId
- the MQTT message id to be acknowledgedqos
- the MQTT QoS of the message to be acknowledgedMqttException
public static java.lang.String generateClientId()
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.
MqttConnectOptions.setCleanSession(boolean)
public IMqttDeliveryToken[] getPendingDeliveryTokens()
IMqttAsyncClient
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
getPendingDeliveryTokens
in interface IMqttAsyncClient
public IMqttDeliveryToken publish(java.lang.String topic, byte[] payload, int qos, boolean retained, java.lang.Object userContext, IMqttActionListener callback) throws MqttException, MqttPersistenceException
IMqttAsyncClient
A convenience method, which will
create a new MqttMessage
object with a byte array payload and the
specified QoS, and then publish it.
publish
in interface IMqttAsyncClient
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 messageMqttException
- for other errors encountered while publishing the message.
For instance client not connected.IMqttAsyncClient.publish(String, MqttMessage, Object, IMqttActionListener)
,
MqttMessage.setQos(int)
,
MqttMessage.setRetained(boolean)
public IMqttDeliveryToken publish(java.lang.String topic, byte[] payload, int qos, boolean retained) throws MqttException, MqttPersistenceException
IMqttAsyncClient
A convenience method, which will
create a new MqttMessage
object with a byte array payload and the
specified QoS, and then publish it.
publish
in interface IMqttAsyncClient
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 messageMqttException
- for other errors encountered while publishing the message.
For instance if too many messages are being processed.IMqttAsyncClient.publish(String, MqttMessage, Object, IMqttActionListener)
,
MqttMessage.setQos(int)
,
MqttMessage.setRetained(boolean)
public IMqttDeliveryToken publish(java.lang.String topic, MqttMessage message) throws MqttException, MqttPersistenceException
IMqttAsyncClient
MqttMessage
message and delivers it to the server at the
requested quality of service.publish
in interface IMqttAsyncClient
topic
- to deliver the message to, for example "finance/stock/ibm".message
- to deliver to the serverMqttPersistenceException
- when a problem occurs storing the messageMqttException
- for other errors encountered while publishing the message.
For instance client not connected.IMqttAsyncClient.publish(String, MqttMessage, Object, IMqttActionListener)
public IMqttDeliveryToken publish(java.lang.String topic, MqttMessage message, java.lang.Object userContext, IMqttActionListener callback) throws MqttException, MqttPersistenceException
IMqttAsyncClient
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:
IMqttAsyncClient.setCallback(MqttCallback)
where the
MqttCallback.deliveryComplete(IMqttDeliveryToken)
method will be called.MqttToken.waitForCompletion()
orIMqttActionListener
to this methodpublish
in interface IMqttAsyncClient
topic
- 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 messageMqttException
- for other errors encountered while publishing the message.
For instance client not connected.MqttMessage
public void reconnect() throws MqttException
MqttException
public void setBufferOpts(DisconnectedBufferOptions bufferOpts)
bufferOpts
- public int getBufferedMessageCount()
public MqttMessage getBufferedMessage(int bufferIndex)
public void deleteBufferedMessage(int bufferIndex)
public void close() throws MqttException
IMqttAsyncClient
close
in interface IMqttAsyncClient
MqttException
- if the client is not disconnected.public Debug getDebug()