org.eclipse.kura.cloudconnection.publisher

Interface CloudPublisher

All Known Subinterfaces:

CloudNotificationPublisher

@ProviderType
public interface CloudPublisher

The CloudPublisher interface is an abstraction on top of the CloudEndpoint to simplify the publishing process for each application running in the framework. A CloudPublisher is used to publish the specified KuraMessage to a cloud platform. The CloudPublisher and the associated CloudEndpoint implementations abstract, to the user applications, all the low level specificities like the message destination address, quality of service or properties because those are added by the CloudPublisher implementation based, for example, on a configuration. When an application wants to publish, it has to take a CloudPublisher instance and use the publish(KuraMessage) method, passing as argument a KuraMessage. Every KuraMessage accepted by the CloudPublisher is associated to a string identifier that can be used to confirm that the KuraMessage has been published. However, the semantics of the confirmation depends on both the implementation and the configuration of the connection. For example, if the protocol of the cloud connection supports message identifiers and acknowledgments, the implementation will map the message identifier to the KuraMessage identifier and confirm it when the message identifier is acknowledged. If the protocol does not support message identifiers, or the message does not request an acknowledge, a confirmed KuraMessage identifier may at most indicate that the message has been successfully transmitted. There is no guarantee that a KuraMessage identifier will ever be confirmed. It is important that the implementation of the CloudPublisher and its configuration match the assumptions of the API consumer about the delivery. For example, if the correct behavior of an application requires guaranteed message delivery, the application should be configured to use a reliable publisher. Of course, applications that do not require this will work with any publisher.

Since:

2.0

Method Summary

Modifier and Type	Method and Description
java.lang.String	publish(KuraMessage message) Publishes the received KuraMessage using the associated cloud connection.
void	registerCloudConnectionListener(CloudConnectionListener cloudConnectionListener) The implementation will register the CloudConnectionListener instance passed as argument.
void	registerCloudDeliveryListener(CloudDeliveryListener cloudDeliveryListener) The implementation will register the CloudDeliveryListener instance passed as argument.
void	unregisterCloudConnectionListener(CloudConnectionListener cloudConnectionListener) Unregisters the provided CloudConnectionListener instance from cloud connection related events notifications.
void	unregisterCloudDeliveryListener(CloudDeliveryListener cloudDeliveryListener) Unregisters the provided CloudDeliveryListener instance from cloud connection related events notifications.

Method Detail

publish

java.lang.String publish(KuraMessage message)
                  throws KuraException

Publishes the received KuraMessage using the associated cloud connection.

Parameters:

message - The KuraMessage to be published

Returns:

a String representing the message ID. null is returned if the cloud endpoint will not confirm the message delivery, either because this is not supported by the underlying protocol or because the cloud endpoint itself is not implemented or configured to request the confirmation. The message ID can be confirmed when the message is delivered. See CloudDeliveryListener.

Throws:

KuraException - if the publishing operation fails.

registerCloudConnectionListener

void registerCloudConnectionListener(CloudConnectionListener cloudConnectionListener)

The implementation will register the CloudConnectionListener instance passed as argument. Once a cloud connection related event happens, all the registered CloudConnectionListeners will be notified.

Parameters:

cloudConnectionListener - a CloudConnectionListener instance

unregisterCloudConnectionListener

void unregisterCloudConnectionListener(CloudConnectionListener cloudConnectionListener)

Unregisters the provided CloudConnectionListener instance from cloud connection related events notifications.

Parameters:

cloudConnectionListener -

registerCloudDeliveryListener

void registerCloudDeliveryListener(CloudDeliveryListener cloudDeliveryListener)

The implementation will register the CloudDeliveryListener instance passed as argument. Once a cloud connection related event happens, all the registered CloudDeliveryListeners will be notified.

Parameters:

cloudDeliveryListener - a CloudDeliveryListener instance

unregisterCloudDeliveryListener

void unregisterCloudDeliveryListener(CloudDeliveryListener cloudDeliveryListener)

Unregisters the provided CloudDeliveryListener instance from cloud connection related events notifications.

Parameters:

cloudConnectionListener -