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 method with the new properties. The implementation of a Configuration Admin service must run these call-backs one a thread that differs from the initiating thread 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 on a different thread with the new properties. The calls to the updated method of a ManagedServiceFactory must be executed sequential 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.

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 to support this concept.

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.

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 class. The filter can test any configuration parameters including the following system properties:

1. service.pid - String - the PID under which this is registered
2. service.factoryPid - String - the factory if applicable
3. 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