org.eclipse.paho.android.service

Class MqttAndroidClient

java.lang.Object

android.content.BroadcastReceiver

org.eclipse.paho.android.service.MqttAndroidClient

All Implemented Interfaces:

org.eclipse.paho.client.mqttv3.IMqttAsyncClient

public class MqttAndroidClient
extends android.content.BroadcastReceiver
implements org.eclipse.paho.client.mqttv3.IMqttAsyncClient

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

Implementation of the MQTT asynchronous client interface IMqttAsyncClient , using the MQTT android service to actually interface with MQTT server. It provides android applications a simple programming interface to all features of the MQTT version 3.1 specification including:

• connect
• publish
• subscribe
• unsubscribe
• disconnect

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MqttAndroidClient.Ack The Acknowledgment mode for messages received from MqttCallback.messageArrived(String, MqttMessage)

Nested classes/interfaces inherited from class android.content.BroadcastReceiver

android.content.BroadcastReceiver.PendingResult

Constructor Summary

Constructors

Constructor and Description
MqttAndroidClient(android.content.Context context, java.lang.String serverURI, java.lang.String clientId) Constructor - create an MqttAndroidClient that can be used to communicate with an MQTT server on android
MqttAndroidClient(android.content.Context ctx, java.lang.String serverURI, java.lang.String clientId, MqttAndroidClient.Ack ackType) Constructor - create an MqttAndroidClient that can be used to communicate with an MQTT server on android
MqttAndroidClient(android.content.Context ctx, java.lang.String serverURI, java.lang.String clientId, org.eclipse.paho.client.mqttv3.MqttClientPersistence persistence) Constructor - create an MqttAndroidClient that can be used to communicate with an MQTT server on android
MqttAndroidClient(android.content.Context context, java.lang.String serverURI, java.lang.String clientId, org.eclipse.paho.client.mqttv3.MqttClientPersistence persistence, MqttAndroidClient.Ack ackType) Constructor- create an MqttAndroidClient that can be used to communicate with an MQTT server on android

Method Summary

