@ProviderType public interface Configuration
ManagedService
or
ManagedServiceFactory
object. The Configuration Admin service uses
this interface to represent the configuration information for a
ManagedService
or for a service instance of a
ManagedServiceFactory
.
A Configuration
object contains a configuration dictionary and allows
the properties to be updated via this object. Bundles wishing to receive
configuration dictionaries do not need to use this class - they register a
ManagedService
or ManagedServiceFactory
. Only administrative
bundles, and bundles wishing to update their own configurations need to use
this class.
The properties handled in this configuration have case insensitive
String
objects as keys. However, case must be preserved from the last
set key/value.
A configuration can be bound to a specific bundle or to a region of
bundles using the location. In its simplest form the location is the
location of the target bundle that registered a Managed Service or a Managed
Service Factory. However, if the location starts with ?
then the
location indicates multiple delivery. In such a case the configuration must
be delivered to all targets. If security is on, the Configuration Permission
can be used to restrict the targets that receive updates. The Configuration
Admin must only update a target when the configuration location matches the
location of the target's bundle or the target bundle has a Configuration
Permission with the action ConfigurationPermission.TARGET
and a name
that matches the configuration location. The name in the permission may
contain wildcards ( '*'
) to match the location using the same
substring matching rules as Filter
. Bundles can always create,
manipulate, and be updated from configurations that have a location that
matches their bundle location.
If a configuration's location is null
, it is not yet bound to a
location. It will become bound to the location of the first bundle that
registers a ManagedService
or ManagedServiceFactory
object
with the corresponding PID.
The same Configuration
object is used for configuring both a Managed
Service Factory and a Managed Service. When it is important to differentiate
between these two the term "factory configuration" is used.
Modifier and Type | Interface and Description |
---|---|
static class |
Configuration.ConfigurationAttribute
Configuration Attributes.
|
Modifier and Type | Method and Description |
---|---|
void |
addAttributes(Configuration.ConfigurationAttribute... attrs)
Add attributes to the configuration.
|
void |
delete()
Delete this
Configuration object. |
boolean |
equals(Object other)
Equality is defined to have equal PIDs
Two Configuration objects are equal when their PIDs are equal.
|
Set<Configuration.ConfigurationAttribute> |
getAttributes()
Get the attributes of this configuration.
|
String |
getBundleLocation()
Get the bundle location.
|
long |
getChangeCount()
Get the change count.
|
String |
getFactoryPid()
For a factory configuration return the PID of the corresponding Managed
Service Factory, else return
null . |
String |
getPid()
Get the PID for this
Configuration object. |
Dictionary<String,Object> |
getProcessedProperties(ServiceReference<?> reference)
Return the processed properties of this
Configuration object. |
Dictionary<String,Object> |
getProperties()
Return the properties of this
Configuration object. |
int |
hashCode()
Hash code is based on PID.
|
void |
removeAttributes(Configuration.ConfigurationAttribute... attrs)
Remove attributes from this configuration.
|
void |
setBundleLocation(String location)
Bind this
Configuration object to the specified location. |
void |
update()
Update the
Configuration object with the current properties. |
void |
update(Dictionary<String,?> properties)
Update the properties of this
Configuration object. |
boolean |
updateIfDifferent(Dictionary<String,?> properties)
Update the properties of this
Configuration object if the
provided properties are different than the currently stored set. |
String getPid()
Configuration
object.Configuration
object.IllegalStateException
- if this configuration has been deletedDictionary<String,Object> getProperties()
Configuration
object.
The Dictionary
object returned is a private copy for the caller
and may be changed without influencing the stored configuration. The keys
in the returned dictionary are case insensitive and are always of type
String
.
If called just after the configuration is created and before update has
been called, this method returns null
.
null
.
These properties must not contain the "service.bundleLocation"
property. The value of this property may be obtained from the
getBundleLocation()
method.IllegalStateException
- If this configuration has been deleted.Dictionary<String,Object> getProcessedProperties(ServiceReference<?> reference)
Configuration
object.
The Dictionary
object returned is a private copy for the caller
and may be changed without influencing the stored configuration. The keys
in the returned dictionary are case insensitive and are always of type
String
.
Before the properties are returned they are processed by all the
registered ConfigurationPlugin
s handling this configuration.
If called just after the configuration is created and before update has
been called, this method returns null
.
reference
- The reference to the Managed Service or Managed Service
Factory to pass to the registered ConfigurationPlugin
s
handling this configuration. Must not be null
.null
. These properties must not contain the
"service.bundleLocation" property. The value of this property may
be obtained from the getBundleLocation()
method.IllegalStateException
- If this configuration has been deleted.void update(Dictionary<String,?> properties) throws IOException
Configuration
object.
Stores the properties in persistent storage after adding or overwriting the following properties:
String
.
If the corresponding Managed Service/Managed Service Factory is registered, its updated method must be called asynchronously. Else, this callback is delayed until aforementioned registration occurs.
Also notifies all Configuration Listeners with a
ConfigurationEvent.CM_UPDATED
event.
properties
- the new set of properties for this configurationReadOnlyConfigurationException
- If the configuration is
read only
.IOException
- if update cannot be made persistentIllegalArgumentException
- if the Dictionary
object
contains invalid configuration types or contains case
variants of the same key name.IllegalStateException
- If this configuration has been deleted.void delete() throws IOException
Configuration
object.
Removes this configuration object from the persistent store. Notify
asynchronously the corresponding Managed Service or Managed Service
Factory. A ManagedService
object is notified by a call to its
updated
method with a null
properties argument. A
ManagedServiceFactory
object is notified by a call to its
deleted
method.
Also notifies all Configuration Listeners with a
ConfigurationEvent.CM_DELETED
event.
ReadOnlyConfigurationException
- If the configuration is
read only
.IOException
- If delete fails.IllegalStateException
- If this configuration has been deleted.String getFactoryPid()
null
.null
IllegalStateException
- If this configuration has been deleted.void update() throws IOException
Configuration
object with the current properties.
Initiate the updated
callback to the Managed Service or Managed
Service Factory with the current properties asynchronously.
This is the only way for a bundle that uses a Configuration Plugin
service to initiate a callback. For example, when that bundle detects a
change that requires an update of the Managed Service or Managed Service
Factory via its ConfigurationPlugin
object.
IOException
- if update cannot access the properties in persistent
storageIllegalStateException
- If this configuration has been deleted.ConfigurationPlugin
boolean updateIfDifferent(Dictionary<String,?> properties) throws IOException
Configuration
object if the
provided properties are different than the currently stored set.
Properties are compared as follows.
equals
Arrays.equals
equals
update(Dictionary)
method.properties
- The new set of properties for this configuration.true
is returned. If the properties are the same,
false
is returned.ReadOnlyConfigurationException
- If the configuration is
read only
.IOException
- If update cannot be made persistent.IllegalArgumentException
- If the Dictionary
object
contains invalid configuration types or contains case
variants of the same key name.IllegalStateException
- If this configuration has been deleted.void setBundleLocation(String location)
Configuration
object to the specified location.
If the location parameter is null
then the Configuration
object will not be bound to a location/region. It will be set to the
bundle's location before the first time a Managed Service/Managed Service
Factory receives this Configuration
object via the updated method
and before any plugins are called. The bundle location or region will be
set persistently.
If the location starts with ?
then all targets registered with
the given PID must be updated.
If the location is changed then existing targets must be informed. If
they can no longer see this configuration, the configuration must be
deleted or updated with null
. If this configuration becomes
visible then they must be updated with this configuration.
Also notifies all Configuration Listeners with a
ConfigurationEvent.CM_LOCATION_CHANGED
event.
location
- a location, region, or null
IllegalStateException
- If this configuration has been deleted.SecurityException
- when the required permissions are not availablenull
, ConfigurationPermission[location,CONFIGURE] if location is not
null
, ConfigurationPermission["*",CONFIGURE] if this.location is
null
or if location is null
String getBundleLocation()
null
if it is not yet bound to a bundle location or
region. If the location starts with ?
then the configuration is
delivered to all targets and not restricted to a single bundle.null
.IllegalStateException
- If this configuration has been deleted.SecurityException
- when the required permissions are not availablenull
, ConfigurationPermission["*",CONFIGURE] if this.location is
null
long getChangeCount()
IllegalStateException
- If this configuration has been deleted.void addAttributes(Configuration.ConfigurationAttribute... attrs) throws IOException
attrs
- The attributes to add.IOException
- If the new state cannot be persisted.IllegalStateException
- If this configuration has been deleted.SecurityException
- when the required permissions are not availablenull
, ConfigurationPermission["*",ATTRIBUTE] if this.location is
null
Set<Configuration.ConfigurationAttribute> getAttributes()
IllegalStateException
- If this configuration has been deleted.void removeAttributes(Configuration.ConfigurationAttribute... attrs) throws IOException
attrs
- The attributes to remove.IOException
- If the new state cannot be persisted.IllegalStateException
- If this configuration has been deleted.SecurityException
- when the required permissions are not availablenull
, ConfigurationPermission["*",ATTRIBUTE] if this.location is
null
boolean equals(Object other)
Copyright © Contributors to the Eclipse Foundation Licensed under the Eclipse Foundation Specification License – v1.0