Interface ConfigurationAdmin
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(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 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
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 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 Configuration 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.
- Version:
- $Revision: 7356 $
-
Field Summary
Fields -
Method Summary
Modifier and TypeMethodDescriptioncreateFactoryConfiguration
(String factoryPid) Create a new factoryConfiguration
object with a new PID.createFactoryConfiguration
(String factoryPid, String location) Create a new factoryConfiguration
object with a new PID.getConfiguration
(String pid) Get an existing or newConfiguration
object from the persistent store.getConfiguration
(String pid, String location) Get an existingConfiguration
object from the persistent store, or create a newConfiguration
object.listConfigurations
(String filter) List the currentConfiguration
objects which match the filter.
-
Field Details
-
SERVICE_FACTORYPID
Configuration property naming the Factory PID in the configuration dictionary. The property's value is of typeString
.- Since:
- 1.1
- See Also:
-
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:
-
-
Method Details
-
createFactoryConfiguration
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:
IOException
- if access to persistent storage fails.SecurityException
- if caller does not haveConfigurationPermission[*,CONFIGURE]
andfactoryPid
is bound to another bundle.
-
createFactoryConfiguration
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:
IOException
- if access to persistent storage fails.SecurityException
- if caller does not haveConfigurationPermission[*,CONFIGURE]
.
-
getConfiguration
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:
IOException
- if access to persistent storage fails.SecurityException
- if the caller does not haveConfigurationPermission[*,CONFIGURE]
.
-
getConfiguration
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:
IOException
- if access to persistent storage fails.SecurityException
- if theConfiguration
object is bound to a location different from that of the calling bundle and it has noConfigurationPermission[*,CONFIGURE]
.
-
listConfigurations
Configuration[] listConfigurations(String filter) throws 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:
IOException
- if access to persistent storage failsorg.osgi.framework.InvalidSyntaxException
- if the filter string is invalid
-