@ConsumerType public interface ConfigurationPlugin
A bundle registers a ConfigurationPlugin
object in order to process
configuration updates before they reach the Managed Service or Managed
Service Factory. The Configuration Admin service will detect registrations of
Configuration Plugin services and must call these services every time before
it calls the ManagedService
or ManagedServiceFactory
updated
method. The Configuration Plugin service thus has the
opportunity to view and modify the properties before they are passed to the
Managed Service or Managed Service Factory.
Configuration Plugin (plugin) services have full read/write access to all configuration information that passes through them.
The Integer
service.cmRanking
registration property may be
specified. Not specifying this registration property, or setting it to
something other than an Integer
, is the same as setting it to the
Integer
zero. The service.cmRanking
property determines the
order in which plugins are invoked. Lower ranked plugins are called before
higher ranked ones. In the event of more than one plugin having the same
value of service.cmRanking
, then the Configuration Admin service
arbitrarily chooses the order in which they are called.
By convention, plugins with service.cmRanking < 0
or
service.cmRanking > 1000
should not make modifications to the
properties. Any modifications made by such plugins must be ignored.
The Configuration Admin service has the right to hide properties from plugins, or to ignore some or all the changes that they make. This might be done for security reasons. Any such behavior is entirely implementation defined.
A plugin may optionally specify a cm.target
registration property
whose value is the PID of the Managed Service or Managed Service Factory
whose configuration updates the plugin is intended to intercept. The plugin
will then only be called with configuration updates that are targeted at the
Managed Service or Managed Service Factory with the specified PID. Omitting
the cm.target
registration property means that the plugin is called
for all configuration updates.
Modifier and Type | Field and Description |
---|---|
static String |
CM_RANKING
A service property to specify the order in which plugins are invoked.
|
static String |
CM_TARGET
A service property to limit the Managed Service or Managed Service
Factory configuration dictionaries a Configuration Plugin service
receives.
|
Modifier and Type | Method and Description |
---|---|
void |
modifyConfiguration(ServiceReference<?> reference,
Dictionary<String,Object> properties)
View and possibly modify the a set of configuration properties before
they are sent to the Managed Service or the Managed Service Factory.
|
static final String CM_TARGET
String[]
of PIDs. A Configuration Admin
service must call a Configuration Plugin service only when this property
is not set, or the target service's PID is listed in this property.static final String CM_RANKING
Integer
ranking of the plugin. Not
specifying this registration property, or setting it to something other
than an Integer
, is the same as setting it to the Integer
zero. This property determines the order in which plugins are invoked.
Lower ranked plugins are called before higher ranked ones.void modifyConfiguration(ServiceReference<?> reference, Dictionary<String,Object> properties)
service.cmRanking
property. If this property is undefined or is a
non- Integer
type, 0 is used.
This method should not modify the properties unless the
service.cmRanking
of this plugin is in the range
0 <= service.cmRanking <= 1000
. Any modification
from this plugin is ignored.
If this method throws any Exception
, the Configuration Admin
service must catch it and should log it. Any modifications made by the
plugin before the exception is thrown are applied.
A Configuration Plugin will only be called for properties from configurations that have a location for which the Configuration Plugin has permission when security is active. When security is not active, no filtering is done.
reference
- reference to the Managed Service or Managed Service
Factoryproperties
- The configuration properties. This argument must not
contain the "service.bundleLocation" property. The value of this
property may be obtained from the
Configuration.getBundleLocation
method.Copyright © Contributors to the Eclipse Foundation Licensed under the Eclipse Foundation Specification License – v1.0