com.eurotech.framework.data
Interface DataTransportService

public interface DataTransportService

DataTransportService implementations provide 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 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. DataTransportListener

Method Summary

void	connect() Connects to the remote broker.
void	disconnect(long quiesceTimeout) Disconnects from the broker.
String	getAccountName() Returns the account name associated with the DataTransportService
String	getBrokerUrl()
String	getUsername()
boolean	isConnected() Returns true if the DataTransportService is currently connected to the remote server.
DataTransportToken	publish(String topic, byte[] payload, int qos, boolean retain) Enqueues a message for publishing with the underlying transport implementation.
void	subscribe(String topic, int qos) Subscribes to a topic on the broker.
void	unsubscribe(String topic) Unsubscribes to a topic on the broker.

Method Detail

connect

void connect()
             throws EsfConnectException

Connects to the remote broker. This method will block until the connection is established or a timeout occurs. The actual configuration needed to establish a connection is protocol specific (e.g. MQTT) and is exposed through the ConfigurationAdmin.

Throws:

EsfConnectException - the caller MAY retry connecting a later time.

isConnected

boolean isConnected()

Returns true if the DataTransportService is currently connected to the remote server.

getBrokerUrl

String getBrokerUrl()

getAccountName

String getAccountName()

Returns the account name associated with the DataTransportService

getUsername

String getUsername()

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.

Parameters:

quiesceTimeout - - timeout that will be used before forcing a disconnect

subscribe

void subscribe(String topic,
               int qos)
               throws EsfTimeoutException,
                      EsfException,
                      EsfNotConnectedException

Subscribes to a topic on the broker. This method MAY block until the underlying protocol message (e.g. the MQTT SUBSCRIBE message) is acknowledged by the broker or a timeout occurs. This message is idempotent so the caller may safely retry subscribing. The timeout interval used by the service is configurable through the ConfigurationService.

Parameters:

topic -

qos -

Throws:

EsfTimeoutException - TODO

EsfException

EsfNotConnectedException - TODO

unsubscribe

void unsubscribe(String topic)
                 throws EsfTimeoutException,
                        EsfException,
                        EsfNotConnectedException

Unsubscribes to a topic on the broker. This method MAY block until the underlying protocol message (e.g. the MQTT UNSUBSCRIBE message) is acknowledged by the broker or a timeout occurs. The timeout interval used by the service is configurable through the ConfigurationService.

Parameters:

topic -

Throws:

EsfTimeoutException

EsfException

EsfNotConnectedException - TODO

publish

DataTransportToken publish(String topic,
                           byte[] payload,
                           int qos,
                           boolean retain)
                           throws EsfTooManyInflightMessagesException,
                                  EsfException,
                                  EsfNotConnectedException

Enqueues a message for publishing with the underlying transport implementation. An active connection to the remote server is required.

Parameters:

topic -

payload -

qos -

retain -

Returns:

Throws:

EsfTooManyInflightMessagesException

EsfException

EsfNotConnectedException - TODO