org.eclipse.paho.client.mqttv3
Class MqttClient

java.lang.Object
  org.eclipse.paho.client.mqttv3.MqttClient

All Implemented Interfaces:

org.eclipse.paho.client.mqttv3.internal.DestinationProvider

public class MqttClient

extends java.lang.Object

implements org.eclipse.paho.client.mqttv3.internal.DestinationProvider

Lightweight client for talking to a server via the MQTT version 3 protocol. The client allows an application to use publish/subscribe messaging.

Constructor Summary

MqttClient(java.lang.String serverURI, java.lang.String clientId)
Creates an MqttClient to connect to the specified address, using the specified client identifier.

MqttClient(java.lang.String serverURI, java.lang.String clientId, MqttClientPersistence persistence)
Creates an MqttClient to connect to the specified address, using the specified client identifer and persistence implementation.

Method Summary

void	connect() Connects to a server using the default options.
void	connect(MqttConnectOptions options) Connects to a server using the specified options.
void	disconnect() Disconnects from the server, which quiesces for up to a maximum of thirty seconds, to allow the client to finish any work it currently has.
void	disconnect(long quiesceTimeout) Disconnects from the server.
static java.lang.String	generateClientId() Returns a randomly generated client identifier based on the current user's login name and the system time.
java.lang.String	getClientId() Returns the client ID used by this client.
MqttDeliveryToken[]	getPendingDeliveryTokens() Returns the delivery tokens for any outstanding publish operations.
java.lang.String	getServerURI() Returns the address of the server used by this client, as a URI.
MqttTopic	getTopic(java.lang.String topic) Gets a topic object which can be used to publish messages.
boolean	isConnected() Determines if this client is currently connected to the server.
void	setCallback(MqttCallback callback) Sets the callback listener to use for asynchronously received messages.
void	subscribe(java.lang.String topicFilter) Subscribes to a topic, which may include wildcards, using the default options.
void	subscribe(java.lang.String[] topicFilters) Subscribes to multiple topics, each of which may include wildcards, using the default options.
void	subscribe(java.lang.String[] topicFilters, int[] qos) Subscribes to multiple topics, each of which may include wildcards, using the specified options.
void	subscribe(java.lang.String topicFilter, int qos) Subscribes to a topic, which may include wildcards, using the specified options.
void	unsubscribe(java.lang.String topicFilter) Unsubscribes from a topic.
void	unsubscribe(java.lang.String[] topicFilters) Unsubscribes from multiple topics.

Methods inherited from class java.lang.Object

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

Constructor Detail

MqttClient

public MqttClient(java.lang.String serverURI,
                  java.lang.String clientId)
           throws MqttException

Creates an MqttClient to connect to the specified address, using the specified client identifier. The address should be a URI, using a scheme of either "tcp://" for a TCP connection or "ssl://" for a TCP connection secured by SSL/TLS. For example:

• tcp://localhost:1883
• ssl://localhost:8883

If the port is not specified, it will default to 1883 for "tcp://" URIs, and 8883 for "ssl://" URIs.

The client identifier should be unique across all clients connecting to the same server. 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 are to be used.

In Java SE, SSL can be configured in one of several ways, which the client will use in the following order:

• Supplying an SSLSocketFactory - applications can use MqttConnectOptions.setSocketFactory(SocketFactory) to supply a factory with the appropriate SSL settings.
• SSL Properties - applications can supply SSL settings as a simple Java Properties using MqttConnectOptions.setSSLProperties(Properties).
• Use JVM settings - There are a number of standard Java system properties that can be used to configure key and trust stores.

In Java ME, the platform settings are used for SSL connections.

A default instance of MqttDefaultFilePersistence is used by the client. To specify a different persistence implementation, or to turn off persistence, use the MqttClient(String, String, MqttClientPersistence) constructor.

Parameters:

serverURI - the address to connect to, specified as a URI

clientId - the client ID to use

Throws:

java.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 23 characters in length

MqttException - if any other problem was encountered

MqttClient

