Two kinds of components are recognised by ConfigurationAdmin: ManagedService and ManagedServiceFactory. They have to be registered in the OSGi^TM service registry under one of theses 2 interfaces.

public interface ManagedService {
  /**
   * Update the configuration for a Managed Service.
   * @param properties A copy of the Configuration properties, or null.
   */ 
  void updated(Dictionary properties) throws ConfigurationException;
}

public interface ManagedServiceFactory {
  /**
   * Return a descriptive name of this factory.
   */
  String getName();

  /**
   * Create a new instance, or update the configuration of an existing instance.
   * @param pid The PID for this configuration.
   * @param properties A copy of the configuration properties.
   */
  void updated(String pid, Dictionary properties) throws ConfigurationException;

  /**
   * Remove the factory instance associated with the PID.
   * @param pid the PID of the service to be removed.
   */
  void deleted(String pid);
}

A Configuration contains both the configuration properties that have to be pushed to a consumer and an identifier that the ConfigurationAdmin service will use to find a matching component (the Configuration's consumer).

The identifier to use is the service PID (See Constants.SERVICE_PID) of the component that will receive the Configuration.

Once the Configuration is updated by the management application, everything happen asynchronously. That means that another Thread will be used to push the Configuration to its consumer (when a matching factory/service will be available).

A <configuration> element represents the configuration to be applied to a ManagedService instance.

The pid attribute is the service PID of the targeted ManagedService (match the service.pid service property of a registered OSGi^TM service).

Every key/value pair is expressed using a <property> element. The name attribute denotes (indeed) the property name used as a key in the Configuration's Dictionary. The text node's value is used as the key's value.

When the configuration XML file is undeployed, all the Configurations are deleted, ant the ManagedService.updated() method is called with a null argument. The ManagedService instance is then responsible to take the appropriate actions.

<configuration pid="service.pid.of.a.ManagedService">
  <property name="name">Guillaume</property>
  <property name="role">Developer</property>
</configuration>

A <factory-configuration> element represents the configuration to be applied to a ManagedServiceFactory instance.

The pid attribute is the service PID of the targeted ManagedServiceFactory (match the service.pid service property of a registered OSGi^TM service).

Every key/value pair is expressed using a <property> element. The name attribute denotes (indeed) the property name used as a key in the Configuration's Dictionary. The text node's value is used as the key's value.

Every <factory-configuration> will trigger the creation of a new instance by the targeted service factory.

When the configuration XML file is undeployed, all the created instances are stopped and destroyed.

<factory-configuration pid="org.ow2.jonas.web.tomcat7.internal.Tomcat7AjpConnector">
  <property name="address">localhost</property>
  <property name="port">9011</property>
</factory-configuration>

The extensibility layer supported by the ConfigurationAdmin deployer allows to use different schema element inside the XML configuration file. Theses schema will provides a dedicated format/syntax for a specific domain, something like an XML DSL (Domain Specific Language).

<configadmin xmlns="http://jonas.ow2.org/ns/configadmin/1.0"
             xmlns:mail="http://jonas.ow2.org/ns/configadmin/mail/1.0">

  <!-- This syntax is provided as an example only... -->
  <mail:session jndi-name="MailSession"
                from="no-reply@ow2.org">
    <transport name="smtp" />
    <store name="pop3"
           host="localhost" />
  </mail:session>

</configadmin>

The ConfigurationAdminDeployer provides a simple API for developers to extends the initial set of supported syntaxes.

package org.ow2.jonas.configadmin;

public interface XmlConfigurationAdapter {

    /**
     * Convert the given Node into one or more ConfigurationInfo instance(s).
     * @param node DOM Element to be converted
     * @return Adapted ConfigurationInfo(s)
     * @throws AdapterException if the Element cannot be converted into ConfigurationInfo(s)
     */
    Set<ConfigurationInfo> convert(Element node) throws AdapterException;
}

package org.ow2.jonas.configadmin;

public interface XmlConfigurationAdapterRegistry {

    /**
     * Returns the adapter handling the given Xml Element local-name.
     * @param name Xml Element local-name (not prefixed)
     * @return the associated adapter or null if none found
     */
    XmlConfigurationAdapter getAdapter(String name);
}

This example will show how to add support of the <mail:session> extension element.

Apache Felix iPOJO will be used to ease the implementation.

First, start with the adapter. Its code will take care of creating the internal ConfigurationInfo object. The adapter knows before hand the target Service PID that will accept the resulting configuration properties. The adapter then parse (or navigate through) the given DOM Element and extract the needed information from it, manipulating it if required (type convertion for example).

public class MailSessionAdapter implements XmlConfigurationAdapter {
    
    public static final String MAIL_SESSION_PID = "org.ow2...mail.Session";
    
    public Set<ConfigurationInfo> convert(Element node) throws AdapterException {

        // Create an empty configuration that will store the info from Xml
        // Hard-code the target PID
        ConfigurationInfo info = new ConfigurationInfo(MAIL_SESSION_PID, true);

        // Transfer from Xml format into internal format
        Map<String, Object> props = info.getProperties();
        props.put("jndi.name", node.getAttribute("jndi-name"));
        props.put("mail.from", node.getAttribute("from"));

        Element transport = getChildElement(node, "transport");
        props.put("mail.transport.protocol", transport.getAttribute("name"));

        // Remaining parsing omitted for brevity ...

        return Collections.singleton(info);
    }
}

	Note
	A simple implementation choice is to perform the Xml parsing by hand (navigating directly through the DOM structure), but it is also possible to use other parsing technics: XPath or JAXB (useful when schema is pre-compiled before hand).

Once the adapter is finished, it is needed to create an XmlConfigurationAdapterRegistry. This one is the component that will be registered as an OSGi^TM service with a 'namespace' service property.

@Component
@Provides
@Instantiate
public class MailAdapterRegistry implements XmlConfigurationAdapterRegistry {

    @ServiceProperty(value = "http://jonas.ow2.org/ns/example/mail")
    private String namespace;

    private XmlConfigurationAdapter sessionAdapter = new MailSessionAdapter();

    public XmlConfigurationAdapter getAdapter(String name) {
        if ("session".equals(name)) {
            return sessionAdapter;
        }
        return null;
    }
}