OSGi 8.1.0 · org.osgi.service.cm.ConfigurationAdmin · APIdia, the JavaDoc alternative

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 service.pid property matches the PID service property ( service.pid) of the Managed Service. If found, it calls ManagedService#updated(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 service.factoryPid property matches the PID service property 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 other bundles requires ConfigurationPermission[location,CONFIGURE], where location is the configuration location.

Configuration objects can be bound to a specified bundle location or to a region (configuration location starts with ?). If a location is not set, it will be learned the first time a target is registered. If the location is learned this way, the Configuration Admin service must detect if the bundle corresponding to the location is uninstalled. If this occurs, the Configuration object must be unbound, that is its location field is set back to null.

If target's bundle location matches the configuration location it is always updated.

If the configuration location starts with ?, that is, the location is a region, then the configuration must be delivered to all targets registered with the given PID. If security is on, the target bundle must have Configuration Permission[location,TARGET], where location matches given the configuration location with wildcards as in the Filter substring match. The security must be verified using the org.osgi.framework.Bundle#hasPermission(Object) method on the target bundle.

If a target cannot be updated because the location does not match or it has no permission and security is active then the Configuration Admin service must not do the normal callback.

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 org.osgi.framework.ServiceFactory to support this concept.

Field Summary

Modifier and Type	Field and Description
public static final String	SERVICE_BUNDLELOCATION Configuration property naming the location of the bundle that is associated with a `Configuration` object.
public static final String	SERVICE_FACTORYPID Configuration property naming the Factory PID in the configuration dictionary.

Method Summary

Modifier and Type	Method and Description
public Configuration	Returns: A new `Configuration` object. createFactoryConfiguration(String PID of factory (not `null`). factoryPid) Create a new factory `Configuration` object with a new PID.
public Configuration	Returns: a new `Configuration` object. createFactoryConfiguration(String PID of factory (not `null`). factoryPid, String A bundle location string, or `null`. location) Create a new factory `Configuration` object with a new PID.
public Configuration	Returns: An existing or new `Configuration` object. getConfiguration(String Persistent identifier. pid, String The bundle location string, or `null`. location) Get an existing `Configuration` object from the persistent store, or create a new `Configuration` object.
public Configuration	Returns: an existing or new `Configuration` matching the PID. getConfiguration(String persistent identifier. pid) Get an existing or new `Configuration` object from the persistent store.
public Configuration	Returns: An existing or new `Configuration` object. getFactoryConfiguration(String PID of factory (not `null`). factoryPid, String A name for `Configuration` (not `null`). name, String The bundle location string, or `null`. location) Get an existing or new `Configuration` object from the persistent store.
public Configuration	Returns: an existing or new `Configuration` matching the PID. getFactoryConfiguration(String PID of factory (not `null`). factoryPid, String A name for `Configuration` (not `null`). name) Get an existing or new `Configuration` object from the persistent store.
public Configuration[]	Returns: All matching `Configuration` objects, or `null` if there aren't any. listConfigurations(String A filter string, or `null` to retrieve all `Configuration` objects. filter) List the current `Configuration` objects which match the filter.

Field Detail

SERVICE_BUNDLELOCATION back to summary

SERVICE_BUNDLELOCATION	back to summary
public static final String SERVICE_BUNDLELOCATION Configuration property naming the location of the bundle that is associated with 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

public static final String SERVICE_BUNDLELOCATION

Configuration property naming the location of the bundle that is associated with 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

SERVICE_FACTORYPID back to summary

SERVICE_FACTORYPID	back to summary
public static final String SERVICE_FACTORYPID Configuration property naming the Factory PID in the configuration dictionary. The property's value is of type `String`. Since 1.1

public static final String SERVICE_FACTORYPID

Configuration property naming the Factory PID in the configuration dictionary. The property's value is of type String.

Since: 1.1

Method Detail

createFactoryConfiguration back to summary

