com.eurotech.framework.cloud
Interface CloudClient
public interface CloudClient
The CloudClient is designed to be used by single application bundles.
CloudClient instances are acquired from the CloudService and they
are released when the work is completed. Generally, a CloudClient
is acquired during the activation phase of a bundle and it is released
during the deactivation phase.
CloudClient leverages the DataService
for all interactions with the transport layer and the communication
with the remote server. CloudClient establishes a set of default
subscriptions that allow remote servers or other devices to direct messages
to the application instance.
If the bundle using the CloudClient relies on custom subscriptions
beyond the default ones, it is responsibility of the application to implement
the CloudClientListener#connectionRestored
callback method in the
CloudCallbackHandler to restore the subscriptions it needs.
The CloudClient.release method will unsubscribe all subscriptions
incurred by this client and it will unregister this CloudClient
instance from the list of CloudCallbackHandlers registered.
There can be more than one instance of CloudClient in the system,
ideally one per ApplicationId but this is not enforced.
The class accepts more than one callback handler; all registered handlers are invoked
when a message is received. It is up to the received to analyze the topic
of the message received and handle it appropriately.
The CloudClient publishes and receives messages using a topic namespace
following a structure as: [CRTL_PREFIX/]accountName/deviceId/appId/appTopic.
- CRTL_PREFIX: is an optional prefix to denote topic used for control messages
as opposed to data messages. The framework makes use of control topics to
separate management messages like replies from those used for application data.
- accountName: an unique identifier that represents a group of devices and users
- deviceId: an unique identifier within an account that represents a single gateway device.
By default, the MAC address of its primary network interface is generally used as the deviceId of the gateway.
In the case of an MQTT transport, for example, deviceId maps to the Client Identifier (Client ID).
- appId: an identifier to denote an application running on the gateway device.
We suggest to version the application identifier in order to allow multiple versions of the application
to coexist, e.g. CONF-V1, CONF-V2, etc.
- appTopic topic defined and managed by the application.
accountName, deviceId, and applicationId are derived based on the configuration parameters
of the system where this instance is deployed while the applicationTopic is controlled
by the application. The following is an example of topic used for publishing where the prefix
used for the control Topics is $EDC.
- publish: accountName/deviceId/applicationId/appTopic
- controlPublish: $EDC/accountName/assetId/applicationId/appTopic
- subscribe: accountName/deviceId/applicationId/appTopic
- controlSubscribe: $EDC/accountName/deviceId/applicationId/appTopic
- default subscriptions: $EDC/accountName/$ALL/#, $EDC/accountName/deviceId/applicationId/#
Note that the default subscription of a CloudClient allows remote servers
or applications running on other devices to publish messages addressed
to specific applications running on specific devices.
Method Summary |
void |
addCloudClientListener(CloudClientListener cloudClientListener)
Adds a CloudCallbackHandler with this CloudClient. |
int |
controlPublish(String appTopic,
EsfPayload payload,
int qos,
boolean retain,
int priority)
Publishes a control message to the remote server. |
int |
controlPublish(String deviceId,
String appTopic,
byte[] payload,
int qos,
boolean retain,
int priority)
Publishes a control message to the remote server addressing it to another device
with a raw byte array payload. |
int |
controlPublish(String deviceId,
String appTopic,
EsfPayload payload,
int qos,
boolean retain,
int priority)
Publishes a control message to the remote server addressing it to another device. |
void |
controlSubscribe(String appTopic,
int qos)
Subscribes to a control topic with the remote server. |
void |
controlUnsubscribe(String appTopic)
Unsubscribes to a control topic with the remote server. |
String |
getApplicationId()
Returns the applicationId of this CloudClient |
List<Integer> |
getDroppedInFlightMessageIds()
Finds the list of identifiers of in-flight messages that have been dropped. |
List<Integer> |
getInFlightMessageIds()
Finds the list of identifiers of messages that are still in-flight
(messages published but not confirmed yet). |
List<Integer> |
getUnpublishedMessageIds()
Gets the list of identifiers of messages that have not been published yet. |
boolean |
isConnected()
Returns an indication of whether the connection to the remote server is established. |
int |
publish(String appTopic,
byte[] payload,
int qos,
boolean retain,
int priority)
Publishes a message to the remote server with a raw byte array payload. |
int |
publish(String appTopic,
EsfPayload payload,
int qos,
boolean retain)
Publishes a message to the remote server using the default priority 5. |
int |
publish(String appTopic,
EsfPayload payload,
int qos,
boolean retain,
int priority)
Publishes a message to the remote server. |
void |
release()
Releases this CloudClient handle. |
void |
removeCloudClientListener(CloudClientListener cloudClientListener)
Removes a CloudCallbackHandler from this CloudClient. |
void |
subscribe(String appTopic,
int qos)
Subscribes to a topic with the remote server. |
void |
unsubscribe(String appTopic)
Unubscribes to a topic with the remote server. |
getApplicationId
String getApplicationId()
- Returns the applicationId of this CloudClient
- Returns:
- applicationId
release
void release()
- Releases this CloudClient handle. This instance should no longer be used.
Note: CloudClient does not unsubscribes all subscriptions incurred by this client,
this responsibility is left to the application developer
isConnected
boolean isConnected()
- Returns an indication of whether the connection to the remote server is established.
If your application needs to manage the connection directly, it can use the
DataService.connect()
and DataService.disconnect(long)
methods.
- Returns:
- boolean, whether connection to broker is established.
publish
int publish(String appTopic,
EsfPayload payload,
int qos,
boolean retain)
throws EsfException
- Publishes a message to the remote server using the default priority 5.
Before passing the message the to
DataService
,
the CloudClient will manipulate the provided topic by appending the necessary parts
to achieve topic partitioning and device identification. It is also responsible to
encode the EsfPayload
payload into binary format.
The EsfStoreCapacityReachedException is thrown if the database buffer
has reached its capacity for messages that are not yet published or
they are still in transit.
- Parameters:
appTopic
- A String specifying the application portion of the topic the message is published on.payload
- An EsfPayload representing the message to be publishedqos
- An integer specifying the quality of service the message was published on.retain
- Whether or not the broker should retain the message
- Returns:
- The published message's ID.
- Throws:
EsfException
publish
int publish(String appTopic,
EsfPayload payload,
int qos,
boolean retain,
int priority)
throws EsfException
- Publishes a message to the remote server.
Before passing the message the to
DataService
,
the CloudClient will manipulate the provided topic by appending the necessary parts
to achieve topic partitioning and device identification. It is also responsible to
encode the EsfPayload
payload into binary format.
The priority argument can be used to control the relative ordering of this
message with other messages that may be currently queued for publishing.
Priority level 0 (highest) should be used sparingly and reserved for
messages that should be sent with the minimum latency. Life-cycle messages
(e.g. device start and stop) are an example of messages that are
published by the framework with priority 0.
Priority 1 messages are used by the framework to publish response messages
in request/response conversations to prevent a timeout at the requester.
Application should consider using priority 5 or higher.
The EsfStoreCapacityReachedException is thrown if the database buffer
has reached its capacity for messages that are not yet published or
they are still in transit. The limit does not apply to internal messages with the priority less than 2.
These priority levels are reserved to the framework which uses it for life-cycle messages
- birth and death certificates - and replies to request/response flows.
- Parameters:
appTopic
- A String specifying the application portion of the topic the message is published on.payload
- An EsfPayload representing the message to be publishedqos
- An integer specifying the quality of service the message was published on.retain
- Whether or not the broker should retain the messagepriority
- Relative ordering of this message with other messages that may be currently queued for publishing.
- Returns:
- The published message's ID.
- Throws:
EsfException
publish
int publish(String appTopic,
byte[] payload,
int qos,
boolean retain,
int priority)
throws EsfException
- Publishes a message to the remote server with a raw byte array payload.
This is the lowest level publish API exposed by the CloudClient.
Before passing the message the to
DataService
,
the CloudClient will manipulate the provided topic by appending the necessary parts
to achieve topic partitioning and device identification.
The priority argument can be used to control the relative ordering of this
message with other messages that may be currently queued for publishing.
Priority level 0 (highest) should be used sparingly and reserved for
messages that should be sent with the minimum latency. Life-cycle messages
(e.g. device start and stop) are an example of messages that are
published by the framework with priority 0.
Priority 1 messages are used by the framework to publish response messages
in request/response conversations to prevent a timeout at the requester.
Application should consider using priority 5 or higher.
The EsfStoreCapacityReachedException is thrown if the database buffer
has reached its capacity for messages that are not yet published or
they are still in transit. The limit does not apply to internal messages with the priority less than 2.
These priority levels are reserved to the framework which uses it for life-cycle messages
- birth and death certificates - and replies to request/response flows.
- Parameters:
appTopic
- A String specifying the application portion of the topic the message is published on.payload
- Binary payload representing the message to be publishedqos
- An integer specifying the quality of service the message was published on.retain
- Whether or not the broker should retain the messagepriority
- Relative ordering of this message with other messages that may be currently queued for publishing.
- Returns:
- The published message's ID.
- Throws:
EsfException
controlPublish
int controlPublish(String appTopic,
EsfPayload payload,
int qos,
boolean retain,
int priority)
throws EsfException
- Publishes a control message to the remote server. Control messages are qualified with an
additional prefix appended at the beginning of the target topic. The
prefix is configured as a property of the
CloudService
and it appended
automatically by this controlPublish method. Just as publish(java.lang.String, com.eurotech.framework.message.EsfPayload, int, boolean)
, the
controlPublish method will manipulate the provided topic by appending the necessary parts
to achieve topic partitioning including device identification and encode
the EsfPayload
payload into binary format.
The priority argument can be used to control the relative ordering of this
message with other messages that may be currently queued for publishing.
Priority level 0 (highest) should be used sparingly and reserved for
messages that should be sent with the minimum latency. Life-cycle messages
(e.g. device start and stop) are an example of messages that are
published by the framework with priority 0.
Priority 1 messages are used by the framework to publish response messages
in request/response conversations to prevent a timeout at the requester.
Application should consider using priority 5 or higher.
The EsfStoreCapacityReachedException is thrown if the database buffer
has reached its capacity for messages that are not yet published or
they are still in transit. The limit does not apply to internal messages with the priority less than 2.
These priority levels are reserved to the framework which uses it for life-cycle messages
- birth and death certificates - and replies to request/response flows.
- Parameters:
appTopic
- A String specifying the application topic the message is published on.payload
- An EsfPayload representing the message to be publishedqos
- An integer specifying the quality of service the message was published on.retain
- Whether or not the broker should retain the messagepriority
- Relative ordering of this message with other messages that may be currently queued for publishing.
- Returns:
- The published message's ID.
- Throws:
EsfException
controlPublish
int controlPublish(String deviceId,
String appTopic,
EsfPayload payload,
int qos,
boolean retain,
int priority)
throws EsfException
- Publishes a control message to the remote server addressing it to another device.
Control messages are qualified with an additional prefix appended at the beginning of the target topic.
The prefix is configured as a property of the
CloudService
and it appended
automatically by this controlPublish method. Just as publish(java.lang.String, com.eurotech.framework.message.EsfPayload, int, boolean)
, the
controlPublish method will manipulate the provided topic by appending the necessary parts
to achieve topic partitioning including device identification and encode
the EsfPayload
payload into binary format.
The priority argument can be used to control the relative ordering of this
message with other messages that may be currently queued for publishing.
Priority level 0 (highest) should be used sparingly and reserved for
messages that should be sent with the minimum latency. Life-cycle messages
(e.g. device start and stop) are an example of messages that are
published by the framework with priority 0.
Priority 1 messages are used by the framework to publish response messages
in request/response conversations to prevent a timeout at the requester.
Application should consider using priority 5 or higher.
The EsfStoreCapacityReachedException is thrown if the database buffer
has reached its capacity for messages that are not yet published or
they are still in transit. The limit does not apply to internal messages with the priority less than 2.
These priority levels are reserved to the framework which uses it for life-cycle messages
- birth and death certificates - and replies to request/response flows.
- Parameters:
deviceId
- A String specifying the asset ID.appTopic
- A String specifying the application topic the message is published on.payload
- An EsfPayload representing the message to be publishedqos
- An integer specifying the quality of service the message was published on.retain
- Whether or not the broker should retain the messagepriority
- Relative ordering of this message with other messages that may be currently queued for publishing.
- Returns:
- The published message's ID.
- Throws:
EsfException
controlPublish
int controlPublish(String deviceId,
String appTopic,
byte[] payload,
int qos,
boolean retain,
int priority)
throws EsfException
- Publishes a control message to the remote server addressing it to another device
with a raw byte array payload.
Control messages are qualified with an additional prefix appended at the beginning of the target topic.
The prefix is configured as a property of the
CloudService
and it appended
automatically by this controlPublish method. Just as publish(java.lang.String, com.eurotech.framework.message.EsfPayload, int, boolean)
, the
controlPublish method will manipulate the provided topic by appending the necessary parts
to achieve topic partitioning including device identification.
The priority argument can be used to control the relative ordering of this
message with other messages that may be currently queued for publishing.
Priority level 0 (highest) should be used sparingly and reserved for
messages that should be sent with the minimum latency. Life-cycle messages
(e.g. device start and stop) are an example of messages that are
published by the framework with priority 0.
Priority 1 messages are used by the framework to publish response messages
in request/response conversations to prevent a timeout at the requester.
Application should consider using priority 5 or higher.
The EsfStoreCapacityReachedException is thrown if the database buffer
has reached its capacity for messages that are not yet published or
they are still in transit. The limit does not apply to internal messages with the priority less than 2.
These priority levels are reserved to the framework which uses it for life-cycle messages
- birth and death certificates - and replies to request/response flows.
- Parameters:
deviceId
- A String specifying the asset ID.appTopic
- A String specifying the application topic the message is published on.payload
- Binary payload representing the message to be publishedqos
- An integer specifying the quality of service the message was published on.retain
- Whether or not the broker should retain the messagepriority
- Relative ordering of this message with other messages that may be currently queued for publishing.
- Returns:
- The published message's ID.
- Throws:
EsfException
subscribe
void subscribe(String appTopic,
int qos)
throws EsfException
- Subscribes to a topic with the remote server. The topic is specified as a String
object and the QoS is specified as an integer. The CloudClient will manipulate the
provided topic by appending the necessary parts to achieve topic partitioning and
device identification.
This is a synchronous call. If the subscribe fails, an exception will be thrown
that will contain information about the cause of the failure.
- Parameters:
appTopic
- A String object containing the application topic.qos
- An int containing the Quality of Service.
- Throws:
EsfException
controlSubscribe
void controlSubscribe(String appTopic,
int qos)
throws EsfException
- Subscribes to a control topic with the remote server. The topic is specified as a String
object and the QoS is specified as an integer. The CloudClient will manipulate the
provided topic by appending the necessary parts to achieve topic partitioning and
including control prefix and device identification.
This is a synchronous call. If the subscribe fails, an exception will be thrown
that will contain information about the cause of the failure.
- Parameters:
appTopic
- A String object containing the application topic.qos
- An int containing the Quality of Service.
- Throws:
EsfException
unsubscribe
void unsubscribe(String appTopic)
throws EsfException
- Unubscribes to a topic with the remote server. The topic is specified as a String
object and the QoS is specified as an integer. The CloudClient will manipulate the
provided topic by appending the necessary parts to achieve topic partitioning and
device identification.
This is a synchronous call. If the unsubscribe fails, an exception will be thrown
that will contain information about the cause of the failure.
- Parameters:
appTopic
- A String object containing the application topic.
- Throws:
EsfException
controlUnsubscribe
void controlUnsubscribe(String appTopic)
throws EsfException
- Unsubscribes to a control topic with the remote server. The topic is specified as a String
object and the QoS is specified as an integer. The CloudClient will manipulate the
provided topic by appending the necessary parts to achieve topic partitioning and
including control prefix and device identification.
This is a synchronous call. If the unsubscribe fails, an exception will be thrown
that will contain information about the cause of the failure.
- Parameters:
appTopic
- A String object containing the application topic.
- Throws:
EsfException
addCloudClientListener
void addCloudClientListener(CloudClientListener cloudClientListener)
- Adds a CloudCallbackHandler with this CloudClient. This handler
will receive events when a client publication has arrived, and
when a publish has been fully acknowledged by the remote server.
- Parameters:
cloudCallbackHandler
- An implementation of the CloudCallbackHandler interface.
removeCloudClientListener
void removeCloudClientListener(CloudClientListener cloudClientListener)
- Removes a CloudCallbackHandler from this CloudClient.
The provided CloudCallbackHandler will no longer receive the events
when a published message is received.
getUnpublishedMessageIds
List<Integer> getUnpublishedMessageIds()
throws EsfException
- Gets the list of identifiers of messages that have not been published yet.
- Returns:
-
- Throws:
EsfException
getInFlightMessageIds
List<Integer> getInFlightMessageIds()
throws EsfException
- Finds the list of identifiers of messages that are still in-flight
(messages published but not confirmed yet).
This only applies to messages published with QoS > 0.
- Returns:
-
- Throws:
EsfException
getDroppedInFlightMessageIds
List<Integer> getDroppedInFlightMessageIds()
throws EsfException
- Finds the list of identifiers of in-flight messages that have been dropped.
This only applies to messages published with QoS > 0.
On the establishment of a new connection, the service can be configured
either to republish or drop in-flight messages.
The former option can be used if service users tolerate publishing message
duplicates.
The latter option can be used it service users tolerate losing messages.
- Returns:
-
- Throws:
EsfException
Copyright © 2013. All Rights Reserved.