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.

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

Method Detail

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 published
qos - 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 published
qos - An integer specifying the quality of service the message was published on.
retain - Whether or not the broker should retain the message
priority - 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 published
qos - An integer specifying the quality of service the message was published on.
retain - Whether or not the broker should retain the message
priority - 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 published
qos - An integer specifying the quality of service the message was published on.
retain - Whether or not the broker should retain the message
priority - 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 published
qos - An integer specifying the quality of service the message was published on.
retain - Whether or not the broker should retain the message
priority - 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 published
qos - An integer specifying the quality of service the message was published on.
retain - Whether or not the broker should retain the message
priority - 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.