* Copyright (c) OSGi Alliance (2001, 2011). All Rights Reserved.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
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
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
Configuration Plugin (plugin) services have full read/write access to all configuration information that passes through them.
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 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
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.
cm.target registration property means that the
plugin is called for all configuration updates.
Stringof 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.
Integerranking 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
Integerzero. This property determines the order in which plugins are invoked. Lower ranked plugins are called before higher ranked ones.
service.cmRankingproperty. If this property is undefined or is a non-
Integertype, 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.
If this method throws any
Exception, the Configuration
Admin service must catch it and should log it.
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.
referencereference to the Managed Service or Managed Service Factory
propertiesThe configuration properties. This argument must not contain the "service.bundleLocation" property. The value of this property may be obtained from the