net.sf.xenqtt.client
Interface MqttClient

All Known Implementing Classes:

AsyncMqttClient, SynchronousMqttClient

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 SynchronousMqttClient 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 SynchronousMqttClient 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, 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.
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

connect

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

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.

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.

connect

ConnectReturnCode connect(String clientId,
                          boolean cleanSession,
                          int keepAliveSeconds)
                          throws MqttCommandCancelledException,
                                 MqttTimeoutException,
                                 MqttInterruptedException

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

See Also:

connect(String, boolean, int, String, String, String, String, QoS, boolean)

connect

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

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

InterruptedException

See Also:

connect(String, boolean, int, String, String, String, String, QoS, boolean)

connect

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

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

See Also:

connect(String, boolean, int, String, String, String, String, QoS, boolean)

disconnect

void disconnect()
                throws MqttCommandCancelledException,
                       MqttTimeoutException,
                       MqttInterruptedException

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

subscribe

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

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

subscribe

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

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

Throws:

MqttQosNotGrantedException

MqttCommandCancelledException

MqttTimeoutException

MqttInterruptedException

See Also:

subscribe(Subscription[])

unsubscribe

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

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

unsubscribe

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

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

Throws:

MqttCommandCancelledException

MqttTimeoutException

MqttInterruptedException

publish

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

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

close

void close()
           throws MqttCommandCancelledException,
                  MqttTimeoutException,
                  MqttInterruptedException

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:

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.