Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
| OSGi Service Platform Release 3
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.osgi.service.cm
Interface ConfigurationAdmin

public interface ConfigurationAdmin

Service for administering configuration data.

The main purpose of this interface is to store bundle configuration data persistently. This information is represented in `Configuration` objects. The actual configuration data is a `Dictionary` of properties inside a `Configuration` object.

There are two principally different ways to manage configurations. First there is the concept of a Managed Service, where configuration data is uniquely associated with an object registered with the service registry.

Next, there is the concept of a factory where the Configuration Admin service will maintain 0 or more `Configuration` objects for a Managed Service Factory that is registered with the Framework.

The first concept is intended for configuration data about "things/services" whose existence is defined externally, e.g. a specific printer. Factories are intended for "things/services" that can be created any number of times, e.g. a configuration for a DHCP server for different networks.

Bundles that require configuration should register a Managed Service or a Managed Service Factory in the service registry. A registration property named `service.pid` (persistent identifier or PID) must be used to identify this Managed Service or Managed Service Factory to the Configuration Admin service.

When the ConfigurationAdmin detects the registration of a Managed Service, it checks its persistent storage for a configuration object whose PID matches the PID registration property (`service.pid`) of the Managed Service. If found, it calls `ManagedService.updated(java.util.Dictionary)` method with the new properties. The implementation of a Configuration Admin service must run these call-backs asynchronously to allow proper synchronization.

When the Configuration Admin service detects a Managed Service Factory registration, it checks its storage for configuration objects whose `factoryPid` matches the PID of the Managed Service Factory. For each such `Configuration` objects, it calls the `ManagedServiceFactory.updated` method asynchronously with the new properties. The calls to the `updated` method of a `ManagedServiceFactory` must be executed sequentially and not overlap in time.

In general, bundles having permission to use the Configuration Admin service can only access and modify their own configuration information. Accessing or modifying the configuration of another bundle requires `AdminPermission`.

`Configuration` objects can be bound to a specified bundle location. In this case, if a matching Managed Service or Managed Service Factory is registered by a bundle with a different location, then the Configuration Admin service must not do the normal callback, and it should log an error. In the case where a `Configuration` object is not bound, its location field is `null`, the Configuration Admin service will bind it to the location of the bundle that registers the first Managed Service or Managed Service Factory that has a corresponding PID property. When a `Configuration` object is bound to a bundle location in this manner, the Confguration Admin service must detect if the bundle corresponding to the location is uninstalled. If this occurs, the `Configuration` object is unbound, that is its location field is set back to `null`.

The method descriptions of this class refer to a concept of "the calling bundle". This is a loose way of referring to the bundle which obtained the Configuration Admin service from the service registry. Implementations of `ConfigurationAdmin` must use a `ServiceFactory` to support this concept.

Field Summary
`static java.lang.String` | `SERVICE_BUNDLELOCATION` Service property naming the location of the bundle that is associated with a a `Configuration` object.
`static java.lang.String` | `SERVICE_FACTORYPID` Service property naming the Factory PID in the configuration dictionary.

Method Summary
`Configuration` | `createFactoryConfiguration(java.lang.String factoryPid)` Create a new factory `Configuration` object with a new PID.
`Configuration` | `createFactoryConfiguration(java.lang.String factoryPid, java.lang.String location)` Create a new factory `Configuration` object with a new PID.
`Configuration` | `getConfiguration(java.lang.String pid)` Get an existing or new `Configuration` object from the persistent store.
`Configuration` | `getConfiguration(java.lang.String pid, java.lang.String location)` Get an existing `Configuration` object from the persistent store, or create a new `Configuration` object.
`Configuration[]` | `listConfigurations(java.lang.String filter)` List the current `Configuration` objects which match the filter.

Field Detail

### SERVICE_FACTORYPID

    public static final java.lang.String SERVICE_FACTORYPID

  Service property naming the Factory PID in the configuration dictionary. The property's value is of type `String`.
  Since:
    1.1

### SERVICE_BUNDLELOCATION

    public static final java.lang.String SERVICE_BUNDLELOCATION

  Service property naming the location of the bundle that is associated with a a `Configuration` object. This property can be searched for but must not appear in the configuration dictionary for security reason. The property's value is of type `String`.
  Since:
    1.1

Method Detail

