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

Methods

Modifier and Type	Method and Description
void	connect() Connects to the remote broker.
void	disconnect(long quiesceTimeout) Disconnects from the broker.
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.

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