Modifier and Type	Method and Description
boolean	acknowledgeMessage(java.lang.String messageId) Acknowledges a message received on the MqttCallback.messageArrived(String, MqttMessage)
void	close() Close the client.
org.eclipse.paho.client.mqttv3.IMqttToken	connect() Connects to an MQTT server using the default options.
org.eclipse.paho.client.mqttv3.IMqttToken	connect(org.eclipse.paho.client.mqttv3.MqttConnectOptions options) Connects to an MQTT server using the provided connect options.
org.eclipse.paho.client.mqttv3.IMqttToken	connect(org.eclipse.paho.client.mqttv3.MqttConnectOptions options, java.lang.Object userContext, org.eclipse.paho.client.mqttv3.IMqttActionListener callback) Connects to an MQTT server using the specified options.
org.eclipse.paho.client.mqttv3.IMqttToken	connect(java.lang.Object userContext, org.eclipse.paho.client.mqttv3.IMqttActionListener callback) Connects to an MQTT server using the default options.
void	deleteBufferedMessage(int bufferIndex)
org.eclipse.paho.client.mqttv3.IMqttToken	disconnect() Disconnects from the server.
org.eclipse.paho.client.mqttv3.IMqttToken	disconnect(long quiesceTimeout) Disconnects from the server.
org.eclipse.paho.client.mqttv3.IMqttToken	disconnect(long quiesceTimeout, java.lang.Object userContext, org.eclipse.paho.client.mqttv3.IMqttActionListener callback) Disconnects from the server.
org.eclipse.paho.client.mqttv3.IMqttToken	disconnect(java.lang.Object userContext, org.eclipse.paho.client.mqttv3.IMqttActionListener callback) Disconnects from the server.
void	disconnectForcibly()
void	disconnectForcibly(long disconnectTimeout)
void	disconnectForcibly(long quiesceTimeout, long disconnectTimeout)
org.eclipse.paho.client.mqttv3.MqttMessage	getBufferedMessage(int bufferIndex)
int	getBufferedMessageCount()
java.lang.String	getClientId() Returns the client ID used by this client.
org.eclipse.paho.client.mqttv3.IMqttDeliveryToken[]	getPendingDeliveryTokens() Returns the delivery tokens for any outstanding publish operations.
java.lang.String	getServerURI() Returns the URI address of the server used by this client.
javax.net.ssl.SSLSocketFactory	getSSLSocketFactory(java.io.InputStream keyStore, java.lang.String password) Get the SSLSocketFactory using SSL key store and password
boolean	isConnected() Determines if this client is currently connected to the server.
void	messageArrivedComplete(int messageId, int qos)
void	onReceive(android.content.Context context, android.content.Intent intent) Process incoming Intent objects representing the results of operations and asynchronous activities such as message received
org.eclipse.paho.client.mqttv3.IMqttDeliveryToken	publish(java.lang.String topic, byte[] payload, int qos, boolean retained) Publishes a message to a topic on the server.
org.eclipse.paho.client.mqttv3.IMqttDeliveryToken	publish(java.lang.String topic, byte[] payload, int qos, boolean retained, java.lang.Object userContext, org.eclipse.paho.client.mqttv3.IMqttActionListener callback) Publishes a message to a topic on the server.
org.eclipse.paho.client.mqttv3.IMqttDeliveryToken	publish(java.lang.String topic, org.eclipse.paho.client.mqttv3.MqttMessage message) Publishes a message to a topic on the server.
org.eclipse.paho.client.mqttv3.IMqttDeliveryToken	publish(java.lang.String topic, org.eclipse.paho.client.mqttv3.MqttMessage message, java.lang.Object userContext, org.eclipse.paho.client.mqttv3.IMqttActionListener callback) Publishes a message to a topic on the server.
void	registerResources(android.content.Context context) Register receiver to receiver intent from MqttService.
void	setBufferOpts(org.eclipse.paho.client.mqttv3.DisconnectedBufferOptions bufferOpts) Sets the DisconnectedBufferOptions for this client
void	setCallback(org.eclipse.paho.client.mqttv3.MqttCallback callback) Sets a callback listener to use for events that happen asynchronously.
void	setManualAcks(boolean manualAcks)
void	setTraceCallback(MqttTraceHandler traceCallback) identify the callback to be invoked when making tracing calls back into the Activity
void	setTraceEnabled(boolean traceEnabled) turn tracing on and off
org.eclipse.paho.client.mqttv3.IMqttToken	subscribe(java.lang.String[] topic, int[] qos) Subscribe to multiple topics, each topic may include wildcards.
org.eclipse.paho.client.mqttv3.IMqttToken	subscribe(java.lang.String[] topicFilters, int[] qos, org.eclipse.paho.client.mqttv3.IMqttMessageListener[] messageListeners) Subscribe to multiple topics, each of which may include wildcards.
org.eclipse.paho.client.mqttv3.IMqttToken	subscribe(java.lang.String[] topic, int[] qos, java.lang.Object userContext, org.eclipse.paho.client.mqttv3.IMqttActionListener callback) Subscribes to multiple topics, each topic may include wildcards.
org.eclipse.paho.client.mqttv3.IMqttToken	subscribe(java.lang.String[] topicFilters, int[] qos, java.lang.Object userContext, org.eclipse.paho.client.mqttv3.IMqttActionListener callback, org.eclipse.paho.client.mqttv3.IMqttMessageListener[] messageListeners) Subscribe to multiple topics, each of which may include wildcards.
org.eclipse.paho.client.mqttv3.IMqttToken	subscribe(java.lang.String topic, int qos) Subscribe to a topic, which may include wildcards.
org.eclipse.paho.client.mqttv3.IMqttToken	subscribe(java.lang.String topicFilter, int qos, org.eclipse.paho.client.mqttv3.IMqttMessageListener messageListener) Subscribe to a topic, which may include wildcards.
org.eclipse.paho.client.mqttv3.IMqttToken	subscribe(java.lang.String topic, int qos, java.lang.Object userContext, org.eclipse.paho.client.mqttv3.IMqttActionListener callback) Subscribe to a topic, which may include wildcards.
org.eclipse.paho.client.mqttv3.IMqttToken	subscribe(java.lang.String topicFilter, int qos, java.lang.Object userContext, org.eclipse.paho.client.mqttv3.IMqttActionListener callback, org.eclipse.paho.client.mqttv3.IMqttMessageListener messageListener) Subscribe to a topic, which may include wildcards.
void	unregisterResources() Unregister receiver which receives intent from MqttService avoids IntentReceiver leaks.
org.eclipse.paho.client.mqttv3.IMqttToken	unsubscribe(java.lang.String topic) Requests the server unsubscribe the client from a topic.
org.eclipse.paho.client.mqttv3.IMqttToken	unsubscribe(java.lang.String[] topic) Requests the server to unsubscribe the client from one or more topics.
org.eclipse.paho.client.mqttv3.IMqttToken	unsubscribe(java.lang.String[] topic, java.lang.Object userContext, org.eclipse.paho.client.mqttv3.IMqttActionListener callback) Requests the server to unsubscribe the client from one or more topics.
org.eclipse.paho.client.mqttv3.IMqttToken	unsubscribe(java.lang.String topic, java.lang.Object userContext, org.eclipse.paho.client.mqttv3.IMqttActionListener callback) Requests the server to unsubscribe the client from a topics.

Methods inherited from class android.content.BroadcastReceiver

abortBroadcast, clearAbortBroadcast, getAbortBroadcast, getDebugUnregister, getResultCode, getResultData, getResultExtras, goAsync, isInitialStickyBroadcast, isOrderedBroadcast, peekService, setDebugUnregister, setOrderedHint, setResult, setResultCode, setResultData, setResultExtras

Methods inherited from class java.lang.Object

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

