org.eclipse.paho.android.service

Class MqttService

java.lang.Object

Service

org.eclipse.paho.android.service.MqttService

All Implemented Interfaces:

MqttTraceHandler

public class MqttService
extends Service
implements MqttTraceHandler

The android service which interfaces with an MQTT client implementation

The main API of MqttService is intended to pretty much mirror the IMqttAsyncClient with appropriate adjustments for the Android environment.
These adjustments usually consist of adding two parameters to each method :-

• invocationContext - a string passed from the application to identify the context of the operation (mainly included for support of the javascript API implementation)
• activityToken - a string passed from the Activity to relate back to a callback method or other context-specific data

To support multiple client connections, the bulk of the MQTT work is delegated to MqttConnection objects. These are identified by "client handle" strings, which is how the Activity, and the higher-level APIs refer to them.

Activities using this service are expected to start it and bind to it using the BIND_AUTO_CREATE flag. The life cycle of this service is based on this approach.

Operations are highly asynchronous - in most cases results are returned to the Activity by broadcasting one (or occasionally more) appropriate Intents, which the Activity is expected to register a listener for.
The Intents have an Action of MqttServiceConstants.CALLBACK_TO_ACTIVITY which allows the Activity to register a listener with an appropriate IntentFilter.
Further data is provided by "Extra Data" in the Intent, as follows :-

;

Name	Data Type	Value	Operations used for
MqttServiceConstants.CALLBACK_CLIENT_HANDLE	String	The clientHandle identifying the client which initiated this operation	All operations
MqttServiceConstants.CALLBACK_STATUS	Serializable	An Status value indicating success or otherwise of the operation	All operations
MqttServiceConstants.CALLBACK_ACTIVITY_TOKEN	String	the activityToken passed into the operation	All operations
MqttServiceConstants.CALLBACK_INVOCATION_CONTEXT	String	the invocationContext passed into the operation	All operations
MqttServiceConstants.CALLBACK_ACTION	String	one of MqttServiceConstants.SEND_ACTION MqttServiceConstants.UNSUBSCRIBE_ACTION MqttServiceConstants.SUBSCRIBE_ACTION MqttServiceConstants.DISCONNECT_ACTION MqttServiceConstants.CONNECT_ACTION MqttServiceConstants.MESSAGE_ARRIVED_ACTION MqttServiceConstants.MESSAGE_DELIVERED_ACTION MqttServiceConstants.ON_CONNECTION_LOST_ACTION	All operations
MqttServiceConstants.CALLBACK_ERROR_MESSAGE	String	A suitable error message (taken from the relevant exception where possible)	All failing operations
MqttServiceConstants.CALLBACK_ERROR_NUMBER	int	A suitable error code (taken from the relevant exception where possible)	All failing operations
MqttServiceConstants.CALLBACK_EXCEPTION_STACK	String	The stacktrace of the failing call	The Connection Lost event
MqttServiceConstants.CALLBACK_MESSAGE_ID	String	The identifier for the message in the message store, used by the Activity to acknowledge the arrival of the message, so that the service may remove it from the store	The Message Arrived event
MqttServiceConstants.CALLBACK_DESTINATION_NAME	String	The topic on which the message was received	The Message Arrived event
MqttServiceConstants.CALLBACK_MESSAGE_PARCEL	Parcelable	The new message encapsulated in Android Parcelable format as a ParcelableMqttMessage	The Message Arrived event

Field Summary

Fields

Modifier and Type	Field and Description
(package private) MessageStore	messageStore
(package private) static java.lang.String	TAG

Constructor Summary

Constructors

Constructor and Description
MqttService()

Method Summary

Methods

