net.sf.xenqtt.client
Class AsyncMqttClient

java.lang.Object
  net.sf.xenqtt.client.AsyncMqttClient

All Implemented Interfaces:

MqttClient

public final class AsyncMqttClient
extends Object

An MqttClient that handles interactions with the MQTT broker in an asynchronous fashion.

Constructor Summary

AsyncMqttClient(String brokerUri, AsyncClientListener listener, Executor executor)
Constructs an instance of this class using a user provided Executor with the default config.

AsyncMqttClient(String brokerUri, AsyncClientListener listener, Executor executor, MqttClientConfig config)
Constructs an instance of this class using a user provided Executor with a custom config.

AsyncMqttClient(String brokerUri, AsyncClientListener listener, int messageHandlerThreadPoolSize)
Constructs an instance of this class using an Executor owned by this class with the default config.

AsyncMqttClient(String brokerUri, AsyncClientListener listener, int messageHandlerThreadPoolSize, MqttClientConfig config)
Constructs an instance of this class using an Executor owned by this class with a custom config.

Method Summary

void	close() Closes this client without doing a clean disconnect.
ConnectReturnCode	connect(String clientId, boolean cleanSession) Connects this client to the broker with no credentials and no Will Message.
ConnectReturnCode	connect(String clientId, boolean cleanSession, String userName, String password) Connects this client to the broker with credentials but no Will Message.
ConnectReturnCode	connect(String clientId, boolean cleanSession, String willTopic, String willMessage, QoS willQos, boolean willRetain) Connects this client to the broker with a Will Message but no credentials.
ConnectReturnCode	connect(String clientId, boolean cleanSession, String userName, String password, String willTopic, String willMessage, QoS willQos, boolean willRetain) Connects this client to the broker with credentials and a WillMessage.
void	disconnect() Disconnects this client from the broker.
MessageStats	getStats(boolean reset)
boolean	isClosed()
void	publish(PublishMessage message) Publishes a message.
List<Subscription>	subscribe(List<Subscription> subscriptions) Subscribes to topics.
Subscription[]	subscribe(Subscription[] subscriptions) Subscribes to topics.
void	unsubscribe(List<String> topics) Unsubscribes from topics.
void	unsubscribe(String[] topics) Unsubscribes from topics.

Methods inherited from class java.lang.Object

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

Constructor Detail

AsyncMqttClient

public AsyncMqttClient(String brokerUri,
                       AsyncClientListener listener,
                       int messageHandlerThreadPoolSize)

Constructs an instance of this class using an Executor owned by this class with the default config.

Parameters:

brokerUri - The URL to the broker to connect to. For example, tcp://q.m2m.io:1883

listener - Handles events from this client. Use AsyncClientListener.NULL_LISTENER if you don't want to receive messages or be notified of events.

messageHandlerThreadPoolSize - The number of threads used to handle incoming messages and invoke the listener's methods

AsyncMqttClient

public AsyncMqttClient(String brokerUri,
                       AsyncClientListener listener,
                       int messageHandlerThreadPoolSize,
                       MqttClientConfig config)

Constructs an instance of this class using an Executor owned by this class with a custom config.

Parameters:

brokerUri - The URL to the broker to connect to. For example, tcp://q.m2m.io:1883

listener - Handles events from this client. Use AsyncClientListener.NULL_LISTENER if you don't want to receive messages or be notified of events.

messageHandlerThreadPoolSize - The number of threads used to handle incoming messages and invoke the listener's methods

config - The configuration for the client

AsyncMqttClient

public AsyncMqttClient(String brokerUri,
                       AsyncClientListener listener,
                       Executor executor)

Constructs an instance of this class using a user provided Executor with the default config.

Parameters:

brokerUri - The URL to the broker to connect to. For example, tcp://q.m2m.io:1883

listener - Handles events from this client. Use AsyncClientListener.NULL_LISTENER if you don't want to receive messages or be notified of events.

executor - The executor used to handle incoming messages and invoke the listener's methods. This class will NOT shut down the executor.

AsyncMqttClient

public AsyncMqttClient(String brokerUri,
                       AsyncClientListener listener,
                       Executor executor,
                       MqttClientConfig config)

Constructs an instance of this class using a user provided Executor with a custom config.

Parameters:

brokerUri - The URL to the broker to connect to. For example, tcp://q.m2m.io:1883

listener - Handles events from this client. Use AsyncClientListener.NULL_LISTENER if you don't want to receive messages or be notified of events.

executor - The executor used to handle incoming messages and invoke the listener's methods. This class will NOT shut down the executor.

config - The configuration for the client

Method Detail

connect

public final ConnectReturnCode connect(String clientId,
                                       boolean cleanSession,
                                       String userName,
                                       String password,
                                       String willTopic,
                                       String willMessage,
                                       QoS willQos,
                                       boolean willRetain)
                                throws MqttCommandCancelledException,
                                       MqttTimeoutException,
                                       MqttInterruptedException

Description copied from interface: MqttClient

Connects this client to the broker with credentials and a WillMessage. This includes these actions:

1. Complete the TCP connection to the broker if it hasn't completed already
2. Send a connect message to the broker
3. Receive a connect acknowledgment from the broker

If the synchronous client is used this method blocks until these actions are completed. If the asynchronous client is used the connected method is called after these actions are completed.

Specified by:

connect in interface MqttClient

Parameters:

clientId - The Client Identifier (Client ID) is between 1 and 23 characters long, and uniquely identifies the client to the broker. It must be unique across all clients connecting to a single broker. If the Client ID contains more than 23 characters, the broker responds with ConnectReturnCode.IDENTIFIER_REJECTED.

cleanSession - If not set, then the broker must store the subscriptions of the client after it disconnects. This includes continuing to store QoS 1 and QoS 2 messages for the subscribed topics so that they can be delivered when the client reconnects. The broker must also maintain the state of in-flight messages being delivered at the point the connection is lost. This information must be kept until the client reconnects.

If set, then the broker must discard any previously maintained information about the client and treat the connection as "clean". The broker must also discard any state when the client disconnects.

Typically, a client will operate in one mode or the other and not change. The choice will depend on the application. A clean session client will not receive stale information and it must re-subscribe each time it connects. A non-clean session client will not miss any QoS 1 or QoS 2 messages that were published whilst it was disconnected. QoS 0 messages are never stored, since they are delivered on a best efforts basis.

userName - The user name identifies the name of the user who is connecting, which can be used for authentication. It is recommended that user names are kept to 12 characters or fewer, but it is not required.

Null if there is no user name.

password - The password corresponding to the user who is connecting, which can be used for authentication. It is recommended that passwords are kept to 12 characters or fewer, but it is not required.

Null if there is no password. If there is no username there can be no password.

willTopic - The Will Message is published to the Will Topic. If there is not a Will Message then this is not applicable.

Null if there is no Will Message.

willMessage - The Will Message defines the content of the message that is published to the Will Topic if the client is unexpectedly disconnected. This may be a zero-length message.

Although the Will Message is UTF-8 encoded in the CONNECT message, when it is published to the Will Topic only the bytes of the message are sent, not the first two length bytes. The message must therefore only consist of 7-bit ASCII characters.

Null if there is no Will Message. Zero length string if there is an empty Will Message.

willQos - The QoS of the #willMessage. If there is not a Will Message then this is not applicable.

willRetain - The retain value of the Will message. False if either retain is false or there is no Will Message.

Returns:

The return code from the broker if the SyncMqttClient is used. Anything other than ConnectReturnCode.ACCEPTED (or null) will result in the client being immediately disconnected. Null if the AsyncMqttClient implementation is used.

Throws:

MqttCommandCancelledException - Thrown when the internal command used to implement this feature is cancelled.

MqttTimeoutException - Thrown when this method has blocked for approximately the configured timeout. Only applicable when the synchronous implementation is used.

MqttInterruptedException - Thrown when the calling thread is interrupted.

See Also:

MqttClient.connect(java.lang.String, boolean, java.lang.String, java.lang.String, java.lang.String, java.lang.String, net.sf.xenqtt.message.QoS, boolean)

connect

public final ConnectReturnCode connect(String clientId,
                                       boolean cleanSession)
                                throws MqttCommandCancelledException,
                                       MqttTimeoutException,
                                       MqttInterruptedException

Description copied from interface: MqttClient

Connects this client to the broker with no credentials and no Will Message. Delegates to #connect(String, boolean, int, String, String, String, String, QoS, boolean).

