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 aDictionary
of properties inside aConfiguration
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 callsManagedService.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
service.factoryPid
property matches the PID service property of the Managed Service Factory. For each suchConfiguration
objects, it calls theManagedServiceFactory.updated
method asynchronously with the new properties. The calls to theupdated
method of aManagedServiceFactory
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
ConfigurationPermission[*,CONFIGURE]
.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 aConfiguration
object is not bound, its location field isnull
, 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 aConfiguration
object is bound to a bundle location in this manner, the Configuration Admin service must detect if the bundle corresponding to the location is uninstalled. If this occurs, theConfiguration
object is unbound, that is its location field is set back tonull
.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 aServiceFactory
to support this concept.- Version:
- $Revision: 7356 $
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
SERVICE_BUNDLELOCATION
Configuration property naming the location of the bundle that is associated with a aConfiguration
object.static java.lang.String
SERVICE_FACTORYPID
Configuration property naming the Factory PID in the configuration dictionary.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description Configuration
createFactoryConfiguration(java.lang.String factoryPid)
Create a new factoryConfiguration
object with a new PID.Configuration
createFactoryConfiguration(java.lang.String factoryPid, java.lang.String location)
Create a new factoryConfiguration
object with a new PID.Configuration
getConfiguration(java.lang.String pid)
Get an existing or newConfiguration
object from the persistent store.Configuration
getConfiguration(java.lang.String pid, java.lang.String location)
Get an existingConfiguration
object from the persistent store, or create a newConfiguration
object.Configuration[]
listConfigurations(java.lang.String filter)
List the currentConfiguration
objects which match the filter.
-
-
-
Field Detail
-
SERVICE_FACTORYPID
static final java.lang.String SERVICE_FACTORYPID
Configuration property naming the Factory PID in the configuration dictionary. The property's value is of typeString
.- Since:
- 1.1
- See Also:
- Constant Field Values
-
SERVICE_BUNDLELOCATION
static final java.lang.String SERVICE_BUNDLELOCATION
Configuration property naming the location of the bundle that is associated with a aConfiguration
object. This property can be searched for but must not appear in the configuration dictionary for security reason. The property's value is of typeString
.- Since:
- 1.1
- See Also:
- Constant Field Values
-
-
Method Detail
-
createFactoryConfiguration
Configuration createFactoryConfiguration(java.lang.String factoryPid) throws java.io.IOException
Create a new factoryConfiguration
object with a new PID. The properties of the newConfiguration
object arenull
until the first time that itsConfiguration.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.- Parameters:
factoryPid
- PID of factory (notnull
).- Returns:
- A new
Configuration
object. - Throws:
java.io.IOException
- if access to persistent storage fails.java.lang.SecurityException
- if caller does not haveConfigurationPermission[*,CONFIGURE]
andfactoryPid
is bound to another bundle.
-
createFactoryConfiguration
Configuration createFactoryConfiguration(java.lang.String factoryPid, java.lang.String location) throws java.io.IOException
Create a new factoryConfiguration
object with a new PID. The properties of the newConfiguration
object arenull
until the first time that itsConfiguration.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 isnull
it will be bound to the location of the first bundle that registers a Managed Service Factory with a corresponding PID.- Parameters:
factoryPid
- PID of factory (notnull
).location
- A bundle location string, ornull
.- Returns:
- a new
Configuration
object. - Throws:
java.io.IOException
- if access to persistent storage fails.java.lang.SecurityException
- if caller does not haveConfigurationPermission[*,CONFIGURE]
.
-
getConfiguration
Configuration getConfiguration(java.lang.String pid, java.lang.String location) throws java.io.IOException
Get an existingConfiguration
object from the persistent store, or create a newConfiguration
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 tonull
. If the location parameter isnull
, it will be set when a Managed Service with the corresponding PID is registered for the first time.- Parameters:
pid
- Persistent identifier.location
- The bundle location string, ornull
.- 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 haveConfigurationPermission[*,CONFIGURE]
.
-
getConfiguration
Configuration getConfiguration(java.lang.String pid) throws java.io.IOException
Get an existing or newConfiguration
object from the persistent store. If theConfiguration
object for this PID does not exist, create a newConfiguration
object for that PID, where properties arenull
. Bind its location to the calling bundle's location.Otherwise, if the location of the existing
Configuration
object isnull
, set it to the calling bundle's location.- 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 theConfiguration
object is bound to a location different from that of the calling bundle and it has noConfigurationPermission[*,CONFIGURE]
.
-
listConfigurations
Configuration[] listConfigurations(java.lang.String filter) throws java.io.IOException, org.osgi.framework.InvalidSyntaxException
List the currentConfiguration
objects which match the filter.Only
Configuration
objects with non-null
properties are considered current. That is,Configuration.getProperties()
is guaranteed not to returnnull
for each of the returnedConfiguration
objects.Normally only
Configuration
objects that are bound to the location of the calling bundle are returned, or all if the caller hasConfigurationPermission[*,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
-String
- the PID under which this is registeredservice.factoryPid
-String
- the factory if applicableservice.bundleLocation
-String
- the bundle location
null
, meaning that allConfiguration
objects should be returned.- Parameters:
filter
- A filter string, ornull
to retrieve allConfiguration
objects.- Returns:
- All matching
Configuration
objects, ornull
if there aren't any. - Throws:
java.io.IOException
- if access to persistent storage failsorg.osgi.framework.InvalidSyntaxException
- if the filter string is invalid
-
-