org.eclipse.kura.configuration

Interface ConfigurationService

public interface ConfigurationService

The Configuration Service is used to manage the configuration of OSGi Declarative Services implementing the ConfigurableComponent or the SelfConfiguringComponent interface. It works in concert with the OSGi Configuration Admin and the OSGi Meta Type services. What it provides over the native OSGi services is the ability to easily access the current configuration of a Configurable Component or a SelfConfiguring Component together with their full Meta Type Object Class Definition, the ability to take snapshots of the current configuration of all managed services or rollback to older snapshots and, finally, the ability to access and manage configurations remotely through the Cloud Service.

The Configuration Service operates on a subset of all the services registered under the OSGi container. It tracks only OSGi services which implement the ConfigurableComponent or the SelfConfiguringComponent interface. More explicitly it does not manage the following services of the OSGi specification:

• Managed Service
• Managed Service Factory
• Component Factory of the Declarative Service specification

When a ConfigurableComponent or a SelfConfiguringComponent is tracked, the Configuration Service will update its Configuration, as returned by the Configuration Admin, with properties fabricated from the default attribute values specified in its Meta Type Object Class Definition.
The configuration properties will be passed in the activate or update methods of the Component definition.
In OSGi terms, this process in similar to the Auto Configuration Service.

The Configuration Service assumes the Meta Type Information XML resource for a given Declarative Service with name "abc" to be stored under OSGI-INF/metatype/abc.xml.
This is an extra restriction over the OSGi specification: the Meta Type Information XML resource must be named as the name of the Declarative Service Component.

The Configuration Service has the ability to create a snapshot for the current configuration of all the tracked components. The snapshot is saved in the form of an XML file stored under $kura.snapshots/snapshot_epoch.xml where epoch is replaced with the epoch timestamp at the time of the snapshot creation. The Configuration Service also has the ability to rollback the configuration of tracked components taking them back to a previous stored snapshot.

The Configuration Service also allows creation of new ConfigurableComponents instances through OSGi Declarative Services by creating a new component Configuration via the OSGi Configuration Admin. The approach is using OSGi Declative Services to configure multiple instances of a component.

In order to manage the configuration of multiple component instances from the same configuration factory, Kura relies on the following configuration properties:

• service.factoryPid is set by the Configuration Admin when the component configuration is first created. Its value has to match the name of the targeted Declarative Service Component
• kura.service.pid is the persistent identity assigned by Kura when the component configuration is first created calling createFactoryConfiguration(String, String, Map, boolean).

Both properties are stored in snapshots to recreate the component instances and restore their configuration at every framework restart.

Field Summary

Fields

Modifier and Type	Field and Description
static String	KURA_SERVICE_PID The name of the the Kura persistent identity property.

Method Summary

Modifier and Type	Method and Description
void	createFactoryConfiguration(String factoryPid, String pid, Map<String,Object> properties, boolean takeSnapshot) Creates a new ConfigurableComponent instance by creating a new configuration from a Configuration Admin factory.
void	deleteFactoryConfiguration(String pid, boolean takeSnapshot) Deletes the ConfigurableComponent instance having the specified PID.
ComponentConfiguration	getComponentConfiguration(String pid) Returns the ComponentConfiguration for the component identified with specified PID.
List<ComponentConfiguration>	getComponentConfigurations() Returns the list of ConfigurableComponents currently registered with the ConfigurationService.
Set<String>	getConfigurableComponentPids() Return the PIDs for all the services that implements the ConfigurableComponent Maker interface and registered themselves with the container.
ComponentConfiguration	getDefaultComponentConfiguration(String pid) Returns the default ComponentConfiguration for the component having the specified PID.
Set<String>	getFactoryComponentPids() Returns the list of Meta Type factory PIDs tracked by the Configuration Service.
List<ComponentConfiguration>	getSnapshot(long sid) Loads a snapshot given its ID and return the component configurations stored in that snapshot.
Set<Long>	getSnapshots() Returns the ID of all the snapshots taken by the ConfigurationService.
long	rollback() Rolls back to the last saved snapshot if available.
void	rollback(long id) Rolls back to the specified snapshot id.
long	snapshot() Takes a new snapshot of the current configuration of all the registered ConfigurableCompoenents.
void	updateConfiguration(String pid, Map<String,Object> properties) Updates the Configuration of the registered component with the specified PID.
void	updateConfiguration(String pid, Map<String,Object> properties, boolean takeSnapshot) Updates the Configuration of the registered component with the specified pid.
void	updateConfigurations(List<ComponentConfiguration> configs) Updates the Configuration of the registered components.
void	updateConfigurations(List<ComponentConfiguration> configs, boolean takeSnapshot) Updates the Configuration of the registered components.

