ConfigurationService (org.eclipse.kura.api 1.0.8 API)

```
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

activate

update

using OSGi Declative Services to configure multiple instances of a component

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).

Field Summary

Fields
Modifier and Type Field and Description

static String KURA_SERVICE_PID
The name of the the Kura persistent identity property.

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

Method Summary

Methods
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 ConfigurationAdmin#createFactoryConfiguration(String, String) 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

Interface ConfigurationService

Field Summary

Method Summary

Field Detail

KURA_SERVICE_PID

Method Detail

getFactoryComponentPids

createFactoryConfiguration

deleteFactoryConfiguration

getConfigurableComponentPids

getComponentConfigurations

getComponentConfiguration

getDefaultComponentConfiguration

updateConfiguration

updateConfiguration

updateConfigurations

updateConfigurations

getSnapshots

getSnapshot

snapshot

rollback

rollback