Modifier and Type	Method and Description
Status	acknowledgeMessageArrival(java.lang.String clientHandle, java.lang.String id) Called by the Activity when a message has been passed back to the application
(package private) void	callbackToActivity(java.lang.String clientHandle, Status status, Bundle dataBundle) pass data back to the Activity, by building a suitable Intent object and broadcasting it
void	close(java.lang.String clientHandle) Close connection from a particular client
void	connect(java.lang.String clientHandle, org.eclipse.paho.client.mqttv3.MqttConnectOptions connectOptions, java.lang.String invocationContext, java.lang.String activityToken) Connect to the MQTT server specified by a particular client
void	disconnect(java.lang.String clientHandle, long quiesceTimeout, java.lang.String invocationContext, java.lang.String activityToken) Disconnect from the server
void	disconnect(java.lang.String clientHandle, java.lang.String invocationContext, java.lang.String activityToken) Disconnect from the server
java.lang.String	getClient(java.lang.String serverURI, java.lang.String clientId, java.lang.String contextId, org.eclipse.paho.client.mqttv3.MqttClientPersistence persistence) Get an MqttConnection object to represent a connection to a server
org.eclipse.paho.client.mqttv3.IMqttDeliveryToken[]	getPendingDeliveryTokens(java.lang.String clientHandle) Get tokens for all outstanding deliveries for a client
boolean	isConnected(java.lang.String clientHandle) Get the status of a specific client
boolean	isOnline()
boolean	isTraceEnabled() Check whether trace is on or off.
void	notifyClientsOffline() Notify clients we're offline
IBinder	onBind(Intent intent)
void	onCreate()
void	onDestroy()
int	onStartCommand(Intent intent, int flags, int startId)
org.eclipse.paho.client.mqttv3.IMqttDeliveryToken	publish(java.lang.String clientHandle, java.lang.String topic, byte[] payload, int qos, boolean retained, java.lang.String invocationContext, java.lang.String activityToken) Publish a message to a topic
org.eclipse.paho.client.mqttv3.IMqttDeliveryToken	publish(java.lang.String clientHandle, java.lang.String topic, org.eclipse.paho.client.mqttv3.MqttMessage message, java.lang.String invocationContext, java.lang.String activityToken) Publish a message to a topic
(package private) void	reconnect() Request all clients to reconnect if appropriate
void	setTraceCallbackId(java.lang.String traceCallbackId) Identify the callbackId to be passed when making tracing calls back into the Activity
void	setTraceEnabled(boolean traceEnabled) Turn tracing on and off
void	subscribe(java.lang.String clientHandle, java.lang.String[] topic, int[] qos, java.lang.String invocationContext, java.lang.String activityToken) Subscribe to one or more topics
void	subscribe(java.lang.String clientHandle, java.lang.String topic, int qos, java.lang.String invocationContext, java.lang.String activityToken) Subscribe to a topic
void	traceDebug(java.lang.String tag, java.lang.String message) Trace debugging information
void	traceError(java.lang.String tag, java.lang.String message) Trace error information
void	traceException(java.lang.String tag, java.lang.String message, java.lang.Exception e) trace exceptions
void	unsubscribe(java.lang.String clientHandle, java.lang.String[] topic, java.lang.String invocationContext, java.lang.String activityToken) Unsubscribe from one or more topics
void	unsubscribe(java.lang.String clientHandle, java.lang.String topic, java.lang.String invocationContext, java.lang.String activityToken) Unsubscribe from a topic

Methods inherited from class java.lang.Object

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

Field Detail

TAG

static final java.lang.String TAG

See Also:

Constant Field Values

messageStore

MessageStore messageStore

Constructor Detail

MqttService

public MqttService()

Method Detail

callbackToActivity

void callbackToActivity(java.lang.String clientHandle,
                      Status status,
                      Bundle dataBundle)

pass data back to the Activity, by building a suitable Intent object and broadcasting it

Parameters:

clientHandle - source of the data

status - OK or Error

dataBundle - the data to be passed

getClient

public java.lang.String getClient(java.lang.String serverURI,
                         java.lang.String clientId,
                         java.lang.String contextId,
                         org.eclipse.paho.client.mqttv3.MqttClientPersistence persistence)

Get an MqttConnection object to represent a connection to a server

Parameters:

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

contextId - specifies the app conext info to make a difference between apps

Returns:

a string to be used by the Activity as a "handle" for this MqttConnection

connect

public void connect(java.lang.String clientHandle,
           org.eclipse.paho.client.mqttv3.MqttConnectOptions connectOptions,
           java.lang.String invocationContext,
           java.lang.String activityToken)
             throws org.eclipse.paho.client.mqttv3.MqttSecurityException,
                    org.eclipse.paho.client.mqttv3.MqttException

Connect to the MQTT server specified by a particular client

Parameters:

clientHandle - identifies the MqttConnection to use

connectOptions - the MQTT connection options to be used

invocationContext - arbitrary data to be passed back to the application

activityToken - arbitrary identifier to be passed back to the Activity

Throws:

org.eclipse.paho.client.mqttv3.MqttSecurityException

org.eclipse.paho.client.mqttv3.MqttException

reconnect

void reconnect()

Request all clients to reconnect if appropriate

close

public void close(java.lang.String clientHandle)

Close connection from a particular client

Parameters:

clientHandle - identifies the MqttConnection to use

disconnect

public void disconnect(java.lang.String clientHandle,
              java.lang.String invocationContext,
              java.lang.String activityToken)

Disconnect from the server

Parameters:

clientHandle - identifies the MqttConnection to use

invocationContext - arbitrary data to be passed back to the application

activityToken - arbitrary identifier to be passed back to the Activity

disconnect

public void disconnect(java.lang.String clientHandle,
              long quiesceTimeout,
              java.lang.String invocationContext,
              java.lang.String activityToken)

Disconnect from the server

Parameters:

clientHandle - identifies the MqttConnection to use

quiesceTimeout - in milliseconds

invocationContext - arbitrary data to be passed back to the application

activityToken - arbitrary identifier to be passed back to the Activity

isConnected

public boolean isConnected(java.lang.String clientHandle)

Get the status of a specific client

Parameters:

clientHandle - identifies the MqttConnection to use

Returns:

true if the specified client is connected to an MQTT server

publish

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

Publish a message to a topic

Parameters:

clientHandle - identifies the MqttConnection to use

topic - the topic to which to publish