Specified by:

connect in interface MqttClient

Throws:

MqttCommandCancelledException

MqttTimeoutException

MqttInterruptedException

See Also:

MqttClient.connect(java.lang.String, boolean)

connect

public final ConnectReturnCode connect(String clientId,
                                       boolean cleanSession,
                                       String userName,
                                       String password)
                                throws MqttCommandCancelledException,
                                       MqttTimeoutException,
                                       MqttInterruptedException

Description copied from interface: MqttClient

Connects this client to the broker with credentials but no Will Message. Delegates to #connect(String, boolean, int, String, String, String, String, QoS, boolean).

Specified by:

connect in interface MqttClient

Throws:

MqttCommandCancelledException

MqttTimeoutException

MqttInterruptedException

See Also:

MqttClient.connect(java.lang.String, boolean, java.lang.String, java.lang.String)

connect

public final ConnectReturnCode connect(String clientId,
                                       boolean cleanSession,
                                       String willTopic,
                                       String willMessage,
                                       QoS willQos,
                                       boolean willRetain)
                                throws MqttTimeoutException,
                                       MqttInterruptedException

Description copied from interface: MqttClient

Connects this client to the broker with a Will Message but no credentials. Delegates to #connect(String, boolean, int, String, String, String, String, QoS, boolean).

Specified by:

connect in interface MqttClient

Throws:

MqttTimeoutException

MqttInterruptedException

See Also:

MqttClient.connect(java.lang.String, boolean, java.lang.String, java.lang.String, net.sf.xenqtt.message.QoS, boolean)

disconnect

public final void disconnect()
                      throws MqttCommandCancelledException,
                             MqttTimeoutException,
                             MqttInterruptedException

Description copied from interface: MqttClient

Disconnects this client from the broker. This includes these actions:

1. Send a disconnect message to the broker
2. Close the TCP connection to the broker

If the synchronous client is used this method blocks until these actions are completed. If the asynchronous client is used the disconnected method is called after these actions are completed.

Specified by:

disconnect in interface MqttClient

Throws:

MqttCommandCancelledException - Thrown when the internal command used to implement this feature is cancelled.

MqttTimeoutException - Thrown when this method has blocked for approximately the configured timeout. Only applicable when the synchronous implementation is used.

MqttInterruptedException - Thrown when the calling thread is interrupted.

See Also:

MqttClient.disconnect()

subscribe

public final Subscription[] subscribe(Subscription[] subscriptions)
                               throws MqttCommandCancelledException,
                                      MqttTimeoutException,
                                      MqttInterruptedException

Description copied from interface: MqttClient

Subscribes to topics. This includes these actions:

1. Send a subscribe message to the broker
2. Receive a subscribe acknowledgment from the broker

If the synchronous client is used this method blocks until these actions are completed. If the asynchronous client is used the subscribed method is called after these actions are completed.

Specified by:

subscribe in interface MqttClient

Parameters:

subscriptions - The topics to subscribe to and the requested QoS for each. The topics can include wildcards:

• '+': Matches a single level in the topic. foo/+ would match foo/bar but not foo/a/b or foo/a/b/c. foo/+/+/c would match foo/a/b/c and foo/d/g/c but not foo/a/c
• '#': Matches the rest of the topic. Must be the last character in the topic. foo/# would match foo/bar, foo/a/b/c, etc

Returns:

The topics subscribed to and the QoS granted for each if the SyncMqttClient is used. Null if the AsyncMqttClient implementation is used.

Throws:

MqttCommandCancelledException - Thrown when the internal command used to implement this feature is cancelled.

MqttTimeoutException - Thrown when this method has blocked for approximately the configured timeout. Only applicable when the synchronous implementation is used.

MqttInterruptedException - Thrown when the calling thread is interrupted.

See Also:

MqttClient.subscribe(net.sf.xenqtt.client.Subscription[])

subscribe

public final List<Subscription> subscribe(List<Subscription> subscriptions)
                                   throws MqttCommandCancelledException,
                                          MqttTimeoutException,
                                          MqttInterruptedException

Description copied from interface: MqttClient

Subscribes to topics. This is the same as MqttClient.subscribe(Subscription[]) except it uses lists instead of arrays.

Specified by:

