org.eclipse.kura.cloud.factory

Interface CloudServiceFactory

@ProviderType
public interface CloudServiceFactory

A CloudServiceFactory represents an OSGi Declarative Service Component which registers CloudServiceS in the framework. The Component creates multiple component instances upon reception of a configuration created through the Configuration Service.
It provides a CloudService implementation that can be used to connect to a specific Cloud platform.
Typically, each CloudService created by a CloudServiceFactory establishes and manages its own connection, for example an Mqtt connection.
Multiple CloudServiceFactory services can be registered in the framework to support multiple simultaneous connections to different Cloud platforms.
Kura provides a default CloudServiceFactory implementation and creates a default CloudService.
A CloudServiceFactory manages the construction of a CloudService and the services it depends on. While the same can be achieved through the ConfigurationService, CloudServiceFactory simplifies this process and offers more control.
For example, in a stack architecture with CloudService at the top of the stack and where lower layers are also components, an implementation of CloudServiceFactory could create new configurations for all the stack layers thus constructing a new whole stack instance.
The Kura CloudService/DataService/DataTransportService cloud stack represents an example of the above architecture and can serve as a reference implementation for alternative Cloud stacks.
In order to leverage the Kura configuration persistence in snapshot files, an implementation will use the ConfigurationService to create component configurations.

Since:

1.0.8

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	KURA_CLOUD_SERVICE_FACTORY_PID The name of the property set in a @{link CloudService} configuration created through createConfiguration(java.lang.String).

Method Summary

Modifier and Type	Method and Description
void	createConfiguration(java.lang.String pid) Creates a CloudService instance and initializes its configuration with the defaults expressed in the Metatype of the target component factory providing the CloudService.
void	deleteConfiguration(java.lang.String pid) Deletes a previously created configuration deactivating the associated CloudService instance.
java.lang.String	getFactoryPid() Returns the factory PID of the OSGi Factory Component represented by this CloudServiceFactory.
java.util.Set<java.lang.String>	getManagedCloudServicePids() Return a set of services managed by this factory It is up to the factory how it does assembles this.
java.util.List<java.lang.String>	getStackComponentsPids(java.lang.String pid) Returns the list of kura.service.pids that compose the cloud stack associated with the provided kura.service.pid of the factory component configuration.

Field Detail

KURA_CLOUD_SERVICE_FACTORY_PID

static final java.lang.String KURA_CLOUD_SERVICE_FACTORY_PID

The name of the property set in a @{link CloudService} configuration created through createConfiguration(java.lang.String). The property is set in the cloud service instance to relate it with the Factory that generated the whole cloud stack.

Since:

1.1.0

See Also:

Constant Field Values

Method Detail

getFactoryPid

java.lang.String getFactoryPid()

Returns the factory PID of the OSGi Factory Component represented by this CloudServiceFactory.

Returns:

a String representing the factory PID of the Factory Component.

createConfiguration

void createConfiguration(java.lang.String pid)
                  throws KuraException

Creates a CloudService instance and initializes its configuration with the defaults expressed in the Metatype of the target component factory providing the CloudService.
Implementation will normally rely on ConfigurationService.createFactoryConfiguration(java.lang.String, java.lang.String, java.util.Map<java.lang.String, java.lang.Object>, boolean) to perform the actual creation of the component instance and the persistence of the component configuration.
The created CloudService instance will have its kura.service.pid property set to the value provided in the pid parameter.
Kura apps can look up the created CloudService instance through ComponentContext.locateServices(java.lang.String) by filtering on the kura.service.pid property.
Likely, Kura apps will rely on OSGi Declarative Services to have their CloudService dependencies satisfied based on a target filter on the value of the property kura.service.pid in their component definition.
In the following example a Kura app declares two dependencies on CloudServiceS whose PIDs are myCloudService and anotherCloudService:

 <reference name="myCloudServiceReference"
              policy="static"
              bind="setMyCloudService"
              unbind="unsetMyCloudService"
              cardinality="1..1"
              interface="org.eclipse.kura.cloud.CloudService"/>
 <property  name="myCloudServiceReference.target"
              type="String"
              value="(kura.service.pid=myCloudService)"/>

 <reference name="anotherCloudServiceReference"
              policy="static"
              bind="setAnotherCloudService"
              unbind="unsetAnotherCloudService"
              cardinality="1..1"
              interface="org.eclipse.kura.cloud.CloudService"/>
 <property  name="anotherCloudServiceReference.target"
              type="String"
              value="(kura.service.pid=anotherCloudService)"/>
 

Parameters:

pid - the Kura persistent identifier, kura.service.pid, of the factory component configuration.

Throws:

KuraException

getStackComponentsPids

java.util.List<java.lang.String> getStackComponentsPids(java.lang.String pid)
                                                 throws KuraException

Returns the list of kura.service.pids that compose the cloud stack associated with the provided kura.service.pid of the factory component configuration.

Parameters:

pid - the Kura persistent identifier, kura.service.pid, of the factory component configuration.

Returns:

List<String>, the list of kura.service.pids associated with the specified factory component configuration.

Throws:

KuraException - if the specified kura.service.pid is not correct or compliant with what the factory implementation expects

Since:

1.1.0

deleteConfiguration

void deleteConfiguration(java.lang.String pid)
                  throws KuraException

Deletes a previously created configuration deactivating the associated CloudService instance.

Parameters:

pid - the Kura persistent identifier, kura.service.pid, of the factory component configuration.

Throws:

KuraException

getManagedCloudServicePids

java.util.Set<java.lang.String> getManagedCloudServicePids()
                                                    throws KuraException

Return a set of services managed by this factory
It is up to the factory how it does assembles this. The PIDs returned by this list must be the PIDs assigned to the OSGi service property kura.service.pid and it must be possible to pass all those results into the method getStackComponentsPids(String) of the same factory instance.
The IDs returned by this method must not necessarily point to registered OSGi services. But if they do, they must point only to instances of the CloudService.

Returns:

the set of services, never returns null

Throws:

KuraException

Since:

1.1.0