Constructor Detail

MqttAndroidClient

public MqttAndroidClient(android.content.Context context,
                         java.lang.String serverURI,
                         java.lang.String clientId)

Constructor - create an MqttAndroidClient that can be used to communicate with an MQTT server on android

Parameters:

context - object used to pass context to the callback.

serverURI - specifies the protocol, host name and port to be used to connect to an MQTT server

clientId - specifies the name by which this connection should be identified to the server

MqttAndroidClient

public MqttAndroidClient(android.content.Context ctx,
                         java.lang.String serverURI,
                         java.lang.String clientId,
                         MqttAndroidClient.Ack ackType)

Constructor - create an MqttAndroidClient that can be used to communicate with an MQTT server on android

Parameters:

ctx - Application's context

serverURI - specifies the protocol, host name and port to be used to connect to an MQTT server

clientId - specifies the name by which this connection should be identified to the server

ackType - how the application wishes to acknowledge a message has been processed

MqttAndroidClient

public MqttAndroidClient(android.content.Context ctx,
                         java.lang.String serverURI,
                         java.lang.String clientId,
                         org.eclipse.paho.client.mqttv3.MqttClientPersistence persistence)

Constructor - create an MqttAndroidClient that can be used to communicate with an MQTT server on android

Parameters:

ctx - Application's context

serverURI - specifies the protocol, host name and port to be used to connect to an MQTT server

clientId - specifies the name by which this connection should be identified to the server

persistence - The object to use to store persisted data

MqttAndroidClient

public MqttAndroidClient(android.content.Context context,
                         java.lang.String serverURI,
                         java.lang.String clientId,
                         org.eclipse.paho.client.mqttv3.MqttClientPersistence persistence,
                         MqttAndroidClient.Ack ackType)

Constructor- create an MqttAndroidClient that can be used to communicate with an MQTT server on android

Parameters:

context - used to pass context to the callback.

serverURI - specifies the protocol, host name and port to be used to connect to an MQTT server

clientId - specifies the name by which this connection should be identified to the server

persistence - the persistence class to use to store in-flight message. If null then the default persistence mechanism is used

ackType - how the application wishes to acknowledge a message has been processed.

Method Detail

isConnected

public boolean isConnected()

Determines if this client is currently connected to the server.

Specified by:

isConnected in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Returns:

true if connected, false otherwise.

getClientId

public java.lang.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.

Specified by:

getClientId in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Returns:

the client ID used by this client.

getServerURI

public java.lang.String getServerURI()

Returns the URI address of the server used by this client.

The format of the returned String is the same as that used on the constructor.

Specified by:

getServerURI in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Returns:

the server's address, as a URI String.

close

public void close()

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.

Specified by:

close in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

connect

public org.eclipse.paho.client.mqttv3.IMqttToken connect()
                                                  throws org.eclipse.paho.client.mqttv3.MqttException

Connects to an MQTT server using the default options.

The default options are specified in MqttConnectOptions class.

Specified by:

connect in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Returns:

token used to track and wait for the connect to complete. The token will be passed to the callback methods if a callback is set.

Throws:

org.eclipse.paho.client.mqttv3.MqttException - for any connected problems

See Also:

connect(MqttConnectOptions, Object, IMqttActionListener)

connect

public org.eclipse.paho.client.mqttv3.IMqttToken connect(org.eclipse.paho.client.mqttv3.MqttConnectOptions options)
                                                  throws org.eclipse.paho.client.mqttv3.MqttException

Connects to an MQTT server using the provided connect options.

The connection will be established using the options specified in the MqttConnectOptions parameter.

Specified by:

connect in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Parameters:

options - a set of connection parameters that override the defaults.

Returns:

token used to track and wait for the connect to complete. The token will be passed to any callback that has been set.

Throws:

org.eclipse.paho.client.mqttv3.MqttException - for any connected problems

See Also:

connect(MqttConnectOptions, Object, IMqttActionListener)

connect

public org.eclipse.paho.client.mqttv3.IMqttToken connect(java.lang.Object userContext,
                                                         org.eclipse.paho.client.mqttv3.IMqttActionListener callback)
                                                  throws org.eclipse.paho.client.mqttv3.MqttException

Connects to an MQTT server using the default options.

The default options are specified in MqttConnectOptions class.

Specified by:

connect in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Parameters:

userContext - optional object used to pass context to the callback. Use null if not required.

callback - optional listener that will be notified when the connect completes. Use null if not required.

Returns:

token used to track and wait for the connect to complete. The token will be passed to any callback that has been set.

Throws:

org.eclipse.paho.client.mqttv3.MqttException - for any connected problems

See Also:

connect(MqttConnectOptions, Object, IMqttActionListener)

connect

public org.eclipse.paho.client.mqttv3.IMqttToken connect(org.eclipse.paho.client.mqttv3.MqttConnectOptions options,
                                                         java.lang.Object userContext,
                                                         org.eclipse.paho.client.mqttv3.IMqttActionListener callback)
                                                  throws org.eclipse.paho.client.mqttv3.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.