public MqttClient(java.lang.String serverURI,
                  java.lang.String clientId,
                  MqttClientPersistence persistence)
           throws MqttException

Creates an MqttClient to connect to the specified address, using the specified client identifer and persistence implementation. The address should be a URI, using a scheme of either "tcp://" for a TCP connection or "ssl://" for a TCP connection secured by SSL/TLS. For example:

• tcp://localhost:1883
• ssl://localhost:8883
• local://FirstBroker

If the port is not specified, it will default to 1883 for "tcp://" URIs, and 8883 for "ssl://" URIs.

The client identifier should be unique across all clients connecting to the same server. 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 are to be used.

In Java SE, SSL can be configured in one of several ways, which the client will use in the following order:

• Supplying an SSLSocketFactory - applications can use MqttConnectOptions.setSocketFactory(SocketFactory) to supply a factory with the appropriate SSL settings.
• SSL Properties - applications can supply SSL settings as a simple Java Properties using MqttConnectOptions.setSSLProperties(Properties).
• Use JVM settings - There are a number of standard Java system properties that can be used to configure key and trust stores.

In Java ME, the platform settings are used for SSL connections.

The persistence mechanism is used to enable reliable messaging. For qualities of server (QoS) 1 or 2 to work, messages must be persisted to disk by both the client and the server. If this is not done, then a failure in the client or server will result in lost messages. It is the application's responsibility to provide an implementation of the MqttClientPersistence interface, which the client can use to persist messages. If the application is only sending QoS 0 messages, then this is not needed.

An implementation of file-based persistence is provided in the class MqttDefaultFilePersistence. If no persistence is needed, it can be explicitly set to null.

Parameters:

serverURI - the address to connect to, specified as a URI

clientId - the client ID to use

persistence - the persistence mechanism to use.

Throws:

java.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 23 characters in length

MqttException - if any other problem was encountered

Method Detail

connect

public void connect()
             throws MqttSecurityException,
                    MqttException

Connects to a server using the default options. It is recommended to call setCallback(MqttCallback) prior to connecting.

Throws:

MqttSecurityException

MqttException

connect

public void connect(MqttConnectOptions options)
             throws MqttSecurityException,
                    MqttException

Connects to a server using the specified options. It is recommended to call setCallback(MqttCallback) prior to connecting.

Throws:

MqttSecurityException

MqttException

disconnect

public void disconnect()
                throws MqttException

Disconnects from the server, which quiesces for up to a maximum of thirty seconds, to allow the client to finish any work it currently has.

Throws:

MqttException

See Also:

disconnect(long)

disconnect

public void disconnect(long quiesceTimeout)
                throws MqttException

Disconnects from the server. This method must not be called from inside MqttCallback methods.

Firstly, the client will wait for all MqttCallback methods to complete. It will then quiesce for the specified time, to allow for work which has already been accepted to complete - for example, it will wait for the QoS 2 flows from earlier publications to complete. After the quiesce timeout, the client will disconnect from the server. When the client is next connected, any QoS 1 or 2 messages which have not completed will be retried.

Parameters:

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.

Throws:

MqttException

isConnected

public boolean isConnected()

Determines if this client is currently connected to the server.

Returns:

true if connected, false otherwise.

getClientId

public java.lang.String getClientId()

Returns the client ID used by this client.

Returns:

the client ID used by this client.

getServerURI

public java.lang.String getServerURI()

Returns the address of the server used by this client, as a URI. The format is the same as specified on the constructor.

Returns:

the server's address, as a URI String.

See Also:

MqttClient(String, String)

getTopic

public MqttTopic getTopic(java.lang.String topic)

Gets a topic object which can be used to publish messages.

When you build an application, the design of the topic tree should take into account the following principles of topic name syntax and semantics:

• A topic must be at least one character long.
• Topic names are case sensitive. For example, ACCOUNTS and Accounts are two different topics.
• Topic names can include the space character. For example, Accounts payable is a valid topic.
• A leading "/" creates a distinct topic. For example, /finance is different from finance. /finance matches "+/+" and "/+", but not "+".
• Do not include the null character (Unicode \x0000) in any topic.

