org.eclipse.paho.android.service

Class MqttService

java.lang.Object

android.content.Context

android.content.ContextWrapper

android.app.Service

org.eclipse.paho.android.service.MqttService

All Implemented Interfaces:

android.content.ComponentCallbacks, android.content.ComponentCallbacks2, MqttTraceHandler

public class MqttService
extends android.app.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 inherited from class android.app.Service

START_CONTINUATION_MASK, START_FLAG_REDELIVERY, START_FLAG_RETRY, START_NOT_STICKY, START_REDELIVER_INTENT, START_STICKY, START_STICKY_COMPATIBILITY, STOP_FOREGROUND_DETACH, STOP_FOREGROUND_REMOVE

Fields inherited from class android.content.Context

ACCESSIBILITY_SERVICE, ACCOUNT_SERVICE, ACTIVITY_SERVICE, ALARM_SERVICE, APP_OPS_SERVICE, APPWIDGET_SERVICE, AUDIO_SERVICE, BATTERY_SERVICE, BIND_ABOVE_CLIENT, BIND_ADJUST_WITH_ACTIVITY, BIND_ALLOW_OOM_MANAGEMENT, BIND_AUTO_CREATE, BIND_DEBUG_UNBIND, BIND_EXTERNAL_SERVICE, BIND_IMPORTANT, BIND_NOT_FOREGROUND, BIND_WAIVE_PRIORITY, BLUETOOTH_SERVICE, CAMERA_SERVICE, CAPTIONING_SERVICE, CARRIER_CONFIG_SERVICE, CLIPBOARD_SERVICE, CONNECTIVITY_SERVICE, CONSUMER_IR_SERVICE, CONTEXT_IGNORE_SECURITY, CONTEXT_INCLUDE_CODE, CONTEXT_RESTRICTED, DEVICE_POLICY_SERVICE, DISPLAY_SERVICE, DOWNLOAD_SERVICE, DROPBOX_SERVICE, FINGERPRINT_SERVICE, HARDWARE_PROPERTIES_SERVICE, INPUT_METHOD_SERVICE, INPUT_SERVICE, JOB_SCHEDULER_SERVICE, KEYGUARD_SERVICE, LAUNCHER_APPS_SERVICE, LAYOUT_INFLATER_SERVICE, LOCATION_SERVICE, MEDIA_PROJECTION_SERVICE, MEDIA_ROUTER_SERVICE, MEDIA_SESSION_SERVICE, MIDI_SERVICE, MODE_APPEND, MODE_ENABLE_WRITE_AHEAD_LOGGING, MODE_MULTI_PROCESS, MODE_NO_LOCALIZED_COLLATORS, MODE_PRIVATE, MODE_WORLD_READABLE, MODE_WORLD_WRITEABLE, NETWORK_STATS_SERVICE, NFC_SERVICE, NOTIFICATION_SERVICE, NSD_SERVICE, POWER_SERVICE, PRINT_SERVICE, RESTRICTIONS_SERVICE, SEARCH_SERVICE, SENSOR_SERVICE, STORAGE_SERVICE, SYSTEM_HEALTH_SERVICE, TELECOM_SERVICE, TELEPHONY_SERVICE, TELEPHONY_SUBSCRIPTION_SERVICE, TEXT_SERVICES_MANAGER_SERVICE, TV_INPUT_SERVICE, UI_MODE_SERVICE, USAGE_STATS_SERVICE, USB_SERVICE, USER_SERVICE, VIBRATOR_SERVICE, WALLPAPER_SERVICE, WIFI_P2P_SERVICE, WIFI_SERVICE, WINDOW_SERVICE

Fields inherited from interface android.content.ComponentCallbacks2

TRIM_MEMORY_BACKGROUND, TRIM_MEMORY_COMPLETE, TRIM_MEMORY_MODERATE, TRIM_MEMORY_RUNNING_CRITICAL, TRIM_MEMORY_RUNNING_LOW, TRIM_MEMORY_RUNNING_MODERATE, TRIM_MEMORY_UI_HIDDEN

Constructor Summary

Constructors

Constructor and Description
MqttService()

Method Summary

Modifier and Type	Method and Description
org.eclipse.paho.android.service.Status	acknowledgeMessageArrival(java.lang.String clientHandle, java.lang.String id) Called by the Activity when a message has been passed back to the application
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	deleteBufferedMessage(java.lang.String clientHandle, int bufferIndex)
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
org.eclipse.paho.client.mqttv3.MqttMessage	getBufferedMessage(java.lang.String clientHandle, int bufferIndex)
int	getBufferedMessageCount(java.lang.String clientHandle)
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.
android.os.IBinder	onBind(android.content.Intent intent)
void	onCreate()
void	onDestroy()
int	onStartCommand(android.content.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
void	setBufferOpts(java.lang.String clientHandle, org.eclipse.paho.client.mqttv3.DisconnectedBufferOptions bufferOpts) Sets the DisconnectedBufferOptions for this client
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[] topicFilters, int[] qos, java.lang.String invocationContext, java.lang.String activityToken, org.eclipse.paho.client.mqttv3.IMqttMessageListener[] messageListeners) Subscribe using topic filters
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 android.app.Service

