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 ManagedS ervice or * Managed Service Factory. * *
Configuration Plugin (plugin) services have full read/write access to all * configuration information. Therefore, bundles using this facility should * be trusted. Access to this facility should be limited with ServicePermission[REGISTER, ConfigurationPlugin]. * Implementations of a Configuration Plugin service should assure that they * only act on appropriate configurations. * *
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. * *
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 targetted 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. * * @version $Revision: 1.1.1.1 $ * @author Open Services Gateway Initiative */ public interface ConfigurationPlugin { /** * A service property to limit the Managed Service or Managed Service Factory * configuration dictionaries a Configuration Plugin service receives. * * This property contains a 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. */ String CM_TARGET = "cm.target"; /** * View and possibly modify the a set of configuration properties * before they are sent to the Managed Service or the * Managed Service Factory. The Configuration Plugin services are called * in increasing order of their 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. *
If this method throws any Exception, the Configuration Admin service * must catch it and should log it. * * @param reference reference to the Managed Service or Managed Service Factory * @param properties 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. */ void modifyConfiguration( ServiceReference reference, Dictionary properties ); }