Field Detail

KURA_SERVICE_PID

static final String KURA_SERVICE_PID

The name of the the Kura persistent identity property.

Since:

org.eclipse.kura.configuration 1.1.0

See Also:

Constant Field Values

Method Detail

getFactoryComponentPids

Set<String> getFactoryComponentPids()

Returns the list of Meta Type factory PIDs tracked by the Configuration Service.

Returns:

the list of Meta Type factory PIDs.

Since:

org.eclipse.kura.configuration 1.1.0

createFactoryConfiguration

void createFactoryConfiguration(String factoryPid,
                                String pid,
                                Map<String,Object> properties,
                                boolean takeSnapshot)
                         throws KuraException

Creates a new ConfigurableComponent instance by creating a new configuration from a Configuration Admin factory. The Configuration Service will use the Configuration Admin to create the component configuration and will update the component configuration with the provided optional properties.

Parameters:

factoryPid - the ID of the factory.

pid - the value of the KURA_SERVICE_PID that will be set in the component configuration properties.

properties - an optional map of properties describing the component configuration. The Configuration Service will first create an initial map of properties with the property KURA_SERVICE_PID set to the provided pid parameter and with the default component configuration from its OSGi Meta Type. If properties is not null, the Configuration Service will first remove KURA_SERVICE_PID from the provided properties and then it will merge them with the initial map.

takeSnapshot - if set to true a snapshot will be taken.

Throws:

KuraException - if pid is null, it already exists or creation fails.

Since:

org.eclipse.kura.configuration 1.1.0

deleteFactoryConfiguration

void deleteFactoryConfiguration(String pid,
                                boolean takeSnapshot)
                         throws KuraException

Deletes the ConfigurableComponent instance having the specified PID. Removes the component configuration and takes a new snapshot.

Parameters:

pid - the PID of the component instance to delete.

takeSnapshot - if set to true a snapshot will be taken.

Throws:

KuraException - if the PID is not found or if the component instance was not created via createFactoryConfiguration(String, String, Map, boolean).

Since:

org.eclipse.kura.configuration 1.1.0

getConfigurableComponentPids

Set<String> getConfigurableComponentPids()

Return the PIDs for all the services that implements the ConfigurableComponent Maker interface and registered themselves with the container.

Returns:

list of PIDs for registered ConfigurableComponents

getComponentConfigurations

List<ComponentConfiguration> getComponentConfigurations()
                                                 throws KuraException

Returns the list of ConfigurableComponents currently registered with the ConfigurationService.

Returns:

list of registered ConfigurableComponents

Throws:

KuraException

getComponentConfiguration

ComponentConfiguration getComponentConfiguration(String pid)
                                          throws KuraException

Returns the ComponentConfiguration for the component identified with specified PID.

Parameters:

pid - The ID of the component whose configuration is requested.

Returns:

ComponentConfiguration of the requested Component.

Throws:

KuraException

getDefaultComponentConfiguration

ComponentConfiguration getDefaultComponentConfiguration(String pid)
                                                 throws KuraException

Returns the default ComponentConfiguration for the component having the specified PID.

Parameters:

pid - The ID of the component whose configuration is requested.

Returns:

the ComponentConfiguration of the requested Component.

Throws:

KuraException

Since:

org.eclipse.kura.configuration 1.1.0

updateConfiguration

void updateConfiguration(String pid,
                         Map<String,Object> properties)
                  throws KuraException

Updates the Configuration of the registered component with the specified PID. Using the OSGi ConfigurationAdmin, it retrieves the Configuration of the component with the specified PID and then sends an update using the specified properties.
If the component to be updated is not yet registered with the ConfigurationService, it is first registered and then it is updated with the specified properties. Before updating the component, the specified properties are validated against the ObjectClassDefinition associated to the Component. The Configuration Service is fully compliant with the OSGi MetaType Information and the validation happens through the OSGi MetaType Service.
The Configuration Service is compliant with the OSGi MetaType Service so it accepts all attribute types defined in the OSGi Compendium Specifications.

Parameters:

pid - The PID of the component whose configuration is requested.

properties - Properties to be used as the new Configuration for the specified Component.

Throws:

KuraException - if the properties specified do not pass the validation of the ObjectClassDefinition

updateConfiguration

void updateConfiguration(String pid,
                         Map<String,Object> properties,
                         boolean takeSnapshot)
                  throws KuraException

Updates the Configuration of the registered component with the specified pid. Using the OSGi ConfigurationAdmin, it retrieves the Configuration of the component with the specified PID and then send an update using the specified properties.
If the component to be updated is not yet registered with the ConfigurationService, it is first registered and then it is updated with the specified properties. Before updating the component, the specified properties are validated against the ObjectClassDefinition associated to the Component. The Configuration Service is fully compliant with the OSGi MetaType Information and the validation happens through the OSGi MetaType Service.
The Configuration Service is compliant with the OSGi MetaType Service so it accepts all attribute types defined in the OSGi Compendium Specifications.

Parameters:

pid - The PID of the component whose configuration is requested.

properties - Properties to be used as the new Configuration for the specified Component.

takeSnapshot - defines whether or not this configuration update should trigger a snapshot.

Throws:

KuraException - if the properties specified do not pass the validation of the ObjectClassDefinition.

Since:

org.eclipse.kura.configuration 1.1.0

updateConfigurations

void updateConfigurations(List<ComponentConfiguration> configs)
                   throws KuraException

Updates the Configuration of the registered components. Using the OSGi ConfigurationAdmin, it retrieves the Configuration of the component with the specified PID and then send an update using the specified properties.
If the component to be updated is not yet registered with the ConfigurationService, it is first registered and then it is updated with the specified properties. Before updating the component, the specified properties are validated against the ObjectClassDefinition associated to the Component. The Configuration Service is fully compliant with the OSGi MetaType Information and the validation happens through the OSGi MetaType Service.
The Configuration Service is compliant with the OSGi MetaType Service so it accepts all attribute types defined in the OSGi Compendium Specifications.

Parameters:

configs - The list of ComponentConfiguration whose update is requested.

Throws:

KuraException - if the properties specified do not pass the validation of the ObjectClassDefinition

updateConfigurations

void updateConfigurations(List<ComponentConfiguration> configs,
                          boolean takeSnapshot)
                   throws KuraException

Updates the Configuration of the registered components. Using the OSGi ConfigurationAdmin, it retrieves the Configuration of the component with the specified PID and then send an update using the specified properties.
If the component to be updated is not yet registered with the ConfigurationService, it is first registered and then it is updated with the specified properties. Before updating the component, the specified properties are validated against the ObjectClassDefinition associated to the Component. The Configuration Service is fully compliant with the OSGi MetaType Information and the validation happens through the OSGi MetaType Service.
The Configuration Service is compliant with the OSGi MetaType Service so it accepts all attribute types defined in the OSGi Compendium Specifications.

Parameters:

configs - The list of ComponentConfiguration whose update is requested.

takeSnapshot - defines whether or not this configuration update should trigger a snapshot.

Throws:

KuraException - if the properties specified do not pass the validation of the ObjectClassDefinition

Since:

org.eclipse.kura.configuration 1.1.0

getSnapshots

Set<Long> getSnapshots()
                throws KuraException

Returns the ID of all the snapshots taken by the ConfigurationService. The snapshot ID is the epoch time at which the snapshot was taken. The snapshots are stored in the KuraHome/snapshots/ directory. This API will return all the snpashot files available in that location.

Returns:

IDs of the snapshots available.

Throws:

KuraException

getSnapshot

List<ComponentConfiguration> getSnapshot(long sid)
                                  throws KuraException

Loads a snapshot given its ID and return the component configurations stored in that snapshot.

Parameters:

sid - - ID of the snapshot to be loaded

Returns:

List of ComponentConfigurations contained in the snapshot

Throws:

KuraException

snapshot

long snapshot()
       throws KuraException

Takes a new snapshot of the current configuration of all the registered ConfigurableCompoenents. It returns the ID of a snapshot as the epoch time at which the snapshot was taken.

Returns:

the ID of the snapshot.

Throws:

KuraException

rollback

long rollback()
       throws KuraException

Rolls back to the last saved snapshot if available.

Returns:

the ID of the snapshot it rolled back to

Throws:

KuraException - if no snapshots are available or

rollback

void rollback(long id)
       throws KuraException

Rolls back to the specified snapshot id.

Parameters:

id - ID of the snapshot we need to rollback to

Throws:

KuraException - if the snapshot is not found