dump, getApplication, onConfigurationChanged, onLowMemory, onRebind, onStart, onTaskRemoved, onTrimMemory, onUnbind, startForeground, stopForeground, stopForeground, stopSelf, stopSelf, stopSelfResult

Methods inherited from class android.content.ContextWrapper

attachBaseContext, bindService, checkCallingOrSelfPermission, checkCallingOrSelfUriPermission, checkCallingPermission, checkCallingUriPermission, checkPermission, checkSelfPermission, checkUriPermission, checkUriPermission, clearWallpaper, createConfigurationContext, createDeviceProtectedStorageContext, createDisplayContext, createPackageContext, databaseList, deleteDatabase, deleteFile, deleteSharedPreferences, enforceCallingOrSelfPermission, enforceCallingOrSelfUriPermission, enforceCallingPermission, enforceCallingUriPermission, enforcePermission, enforceUriPermission, enforceUriPermission, fileList, getApplicationContext, getApplicationInfo, getAssets, getBaseContext, getCacheDir, getClassLoader, getCodeCacheDir, getContentResolver, getDatabasePath, getDataDir, getDir, getExternalCacheDir, getExternalCacheDirs, getExternalFilesDir, getExternalFilesDirs, getExternalMediaDirs, getFilesDir, getFileStreamPath, getMainLooper, getNoBackupFilesDir, getObbDir, getObbDirs, getPackageCodePath, getPackageManager, getPackageName, getPackageResourcePath, getResources, getSharedPreferences, getSystemService, getSystemServiceName, getTheme, getWallpaper, getWallpaperDesiredMinimumHeight, getWallpaperDesiredMinimumWidth, grantUriPermission, isDeviceProtectedStorage, isRestricted, moveDatabaseFrom, moveSharedPreferencesFrom, openFileInput, openFileOutput, openOrCreateDatabase, openOrCreateDatabase, peekWallpaper, registerReceiver, registerReceiver, removeStickyBroadcast, removeStickyBroadcastAsUser, revokeUriPermission, sendBroadcast, sendBroadcast, sendBroadcastAsUser, sendBroadcastAsUser, sendOrderedBroadcast, sendOrderedBroadcast, sendOrderedBroadcastAsUser, sendStickyBroadcast, sendStickyBroadcastAsUser, sendStickyOrderedBroadcast, sendStickyOrderedBroadcastAsUser, setTheme, setWallpaper, setWallpaper, startActivities, startActivities, startActivity, startActivity, startInstrumentation, startIntentSender, startIntentSender, startService, stopService, unbindService, unregisterReceiver

Methods inherited from class android.content.Context

getColor, getColorStateList, getDrawable, getString, getString, getSystemService, getText, obtainStyledAttributes, obtainStyledAttributes, obtainStyledAttributes, obtainStyledAttributes, registerComponentCallbacks, unregisterComponentCallbacks

Methods inherited from class java.lang.Object

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

Constructor Detail

MqttService

public MqttService()

Method Detail

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

persistence - specifies the persistence layer to be used with this client

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 - thrown if there is a security exception

org.eclipse.paho.client.mqttv3.MqttException - thrown for all other MqttExceptions

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 - when a problem occurs storing the message

org.eclipse.paho.client.mqttv3.MqttException - if there was an error publishing the message

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 - when a problem occurs storing the message

org.eclipse.paho.client.mqttv3.MqttException - if there was an error publishing the message

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

subscribe

public void subscribe(java.lang.String clientHandle,
                      java.lang.String[] topicFilters,
                      int[] qos,
                      java.lang.String invocationContext,
                      java.lang.String activityToken,
                      org.eclipse.paho.client.mqttv3.IMqttMessageListener[] messageListeners)

Subscribe using topic filters

Parameters:

clientHandle - identifies the MqttConnection to use

topicFilters - a list of possibly wildcarded topicfilters

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

messageListeners - a callback to handle incoming messages

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 org.eclipse.paho.android.service.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

Returns:

Status

onCreate

public void onCreate()

Overrides:

onCreate in class android.app.Service

See Also:

Service.onCreate()

onDestroy

public void onDestroy()

Overrides:

onDestroy in class android.app.Service

See Also:

Service.onDestroy()

onBind

public android.os.IBinder onBind(android.content.Intent intent)

Specified by:

onBind in class android.app.Service

See Also:

Service.onBind(Intent)

onStartCommand

public int onStartCommand(android.content.Intent intent,
                          int flags,
                          int startId)

Overrides:

onStartCommand in class android.app.Service

See Also:

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

setBufferOpts

public void setBufferOpts(java.lang.String clientHandle,
                          org.eclipse.paho.client.mqttv3.DisconnectedBufferOptions bufferOpts)

Sets the DisconnectedBufferOptions for this client

Parameters:

clientHandle - identifier for the client

bufferOpts - the DisconnectedBufferOptions for this client

getBufferedMessageCount

public int getBufferedMessageCount(java.lang.String clientHandle)

getBufferedMessage

public org.eclipse.paho.client.mqttv3.MqttMessage getBufferedMessage(java.lang.String clientHandle,
                                                                     int bufferIndex)

deleteBufferedMessage

public void deleteBufferedMessage(java.lang.String clientHandle,
                                  int bufferIndex)