Configuration Admin

Configuration Admin is a service defined by OSGi that allows deployed bundles to be dynamically configured. The OSGi specification defines the ConfigurationAdmin service as follows:

"The Configuration Admin service is responsible for supplying configuration target bundles with their configuration information. It maintains a database with configuration information, keyed on the service.pid of configuration target services. These services receive their configuration dictionary or dictionaries when they are registered with the Framework. Configurations can be modified or extended using Configuration Plugin services before they reach the target bundle."

The Configuration Admin service is responsible for knowing the various configurations and for notifying target bundles of configuration changes. There are two flavors of target bundle, which are defined by the OSGi specification as follows:

ManagedService: "A Managed Service represents a client of the Configuration Admin service, and is thus a configuration target. Bundles should register a Managed Service to receive the configuration data from the Configuration Admin service. A Managed Service adds a unique service.pid service registration property as a primary key for the configuration information."
Managed Service Factory: "A Managed Service Factory can receive a number of configuration dictionaries from the Configuration Admin service, and is thus also a configuration target service. It should register with a service.pid and receives zero or more configuration dictionaries. Each dictionary has its own PID."

Managed Service

The OSGi specification states that a Managed Service should be registered by a bundle when it create a singleton object that needs to be remotely configured.

By registering a Managed Service a bundle will receive configuration data from the Configuration Admin bundle that it uses to create and configure a singleton object. The singleton object that a Managed Service creates is often, but not always, registered as an OSGi service.
See the OSGi Configuration Admin Service Specification for more information on ManagedService objects and the ConfigurationAdmin service.

The OSGi specification defines the ManagedService interface as follows:

  public interface ManagedService {
    void updated(Dictionary properties) throws ConfigurationException;
  }

A bundle should implement this interface and register a ManagedService with the OSGi framework. The service will be notified by the ConfigurationAdmin bundle when the configuration is created, updated and deleted.

The updated(Dictionary) method is called whenever the configuration is created, updated and deleted. The parameter is the configuration's properties.
- A non-null parameter means that the configuration has either been created or updated. It is the responsibility of the Managed Service to keep track of whether the singleton object must be created or updated. If the singleton object is to be registered as an OSGi service then the Managed Service must consider carefully how to handle updates. In some cases the singleton object can simply be updated, while in other cases the singleton object might need to be unregistered and destroyed, and then re-created and re-registered as an OSGi service.
- A null parameter means that the configuration has been deleted. The Managed Service must again consider carefully how to handle the deletion of a configuration. How this is handled depends on the implementation of the singleton object and whether it has been registered as an OSGi service.

While creating a ManagedService is in principal simple, consider the following problems that must be addressed:

What if the singleton object needs to acquire one or more imported service?
What if the imported services vary based on the configuration's properties?
What if an imported service needs to be acquired based on an LDAP filter that varies based on the configuration's properties?
How are you going to handle the case where one of the acquired imported services needs to be released because it has been unregistered or has changed it registered properties?

Managed Service Factory

When a bundle needs to create objects based on varying runtime configuration data, the OSGi specification states that a Managed Service Factory should be used.

By registering a Managed Service Factory a bundle will receive multiple sets of configuration data from the Configuration Admin bundle that it uses to create and configure objects. The objects that a Managed Service Factory creates are often, but not always, registered as OSGi services themselves.
The term Managed Service Factory is a misnomer: If you were to visit a chocolate factory you would expect to see a factory that makes chocolate, not a factory made out of chocolate. A Managed Service Factory is not a factory that makes Managed Service objects, but rather an object factory that is also a Managed Service. For this reason, the name Factory Managed Service would have been a better choice, but it was not to be.
See the OSGi Configuration Admin Service Specification for more information on ManagedServiceFactory objects and the ConfigurationAdmin service.

OSGi defines the ManagedServiceFactory interface as follows:

  public interface ManagedServiceFactory {
    String getName();
    void updated(String pid, Dictionary properties) throws ConfigurationException;
    void deleted(String pid);
  }

A bundle should implement this interface and register the ManagedServiceFactory object with the OSGi framework. The service will be notified by the ConfigurationAdmin bundle when a configuration is created, updated and deleted.

The getName() method simply returns a descriptive name for the factory.
- A reasonable implementation of this method would be to return the fully qualified class name of the Managed Service Factory.
- Returning a name that uniquely identifies the factory is desirable but not required.
- The name is used for debugging and tool support.
The updated(String, Dictionary) method is called whenever a configuration is created and updated. The first parameter is the persistent ID, often referred to as simply the pid, for the configuration, and the second parameter is the configuration's properties.
- It is the responsibility of the factory to manage the object it creates for each configuration, which is typically done using a Map, with the persistent ID as the key and the object created for the configuration as the value.
- If the persistent ID does not exist as a key in the Map then the configuration is clearly new, meaning that the factory must create an object using the properties, and store it in the Map.
- Sometimes the object created needs to acquire one or more services from the OSGi framework.
- Sometimes the object created will be registered as a service with the OSGi framework.
- If the persistent ID exists as a key in the Map then the configuration is clearly not new, meaning that the factory must update the associated object in the Map using the properties. This might mean simply updating the object, or it might mean creating a brand new object that replaces the existing one.
The deleted(String) method is called whenever one of the factory's configurations is deleted by ConfigurationAdmin. The parameter is the persistent ID for the deleted configuration.
- The factory is responsible for destroying the object associated with the persistent ID. How the object is destroyed is dependent upon the type of object. Many objects need no custom destruction.
- If the object was registered as a service with the OSGi framework, it must be unregistered.
- Once the object is destroyed the persistent ID is removed from the Map.

Creating a ManagedServiceFactory as described above is only really feasible for the simplest cases. In fact, even simple cases can be complicated to implement. Consider the following problems that must be addressed:

What if the application requires many bundles to implement a Managed Service Factory? Implementing the code to manage the objects created for each configuration is complicated, repetitive and error prone.
What if an object created by the factory needs to acquire one or more imported service?
What if the imported services for each object vary based on the configuration's properties?
What if an imported service needs to be acquired based on an LDAP filter that varies based on the configuration's properties?
How are you going to handle the case where one of the acquired imported services needs to be released because it has been unregistered or has changed it registered properties?

How Does SAT Help?

Implementing a bundle that registers a Managed Service or a Managed Service Factory can be complicated and error prone. SAT provides support to make it very easy for a bundle to register a Managed Service or a Managed Service Factory. This support is provided via two abstract subclasses of SAT's BaseBundleActivator class, one for registering a ManagedService and another for registering a ManagedServiceFactory. In this way, the bundle activator is the managed service, or, is the managed service factory, implying that a single bundle may register exactly one ManagedService, or register exactly one ManagedServiceFactory.

Rest assured that with a little more effort, SAT supports a single bundle registering multiple instances of a ManagedService and multiple instances of a ManagedServiceFactory.