org.eclipse.paho.client.mqttv3
Interface IMqttClient

All Known Implementing Classes:
MqttClient

public interface IMqttClient

Enables an application to communicate with an MQTT server using using blocking methods.

This interface allows applications to utilize all features of the MQTT version 3.1 specification including:

There are two styles of MQTT client, this one and IMqttAsyncClient.

The non-blocking client can also be used in a blocking form by turning a non-blocking method into a blocking invocation using the following pattern:

     IMqttToken token;
     token = asyncClient.method(parms).waitForCompletion();
     
Using the non-blocking client allows an application to use a mixture of blocking and non-blocking styles. Using the blocking client only allows an application to use one style. The blocking client provides compatibility with earlier versions of the MQTT client.


Method Summary
 void close()
          Close the client Releases all resource associated with the client.
 void connect()
          Connects to an MQTT server using the default options.
 void connect(MqttConnectOptions options)
          Connects to an MQTT server using the specified options.
 void disconnect()
          Disconnects from the server.
 void disconnect(long quiesceTimeout)
          Disconnects from the server.
 String getClientId()
          Returns the client ID used by this client.
 IMqttDeliveryToken[] getPendingDeliveryTokens()
          Returns the delivery tokens for any outstanding publish operations.
 String getServerURI()
          Returns the address of the server used by this client, as a URI.
 MqttTopic getTopic(String topic)
          Get a topic object which can be used to publish messages.
 boolean isConnected()
          Determines if this client is currently connected to the server.
 void publish(String topic, byte[] payload, int qos, boolean retained)
          Publishes a message to a topic on the server and return once it is delivered.
 void publish(String topic, MqttMessage message)
          Publishes a message to a topic on the server.
 void setCallback(MqttCallback callback)
          Sets the callback listener to use for events that happen asynchronously.
 void subscribe(String topicFilter)
          Subscribe to a topic, which may include wildcards using a QoS of 1.
 void subscribe(String[] topicFilters)
          Subscribes to a one or more topics, which may include wildcards using a QoS of 1.
 void subscribe(String[] topicFilters, int[] qos)
          Subscribes to multiple topics, each of which may include wildcards.
 void subscribe(String topicFilter, int qos)
          Subscribe to a topic, which may include wildcards.
 void unsubscribe(String topicFilter)
          Requests the server unsubscribe the client from a topic.
 void unsubscribe(String[] topicFilters)
          Requests the server unsubscribe the client from one or more topics.
 

Method Detail

connect

void connect()
             throws MqttSecurityException,
                    MqttException
Connects to an MQTT server using the default options.

The default options are specified in MqttConnectOptions class.

Throws:
MqttSecurityException - when the server rejects the connect for security reasons
MqttException - for non security related problems
See Also:
connect(MqttConnectOptions)

connect

void connect(MqttConnectOptions options)
             throws MqttSecurityException,
                    MqttException
Connects to an MQTT server using the specified options.

The server to connect to is specified on the constructor. It is recommended to call setCallback(MqttCallback) prior to connecting in order that messages destined for the client can be accepted as soon as the client is connected.

This is a blocking method that returns once connect completes

Parameters:
options - a set of connection parameters that override the defaults.
Throws:
MqttSecurityException - when the server rejects the connect for security reasons
MqttException - for non security related problems including communication errors

disconnect

void disconnect()
                throws MqttException
Disconnects from the server.

An attempt is made to quiesce the client allowing outstanding work to complete before disconnecting. It will wait for a maximum of 30 seconds for work to quiesce before disconnecting. This method must not be called from inside MqttCallback methods.

Throws:
MqttException
See Also:
disconnect(long)

disconnect

void disconnect(long quiesceTimeout)
                throws MqttException
Disconnects from the server.

The client will wait for all MqttCallback methods to complete. It will then wait for up to the quiesce timeout to allow for work which has already been initiated to complete - for example, it will wait for the QoS 2 flows from earlier publications to complete. When work has completed or after the quiesce timeout, the client will disconnect from the server. If the cleanSession flag was set to false and is set to false the next time a connection is made QoS 1 and 2 messages that were not previously delivered will be delivered.

This is a blocking method that returns once disconnect completes

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 - if a problem is encountered while disconnecting

subscribe

void subscribe(String topicFilter)
               throws MqttException,
                      MqttSecurityException
Subscribe to a topic, which may include wildcards using a QoS of 1.

Parameters:
topicFilter - the topic to subscribe to, which can include wildcards.
Throws:
MqttException - if there was an error registering the subscription.
MqttSecurityException
See Also:
subscribe(String[], int[])

subscribe

void subscribe(String[] topicFilters)
               throws MqttException
Subscribes to a one or more topics, which may include wildcards using a QoS of 1.

Parameters:
topicFilters - the topic to subscribe to, which can include wildcards.
Throws:
MqttException - if there was an error registering the subscription.
See Also:
subscribe(String[], int[])

subscribe

void subscribe(String topicFilter,
               int qos)
               throws MqttException
Subscribe to a topic, which may include wildcards.

