@ProviderType public 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(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
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
ServiceFactory
to support this concept.
Modifier and Type | Field and Description |
---|---|
static String |
SERVICE_BUNDLELOCATION
Configuration property naming the location of the bundle that is
associated with a
Configuration object. |
static String |
SERVICE_FACTORYPID
Configuration property naming the Factory PID in the configuration
dictionary.
|
Modifier and Type | Method and Description |
---|---|
Configuration |
createFactoryConfiguration(String factoryPid)
Create a new factory
Configuration object with a new PID. |
Configuration |
createFactoryConfiguration(String factoryPid,
String location)
Create a new factory
Configuration object with a new PID. |
Configuration |
getConfiguration(String pid)
Get an existing or new
Configuration object from the persistent
store. |
Configuration |
getConfiguration(String pid,
String location)
Get an existing
Configuration object from the persistent store,
or create a new Configuration object. |
Configuration |
getFactoryConfiguration(String factoryPid,
String name)
Get an existing or new
Configuration object from the persistent
store. |
Configuration |
getFactoryConfiguration(String factoryPid,
String name,
String location)
Get an existing or new
Configuration object from the persistent
store. |
Configuration[] |
listConfigurations(String filter)
List the current
Configuration objects which match the filter. |
static final String SERVICE_FACTORYPID
String
.static final String SERVICE_BUNDLELOCATION
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
.Configuration createFactoryConfiguration(String factoryPid) throws IOException
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.
factoryPid
- PID of factory (not null
).Configuration
object.IOException
- if access to persistent storage fails.Configuration createFactoryConfiguration(String factoryPid, String location) throws IOException
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.
factoryPid
- PID of factory (not null
).location
- A bundle location string, or null
.Configuration
object.IOException
- if access to persistent storage fails.SecurityException
- when the require permissions are not availablenull
, ConfigurationPermission["*",CONFIGURE] if location is
null
Configuration getConfiguration(String pid, String location) throws IOException
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.
pid
- Persistent identifier.location
- The bundle location string, or null
.Configuration
object.IOException
- if access to persistent storage fails.SecurityException
- when the require permissions are not availablenull
or if the returned configuration c
already
exists and c.location is null
, ConfigurationPermission[location,CONFIGURE] if location is not
null
, ConfigurationPermission[c.location,CONFIGURE] if the returned
configuration c
already exists and c.location is not
null
Configuration getConfiguration(String pid) throws IOException
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.
pid
- persistent identifier.Configuration
matching the PID.IOException
- if access to persistent storage fails.SecurityException
- when the required permission is not availablec
already exists and c.location is not
null
Configuration getFactoryConfiguration(String factoryPid, String name, String location) throws IOException
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.
factoryPid
- PID of factory (not null
).name
- A name for Configuration
(not null
).location
- The bundle location string, or null
.Configuration
object.IOException
- if access to persistent storage fails.SecurityException
- when the require permissions are not availablenull
or if the returned configuration c
already
exists and c.location is null
, ConfigurationPermission[location,CONFIGURE] if location is not
null
, ConfigurationPermission[c.location,CONFIGURE] if the returned
configuration c
already exists and c.location is not
null
Configuration getFactoryConfiguration(String factoryPid, String name) throws IOException
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.
factoryPid
- PID of factory (not null
).name
- A name for Configuration
(not null
).Configuration
matching the PID.IOException
- if access to persistent storage fails.SecurityException
- when the required permission is not availablec
already exists and c.location is not
null
Configuration[] listConfigurations(String filter) throws IOException, InvalidSyntaxException
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 identityservice.factoryPid
- the factory PID, if applicableservice.bundleLocation
- the bundle locationnull
, meaning that all
Configuration
objects should be returned.filter
- A filter string, or null
to retrieve all
Configuration
objects.Configuration
objects, or null
if
there aren't any.IOException
- if access to persistent storage failsInvalidSyntaxException
- if the filter string is invalidc
are returned for which the caller has
this permissionCopyright © Contributors to the Eclipse Foundation Licensed under the Eclipse Foundation Specification License – v1.0