payload - the content of the message to publish

qos - the quality of service requested

retained - whether the MQTT server should retain this message

invocationContext - arbitrary data to be passed back to the application

activityToken - arbitrary identifier to be passed back to the Activity

Returns:

token for tracking the operation

Throws:

org.eclipse.paho.client.mqttv3.MqttPersistenceException

org.eclipse.paho.client.mqttv3.MqttException

publish

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

Publish a message to a topic

Parameters:

clientHandle - identifies the MqttConnection to use

topic - the topic to which to publish

message - the message to publish

invocationContext - arbitrary data to be passed back to the application

activityToken - arbitrary identifier to be passed back to the Activity

Returns:

token for tracking the operation

Throws:

org.eclipse.paho.client.mqttv3.MqttPersistenceException

org.eclipse.paho.client.mqttv3.MqttException

subscribe

public void subscribe(java.lang.String clientHandle,
             java.lang.String topic,
             int qos,
             java.lang.String invocationContext,
             java.lang.String activityToken)

Subscribe to a topic

Parameters:

clientHandle - identifies the MqttConnection to use

topic - a possibly wildcarded topic name

qos - requested quality of service for the topic

invocationContext - arbitrary data to be passed back to the application

activityToken - arbitrary identifier to be passed back to the Activity

subscribe

public void subscribe(java.lang.String clientHandle,
             java.lang.String[] topic,
             int[] qos,
             java.lang.String invocationContext,
             java.lang.String activityToken)

Subscribe to one or more topics

Parameters:

clientHandle - identifies the MqttConnection to use

topic - a list of possibly wildcarded topic names

qos - requested quality of service for each topic

invocationContext - arbitrary data to be passed back to the application

activityToken - arbitrary identifier to be passed back to the Activity

unsubscribe

public void unsubscribe(java.lang.String clientHandle,
               java.lang.String topic,
               java.lang.String invocationContext,
               java.lang.String activityToken)

Unsubscribe from a topic

Parameters:

clientHandle - identifies the MqttConnection

topic - a possibly wildcarded topic name

invocationContext - arbitrary data to be passed back to the application

activityToken - arbitrary identifier to be passed back to the Activity

unsubscribe

public void unsubscribe(java.lang.String clientHandle,
               java.lang.String[] topic,
               java.lang.String invocationContext,
               java.lang.String activityToken)

Unsubscribe from one or more topics

Parameters:

clientHandle - identifies the MqttConnection

topic - a list of possibly wildcarded topic names

invocationContext - arbitrary data to be passed back to the application

activityToken - arbitrary identifier to be passed back to the Activity

getPendingDeliveryTokens

public org.eclipse.paho.client.mqttv3.IMqttDeliveryToken[] getPendingDeliveryTokens(java.lang.String clientHandle)

Get tokens for all outstanding deliveries for a client

Parameters:

clientHandle - identifies the MqttConnection

Returns:

an array (possibly empty) of tokens

acknowledgeMessageArrival

public Status acknowledgeMessageArrival(java.lang.String clientHandle,
                               java.lang.String id)

Called by the Activity when a message has been passed back to the application

Parameters:

clientHandle - identifier for the client which received the message

id - identifier for the MQTT message

onCreate

public void onCreate()

See Also:

android.app.Service#onCreate()

onDestroy

public void onDestroy()

See Also:

android.app.Service#onDestroy()

onBind

public IBinder onBind(Intent intent)

See Also:

android.app.Service#onBind(Intent)

onStartCommand

public int onStartCommand(Intent intent,
                 int flags,
                 int startId)

See Also:

android.app.Service#onStartCommand(Intent,int,int)

setTraceCallbackId

public void setTraceCallbackId(java.lang.String traceCallbackId)

Identify the callbackId to be passed when making tracing calls back into the Activity

Parameters:

traceCallbackId - identifier to the callback into the Activity

setTraceEnabled

public void setTraceEnabled(boolean traceEnabled)

Turn tracing on and off

Parameters:

traceEnabled - set true to turn on tracing, false to turn off tracing

isTraceEnabled

public boolean isTraceEnabled()

Check whether trace is on or off.

Returns:

the state of trace

traceDebug

public void traceDebug(java.lang.String tag,
              java.lang.String message)

Trace debugging information

Specified by:

traceDebug in interface MqttTraceHandler

Parameters:

tag - identifier for the source of the trace

message - the text to be traced

traceError

public void traceError(java.lang.String tag,
              java.lang.String message)

Trace error information

Specified by:

traceError in interface MqttTraceHandler

Parameters:

tag - identifier for the source of the trace

message - the text to be traced

traceException

public void traceException(java.lang.String tag,
                  java.lang.String message,
                  java.lang.Exception e)

trace exceptions

Specified by:

traceException in interface MqttTraceHandler

Parameters:

tag - identifier for the source of the trace

message - the text to be traced

e - the exception

isOnline

public boolean isOnline()

Returns:

whether the android service can be regarded as online

notifyClientsOffline

public void notifyClientsOffline()

Notify clients we're offline