Parameters:
topicFilter - the topic to subscribe to, which can include wildcards.
qos - the maximum quality of service at which to subscribe. Messages published at a lower quality of service will be received at the published QoS. Messages published at a higher quality of service will be received using the QoS specified on the subscribe.
Throws:
MqttException - if there was an error registering the subscription.
See Also:
subscribe(String[], int[])

subscribe

void subscribe(String[] topicFilters,
               int[] qos)
               throws MqttException
Subscribes to multiple topics, each of which may include wildcards.

The setCallback(MqttCallback) method should be called before this method, otherwise any received messages will be discarded.

If (@link MqttConnectOptions#setCleanSession(boolean)} was set to true when when connecting to the server then the subscription remains in place until either:


unsubscribe

void unsubscribe(String topicFilter)
                 throws MqttException
Requests the server unsubscribe the client from a topic.

Parameters:
topicFilter - the topic to unsubscribe from. It must match a topicFilter specified on the subscribe.
Throws:
MqttException - if there was an error unregistering the subscription.
See Also:
unsubscribe(String[])

unsubscribe

void unsubscribe(String[] topicFilters)
                 throws MqttException
Requests the server unsubscribe the client from one or more topics.

Unsubcribing is the opposite of subscribing. When the server receives the unsubscribe request it looks to see if it can find a subscription for the client and then removes it. After this point the server will send no more messages to the client for this subscription.

The topic(s) specified on the unsubscribe must match the topic(s) specified in the original subscribe request for the subscribe to succeed

This is a blocking method that returns once unsubscribe completes

Parameters:
topicFilters - one or more topics to unsubscribe from. Each topicFilter must match one specified on a subscribe
Throws:
MqttException - if there was an error unregistering the subscription.

publish

void publish(String topic,
             byte[] payload,
             int qos,
             boolean retained)
             throws MqttException,
                    MqttPersistenceException
Publishes a message to a topic on the server and return once it is delivered.

This is a convenience method, which will create a new MqttMessage object with a byte array payload and the specified QoS, and then publish it. All other values in the message will be set to the defaults.

Parameters:
topic - to deliver the message to, for example "finance/stock/ibm".
payload - the byte array to use as the payload
qos - the Quality of Service to deliver the message at. Valid values are 0, 1 or 2.
retained - whether or not this message should be retained by the server.
Throws:
MqttPersistenceException - when a problem with storing the message
IllegalArgumentException - if value of QoS is not 0, 1 or 2.
MqttException - for other errors encountered while publishing the message. For instance client not connected.
See Also:
publish(String, MqttMessage), MqttMessage.setQos(int), MqttMessage.setRetained(boolean)

publish

void publish(String topic,
             MqttMessage message)
             throws MqttException,
                    MqttPersistenceException
Publishes a message to a topic on the server.

Delivers a message to the server at the requested quality of service and returns control once the message has been delivered. In the event the connection fails or the client stops, any messages that are in the process of being delivered will be delivered once a connection is re-established to the server on condition that:

In the event that the connection breaks or the client stops it is still possible to determine when the delivery of the message completes. Prior to re-establishing the connection to the server:

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

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

This is a blocking method that returns once publish completes

*

Parameters:
topic - to deliver the message to, for example "finance/stock/ibm".
message - to delivery to the server
Throws:
MqttPersistenceException - when a problem with storing the message
IllegalArgumentException - if value of QoS is not 0, 1 or 2.
MqttException - for other errors encountered while publishing the message. For instance client not connected.

setCallback

void setCallback(MqttCallback callback)
Sets the callback listener to use for events that happen asynchronously.

There are a number of events that listener will be notified about. These include

Other events that track the progress of an individual operation such as connect and subscribe can be tracked using the MqttToken passed to the operation

Parameters:
callback - the class to callback when for events related to the client
See Also:
MqttCallback

getTopic

MqttTopic getTopic(String topic)
Get a topic object which can be used to publish messages.

An alternative method that should be used in preference to this one when publishing a message is:

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

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

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:
IllegalArgumentException - if the topic contains a '+' or '#' wildcard character.

isConnected

boolean isConnected()
Determines if this client is currently connected to the server.

Returns:
true if connected, false otherwise.

getClientId

String getClientId()
Returns the client ID used by this client.

All clients connected to the same server or server farm must have a unique ID.

Returns:
the client ID used by this client.

getServerURI

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:
MqttAsyncClient.MqttAsyncClient(String, String)

getPendingDeliveryTokens

IMqttDeliveryToken[] getPendingDeliveryTokens()
Returns the delivery tokens for any outstanding publish operations.

If a client has been restarted and there are messages that were in the process of being delivered when the client stopped this method will return a token for each message enabling the delivery to be tracked Alternately the MqttCallback.deliveryComplete(IMqttDeliveryToken) callback can be used to track the delivery of outstanding messages.

If a client connects with cleanSession true then there will be no delivery tokens as the cleanSession option deletes all earlier state. For state to be remembered the client must connect with cleanSession set to false

Returns:
zero or more delivery tokens

close

void close()
           throws MqttException
Close the client Releases all resource associated with the client. After the client has been closed it cannot be reused. For instance attempts to connect will fail.

Throws:
MqttException - if the client is not disconnected.


Copyright © 2013. All Rights Reserved.