createFactoryConfiguration	back to summary
public Configuration createFactoryConfiguration(String factoryPid) throws 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(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. It is possible that the same factoryPid has associated configurations that are bound to different bundles. Bundles should only see the factory configurations that they are bound to or have the proper permission. Parameters factoryPid:String PID of factory (not `null`). Returns:Configuration A new `Configuration` object. Exceptions IOException: if access to persistent storage fails.

public Configuration createFactoryConfiguration(String factoryPid) throws 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(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. It is possible that the same factoryPid has associated configurations that are bound to different bundles. Bundles should only see the factory configurations that they are bound to or have the proper permission.

Parameters

factoryPid:String: PID of factory (not null).

Returns:Configuration

A new Configuration object.

Exceptions

IOException:: if access to persistent storage fails.

createFactoryConfiguration back to summary

createFactoryConfiguration	back to summary
public Configuration createFactoryConfiguration(String factoryPid, String location) throws 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(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. It is possible that the same factoryPid has associated configurations that are bound to different bundles. Bundles should only see the factory configurations that they are bound to or have the proper permission. If the location starts with `?` then the configuration must be delivered to all targets with the corresponding PID. Parameters factoryPid:String PID of factory (not `null`). location:String A bundle location string, or `null`. Returns:Configuration a new `Configuration` object. Exceptions IOException: if access to persistent storage fails. SecurityException: when the require permissions are not available

public Configuration createFactoryConfiguration(String factoryPid, String location) throws IOException

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. It is possible that the same factoryPid has associated configurations that are bound to different bundles. Bundles should only see the factory configurations that they are bound to or have the proper permission.

If the location starts with ? then the configuration must be delivered to all targets with the corresponding PID.

Parameters

factoryPid:String: PID of factory (not null).
location:String: A bundle location string, or null.

Returns:Configuration

a new Configuration object.

Exceptions

IOException:: if access to persistent storage fails.
SecurityException:: when the require permissions are not available

getConfiguration back to summary

getConfiguration	back to summary
public Configuration getConfiguration(String pid, String location) throws 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 though it is still used for a security check. 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. If the location starts with `?` then the configuration is bound to all targets that are registered with the corresponding PID. Parameters pid:String Persistent identifier. location:String The bundle location string, or `null`. Returns:Configuration An existing or new `Configuration` object. Exceptions IOException: if access to persistent storage fails. SecurityException: when the require permissions are not available

public Configuration getConfiguration(String pid, String location) throws 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 though it is still used for a security check.

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. If the location starts with ? then the configuration is bound to all targets that are registered with the corresponding PID.

Parameters

pid:String: Persistent identifier.
location:String: The bundle location string, or null.

Returns:Configuration

An existing or new Configuration object.

Exceptions

IOException:: if access to persistent storage fails.
SecurityException:: when the require permissions are not available

getConfiguration back to summary

getConfiguration	back to summary
public Configuration getConfiguration(String pid) throws 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. Otherwise, if the location of the existing `Configuration` object is `null`, set it to the calling bundle's location. Parameters pid:String persistent identifier. Returns:Configuration an existing or new `Configuration` matching the PID. Exceptions IOException: if access to persistent storage fails. SecurityException: when the required permission is not available

public Configuration getConfiguration(String pid) throws 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.

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

Parameters

pid:String: persistent identifier.

Returns:Configuration

an existing or new Configuration matching the PID.

Exceptions

IOException:: if access to persistent storage fails.
SecurityException:: when the required permission is not available

getFactoryConfiguration back to summary

getFactoryConfiguration	back to summary
public Configuration getFactoryConfiguration(String factoryPid, String name, String location) throws IOException Get an existing or new `Configuration` object from the persistent store. The PID for this `Configuration` object is generated from the provided factory PID and the name by starting with the factory PID appending a tilde (`'~'` \u007E), and then appending the name. If a `Configuration` with this PID already exists in Configuration Admin service return it. The location parameter is ignored in this case though it is still used for a security check. 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. If the location starts with `?` then the configuration is bound to all targets that are registered with the corresponding PID. Parameters factoryPid:String PID of factory (not `null`). name:String A name for `Configuration` (not `null`). location:String The bundle location string, or `null`. Returns:Configuration An existing or new `Configuration` object. Exceptions IOException: if access to persistent storage fails. SecurityException: when the require permissions are not available Since 1.6

public Configuration getFactoryConfiguration(String factoryPid, String name, String location) throws IOException

Get an existing or new Configuration object from the persistent store. The PID for this Configuration object is generated from the provided factory PID and the name by starting with the factory PID appending a tilde ('~' \u007E), and then appending the name.

If a Configuration with this PID already exists in Configuration Admin service return it. The location parameter is ignored in this case though it is still used for a security check.

Parameters

factoryPid:String: PID of factory (not null).
name:String: A name for Configuration (not null).
location:String: The bundle location string, or null.

Returns:Configuration

An existing or new Configuration object.

Exceptions

IOException:: if access to persistent storage fails.
SecurityException:: when the require permissions are not available

Since

1.6

getFactoryConfiguration back to summary

getFactoryConfiguration	back to summary
public Configuration getFactoryConfiguration(String factoryPid, String name) throws IOException Get an existing or new `Configuration` object from the persistent store. The PID for this `Configuration` object is generated from the provided factory PID and the name by starting with the factory PID appending a tilde (`'~'` \u007E), and then appending the name. If a `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. Otherwise, if the location of the existing `Configuration` object is `null`, set it to the calling bundle's location. Parameters factoryPid:String PID of factory (not `null`). name:String A name for `Configuration` (not `null`). Returns:Configuration an existing or new `Configuration` matching the PID. Exceptions IOException: if access to persistent storage fails. SecurityException: when the required permission is not available Since 1.6

public Configuration getFactoryConfiguration(String factoryPid, String name) throws IOException

If a 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.

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

Parameters

factoryPid:String: PID of factory (not null).
name:String: A name for Configuration (not null).

Returns:Configuration

an existing or new Configuration matching the PID.

Exceptions

IOException:: if access to persistent storage fails.
SecurityException:: when the required permission is not available

Since

1.6

listConfigurations back to summary

listConfigurations	back to summary
public Configuration[] listConfigurations(String filter) throws 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. When there is no security on then all configurations can be returned. If security is on, the caller must have ConfigurationPermission[location,CONFIGURE]. The syntax of the filter string is as defined in the `Filter` class. The filter can test any configuration properties including the following: `service.pid` - the persistent identity `service.factoryPid` - the factory PID, if applicable `service.bundleLocation` - the bundle location The filter can also be `null`, meaning that all `Configuration` objects should be returned. Parameters filter:String A filter string, or `null` to retrieve all `Configuration` objects. Returns:Configuration[] All matching `Configuration` objects, or `null` if there aren't any. Exceptions IOException: if access to persistent storage fails InvalidSyntaxException: if the filter string is invalid

public Configuration[] listConfigurations(String filter) throws 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.

When there is no security on then all configurations can be returned. If security is on, the caller must have ConfigurationPermission[location,CONFIGURE].

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

service.pid - the persistent identity
service.factoryPid - the factory PID, if applicable
service.bundleLocation - the bundle location

The filter can also be null, meaning that all Configuration objects should be returned.

Parameters

filter:String: A filter string, or null to retrieve all Configuration objects.

Returns:Configuration[]

All matching Configuration objects, or null if there aren't any.

Exceptions

IOException:: if access to persistent storage fails
InvalidSyntaxException:: if the filter string is invalid

public Interface ConfigurationAdmin

Field Summary

Method Summary

Field Detail

Method Detail