subscribe in interface MqttClient

Throws:

MqttCommandCancelledException

MqttTimeoutException

MqttInterruptedException

See Also:

MqttClient.subscribe(java.util.List)

unsubscribe

public final void unsubscribe(String[] topics)
                       throws MqttCommandCancelledException,
                              MqttTimeoutException,
                              MqttInterruptedException

Description copied from interface: MqttClient

Unsubscribes from topics. This includes these actions:

1. Send an unsubscribe message to the broker
2. Receive the broker's unsubscribe acknowledgment

If the synchronous client is used this method blocks until these actions are completed. If the asynchronous client is used the unsubscribed method is called after these actions are completed.

Specified by:

unsubscribe in interface MqttClient

Parameters:

topics - The topics to unsubscribe from. This can include wildcards:

• '+': Matches a single level in the topic. foo/+ would match foo/bar but not foo/a/b or foo/a/b/c. foo/+/+/c would match foo/a/b/c and foo/d/g/c but not foo/a/c
• '#': Matches the rest of the topic. Must be the last character in the topic. foo/# would match foo/bar, foo/a/b/c, etc

Throws:

MqttCommandCancelledException - Thrown when the internal command used to implement this feature is cancelled.

MqttTimeoutException - Thrown when this method has blocked for approximately the configured timeout. Only applicable when the synchronous implementation is used.

MqttInterruptedException - Thrown when the calling thread is interrupted.

See Also:

MqttClient.unsubscribe(java.lang.String[])

unsubscribe

public final void unsubscribe(List<String> topics)
                       throws MqttCommandCancelledException,
                              MqttTimeoutException,
                              MqttInterruptedException

Description copied from interface: MqttClient

Unsubscribes from topics. This is the same as MqttClient.unsubscribe(String[]) except it uses lists instead of arrays.

Specified by:

unsubscribe in interface MqttClient

Throws:

MqttCommandCancelledException

MqttTimeoutException

MqttInterruptedException

See Also:

MqttClient.unsubscribe(java.util.List)

publish

public final void publish(PublishMessage message)
                   throws MqttCommandCancelledException,
                          MqttTimeoutException,
                          MqttInterruptedException

Description copied from interface: MqttClient

Publishes a message. This includes these actions:

1. Send a publish message to the broker
2. If the QoS is not QoS.AT_MOST_ONCE then wait for the broker's acknowledgment

If the synchronous client is used this method blocks until these actions are completed. If the asynchronous client is used the published method is called after these actions are completed.

Specified by:

publish in interface MqttClient

Parameters:

message - The message to publish to the broker

Throws:

MqttCommandCancelledException - Thrown when the internal command used to implement this feature is cancelled.

MqttTimeoutException - Thrown when this method has blocked for approximately the configured timeout. Only applicable when the synchronous implementation is used.

MqttInterruptedException - Thrown when the calling thread is interrupted.

See Also:

MqttClient.publish(net.sf.xenqtt.client.PublishMessage)

close

public final void close()
                 throws MqttTimeoutException,
                        MqttInterruptedException

Description copied from interface: MqttClient

Closes this client without doing a clean disconnect. This includes these actions:

1. Close the TCP connection to the broker

If the synchronous client is used this method blocks until these actions are completed. If the asynchronous client is used the disconnected method is called after these actions are completed.

Specified by:

close in interface MqttClient

Throws:

MqttTimeoutException - Thrown when this method has blocked for approximately the configured timeout. Only applicable when the synchronous implementation is used.

MqttInterruptedException - Thrown when the calling thread is interrupted.

See Also:

MqttClient.close()

isClosed

public final boolean isClosed()

Specified by:

isClosed in interface MqttClient

Returns:

True if this client has been closed. Disconnected will have been called and all internal thread pools will be shut down or will be in the process of shutting down.

See Also:

MqttClient.isClosed()

getStats

public MessageStats getStats(boolean reset)

Specified by:

getStats in interface MqttClient

Parameters:

reset - If true the stats will be reset to 0 (where applicable) so the next time they are retrieved they will be for the time between the 2 calls to this method.

Returns:

A snapshot of the statistics for this client. If this client was created using an MqttClientFactory these stats will be for all the clients created using the same factory as this client.

See Also:

MqttClient.getStats(boolean)