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, ReconnectionStrategy reconnectionStrategy, Executor executor, int connectTimeoutSeconds, int messageResendIntervalSeconds)
Constructs an instance of this class using a user provided Executor.

AsyncMqttClient(String brokerUri, AsyncClientListener listener, ReconnectionStrategy reconnectionStrategy, int messageHandlerThreadPoolSize, int connectTimeoutSeconds, int messageResendIntervalSeconds)
Constructs an instance of this class using an Executor owned by this class.

Method Summary

void	close() Closes this client without doing a clean disconnect.
ConnectReturnCode	connect(String clientId, boolean cleanSession, int keepAliveSeconds) Connects this client to the broker with no credentials and no Will Message.
ConnectReturnCode	connect(String clientId, boolean cleanSession, int keepAliveSeconds, String userName, String password) Connects this client to the broker with credentials but no Will Message.
ConnectReturnCode	connect(String clientId, boolean cleanSession, int keepAliveSeconds, 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, int keepAliveSeconds, 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.
void	publish(PublishMessage message) Publishes a message.
void	shutdown() Stops this client.
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,
                       ReconnectionStrategy reconnectionStrategy,
                       int messageHandlerThreadPoolSize,
                       int connectTimeoutSeconds,
                       int messageResendIntervalSeconds)

Constructs an instance of this class using an Executor owned by this class.

Parameters:

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

listener - Handles events from this client

reconnectionStrategy - The algorithm used to reconnect to the broker if the connection is lost

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

connectTimeoutSeconds - Seconds to wait for an ack to a connect message before timing out and closing the channel. 0 to wait forever.

messageResendIntervalSeconds - Seconds between attempts to resend a message that is MqttMessage.isAckable(). The minimum allowable value for this setting is 2

AsyncMqttClient

public AsyncMqttClient(String brokerUri,
                       AsyncClientListener listener,
                       ReconnectionStrategy reconnectionStrategy,
                       Executor executor,
                       int connectTimeoutSeconds,
                       int messageResendIntervalSeconds)

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

Parameters:

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

listener - Handles events from this client

reconnectionStrategy - The algorithm used to reconnect to the broker if the connection is lost

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

connectTimeoutSeconds - Seconds to wait for an ack to a connect message before timing out and closing the channel. 0 to wait forever.

messageResendIntervalSeconds - Seconds between attempts to resend a message that is MqttMessage.isAckable(). The minimum allowable value for this setting is 2

Method Detail

connect

public final ConnectReturnCode connect(String clientId,
                                       boolean cleanSession,
                                       int keepAliveSeconds,
                                       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.

keepAliveSeconds - The Keep Alive timer, measured in seconds, defines the maximum time interval between messages received from a client. It enables the broker to detect that the network connection to a client has dropped, without having to wait for the long TCP/IP timeout. In the absence of a data-related message during the time period, this client sends a PINGREQ message, which the broker acknowledges with a PINGRESP message.

If the broker does not receive a message from the client within one and a half times the Keep Alive time period (the client is allowed "grace" of half a time period), it disconnects the client. This action does not impact any of the client's subscriptions.

If this client does not receive a PINGRESP message within a Keep Alive time period after sending a PINGREQ, it closes the TCP/IP socket connection.

The Keep Alive timer is a 16-bit value that represents the number of seconds for the time period. The actual value is application-specific, but a typical value is a few minutes. The maximum value is approximately 18 hours. A value of zero (0) means the client is not disconnected.

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 SynchronousMqttClient 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 SynchronousMqttClient implementation is used and the internal common used to implement this feature is cancelled typically because of some exception.

MqttTimeoutException - Thrown when the SynchronousMqttClient implementation is used and this method has blocked for approximately the configured timeout.

MqttInterruptedException - Thrown when the SynchronousMqttClient implementation is used and the calling thread is interrupted.

See Also:

MqttClient.connect(java.lang.String, boolean, int, 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,
                                       int keepAliveSeconds)
                                throws MqttCommandCancelledException,
                                       MqttTimeoutException,
                                       MqttInterruptedException

Description copied from interface: MqttClient

Connects this client to the broker with no credentials and no Will Message. Delegates to MqttClient.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, int)

connect

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

Description copied from interface: MqttClient

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

Specified by:

connect in interface MqttClient

Throws:

MqttCommandCancelledException

MqttTimeoutException

InterruptedException

See Also:

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

connect

public final ConnectReturnCode connect(String clientId,
                                       boolean cleanSession,
                                       int keepAliveSeconds,
                                       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 MqttClient.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, int, 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 SynchronousMqttClient implementation is used and the internal common used to implement this feature is cancelled typically because of some exception.

MqttTimeoutException - Thrown when the SynchronousMqttClient implementation is used and this method has blocked for approximately the configured timeout.

MqttInterruptedException - Thrown when the SynchronousMqttClient implementation is used and 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 SynchronousMqttClient is used. Null if the AsyncMqttClient implementation is used.

Throws:

MqttCommandCancelledException - Thrown when the SynchronousMqttClient implementation is used and the internal common used to implement this feature is cancelled typically because of some exception.

MqttTimeoutException - Thrown when the SynchronousMqttClient implementation is used and this method has blocked for approximately the configured timeout.

MqttInterruptedException - Thrown when the SynchronousMqttClient implementation is used and 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 SynchronousMqttClient implementation is used and the internal common used to implement this feature is cancelled typically because of some exception.

MqttTimeoutException - Thrown when the SynchronousMqttClient implementation is used and this method has blocked for approximately the configured timeout.

MqttInterruptedException - Thrown when the SynchronousMqttClient implementation is used and 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 SynchronousMqttClient implementation is used and the internal common used to implement this feature is cancelled typically because of some exception.

MqttTimeoutException - Thrown when the SynchronousMqttClient implementation is used and this method has blocked for approximately the configured timeout.

MqttInterruptedException - Thrown when the SynchronousMqttClient implementation is used and the calling thread is interrupted.

See Also:

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

close

public final void close()
                 throws MqttCommandCancelledException,
                        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:

MqttCommandCancelledException - Thrown when the SynchronousMqttClient implementation is used and the internal common used to implement this feature is cancelled typically because of some exception.

MqttTimeoutException - Thrown when the SynchronousMqttClient implementation is used and this method has blocked for approximately the configured timeout.

MqttInterruptedException - Thrown when the SynchronousMqttClient implementation is used and the calling thread is interrupted.

See Also:

MqttClient.close()

shutdown

public final void shutdown()
                    throws MqttInterruptedException

Stops this client. Closes the connection to the broker if it is open. Blocks until shutdown is complete. Any other methods called after this have unpredictable results.

Throws:

MqttInterruptedException - If the thread is interrupted