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(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.
Modifier and Type | Field and Description |
---|---|
static String |
SERVICE_BUNDLELOCATION
Configuration property naming the location of the bundle that is
associated with a 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[] |
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.
factoryPid
- PID of factory (not null
).Configuration
object.IOException
- if access to persistent storage fails.SecurityException
- if caller does not have ConfigurationPermission[*,CONFIGURE]
and factoryPid
is bound to another bundle.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.
factoryPid
- PID of factory (not null
).location
- A bundle location string, or null
.Configuration
object.IOException
- if access to persistent storage fails.SecurityException
- if caller does not have ConfigurationPermission[*,CONFIGURE]
.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.
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.
pid
- Persistent identifier.location
- The bundle location string, or null
.Configuration
object.IOException
- if access to persistent storage fails.SecurityException
- if the caller does not have ConfigurationPermission[*,CONFIGURE]
.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
- if the Configuration
object is bound to a location different from that of the calling bundle and it has no ConfigurationPermission[*,CONFIGURE]
.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.
Normally only Configuration
objects that are bound to the
location of the calling bundle are returned, or all if the caller has
ConfigurationPermission[*,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
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 invalidCopyright © 2018 JBoss by Red Hat. All rights reserved.