Page History

...

The Configuration Admin service is a configuration manager describe in the OSGi R4 Compendium. It allows an operator to set the configuration information of deployed applications .  The Configuration Admin defines the Configuration as the process of defining the configuration data of applications and assuring that those applications receive that data when they are running. The Configuration Admin is becoming an important piece on OSGi Gateway. It is become the standard way to configure applications on OSGi gateways.

...

• Create new component instances
• Configuring / Reconfiguring reconfiguring these instances
• Destroying these instances instances
• Reconfiguring instances by using Managed Services (not addressed in this page, see HERE for further information)

The configuration admin is persistent, so stored configuration will be reload it the framework restarts.
Moreover, using the configuration admin allows avoiding describing instances inside iPOJO metadata file. These instances are created by inserting new configurations in the configuration admin.

...

All these examples are downloadable here. The archive contains both the project sources and a pre-configured version of felix.
To compile the project, launch ant from the config.admin.tutorial directory
Then, you can launch Felix by launching the following command from the felix-1.0.3 directory

Java -jar bin/felix.jar

Note When felix asks for a profile name, enter any name

Prerequisites

Let's take 4 Felix shell commands to manage configuration admin configurations (available in the example archive):

• Create_conf <type> <property-key=property-value>* allows to create a new Factory Configuration attached to the given type. The configuration contains the given properties.
• Update_conf <configuration_name> < property-key=property-value>* allows to update the configuration with the given name with the given properties.
• Delete_conf <configuration_name> allows deleting the configuration with the given name. If the name is 'all', delete all stored configurations.
• List_conf allows listing all stored configuration.

...

-> ps
START LEVEL 1
   ID   State         Level  Name
[   0] [Active     ] [    0] System Bundle (0.91.0.incubator-SNAPSHOT3)
[   1] [Active     ] [    1] Apache Felix Shell Service (1.0.9.0.incubator_SNAPSHOT)
[   2] [Active     ] [    1] Apache Felix Shell TUI (1.0.9.0.incubator_SNAPSHOT)
[   3] [Active     ] [    1] Apache Felix Bundle Repository (0.91.0.incubator_SNAPSHOT2)
[   4] [Active     ] [    1] Apache Felix Configuration Admin ServiceiPOJO (0.97.06.incubator_SNAPSHOT)
[   5] [Active     ] [    1] iPOJO Arch Felix Command (0.7.16.incubator_SNAPSHOT)
[   6] [Active     ] [    1] OSGiApache Felix R4Configuration CompendiumAdmin BundleService (4)
[   7] [Active     ] [    1] javax.servlet-2.3 (0.0.1)

Simple

...

Instanciation

Imagine the following dummy very simple component implementation:

public class Hello1 {
    public Hello1() {
        System.out.println("Hello");
    }
}

The component type is defined with following metadata:

<component classname="org.apache.felix.ipojo.example.ca.component.Hello1" factory="hello1" immediate="true" architecture="true"/>

The defined component type (Hello1) just creates a Hello1 object when the instance is created (thanks to the immediate attribute).
So if we deploy this bundle and add a consistent configuration we obtain:

-> start file:/F:\dev\workspaces\iPOJO_dev\ConfigAdminExample\ConfigAdminExample..\config.admin.tutorial\output\config.admin.tutorial.jar
-> create_conf hello1
Insert the configuration : {service.factoryPid=hello1}
-> Hello

Note: Debug messages from the configuration admin were removed
So as predicted, the Hello message appears. To be really sure of the creating, we can ask for the instance architecture (the component type allows architecture introspection thank to the architecture attribute):

-> arch
Instance ArchCommand -> valid
*Instance hello1.02f683efe40fe80a-85b22c0d-44fc4c51-8ef5b00b-719d40557c07a82565874cd8 -> valid*
->
-> arch -instance hello1.02f683efe40fe80a-85b22c0d-44fc4c51-8ef5b00b-719d40557c07a82565874cd8
instance name="hello1.02f683efe40fe80a-85b22c0d-44fc4c51-8ef5-719d40557c07b00b-a82565874cd8" component.type="hello1" state="valid" bundle="8" component.type="hello1"
	7"
        object name="org.apache.felix.ipojo.example.ca.component.Hello1@120cc56"
        handler name="org.apache.felix.ipojo.handlers.lifecycle.callback.LifecycleCallbackHandler" state="valid"
	        handler name="org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler" state="valid"
	object name="org.apache.felix.ipojo.example.ca.component.Hello1@16925b0"
->

So, the instance is correctly created. The name of the instance was created from the given one by the configuration admin. It could change according to your configuration admin implementation.

Note : The arch command is available on the Felix trunk

Then, we can delete the instance by removing the configuration from the configuration admin:

-> delete_conf hello1.02f683efe40fe80a-85b22c0d-44fc4c51-8ef5b00b-719d40557c07a82565874cd8
Delete the configuration : hello1.02f683efe40fe80a-85b22c0d-44fc4c51-8ef5b00b-719d40557c07a82565874cd8
-> arch
Instance ArchCommand -> valid

So, arch does no more displayed any instance hello instances, the created instance was disposed.

...

Imagine the following component implementation:

