org.eclipse.kura.data

Interface DataService

public interface DataService

The DataService provides the ability of connecting to a remote broker, publish messages, subscribe to topics, receive messages on the subscribed topics, and disconnect from the remote message broker. The DataService delegates to the DataTransportService the implementation of the transport protocol used to interact with the remote server.
The DataService offers methods and configuration options to manage the connection to the remote server. For example, it can be configured to auto-connect to the remote server on start-up or it offers methods for applications to directly manage the connection. It also adds the capability of storing published messages in a persistent store and send them over the wire at a later time. The purpose is to relieve service users from implementing their own persistent store. Service users may publish messages independently on the DataService connection status.
In order to overcome the potential latencies introduced by buffering messages, the DataService allows to assign a priority level to each published message. Dependently on the store configuration there are certain guarantees that stored messages are not lost due to sudden crashes or power outages.
The whiteboard pattern http://www.osgi.org/wiki/uploads/Links/whiteboard.pdf is used to notify the service users about events such as message arrived, connection lost etc. DataServiceListener

Method Summary

Methods

Modifier and Type	Method and Description
void	connect() Connects to the broker if not already connected.
void	disconnect(long quiesceTimeout) Disconnects from the broker.
List<Integer>	getDroppedInFlightMessageIds(String topicRegex) Finds the list of identifiers of in-flight messages that have been dropped.
List<Integer>	getInFlightMessageIds(String topicRegex) Finds the list of identifiers of messages that are still in-flight (messages published but not confirmed yet).
int	getRetryInterval()
List<Integer>	getUnpublishedMessageIds(String topicRegex) Finds the list of identifiers of messages that have not been published yet.
boolean	isAutoConnectEnabled()
boolean	isConnected() Answers if the DataService is connected to the broker.
int	publish(String topic, byte[] payload, int qos, boolean retain, int priority) Publishes a message to the broker.
void	subscribe(String topic, int qos) Subscribes to the specified topic with the remote server.
void	unsubscribe(String topic) Unubscribes to the specified topic with the remote server.

Method Detail

connect

void connect()
             throws KuraConnectException

Connects to the broker if not already connected.

Throws:

KuraConnectException

isConnected

boolean isConnected()

Answers if the DataService is connected to the broker.

Returns:

isAutoConnectEnabled

boolean isAutoConnectEnabled()

getRetryInterval

int getRetryInterval()

disconnect

void disconnect(long quiesceTimeout)

Disconnects from the broker. This method will block, up to the specified duration, allowing the protocol implementation to complete delivery of in-flight messages before actually disconnecting from the broker. If the Data Service is configured to auto-connect on startup and it's explicitly disconnected it will not automatically reconnect.

Parameters:

quiesceTimeout -

subscribe

void subscribe(String topic,
             int qos)
               throws KuraTimeoutException,
                      KuraException,
                      KuraNotConnectedException

Subscribes to the specified topic with the remote server. The method requires an active connection with the remote server and it is operates synchronously. The implementation is a pass-through to the DataTransportService.subscribe(java.lang.String, int) method.

Parameters:

topic -

qos -

Throws:

KuraTimeoutException

KuraException

KuraNotConnectedException - TODO

unsubscribe

void unsubscribe(String topic)
                 throws KuraTimeoutException,
                        KuraException,
                        KuraNotConnectedException

Unubscribes to the specified topic with the remote server. The method requires an active connection with the remote server and it is operates synchronously. The implementation is a pass-through to the DataTransportService.unsubscribe(java.lang.String) method.

Parameters:

topic -

Throws:

KuraTimeoutException

KuraException

KuraNotConnectedException - TODO

publish

int publish(String topic,
          byte[] payload,
          int qos,
          boolean retain,
          int priority)
            throws KuraStoreException

Publishes a message to the broker. This method quickly returns deferring the actual message publication accordingly to the current service policy and to the specified priority, 0 being the highest. Messages are confirmed asynchronously to the caller by the DataServiceListener.onMessageConfirmed(int, java.lang.String) callback. A unique identifier is always returned, independently on the specified QoS or priority level, which can be used to match the asynchronous message confirm. The actual semantics associated to a message confirm is as follows:

• For messages published at QoS = 0, receiving the confirm just means that the message is about to be transmitted on the wire without any guarantee that it eventually will.
• For messages published at QoS > 0, receiving the confirm means that the broker acknowledged the message.

Priority level 0 (highest) should be used sparingly and reserved for messages that should be sent with the minimum latency. For example Cloud life-cycle messages are published with priority 0 as soon the connection is established and just before disconnecting.
Data messages, tolerating an higher latency, may be published with a lower priority. Within each priority level and each QoS level, messages are guaranteed do be delivered in order (oldest first).
The KuraStoreCapacityReachedException 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:

topic -

payload -

qos -

retain -

priority -

Returns:

Throws:

KuraStoreException

getUnpublishedMessageIds

List<Integer> getUnpublishedMessageIds(String topicRegex)
                                       throws KuraStoreException

Finds the list of identifiers of messages that have not been published yet. Given the service has no means of knowing who published the message, a regex topic must be specified in order to find only the relevant identifiers.

Parameters:

topicRegex -

Returns:

Throws:

KuraStoreException

getInFlightMessageIds

List<Integer> getInFlightMessageIds(String topicRegex)
                                    throws KuraStoreException

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. Given the service has no means of knowing who published the message, a regex topic must be specified in order to find only the relevant identifiers.

Parameters:

topicRegex -

Returns:

Throws:

KuraStoreException

getDroppedInFlightMessageIds

List<Integer> getDroppedInFlightMessageIds(String topicRegex)
                                           throws KuraStoreException

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. Given the service has no means of knowing who published the message, a regex topic must be specified in order to find only the relevant identifiers.

Throws:

KuraStoreException