net.sf.xenqtt.client
Interface MqttClient

All Known Implementing Classes:

AsyncMqttClient, SyncMqttClient

public interface MqttClient

A client to an MQTT broker. This interface is implemented by both synchronous and asynchronous clients.

To use the synchronous client create a SyncMqttClient and MqttClientListener. The synchronous client blocks until it receives an acknowledgment from the broker for each operation that requires such an acknowledgment. Each method's javadoc details what has to happen before the calling thread is allowed to return. If the timeout configured in the SyncMqttClient expires an MqttTimeoutException is thrown and any messages it is trying to send will be cancelled. To abort any of the blocking client calls interrupt the calling thread which will cause an MqttInterruptedException to be thrown.

To use the asynchronous client create an AsyncMqttClient and AsyncClientListener. None of the methods in the asynchronous client block. Asynchronous client methods will never throw an MqttTimeoutException or MqttInterruptedException and those that have a return type other than void will return null. You implement AsyncClientListener to be informed of the results of an asynchronous client method.

Received publish messages are handled the same way by both the synchronous and asynchronous clients. When a publish message is received publish is invoked with the client that received the message and the message that was received. If the message's QoS level is anything other than AT_MOST_ONCE you must call ack() when you are finished processing the message. It is recommended that you always call ack() regardless of the message's QoS. If you do not call ack or you wait too long to call ack the message will be resent by the broker and publish will be called with the resent message. isDuplicate() will be true for messages that are resent by the broker.

If the connection is lost it will be restored using the ReconnectionStrategy, if any, provided to the client.

This class is thread safe.

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.

Method Detail

isClosed

boolean isClosed()

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.

connect

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

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.

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.

MqttInvocationException - Thrown when the internal command used to implement this feature throws an Exception.

MqttInvocationError - Thrown when the internal command used to implement this feature throws an Error.

connect

ConnectReturnCode connect(String clientId,
                          boolean cleanSession)
                          throws MqttCommandCancelledException,
                                 MqttTimeoutException,
                                 MqttInterruptedException,
                                 MqttInvocationException,
                                 MqttInvocationError

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).

Throws:

MqttCommandCancelledException

MqttTimeoutException

MqttInterruptedException

MqttInvocationException

MqttInvocationError

See Also:

net.sf.xenqtt.client.MqttClient#connect(String, boolean, int, String, String, String, String, QoS, boolean)

connect

ConnectReturnCode connect(String clientId,
                          boolean cleanSession,
                          String userName,
                          String password)
                          throws MqttCommandCancelledException,
                                 MqttTimeoutException,
                                 MqttInterruptedException,
                                 MqttInvocationException,
                                 MqttInvocationError

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

Throws:

MqttCommandCancelledException

MqttTimeoutException

MqttInterruptedException

MqttInvocationException

MqttInvocationError

See Also:

net.sf.xenqtt.client.MqttClient#connect(String, boolean, int, String, String, String, String, QoS, boolean)

connect

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

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).

Throws:

MqttTimeoutException

MqttInterruptedException

MqttInvocationException

MqttInvocationError

See Also:

net.sf.xenqtt.client.MqttClient#connect(String, boolean, int, String, String, String, String, QoS, boolean)

disconnect

void disconnect()
                throws MqttCommandCancelledException,
                       MqttTimeoutException,
                       MqttInterruptedException,
                       MqttInvocationException,
                       MqttInvocationError

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.

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.

MqttInvocationException - Thrown when the internal command used to implement this feature throws an Exception.

MqttInvocationError - Thrown when the internal command used to implement this feature throws an Error.

subscribe

Subscription[] subscribe(Subscription[] subscriptions)
                         throws MqttQosNotGrantedException,
                                MqttCommandCancelledException,
                                MqttTimeoutException,
                                MqttInterruptedException,
                                MqttInvocationException,
                                MqttInvocationError

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.

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:

MqttQosNotGrantedException - Thrown when the QoS granted for any topic does not match the QoS requested.

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.

MqttInvocationException - Thrown when the internal command used to implement this feature throws an Exception.

MqttInvocationError - Thrown when the internal command used to implement this feature throws an Error.

subscribe

List<Subscription> subscribe(List<Subscription> subscriptions)
                             throws MqttQosNotGrantedException,
                                    MqttCommandCancelledException,
                                    MqttTimeoutException,
                                    MqttInterruptedException,
                                    MqttInvocationException,
                                    MqttInvocationError

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

Throws:

MqttQosNotGrantedException

MqttCommandCancelledException

MqttTimeoutException

MqttInterruptedException

MqttInvocationException

MqttInvocationError

See Also:

subscribe(Subscription[])

unsubscribe

void unsubscribe(String[] topics)
                 throws MqttCommandCancelledException,
                        MqttTimeoutException,
                        MqttInterruptedException,
                        MqttInvocationException,
                        MqttInvocationError

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.

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.

MqttInvocationException - Thrown when the internal command used to implement this feature throws an Exception.

MqttInvocationError - Thrown when the internal command used to implement this feature throws an Error.

unsubscribe

void unsubscribe(List<String> topics)
                 throws MqttCommandCancelledException,
                        MqttTimeoutException,
                        MqttInterruptedException,
                        MqttInvocationException,
                        MqttInvocationError

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

Throws:

MqttCommandCancelledException

MqttTimeoutException

MqttInterruptedException

MqttInvocationException

MqttInvocationError

publish

void publish(PublishMessage message)
             throws MqttCommandCancelledException,
                    MqttTimeoutException,
                    MqttInterruptedException,
                    MqttInvocationException,
                    MqttInvocationError

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.

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.

MqttInvocationException - Thrown when the internal command used to implement this feature throws an Exception.

MqttInvocationError - Thrown when the internal command used to implement this feature throws an Error.

close

void close()
           throws MqttTimeoutException,
                  MqttInterruptedException,
                  MqttInvocationException,
                  MqttInvocationError

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.

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.

MqttInvocationException - Thrown when the internal command used to implement this feature throws an Exception.

MqttInvocationError - Thrown when the internal command used to implement this feature throws an Error.

getStats

MessageStats getStats(boolean reset)

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.