public class Hello2 {
     String m_name;
    public void stop() {
        System.out.println("Good by " + m_name);
    }
    public void setName(String newName) {
        m_name = newName;
        System.out.println("Hello " + m_name);
    }

And the following metadata:

<component classname="org.apache.felix.ipojo.example.ca.component.Hello2" factory="hello2" immediate="true" architecture="true">
	<callback initialtransition="VALIDvalidate" final="INVALID" method="stop"/>
	<properties>
		<property field="m_name" name="to" method="setName"/>
	</properties>
</component>

The defined component type (Hello2) write "Hello + $name" when the property 'to' (attached to the field _m_name_) receive a new value. A value is necessary insert in the instance configuration. Moreover when killed, the instance will display a "Good By" message.
Let's play a simple scenario:

• Create an a Hello2 instance
• Update the instance configuration
• Kill the created instance

-> create_conf hello2 to=clementipojo
Insert the configuration : {service.factoryPid=hello2, to=clement}ipojo}
Created configuration: hello2.75082279-9b4b-4c49-b0e0-8efb38b67aa3
Hello clementipojo
-> list_conf
hello2.e41713c375082279-9ff89b4b-4bbb4c49-a128b0e0-97d267962e588efb38b67aa3 : {service.pid=hello2.e41713c375082279-9ff89b4b-4bbb4c49-a128b0e0-97d267962e588efb38b67aa3, service.factorypid=hello2, to=clementipojo}
-> update_conf hello2.e41713c375082279-9ff89b4b-4bbb4c49-a128b0e0-97d267962e588efb38b67aa3 to=Rickfelix
Update the configuration : {service.pid=hello2.e41713c375082279-9ff89b4b-4bbb4c49-a128-97d267962e58, service.factorypid=hello2, to=Rickb0e0-8efb38b67aa3
Update the configuration : {to=felix}
Hello Rickfelix
-> delete_conf hello2.e41713c375082279-9ff89b4b-4bbb4c49-a128b0e0-97d267962e588efb38b67aa3
Delete the configuration : hello2.e41713c375082279-9ff89b4b-4bbb4c49-a128b0e0-97d267962e588efb38b67aa3
Good by Rick felix
-> list_conf

In this simple scenario, we see that when updated the attached configuration is updated, the instance receives the new value. The setName method is immediately invoked to inject the new value. Moreover, when the configuration is deleted, the instance is going to be killed: the "Good Bye" message appears and the instance is disposed.
Obviously it is possible to create several instance of the same type:

-> create_conf hello2 to=clementipojo
Insert the configuration : {service.factoryPid=hello2, to=clementipojo}
 Hello clementipojo
-> create_conf hello2 to=rickfelix
Insert the configuration : {service.factoryPid=hello2, to=rickfelix}
 Hello rickfelix
-> arch
Instance ArchCommand -> valid
Instance hello2.3d64ae54aaf1927c-98ae1a81-43f4490d-845abd7b-15956b2a78ce21b13d454987 -> valid
Instance hello2.b5e3fc829344fdbe-25bfc35e-41914afc-bb56b839-f5afe516e2faf7ad0ea59a9d -> valid 

The 'arch' command displays the two created instances.

Note you can delete all created configurations with the delete_conf all command

Property Propagation

It is possible to propagate the instance configuration to the published service properties. To activate property propagation you need to write the 'configurablepropagation' attribute in the 'properties' element as in

<component classname="org.apache.felix.ipojo.example.ca.component.Hello3" factory="hello3" architecture="true">
	<provides/>
	<properties configurablepropagation="true">
		<property field="m_name" value="clement"/>
	</properties>
</component>

The defined type provides a service. Moreover it supports properties propagation. So all property, except listed one (m_name), will be published inside the provided services.
Imagine that we have created So create an instance of the previous component. Service information about this instance are:Hello3 component type as follow:

-> create_conf hello3
Insert the configuration : {service.factoryPid=hello3}

Then, you can check provided services with the services 7 command

-> services 7
// Factories and Managed Service factories //
----
factory.name = hello3
instance.name = hello3.a5ca5901-6e20-4636-8805-fbca2db1d68b

factory.pid = hello3
objectClass = org.apache.felix.ipojo.example.ca.service.Hello
service.factoryPid = hello3
service.id = 287
service.pid = hello3.e964c4e0-029f-4e49-a7cd-a4d8880f20c169
->

Now, we update the instance configuration with a new property 'p1':

-> update_conf hello3.e964c4e0a5ca5901-029f6e20-4e494636-a7cd8805-a4d8880f20c1fbca2db1d68b p1=v1
Update the configuration : {p1=v1}
-> Remove : {service.pid=hello3.e964c4e0-029f-4e49-a7cd-a4d8880f20c1, service.factoryPid=hello3}
-> services 8
ConfigAdminExample (8) provides:services 7

config.admin.tutorial (7) provides:
// Factories and Managed Service factories //
----
factory.pidname = hello3
instance.name = hello3.a5ca5901-6e20-4636-8805-fbca2db1d68b
objectClass = org.apache.felix.ipojo.example.ca.service.Hello
p1 = v1
service.factoryPid = hello3
service.id = 287
service.pid = hello3.e964c4e0-029f-4e49-a7cd-a4d8880f20c1
69

Remark that the new property p1 is published.
Now we can remove this property by reconfiguring the instance with an empty configuration:

-> update_conf hello3.e964c4e0a5ca5901-029f6e20-4e494636-a7cd8805-a4d8880f20c1fbca2db1d68b
Update the configuration : {} 
-> services 87
ConfigAdminExample (8) provides:
// Factories and Managed Service factories //
----
factory.pid.name = hello3
instance.name = hello3.a5ca5901-6e20-4636-8805-fbca2db1d68b
objectClass = org.apache.felix.ipojo.example.ca.service.Hello
service.factoryPid = hello3
service.id = 287
service.pid = hello3.e964c4e0-029f-4e49-a7cd-a4d8880f20c1
69

The service does no more publish the p1 property.

...

This page has presented how to combine the configuration admin and iPOJO. If you have any comment or question, do not hesitate to send me an email. Subscribe to the Felix users mailing list by sending a message to users-subscribe@felix.apache.org; after subscribing, email questions or feedback to users@felix.apache.org