OSGi Declarative Services components are configured by properties defined by the component developer in the component descriptor and by configuration managed by system administrators using the OSGi Configuration Admin Service. The combined set of properties is traditionally made available to the component as a Dictionary calling the ComponentContext.getProperties() method. The component context is provided to the activate method called when the component is activated.
This makes configuration of components very simple, since the component itself does not have to care where configuration comes from and how it is maintained. In addition, a component always knows it is starting from scratch when the activate method is called. This is because a component instance is never reused and a component reconfiguration means the component is deactivated and activated with the new configuration.
There are some drawbacks to this solution, though:
- Reactivation of a component may be an expensive operation. Particularly if the component provides a service which is heavily used and relied upon, such as for example the SlingRepository service in Communique 5.
- If a component is keeping internal state, e.g. gathering statistics, reactivation of the component will cause loss of this state.
This is where the new Declarative Services specification version 1.1 kicks in and improves much. First of all, configuration may be updated dynamically without reactivating the component. Second a component may declare itself as not needing configuration or even as requiring configuration thus only activating the component if configuration is actually available from the Configuration Admin service.
To use dynamic reconfiguration you have to declare a method to take this updated configuration in the modified attribute of the component element. When using the Apache Felix Maven SCR Plugin, use the modified attribute of the @scr.component tag:
@scr.component modified="modified"
and define a method taking the configuration, for example:
private void modified(Mapconfig) {
// apply the configuration dynamically
}
Unless the configuration may cause the component's references to be modified the component configuration is now dynamically provided without reactivating the component.
The method defined in the modified attribute has the same requirements as the activate method: It may be have any access modifier (but should not be public) and it may take any combination of ComponentContext, BundleContext, and Map arguments. Of course for a modified the primary useful type Map as in the example above<.
If you know your component cannot be configured or if you absolutely need configuration of your component, you can declare this desire using the configuration-policy attribute of the component element (or the policy attribute of the @scr.component JavaDoc tag):
- optional
- Configuration from the Configuration Admin Service is provided to the component if available. This is the default setting and is the same as in the previous Declarative Services specification.
- require
- Configuration from the Configuration Admin Service is required for the component to be activated. If the configuration is deleted, the component will be deactivated. This setting allows for a component to be controlled by the existence of configuration.
- ignore
- Configuration from the Configuration Admin Service is never retrieved on behalf of and provided to the component. If your component has no configurable properties, this setting makes sense.
Note: To use the functionality described in this article, you have to use a Declarative Services 1.1 implementation such as Apache Felix SCR 1.2.0 or newer.