### createFactoryConfiguration

    public Configuration createFactoryConfiguration(java.lang.String factoryPid)
                                             throws java.io.IOException

  Create a new factory `Configuration` object with a new PID. The properties of the new `Configuration` object are `null` until the first time that its `Configuration.update(java.util.Dictionary)` method is called.

  It is not required that the `factoryPid` maps to a registered Managed Service Factory.

  The `Configuration` object is bound to the location of the calling bundle.

  Parameters:
    `factoryPid` - PID of factory (not `null`).
  Returns:
    a new `Configuration` object.
  Throws:
    `java.io.IOException` - if access to persistent storage fails.
    `java.lang.SecurityException` - if caller does not have `AdminPermission` and `factoryPid` is bound to another bundle.

### createFactoryConfiguration

    public Configuration createFactoryConfiguration(java.lang.String factoryPid,
                                                    java.lang.String location)
                                             throws java.io.IOException

  Create a new factory `Configuration` object with a new PID. The properties of the new `Configuration` object are `null` until the first time that its `Configuration.update(java.util.Dictionary)` method is called.

  It is not required that the `factoryPid` maps to a registered Managed Service Factory.

  The `Configuration` is bound to the location specified. If this location is `null` it will be bound to the location of the first bundle that registers a Managed Service Factory with a corresponding PID.

  This method requires `AdminPermission`.

  Parameters:
    `factoryPid` - PID of factory (not `null`).
    `location` - a bundle location string, or `null`.
  Returns:
    a new `Configuration` object.
  Throws:
    `java.io.IOException` - if access to persistent storage fails.
    `java.lang.SecurityException` - if caller does not have `AdminPermission`.

### getConfiguration

    public Configuration getConfiguration(java.lang.String pid,
                                          java.lang.String location)
                                   throws java.io.IOException

  Get an existing `Configuration` object from the persistent store, or create a new `Configuration` object.

  If a `Configuration` with this PID already exists in Configuration Admin service return it. The location parameter is ignored in this case.

  Else, return a new `Configuration` object. This new object is bound to the location and the properties are set to `null`. If the location parameter is `null`, it will be set when a Managed Service with the corresponding PID is registered for the first time.

  This method requires `AdminPermission`.

  Parameters:
    `pid` - persistent identifier.
    `location` - the bundle location string, or `null`.
  Returns:
    an existing or new `Configuration` object.
  Throws:
    `java.io.IOException` - if access to persistent storage fails.
    `java.lang.SecurityException` - if the caller does not have `AdminPermission`.

### getConfiguration

    public Configuration getConfiguration(java.lang.String pid)
                                   throws java.io.IOException

  Get an existing or new `Configuration` object from the persistent store. If the `Configuration` object for this PID does not exist, create a new `Configuration` object for that PID, where properties are `null`. Bind its location to the calling bundle's location.

  Else, if the location of the existing `Configuration` object is `null`, set it to the calling bundle's location.

  If the location of the `Configuration` object does not match the calling bundle, throw a `SecurityException`.

  Parameters:
    `pid` - persistent identifier.
  Returns:
    an existing or new `Configuration` matching the PID.
  Throws:
    `java.io.IOException` - if access to persistent storage fails.
    `java.lang.SecurityException` - if the `Configuration` object is bound to a location different from that of the calling bundle and it has no `AdminPermission`.

### listConfigurations

    public Configuration[] listConfigurations(java.lang.String filter)
                                       throws java.io.IOException,
                                              InvalidSyntaxException

  List the current `Configuration` objects which match the filter.

  Only `Configuration` objects with non-`null` properties are considered current. That is, `Configuration.getProperties()` is guaranteed not to return `null` for each of the returned `Configuration` objects.

  Normally only `Configuration` objects that are bound to the location of the calling bundle are returned. If the caller has `AdminPermission`, then all matching `Configuration` objects are returned.

  The syntax of the filter string is as defined in the `Filter` class. The filter can test any configuration parameters including the following system properties:

  - `service.pid` - `String` - the PID under which this is registered
  - `service.factoryPid` - `String` - the factory if applicable
  - `service.bundleLocation` - `String` - the bundle location
  The filter can also be `null`, meaning that all `Configuration` objects should be returned.
  Parameters:
    `filter` - a `Filter` object, or `null` to retrieve all `Configuration` objects.
  Returns:
    all matching `Configuration` objects, or `null` if there aren't any
  Throws:
    `java.io.IOException` - if access to persistent storage fails
    `InvalidSyntaxException` - if the filter string is invalid

Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
| OSGi Service Platform Release 3
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) OSGi Alliance (2000, 2003). All Rights Reserved.