The method returns control before the connect completes. Completion can be tracked by:

• Waiting on the returned token IMqttToken.waitForCompletion() or
• Passing in a callback IMqttActionListener

Specified by:

connect in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Parameters:

options - a set of connection parameters that override the defaults.

userContext - optional object for used to pass context to the callback. Use null if not required.

callback - optional listener that will be notified when the connect completes. Use null if not required.

Returns:

token used to track and wait for the connect to complete. The token will be passed to any callback that has been set.

Throws:

org.eclipse.paho.client.mqttv3.MqttException - for any connected problems, including communication errors

disconnect

public org.eclipse.paho.client.mqttv3.IMqttToken disconnect()
                                                     throws org.eclipse.paho.client.mqttv3.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.

Specified by:

disconnect in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Returns:

token used to track and wait for disconnect to complete. The token will be passed to any callback that has been set.

Throws:

org.eclipse.paho.client.mqttv3.MqttException - for problems encountered while disconnecting

See Also:

disconnect(long, Object, IMqttActionListener)

disconnect

public org.eclipse.paho.client.mqttv3.IMqttToken disconnect(long quiesceTimeout)
                                                     throws org.eclipse.paho.client.mqttv3.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 the specified quiesce time for work to complete before disconnecting. This method must not be called from inside MqttCallback methods.

Specified by:

disconnect in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

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.

Returns:

token used to track and wait for disconnect to complete. The token will be passed to the callback methods if a callback is set.

Throws:

org.eclipse.paho.client.mqttv3.MqttException - for problems encountered while disconnecting

See Also:

disconnect(long, Object, IMqttActionListener)

disconnect

public org.eclipse.paho.client.mqttv3.IMqttToken disconnect(java.lang.Object userContext,
                                                            org.eclipse.paho.client.mqttv3.IMqttActionListener callback)
                                                     throws org.eclipse.paho.client.mqttv3.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.

Specified by:

disconnect in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Parameters:

userContext - optional object used to pass context to the callback. Use null if not required.

callback - optional listener that will be notified when the disconnect completes. Use null if not required.

Returns:

token used to track and wait for the disconnect to complete. The token will be passed to any callback that has been set.

Throws:

org.eclipse.paho.client.mqttv3.MqttException - for problems encountered while disconnecting

See Also:

disconnect(long, Object, IMqttActionListener)

disconnect

public org.eclipse.paho.client.mqttv3.IMqttToken disconnect(long quiesceTimeout,
                                                            java.lang.Object userContext,
                                                            org.eclipse.paho.client.mqttv3.IMqttActionListener callback)
                                                     throws org.eclipse.paho.client.mqttv3.MqttException

Disconnects from the server.

The client will wait for 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 instance when a QoS 2 message has started flowing to the server but the QoS 2 flow has not completed.It prevents new messages being accepted and does not send any messages that have been accepted but not yet started delivery across the network to the server. 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 next time it is also set to false in the connection, the messages made in QoS 1 or 2 which were not previously delivered will be delivered this time.

This method must not be called from inside MqttCallback methods.

The method returns control before the disconnect completes. Completion can be tracked by:

• Waiting on the returned token IMqttToken.waitForCompletion() or
• Passing in a callback IMqttActionListener

Specified by:

disconnect in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

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.

userContext - optional object used to pass context to the callback. Use null if not required.

callback - optional listener that will be notified when the disconnect completes. Use null if not required.

Returns:

token used to track and wait for the disconnect to complete. The token will be passed to any callback that has been set.

Throws:

org.eclipse.paho.client.mqttv3.MqttException - for problems encountered while disconnecting

publish

public org.eclipse.paho.client.mqttv3.IMqttDeliveryToken publish(java.lang.String topic,
                                                                 byte[] payload,
                                                                 int qos,
                                                                 boolean retained)
                                                          throws org.eclipse.paho.client.mqttv3.MqttException,
                                                                 org.eclipse.paho.client.mqttv3.MqttPersistenceException

Publishes a message to a topic on the server.

A convenience method, which will create a new MqttMessage object with a byte array payload and the specified QoS, and then publish it.

Specified by:

publish in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

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.

Returns:

token used to track and wait for the publish to complete. The token will be passed to any callback that has been set.

Throws:

org.eclipse.paho.client.mqttv3.MqttPersistenceException - when a problem occurs storing the message

java.lang.IllegalArgumentException - if value of QoS is not 0, 1 or 2.

org.eclipse.paho.client.mqttv3.MqttException - for other errors encountered while publishing the message. For instance, too many messages are being processed.

See Also:

publish(String, MqttMessage, Object, IMqttActionListener)

publish

public org.eclipse.paho.client.mqttv3.IMqttDeliveryToken publish(java.lang.String topic,
                                                                 org.eclipse.paho.client.mqttv3.MqttMessage message)
                                                          throws org.eclipse.paho.client.mqttv3.MqttException,
                                                                 org.eclipse.paho.client.mqttv3.MqttPersistenceException

