DataService (Eclipse Kura 3.0.0)

```
@ProviderType
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 is used to notify the service users about events such as message arrived, connection lost etc. through the DataServiceListener. DataServiceListener

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`addDataServiceListener(DataServiceListener listener)` Adds a listener.
`void`	`connect()` Connects to the broker if not already connected.
`void`	`disconnect(long quiesceTimeout)` Disconnects from the broker.
`java.util.List<java.lang.Integer>`	`getDroppedInFlightMessageIds(java.lang.String topicRegex)` Finds the list of identifiers of in-flight messages that have been dropped.
`java.util.List<java.lang.Integer>`	`getInFlightMessageIds(java.lang.String topicRegex)` Finds the list of identifiers of messages that are still in-flight (messages published but not confirmed yet).
`int`	`getRetryInterval()`
`java.util.List<java.lang.Integer>`	`getUnpublishedMessageIds(java.lang.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(java.lang.String topic, byte[] payload, int qos, boolean retain, int priority)` Publishes a message to the broker.
`void`	`removeDataServiceListener(DataServiceListener listener)` Removes a listener.
`void`	`subscribe(java.lang.String topic, int qos)` Subscribes to the specified topic with the remote server.
`void`	`unsubscribe(java.lang.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(java.lang.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(java.lang.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(java.lang.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
```
java.util.List<java.lang.Integer> getUnpublishedMessageIds(java.lang.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
```
java.util.List<java.lang.Integer> getInFlightMessageIds(java.lang.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
```
java.util.List<java.lang.Integer> getDroppedInFlightMessageIds(java.lang.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
  - addDataServiceListener
```
void addDataServiceListener(DataServiceListener listener)
```
    Adds a listener.
    
    Parameters:
    
    listener -
    
    Since:
    
    1.0.8
  - removeDataServiceListener
```
void removeDataServiceListener(DataServiceListener listener)
```
    Removes a listener.
    
    Parameters:
    
    listener -
    
    Since:
    
    1.0.8

Interface DataService

Method Summary

Method Detail

connect

isConnected

isAutoConnectEnabled

getRetryInterval

disconnect

subscribe

unsubscribe

publish

getUnpublishedMessageIds

getInFlightMessageIds

getDroppedInFlightMessageIds

addDataServiceListener

removeDataServiceListener