The following principles apply to the construction and content of a topic tree:

• The length is limited to 64k but within that there are no limits to the number of levels in a topic tree.
• There can be any number of root nodes; that is, there can be any number of topic trees.

Specified by:

getTopic in interface org.eclipse.paho.client.mqttv3.internal.DestinationProvider

Parameters:

topic - the topic to use, for example "finance/stock/ibm".

Returns:

an MqttTopic object, which can be used to publish messages to the topic.

Throws:

java.lang.IllegalArgumentException - if the topic contains a '+' or '#' wildcard character.

subscribe

public void subscribe(java.lang.String topicFilter)
               throws MqttException,
                      MqttSecurityException

Subscribes to a topic, which may include wildcards, using the default options. The setCallback(MqttCallback) method should be called before this method, otherwise any received messages will be discarded.

Throws:

MqttException

MqttSecurityException

See Also:

subscribe(String[], int[])

subscribe

public void subscribe(java.lang.String[] topicFilters)
               throws MqttException,
                      MqttSecurityException

Subscribes to multiple topics, each of which may include wildcards, using the default options. The setCallback(MqttCallback) method should be called before this method, otherwise any received messages will be discarded.

Throws:

MqttException

MqttSecurityException

See Also:

subscribe(String[], int[])

subscribe

public void subscribe(java.lang.String topicFilter,
                      int qos)
               throws MqttException,
                      MqttSecurityException

Subscribes to a topic, which may include wildcards, using the specified options. The setCallback(MqttCallback) method should be called before this method, otherwise any received messages will be discarded.

Parameters:

topicFilter - the topic to subscribe to, which can include wildcards.

qos - the quality of service at which to subscribe.

Throws:

MqttException

MqttSecurityException

See Also:

subscribe(String[], int[])

subscribe

public void subscribe(java.lang.String[] topicFilters,
                      int[] qos)
               throws MqttException,
                      MqttSecurityException

Subscribes to multiple topics, each of which may include wildcards, using the specified options. The setCallback(MqttCallback) method should be called before this method, otherwise any received messages will be discarded.

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.

Topic level separator

The forward slash (/) is used to separate each level within a topic tree and provide a hierarchical structure to the topic space. The use of the topic level separator is significant when the two wildcard characters are encountered in topics specified by subscribers.

Multi-level wildcard

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.

Single-level wildcard

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.

Parameters:

topicFilters - the topics to subscribe to, which can include wildcards.

qos - the qualities of service levels at which to subscribe.

Throws:

MqttException - if there was an error registering the subscription.

java.lang.IllegalArgumentException - if the two supplied arrays are not the same size.

MqttSecurityException

unsubscribe

public void unsubscribe(java.lang.String topicFilter)
                 throws MqttException

Unsubscribes from a topic.

Parameters:

topicFilter - the topic to unsubscribe from.

Throws:

MqttException

unsubscribe

public void unsubscribe(java.lang.String[] topicFilters)
                 throws MqttException

Unsubscribes from multiple topics.

Parameters:

topicFilters - the topics to unsubscribe from.

Throws:

MqttException

setCallback

public void setCallback(MqttCallback callback)
                 throws MqttException

Sets the callback listener to use for asynchronously received messages. The MqttCallback.messageArrived(MqttTopic, MqttMessage) method will be called back whenever a message arrives.

Parameters:

callback - the class to callback when a message arrives.

Throws:

MqttException

generateClientId

public static java.lang.String generateClientId()

Returns a randomly generated client identifier based on the current user's login name and the system time.

When cleanSession is set to false, an application should ensure it uses the same client identifier when it reconnects to the server to resume state and maintain assured message delivery.

Returns:

a generated client identifier

See Also:

MqttConnectOptions.setCleanSession(boolean)

getPendingDeliveryTokens

public MqttDeliveryToken[] getPendingDeliveryTokens()

Returns the delivery tokens for any outstanding publish operations.