Publishes a message to a topic on the server. Takes an MqttMessage message and delivers it to the server at the requested quality of service.

Specified by:

publish in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Parameters:

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

message - to deliver to the server

Returns:

token used to track and wait for the publish to complete. The token will be passed to any callback that has been set.

Throws:

org.eclipse.paho.client.mqttv3.MqttPersistenceException - when a problem occurs storing the message

java.lang.IllegalArgumentException - if value of QoS is not 0, 1 or 2.

org.eclipse.paho.client.mqttv3.MqttException - for other errors encountered while publishing the message. For instance client not connected.

See Also:

publish(String, MqttMessage, Object, IMqttActionListener)

publish

public org.eclipse.paho.client.mqttv3.IMqttDeliveryToken publish(java.lang.String topic,
                                                                 byte[] payload,
                                                                 int qos,
                                                                 boolean retained,
                                                                 java.lang.Object userContext,
                                                                 org.eclipse.paho.client.mqttv3.IMqttActionListener callback)
                                                          throws org.eclipse.paho.client.mqttv3.MqttException,
                                                                 org.eclipse.paho.client.mqttv3.MqttPersistenceException

Publishes a message to a topic on the server.

A convenience method, which will create a new MqttMessage object with a byte array payload, the specified QoS and retained, then publish it.

Specified by:

publish in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

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.

userContext - optional object used to pass context to the callback. Use null if not required.

callback - optional listener that will be notified when message delivery has completed to the requested quality of service

Returns:

token used to track and wait for the publish to complete. The token will be passed to any callback that has been set.

Throws:

org.eclipse.paho.client.mqttv3.MqttPersistenceException - when a problem occurs storing the message

java.lang.IllegalArgumentException - if value of QoS is not 0, 1 or 2.

org.eclipse.paho.client.mqttv3.MqttException - for other errors encountered while publishing the message. For instance client not connected.

See Also:

publish(String, MqttMessage, Object, IMqttActionListener)

publish

public org.eclipse.paho.client.mqttv3.IMqttDeliveryToken publish(java.lang.String topic,
                                                                 org.eclipse.paho.client.mqttv3.MqttMessage message,
                                                                 java.lang.Object userContext,
                                                                 org.eclipse.paho.client.mqttv3.IMqttActionListener callback)
                                                          throws org.eclipse.paho.client.mqttv3.MqttException,
                                                                 org.eclipse.paho.client.mqttv3.MqttPersistenceException

Publishes a message to a topic on the server.

Once this method has returned cleanly, the message has been accepted for publication by the client and will be delivered on a background thread. In the event the connection fails or the client stops, Messages will be delivered to the requested quality of service once the connection is re-established to the server on condition that:

• The connection is re-established with the same clientID
• The original connection was made with (@link MqttConnectOptions#setCleanSession(boolean)} set to false
• The connection is re-established with (@link MqttConnectOptions#setCleanSession(boolean)} set to false
• Depending when the failure occurs QoS 0 messages may not be delivered.

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

The method returns control before the publish completes. Completion can be tracked by:

• Setting an IMqttAsyncClient.setCallback(MqttCallback) where the MqttCallback.deliveryComplete(IMqttDeliveryToken) method will be called.
• Waiting on the returned token MqttToken.waitForCompletion() or
• Passing in a callback IMqttActionListener to this method

Specified by:

publish in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Parameters:

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

message - to deliver to the server

userContext - optional object used to pass context to the callback. Use null if not required.

callback - optional listener that will be notified when message delivery has completed to the requested quality of service

Returns:

token used to track and wait for the publish to complete. The token will be passed to callback methods if set.

Throws:

org.eclipse.paho.client.mqttv3.MqttPersistenceException - when a problem occurs storing the message

java.lang.IllegalArgumentException - if value of QoS is not 0, 1 or 2.

org.eclipse.paho.client.mqttv3.MqttException - for other errors encountered while publishing the message. For instance, client not connected.

See Also:

MqttMessage

subscribe

public org.eclipse.paho.client.mqttv3.IMqttToken subscribe(java.lang.String topic,
                                                           int qos)
                                                    throws org.eclipse.paho.client.mqttv3.MqttException,
                                                           org.eclipse.paho.client.mqttv3.MqttSecurityException

Subscribe to a topic, which may include wildcards.

Specified by:

subscribe in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Parameters:

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

Returns:

token used to track and wait for the subscribe to complete. The token will be passed to callback methods if set.

Throws:

org.eclipse.paho.client.mqttv3.MqttSecurityException - for security related problems

org.eclipse.paho.client.mqttv3.MqttException - for non security related problems

See Also:

subscribe(String[], int[], Object, IMqttActionListener)

subscribe

public org.eclipse.paho.client.mqttv3.IMqttToken subscribe(java.lang.String[] topic,
                                                           int[] qos)
                                                    throws org.eclipse.paho.client.mqttv3.MqttException,
                                                           org.eclipse.paho.client.mqttv3.MqttSecurityException

Subscribe to multiple topics, each topic may include wildcards.

Provides an optimized way to subscribe to multiple topics compared to subscribing to each one individually.

Specified by:

subscribe in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Parameters:

topic - one or more topics 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 subscription.

Returns:

token used to track and wait for the subscription to complete. The token will be passed to callback methods if set.

Throws:

org.eclipse.paho.client.mqttv3.MqttSecurityException - for security related problems

org.eclipse.paho.client.mqttv3.MqttException - for non security related problems

See Also:

subscribe(String[], int[], Object, IMqttActionListener)

subscribe

public org.eclipse.paho.client.mqttv3.IMqttToken subscribe(java.lang.String topic,
                                                           int qos,
                                                           java.lang.Object userContext,
                                                           org.eclipse.paho.client.mqttv3.IMqttActionListener callback)
                                                    throws org.eclipse.paho.client.mqttv3.MqttException

Subscribe to a topic, which may include wildcards.

Specified by:

subscribe in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Parameters:

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

userContext - optional object used to pass context to the callback. Use null if not required.

callback - optional listener that will be notified when subscribe has completed

Returns:

token used to track and wait for the subscribe to complete. The token will be passed to callback methods if set.

Throws:

org.eclipse.paho.client.mqttv3.MqttException - if there was an error when registering the subscription.

See Also:

subscribe(String[], int[], Object, IMqttActionListener)

subscribe

public org.eclipse.paho.client.mqttv3.IMqttToken subscribe(java.lang.String[] topic,
                                                           int[] qos,
                                                           java.lang.Object userContext,
                                                           org.eclipse.paho.client.mqttv3.IMqttActionListener callback)
                                                    throws org.eclipse.paho.client.mqttv3.MqttException

Subscribes to multiple topics, each topic may include wildcards.

Provides an optimized way to subscribe to multiple topics compared to subscribing to each one individually.

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 connecting to the server, the subscription remains in place until either:

• The client disconnects
• An unsubscribe method is called to unsubscribe the topic

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

• An unsubscribe method is called to unsubscribe the topic
• The next time the client connects with cleanSession set to true

With cleanSession set to false the MQTT server will store messages on behalf of the client when the client is not connected. The next time the client connects with the same client ID the server will deliver the stored messages to the client.

The "topic filter" string is used when subscription may contain special characters, which allows you to subscribe to multiple topics at once.

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.

The method returns control before the subscribe completes. Completion can be tracked by:

• Waiting on the supplied token MqttToken.waitForCompletion() or
• Passing in a callback IMqttActionListener to this method

Specified by:

subscribe in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Parameters:

topic - one or more topics to subscribe to, which can include wildcards

qos - the maximum quality of service to subscribe each topic at.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 subscription.

userContext - optional object used to pass context to the callback. Use null if not required.

callback - optional listener that will be notified when subscribe has completed

Returns:

token used to track and wait for the subscribe to complete. The token will be passed to callback methods if set.

Throws:

org.eclipse.paho.client.mqttv3.MqttException - if there was an error registering the subscription.

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

subscribe

public org.eclipse.paho.client.mqttv3.IMqttToken subscribe(java.lang.String topicFilter,
                                                           int qos,
                                                           java.lang.Object userContext,
                                                           org.eclipse.paho.client.mqttv3.IMqttActionListener callback,
                                                           org.eclipse.paho.client.mqttv3.IMqttMessageListener messageListener)
                                                    throws org.eclipse.paho.client.mqttv3.MqttException

Subscribe to a topic, which may include wildcards.

Specified by:

subscribe in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

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.

userContext - optional object used to pass context to the callback. Use null if not required.

callback - optional listener that will be notified when subscribe has completed

messageListener - a callback to handle incoming messages

Returns:

token used to track and wait for the subscribe to complete. The token will be passed to callback methods if set.

Throws:

org.eclipse.paho.client.mqttv3.MqttException - if there was an error registering the subscription.

See Also:

subscribe(String[], int[], Object, IMqttActionListener)

subscribe

public org.eclipse.paho.client.mqttv3.IMqttToken subscribe(java.lang.String topicFilter,
                                                           int qos,
                                                           org.eclipse.paho.client.mqttv3.IMqttMessageListener messageListener)
                                                    throws org.eclipse.paho.client.mqttv3.MqttException

Subscribe to a topic, which may include wildcards.

Specified by:

subscribe in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

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.

messageListener - a callback to handle incoming messages

Returns:

token used to track and wait for the subscribe to complete. The token will be passed to callback methods if set.

Throws:

org.eclipse.paho.client.mqttv3.MqttException - if there was an error registering the subscription.

See Also:

subscribe(String[], int[], Object, IMqttActionListener)

subscribe

public org.eclipse.paho.client.mqttv3.IMqttToken subscribe(java.lang.String[] topicFilters,
                                                           int[] qos,
                                                           org.eclipse.paho.client.mqttv3.IMqttMessageListener[] messageListeners)
                                                    throws org.eclipse.paho.client.mqttv3.MqttException

Subscribe to multiple topics, each of which may include wildcards.

Provides an optimized way to subscribe to multiple topics compared to subscribing to each one individually.

Specified by:

subscribe in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Parameters:

topicFilters - one or more topics 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.

messageListeners - an array of callbacks to handle incoming messages

Returns:

token used to track and wait for the subscribe to complete. The token will be passed to callback methods if set.

Throws:

org.eclipse.paho.client.mqttv3.MqttException - if there was an error registering the subscription.

See Also:

subscribe(String[], int[], Object, IMqttActionListener)

subscribe

public org.eclipse.paho.client.mqttv3.IMqttToken subscribe(java.lang.String[] topicFilters,
                                                           int[] qos,
                                                           java.lang.Object userContext,
                                                           org.eclipse.paho.client.mqttv3.IMqttActionListener callback,
                                                           org.eclipse.paho.client.mqttv3.IMqttMessageListener[] messageListeners)
                                                    throws org.eclipse.paho.client.mqttv3.MqttException

Subscribe to multiple topics, each of which may include wildcards.

Provides an optimized way to subscribe to multiple topics compared to subscribing to each one individually.

Specified by:

subscribe in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Parameters:

topicFilters - one or more topics 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.

userContext - optional object used to pass context to the callback. Use null if not required.

callback - optional listener that will be notified when subscribe has completed

messageListeners - an array of callbacks to handle incoming messages

Returns:

token used to track and wait for the subscribe to complete. The token will be passed to callback methods if set.

Throws:

org.eclipse.paho.client.mqttv3.MqttException - if there was an error registering the subscription.

See Also:

subscribe(String[], int[], Object, IMqttActionListener)

unsubscribe

public org.eclipse.paho.client.mqttv3.IMqttToken unsubscribe(java.lang.String topic)
                                                      throws org.eclipse.paho.client.mqttv3.MqttException

Requests the server unsubscribe the client from a topic.

Specified by:

unsubscribe in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Parameters:

topic - the topic to unsubscribe from. It must match a topic specified on an earlier subscribe.

Returns:

token used to track and wait for the unsubscribe to complete. The token will be passed to callback methods if set.

Throws:

org.eclipse.paho.client.mqttv3.MqttException - if there was an error unregistering the subscription.

See Also:

unsubscribe(String[], Object, IMqttActionListener)

unsubscribe

public org.eclipse.paho.client.mqttv3.IMqttToken unsubscribe(java.lang.String[] topic)
                                                      throws org.eclipse.paho.client.mqttv3.MqttException

Requests the server to unsubscribe the client from one or more topics.

Specified by:

unsubscribe in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Parameters:

topic - one or more topics to unsubscribe from. Each topic must match one specified on an earlier subscription.

Returns:

token used to track and wait for the unsubscribe to complete. The token will be passed to callback methods if set.

Throws:

org.eclipse.paho.client.mqttv3.MqttException - if there was an error unregistering the subscription.

See Also:

unsubscribe(String[], Object, IMqttActionListener)

unsubscribe

public org.eclipse.paho.client.mqttv3.IMqttToken unsubscribe(java.lang.String topic,
                                                             java.lang.Object userContext,
                                                             org.eclipse.paho.client.mqttv3.IMqttActionListener callback)
                                                      throws org.eclipse.paho.client.mqttv3.MqttException

Requests the server to unsubscribe the client from a topics.

Specified by:

unsubscribe in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Parameters:

topic - the topic to unsubscribe from. It must match a topic specified on an earlier subscribe.

userContext - optional object used to pass context to the callback. Use null if not required.

callback - optional listener that will be notified when unsubscribe has completed

Returns:

token used to track and wait for the unsubscribe to complete. The token will be passed to callback methods if set.

Throws:

org.eclipse.paho.client.mqttv3.MqttException - if there was an error unregistering the subscription.

See Also:

unsubscribe(String[], Object, IMqttActionListener)

unsubscribe

public org.eclipse.paho.client.mqttv3.IMqttToken unsubscribe(java.lang.String[] topic,
                                                             java.lang.Object userContext,
                                                             org.eclipse.paho.client.mqttv3.IMqttActionListener callback)
                                                      throws org.eclipse.paho.client.mqttv3.MqttException

Requests the server to 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 matching 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 unsubscribe to succeed

The method returns control before the unsubscribe completes. Completion can be tracked by:

• Waiting on the returned token MqttToken.waitForCompletion() or
• Passing in a callback IMqttActionListener to this method

Specified by:

unsubscribe in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Parameters:

topic - one or more topics to unsubscribe from. Each topic must match one specified on an earlier subscription.

userContext - optional object used to pass context to the callback. Use null if not required.

callback - optional listener that will be notified when unsubscribe has completed

Returns:

token used to track and wait for the unsubscribe to complete. The token will be passed to callback methods if set.

Throws:

org.eclipse.paho.client.mqttv3.MqttException - if there was an error unregistering the subscription.

getPendingDeliveryTokens

public org.eclipse.paho.client.mqttv3.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 returns a token for each in-flight message to enable 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

Specified by:

getPendingDeliveryTokens in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Returns:

zero or more delivery tokens

setCallback

public void setCallback(org.eclipse.paho.client.mqttv3.MqttCallback callback)

Sets a callback listener to use for events that happen asynchronously.

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

• A new message has arrived and is ready to be processed
• The connection to the server has been lost
• Delivery of a message to the server has completed

Other events that track the progress of an individual operation such as connect and subscribe can be tracked using the MqttToken returned from each non-blocking method or using setting a IMqttActionListener on the non-blocking method.

Specified by:

setCallback in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Parameters:

callback - which will be invoked for certain asynchronous events

See Also:

MqttCallback

setTraceCallback

public void setTraceCallback(MqttTraceHandler traceCallback)

identify the callback to be invoked when making tracing calls back into the Activity

Parameters:

traceCallback - handler

setTraceEnabled

public void setTraceEnabled(boolean traceEnabled)

turn tracing on and off

Parameters:

traceEnabled - set true to enable trace, otherwise, set false to disable trace

onReceive

public void onReceive(android.content.Context context,
                      android.content.Intent intent)

Process incoming Intent objects representing the results of operations and asynchronous activities such as message received

Note: This is only a public method because the Android APIs require such.
This method should not be explicitly invoked.

Specified by:

onReceive in class android.content.BroadcastReceiver

acknowledgeMessage

public boolean acknowledgeMessage(java.lang.String messageId)

Acknowledges a message received on the MqttCallback.messageArrived(String, MqttMessage)

Parameters:

messageId - the messageId received from the MqttMessage (To access this field you need to cast MqttMessage to ParcelableMqttMessage)

Returns:

whether or not the message was successfully acknowledged

messageArrivedComplete

public void messageArrivedComplete(int messageId,
                                   int qos)
                            throws org.eclipse.paho.client.mqttv3.MqttException

Specified by:

messageArrivedComplete in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Throws:

org.eclipse.paho.client.mqttv3.MqttException

setManualAcks

public void setManualAcks(boolean manualAcks)

Specified by:

setManualAcks in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

setBufferOpts

public void setBufferOpts(org.eclipse.paho.client.mqttv3.DisconnectedBufferOptions bufferOpts)

Sets the DisconnectedBufferOptions for this client

Parameters:

bufferOpts - the DisconnectedBufferOptions

getBufferedMessageCount

public int getBufferedMessageCount()

getBufferedMessage

public org.eclipse.paho.client.mqttv3.MqttMessage getBufferedMessage(int bufferIndex)

deleteBufferedMessage

public void deleteBufferedMessage(int bufferIndex)

getSSLSocketFactory

public javax.net.ssl.SSLSocketFactory getSSLSocketFactory(java.io.InputStream keyStore,
                                                          java.lang.String password)
                                                   throws org.eclipse.paho.client.mqttv3.MqttSecurityException

Get the SSLSocketFactory using SSL key store and password

A convenience method, which will help user to create a SSLSocketFactory object

Parameters:

keyStore - the SSL key store which is generated by some SSL key tool, such as keytool in Java JDK

password - the password of the key store which is set when the key store is generated

Returns:

SSLSocketFactory used to connect to the server with SSL authentication

Throws:

org.eclipse.paho.client.mqttv3.MqttSecurityException - if there was any error when getting the SSLSocketFactory

disconnectForcibly

public void disconnectForcibly()
                        throws org.eclipse.paho.client.mqttv3.MqttException

Specified by:

disconnectForcibly in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Throws:

org.eclipse.paho.client.mqttv3.MqttException

disconnectForcibly

public void disconnectForcibly(long disconnectTimeout)
                        throws org.eclipse.paho.client.mqttv3.MqttException

Specified by:

disconnectForcibly in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Throws:

org.eclipse.paho.client.mqttv3.MqttException

disconnectForcibly

public void disconnectForcibly(long quiesceTimeout,
                               long disconnectTimeout)
                        throws org.eclipse.paho.client.mqttv3.MqttException

Specified by:

disconnectForcibly in interface org.eclipse.paho.client.mqttv3.IMqttAsyncClient

Throws:

org.eclipse.paho.client.mqttv3.MqttException

unregisterResources

public void unregisterResources()

Unregister receiver which receives intent from MqttService avoids IntentReceiver leaks.

registerResources

public void registerResources(android.content.Context context)

Register receiver to receiver intent from MqttService. Call this method when activity is hidden and become to show again.

Parameters:

context - - Current activity context.