Page History

...

This page describes how works the composition mechanisms provided by iPOJO and how to use it. this feature allows you to design applications that will natively support the dynamism and the evolution.

...

Why providing a composition layer?

...

Service or component composition has a stringent requirement. How to isolate components and services of an application to avoid side effects as an unexpected access to a used service ...iPOJO composites just provide an isolation mechanism. Services provided inside a composite ARE NOT published globally (inside the OSGi service registry). So, only the component instances living in the same composite can access to those services.
However, it is also possible to import a service from the parent/global service registry, as well as to export a service to the parent (i.e. superior) composite.

The different types of composition in the

...

OSGi world

Basically there is two types of composition in OSGi™OSGi:

• The intra-bundle composition
• The service-based composition

...

First, a composite type is declared inside an iPOJO descriptor. A composite contain always a name attribute, which is the component type name. Inside the <composite></composite>, three instances are declared: the three instances used by our application. Remark that these instances are declared as 'regular' instances. The component attribute indicates the component type to use. Instances can be configured as regular iPOJO instances. Finally, an instance of our type is also declared.
To execute our composition, go in the felix directory and launch the following command:

java -jar bin/felix.jar

This version of Felix starts with the iPOJO framework, the iPOJO Arch command and the composite support. So, we just need to install our component types and the composition.
In the Felix prompt, launch the following commands:

start file:../spell.services/output/spell.services.jar
start file:../spell.english/output/spell.english.jar
start file:../spell.checker/output/spell.checker.jar
start file:../spell.checker.gui/output/spell.checker.gui.jar

Those commands deploy the component types. Remark that no 'functional' (i.e. neither Check service, nor Dictionary service) services are provided. Deployed bundles provide only iPOJO Factory services:

-> inspect servicess c
System Bundle (0) provides:
---------------------------
org.osgi.service.startlevel.StartLevel
org.osgi.service.packageadmin.PackageAdmin
Apache Felix Shell Service (1) provides:
----------------------------------------
...
Apache Felix Bundle Repository (3) provides:
--------------------------------------------
org.osgi.service.obr.RepositoryAdmin
iPOJO (4) provides:
-------------------
...
iPOJO Composite (6) provides:
-----------------------------
...
spell.english (8) provides:
---------------------------
org.apache.felix.ipojo.Factory, org.osgi.service.cm.ManagedServiceFactory
spell.checker (9) provides:
---------------------------
org.apache.felix.ipojo.Factory, org.osgi.service.cm.ManagedServiceFactory
spell.checker.gui (10) provides:
-------------------------------
org.apache.felix.ipojo.Factory, org.osgi.service.cm.ManagedServiceFactory

...

Once deployed and started, the fancy GUI appears:

Now, you can check that the functional services are not unavailable outside the composite:

-> inspect s servicesc
System Bundle (0) provides:
---------------------------
org.osgi.service.startlevel.StartLevel
org.osgi.service.packageadmin.PackageAdmin
Apache Felix Shell Service (1) provides:
----------------------------------------
...
Apache Felix Bundle Repository (3) provides:
--------------------------------------------
org.osgi.service.obr.RepositoryAdmin
iPOJO (4) provides:
-------------------
...
iPOJO Composite (6) provides:
-----------------------------
...
spell.english (8) provides:
---------------------------
org.apache.felix.ipojo.Factory, org.osgi.service.cm.ManagedServiceFactory
spell.checker (9) provides:
---------------------------
org.apache.felix.ipojo.Factory, org.osgi.service.cm.ManagedServiceFactory
spell.checker.gui (10) provides:
-------------------------------
org.apache.felix.ipojo.Factory, org.osgi.service.cm.ManagedServiceFactory
Bundle 11 provides:
-------------------
org.apache.felix.ipojo.Factory, org.osgi.service.cm.ManagedServiceFactory

...

This composite just adds a subservice nested element. This subservice allows importing a service inside the composite. The action attribute specifies that we want to import the service from the parent scope (i.e. superior). The specification attribute indicates the required service.

Now, relaunch Felix and enter another profile name (composition2 for example). Once started, executes the following commands:

start file:bundle/org.apache.felix.log-0.9.0-SNAPSHOT.jar
start file:../spell.services/output/spell.services.jar
start file:../spell.english/output/spell.english.jar
start file:../spell.checker-v2/output/spell.checker-v2.jar
start file:../spell.checker.gui/output/spell.checker.gui.jar
start file:../example2/output/composition2.jar

...

stop 9
start 9
stop 710
start 710

When the log service is stopped, the GUI disappears. In fact, the service can no more be imported, and so, the composition becomes invalid. When you stop a bundle containing a used component type, the same behaviour behavior occurs.
Like in the previous example, you can check that only the log service is globally available. Other services are isolated inside the composite.
In this case the parent scope is the OSGi service registry, but composite can also contain other composite. In such context, the import tracks services from the superior composite. An example of hierarchical composition is described later in this tutorial.

...

These commands deploy component types and the composition. Only one implementation of the dictionary service is available (English). You can check this by executing the service 8 command.

-> inspect s servicesc 89
spell.english (89) provides:
---------------------------
component.class = spell.english.EnglishDictionary
component.description = <unknown value type>
component.properties = <unknown value type>
component.providedServiceSpecifications = spell.services.DictionaryService
factory.name = spell.english.EnglishDictionary
factory.state = 1
objectClass = org.apache.felix.ipojo.Factory, 
              org.osgi.service.cm.ManagedServiceFactory
service.id = 39
service.pid = spell.english.EnglishDictionary

...

Write welcome in the GUI and then check. The word is correctly spelled. Then, stop the bundle providing the English dictionary.

stop 89

Write welcome in the GUI, and check. The word is misspelled! Try to write bienvenue and check. The word is correctly spelled. This means that the composite has substitutes the previous English dictionary by the French one. This one will be use until it disappears. If you stop the bundle containing this implementation, the composite becomes invalid.

...

You can check that the composition exports the service with the following command:

-> services 1112
Bundle 1112 provides:
-------------------
component.description = <unknown value type>
component.properties = <unknown value type>
component.providedServiceSpecifications = spell.services.SpellChecker
factory.name = composition4
factory.state = 1
objectClass = org.apache.felix.ipojo.Factory, 
              org.osgi.service.cm.ManagedServiceFactory
service.id = 36
service.pid = composition4
----
factory.name = composition4
instance.name = composition4-0
objectClass = spell.services.SpellChecker
service.id = 37

So, now you can play with dynamism. Stop the bundle containing the Check service implementation. The GUI disappears. Restart it. The GUI reappears. Now, stop the bundle containing the GUI implementation. The checker service stills available. Indeed, the GUI is no more inside the composition, and so stills valid despite the unavailability of the GUI:

-> stop 89
-> start 89
-> stop 1011
-> services 11inspect s c 12
Bundle 1112 provides:
-------------------
component.description = <unknown value type>
component.properties = <unknown value type>
component.providedServiceSpecifications = spell.services.SpellChecker
factory.name = composition4
factory.state = 1
objectClass = org.apache.felix.ipojo.Factory, 
              org.osgi.service.cm.ManagedServiceFactory
service.id = 36
service.pid = composition4
----
factory.name = composition4
instance.name = composition4-0
objectClass = spell.services.SpellChecker
service.id = 41
-> 

...

This page has presented how to use iPOJO composition model. Several topics were not addressed and will be added shortly:

• Service Dynamic service implementation
• The dependency model
• Composable services and composition consistency
• Context-awareness

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.