ConfigurationPlugin
Date: 2016-06-25

org.osgi.service.cm

## Interface ConfigurationPlugin

-     @ConsumerType
      public interface ConfigurationPlugin

  A service interface for processing configuration dictionary before the update.

  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.

  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.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `CM_RANKING` A service property to specify the order in which plugins are invoked.
    `static java.lang.String` | `CM_TARGET` A service property to limit the Managed Service or Managed Service Factory configuration dictionaries a Configuration Plugin service receives.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `modifyConfiguration(org.osgi.framework.ServiceReference<?> reference, java.util.Dictionary<java.lang.String,java.lang.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.

- - ### Field Detail

    - #### CM_TARGET

          static final java.lang.String CM_TARGET

      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.
      See Also:
        Constant Field Values

    - #### CM_RANKING

          static final java.lang.String CM_RANKING

      A service property to specify the order in which plugins are invoked. This property contains an `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.
      Since:
        1.2
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### modifyConfiguration

          void modifyConfiguration(org.osgi.framework.ServiceReference<?> reference,
                                 java.util.Dictionary<java.lang.String,java.lang.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. 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.

      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.

      Parameters:
        `reference` - reference to the Managed Service or Managed Service Factory
        `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.