felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fmesc...@apache.org
Subject svn commit: r1421893 [8/24] - in /felix/site/trunk/content: ./ documentation/ documentation/community/ documentation/development/ documentation/faqs/ documentation/subprojects/ documentation/subprojects/apache-felix-commons/ documentation/subprojects/a...
Date Fri, 14 Dec 2012 14:30:22 GMT
Added: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-composition-tutorial.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-composition-tutorial.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-composition-tutorial.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-composition-tutorial.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,460 @@
+Title: iPOJO Composition Tutorial
+
+{include:apache-felix-ipojo-header}
+
+<div class="content">
+
+# iPOJO Composition Tutorial
+*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.*
+
+{div:class=toc}
+[TOC]
+{div}
+
+## Why providing a composition layer?
+iPOJO aims to simplify the creation of OSGi (dynamic) applications. Creating such as applications is basically a two steps process:
+* Developing services and components
+* Assembling them together to create the application
+
+To tackle the first step, iPOJO provides an easy-to-use development model. But, this does not help to design the application. To conduct the second step, iPOJO provides a composition language allowing to:
+* Assemble components and services together
+* Assert service isolation inside a composition
+* Hide/Abstract implementations 
+
+### What about privacy?
+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:
+* The intra-bundle composition
+* The service-based composition
+
+### Intra-bundle composition
+The intra-bundle composition is the policy followed by Spring-DM. Each bundle contains components. These components can require and provide services from the global (OSGi) registry. Moreover, these components can collaborate together inside the bundle without providing/requiring services. So the isolation scope of intra-bundle composition is the *bundle*. This type of composition allows providing coarse-grain services provided by the collaboration of several components. However, it is not possible to update one of those components, as the update unity is the bundle.
+
+### Service-based composition
+There are two types of service composition. The behavioral service composition is like [BPEL](http://www.ibm.com/developerworks/library/specification/ws-bpel/) for the web services. An orchestrator supervises the execution and the collaboration of services like:
+1. Call service A
+1. Call service B 
+1. ...
+
+The second type of service composition is the structural service composition. This aims to provide a kind of Architecture Description Language for service-based applications. iPOJO follows this trend. This way as several advantages:
+* Avoids coupling a composition to specific implementation, and so it supports the dynamic substitution
+* Allows the evolution of used services and components at runtime
+This is also the way followed by [SCA](http://www.ibm.com/developerworks/library/specification/ws-sca/). However, SCA does not specify how the dynamism should be handled.
+
+## The iPOJO composition theory for the dummies
+The distinction between component types and instances
+When you declare a `<component>` (or a `<composite>`) in your metadata, you're declaring a component type. Then you declare instances from these component types. This mechanism is critic for the iPOJO composition. Indeed, inside a composite, you're able to create instances from any (public) component types (Refer to the [Factory]({{ refs.how-to-use-ipojo-factories.path }}) web page for further details). 
+On the top of this mechanism, we can define the concept of service implementation. A service implementation is just a component type where the instances provide a service. For example, if the instance from a component type provides the service S, the component type is a service implementation of S, and so can be used to create a provider of S. 
+The service context concept
+The service context is the concept allowing service isolation. OSGi bundle context allows accessing both to bundle-based functionality (like `loadClass`) and to the service registry. However, OSGi defines only one service registry, accessible by any bundles. iPOJO splits these two interaction types. Instances receive an iPOJO Bundle Context delegating bundle-related methods to the "regular" bundle context, and service-related methods to a service context. This service context can access to the OSGi service registry or to a new one. Each composition instances have a service registry. Instances creates inside the composition used this service registry through received the iPOJO Bundle Context. 
+
+## Downloads
+Download the [archive](http://people.apache.org/~clement/ipojo/tutorials/composite/composite-tutorial.zip). This archive contains:
+* The different applications and component types implemented in this tutorial
+* A preconfigured version of Felix
+* Deployment scripts
+
+Launch `ant` from the base directory of the unzipped archive to create every bundles. Then, you can test the different examples by copying and pasting commands from the `script.txt` file (in the felix folder) in the Felix shell.
+
+## Let's start with a first composition
+In the [iPOJO in 10 minutes]({{ refs.ipojo-in-10-minutes.path }}) tutorial, we created an application checking a sentence against dictionaries. We'll reuse this simple application in this tutorial. 
+So first, we need to implements several component types:
+* The dictionary service implementation, containing words
+* The Check service implementation, providing methods to check words against dictionaries
+* And the client GUI, using a Check Service to indicate misspelled words.
+
+We will reuse the same implementation than in the previous tutorial. The current application is designed as follow:
+!app1.png!
+However, imagine that you want to isolate services provided and required by your application. For example, you want to isolate a stateful service or a critical (private) resource. 
+So, let's imagine a second version of our spellchecker application. In this application, the dictionary service, and the checker service are isolated inside a composite. So, those services will be accessible only from instances living in the composite. The GUI will also be instantiated inside the composite. The composition will be something like:
+!app2.png!
+The descriptor of this application is:
+
+    <ipojo>
+    
+    <!--  Declares a composition -->
+    <composite name="composition1">
+    	<!--  Instantiates an instance of the English dictionary -->
+    	<instance component="spell.english.EnglishDictionary"/>
+    	
+    	<!--  Instantiates an instance of the Checker -->
+    	<instance component="spell.checker.SpellCheck"/>
+    	
+    	<!--  Instantiates an instance of the GUI -->
+    	<instance component="spell.gui.SpellCheckerGui"/>
+    </composite>
+    
+    <!--  Instantiates an instance of our composition -->
+    <instance component="composition1"/>
+    
+    </ipojo>
+
+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:
+{code:none}
+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:
+    {code:none}
+    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:
+{code:none}
+-> inspect s 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
+
+    Now, when can deploy our composition:
+
+start file:../example1/output/composition1.jar
+
+    Once deployed and started, the fancy GUI appears:
+    !ss.png!
+    Now, you can check that the functional services are not unavailable outside the composite:
+    {code:none}
+    -> inspect s 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
+    Bundle 11 provides:
+    -------------------
+    org.apache.felix.ipojo.Factory, org.osgi.service.cm.ManagedServiceFactory
+
+Of course, if you stop a bundle providing a required service type, the application is stopped:
+
+    -> stop 8
+    -> start 8
+
+Then, the application also supports component type update. However the component type name must not change. We will see later how we can avoid this issue by abstracting implementations.
+
+## Importing a service inside a composite
+Let's imagine a second version of the checker service implementation (spell.checker-v2). This implementation removes the trace when wrong words are detected. Indeed, this implementation uses a log service to store such kind of errors. 
+If we use this implementation, we need to make a log service available inside the composite. Else, the checker will not be valid. To achieve this, use the following composite:
+
+    <ipojo>
+    
+    <!--  Declares a composition -->
+    <composite name="composition2">
+    	<!--  Instantiates an instance of the English dictionary -->
+    	<instance component="spell.english.EnglishDictionary"/>
+    	
+    	<!--  Instantiates an instance of the Checker -->
+    	<instance component="spell.checker.SpellCheck"/>
+    	
+    	<!--  Instantiates an instance of the GUI -->
+    	<instance component="spell.gui.SpellCheckerGui"/>
+    	
+    	<!-- Imports the log service -->
+    	<subservice action="import" 
+                 specification="org.osgi.service.log.LogService"/>
+    </composite>
+    
+    <!--  Instantiates an instance of our composition -->
+    <instance component="composition2"/>
+    
+    </ipojo>
+
+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. 
+!app3.png!
+Now, relaunch Felix and enter another profile name (`composition2` for example). Once started, executes the following commands:
+
+    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
+
+Those commands deploy required component type (note that we deploy spell.checker-v2) and an implementation of the OSGi Log Service.  When you execute the last command, the fancy interface re-appears. 
+Try to enter a wrong word (as `composite`), and click on the check button. The trace does no more appear... the message is logged inside the log service. 
+Of course, such composite support dynamism. Try the following scenario
+
+    stop 9
+    start 9
+    stop 10
+    start 10
+
+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 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.
+
+<div class="box">
+	<div class="box-blue-header">
+	<div class="box-blue-title">
+		<img src="http://people.apache.org/~clement/ipojo/site/information.gif"> <b>Service Resolution</b>
+	</div>
+	</div>
+	<div class="box-blue-content">
+To tackle implementation service dependency resolution issues, iPOJO instances track services inside the composite but also in the global service context (OSGi service registry).  This feature allows avoiding the declaration of common service import published in the OSGi service registry.
+	</div>
+	<div class="box-blue-footer"></div>
+</div>
+
+
+## Abstracting implementation... Composing services
+We saw in the first composition that we depend on specific component types. This can be avoided by specifying the composition in term of services instead of component types. So, every available service implementation can be used. Moreover, if the used one disappears, another one can be immediately used to replace the missing service. Let's illustrate this.
+In the first composition, we create an instance of the English dictionary service implementation. We can remove this coupling to this specific implementation. To do this, we will target any implementation of the dictionary service regardless the language. 
+
+    <ipojo>
+    
+    <!--  Declares a composition -->
+    <composite name="composition3">
+    	<!--  Instantiates an instance of the English dictionary -->
+    	<subservice action="instantiate" 
+                 specification="spell.services.DictionaryService"/>
+    	
+    	<!--  Instantiates an instance of the Checker -->
+    	<instance component="spell.checker.SpellCheck"/>
+    	
+    	<!--  Instantiates an instance of the GUI -->
+    	<instance component="spell.gui.SpellCheckerGui"/>
+    </composite>
+    
+    <!--  Instantiates an instance of our composition -->
+    <instance component="composition3"/>
+    
+    </ipojo>
+
+
+The previous composition instantiates a dictionary service.  This means that the composite looks for an implementation of the Dictionary service and creates an instance of this implementation (i.e. component type) inside the composition. 
+If several implementations are available, the composite chooses one, and switches to another one if the used implementation becomes unavailable.
+!app4.png!
+To execute this composition, launch Felix and execute the following command:
+
+    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
+    start file:../example3/output/composition3.jar
+
+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 c 9
+    spell.english (9) 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
+
+Note the `component.providedServiceSpecifications` property indicating provided services. 
+Now deploy another implementation of the dictionary service, such as the French dictionary service ☺
+
+    start file:../spell.french/output/spell.french.jar
+
+Write  `welcome` in the GUI and then check. The word is correctly spelled. Then, stop the bundle providing the English dictionary.
+
+    stop 9
+
+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.
+
+## Publishing services
+A composition can also provide services. iPOJO composites support two methods to provide services :
+* The service export: re-export a service from the composite to the parent context
+* The service implementation: the composite computes a delegation scheme to delegate every method of the provided service on internal entities (services and instances)
+
+This section addresses the export. Exporting a service is the opposite of the service import. It tracks services from the composites to publish it in the parent (superior) context.
+So, let's imagine a fourth version of our application. In this application, the GUI is externalized and lives in the global context (i.e. OSGi). So, the composition exports the spell checker service. 
+
+    <ipojo>
+    
+    <!--  Declares a composition -->
+    <composite name="composition4">
+    	<!--  Instantiates an instance of the English dictionary -->
+    	<subservice action="instantiate" 
+              specification="spell.services.DictionaryService"/>
+    	
+    	<!--  Instantiates an instance of the Checker -->
+    	<instance component="spell.checker.SpellCheck"/>
+    	
+    	<!-- Export the SpellChecker service -->
+    	<provides action="export" 
+                specification="spell.services.SpellChecker"/>
+    </composite>
+    
+    <!--  Instantiates an instance of our composition -->
+    <instance component="composition4"/>
+    
+    <!--  Instantiates an instance of the GUI in the global context -->
+    <instance component="spell.gui.SpellCheckerGui"/>
+    
+    </ipojo>
+
+In the previous composition, the composite exports the spell checker service. Moreover, the GUI is also created but in the global context. At runtime, the result will be as following:
+!app5.png!
+The composite published the spell checker service in the OSGi service registry. The GUI tracks this service in the OSGi service registry too.
+To execute this composition, launch Felix and execute following the 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
+    start file:../example4/output/composition4.jar
+
+You can check that the composition exports the service with the following command:
+
+    -> services 12
+    Bundle 12 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 9
+    -> start 9
+    -> stop 11
+    -> inspect s c 12
+    Bundle 12 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
+    -> 
+
+## Hierarchical composites
+A composition can also contain others compositions. Let's imagine a variation of the latest application. In this case, we define a composite containing the GUI and the previous composite.
+
+    <ipojo>
+    
+    <!--  Declares the same composition than the latest one -->
+    <composite name="composition4">
+    	<!--  Instantiates an instance of the English dictionary -->
+    	<subservice action="instantiate" 
+                specification="spell.services.DictionaryService"/>
+    	
+    	<!--  Instantiates an instance of the Checker -->
+    	<instance component="spell.checker.SpellCheck"/>
+    	
+    	<!-- Exports the SpellChecker service -->
+    	<provides action="export" 
+                specification="spell.services.SpellChecker"/>
+    </composite>
+    
+    <!--  Declares another composition containing an instance of the previous 
+          composition and an instance of the GUI
+     -->
+    <composite name="composition5">
+        <!-- Instantiates the previous composition
+             You can access to composition by following the
+             same way as for other types
+         -->
+    	<instance component="composition4"/>
+    
+        <!--  Instantiates an instance of the GUI in the composite -->
+    <instance component="spell.gui.SpellCheckerGui"/>
+    </composite>
+    
+    <!--  Instantiates an instance of our composition -->
+    <instance component="composition5"/>
+    
+    </ipojo>
+
+The `composition5` contains an instance of the `composition4` and of the GUI. So the spell checker service exported by the composition4 is published inside the service context of the `composite 5` (the parent context). The GUI instance lives in this service context, and so can access to the exported Spell checker service.
+!app6.png!
+To execute this composition, restart Felix and 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
+    start file:../example5/output/composition5.jar
+
+You can check that the composite does no more publish the spell checker service in the OSGi service registry.
+
+## Conclusion
+
+This page has presented how to use iPOJO composition model. Several topics were not addressed and will be added shortly:
+* 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 [mailto:users-subscribe@felix.apache.org]({{ refs.mailto-users-subscribe-felix-apache-org.path }}); after subscribing, email questions or feedback to [mailto:users@felix.apache.org].
+  
+  
+  
+  
+  
+  
+{include:apache-felix-ipojo-footer}
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-hello-word-maven-based-tutorial.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-hello-word-maven-based-tutorial.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-hello-word-maven-based-tutorial.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-hello-word-maven-based-tutorial.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,418 @@
+Title: iPOJO Hello Word (Maven-Based) tutorial
+
+{include:apache-felix-ipojo-header}
+
+<div class="content">
+
+# iPOJO Hello World
+
+*This page presents how to use the iPOJO runtime and its associated service component model. The concepts of the service component model are introduced, followed by a simple example that demonstrates the features of iPOJO.*
+
+## Introduction
+
+iPOJO aims to simplify service-oriented programming on OSGi frameworks; the name iPOJO is an abbreviation for *injected POJO*. iPOJO provides a new way to develop OSGi service components with the main goal being to simplify service component implementation by transparently managing the dynamics of the environment as well as other non-functional requirements. The iPOJO framework allows developers to more clearly separate functional code (i.e., the POJO) from the non-functional code (i.e., dependency management, service provision, configuration, etc.). iPOJO combines the functional and non-functional aspects at run time. To achieve this, iPOJO provides a simple and extensible service component model based on POJOs.
+
+## The POJO concept
+
+POJO is an acronym for Plain Old Java Object, but it embodies a concept that the simpler and less intrusive the design of a given framework, the better. The name is used to emphasize that a given object is not somehow special, but is an ordinary Java Object. Martin Fowler, Rebecca Parsons and Josh Mackenzie coined the term POJO in September 2000: "We wondered why people were so against using regular objects in their systems and concluded that it was because simple objects lacked a fancy name. So we gave them one, and it's caught on very nicely." From the developer's perspective, the iPOJO framework strives to only require POJOs in as much as it is possible.
+
+## iPOJO service component overview
+
+A service component is able to provide and/or require services, where a service is an object that implements a given service interface embodied as a Java interface. In addition, iPOJO introduces a callback concept to notify a component about various state changes.
+
+The component is the central concept in iPOJO. In the core iPOJO model, a component describes service dependencies, provided services, and callbacks; this information is recorded in the component's metadata. Then, the second important concept in iPOJO is component instances. A component instances is a special *version* of the component. By merging component metadata and instance configuration, the iPOJO runtime is able to manage the component, i.e., manage its life cycle, inject required services, publish provided services, discover needed services.
+
+## A simple example
+
+The following is a simple example illustrating how to use the core iPOJO concepts. The example is comprised of two components, one providing a *Hello* service and one requiring any number of *Hello* services. The components are packaged into three different bundles using Maven. The *hello.service* bundle contains the service interface. The *hello.impl* bundle contains a component implementing the service. The *hello.client* bundle contains the consumer component.
+
+Download the tutorial archive [here](http://people.apache.org/~clement/ipojo/tutorials/maven/tutorial.zip). This archive contains a version of Felix (configured with iPOJO), and the projects explained below.
+
+### Preparing Maven & Installing the tutorial
+
+The first step is to download and install Maven; the example was created using Maven 2.1+. Once maven is installed on your machine, you can compile the tutorial by unzipping the archive, and by launching the '*mvn clean install*' command at the root of tutorial.
+
+*Be aware that Maven outputs a lot of information while it executes and often downloads a lot of required JAR files into its local repository.*
+
+### Hello Service
+
+The first project is the *hello.service* project. This project contains only the *hello* service interface. Look at the `src/main/java/ipojo/example/hello/Hello.java` file.
+{code:java}
+/**
+ * Hello Interface.
+ * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
+ */
+public interface Hello {
+
+    /**
+     * Returns a message like: "Hello $user_name".
+     * @param name the name
+     * @return the hello message
+     */
+    String sayHello(String name);
+}
+
+    
+    In the project directory, the pom.xml file contains the instructions to build the bundle. The bundle uses the _maven-bundle-plugin_ (see here for more information on this plug-in).
+    {div:class=pom}
+    <project>
+    &nbsp;&nbsp;&nbsp; <modelVersion>4.0.0</modelVersion>
+    &nbsp;&nbsp;&nbsp; <packaging>bundle</packaging>
+    &nbsp;&nbsp;&nbsp; {color:#ff0000}<groupId>ipojo.example</groupId>{color}
+    {color:#ff0000}&nbsp;&nbsp;&nbsp; <artifactId>hello.service</artifactId>{color}
+    {color:#ff0000}&nbsp;&nbsp;&nbsp; <version>1.0.0</version>{color}
+    {color:#ff0000}&nbsp;&nbsp;&nbsp; <name>Hello Service</name>{color}
+    
+    <build>
+    &nbsp;&nbsp;&nbsp; <plugins>
+    &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; <plugin>
+    &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; <groupId>org.apache.felix</groupId>
+    &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; <artifactId>maven-bundle-plugin</artifactId>
+    &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; <version>2.0.1</version>
+    &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; <extensions>true</extensions>
+    &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; <configuration>
+    &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; <instructions>
+    &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; <Bundle-SymbolicName>
+    &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; $\{pom.artifactId}
+    &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; </Bundle-SymbolicName>
+    &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; {color:#ff0000}<Export-Package>{color}
+    {color:#ff0000}&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; ipojo.example.hello{color}
+    {color:#ff0000}&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; </Export-Package>{color}
+    &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; </instructions>
+    &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; </configuration>
+    &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; </plugin>
+    &nbsp;&nbsp;&nbsp; </plugins>
+    </build>
+    
+    </project>
+    {div}
+    Then, the project is ready to be built issuing the following Maven command inside the project directory:
+
+mvn clean install
+
+    Maven should report that the build was a success; if an error was reported then verify the previous steps. Upon success the _Hello_ service component JAR file is installed into the local Maven repository. A copy of the bundle JAR file will also be present in the "target" directory inside the project directory.
+    
+    h3. Hello Service Provider
+    
+    The component implementation of the service is a simple Java class implementing the _Hello_ service interface. The implementation is in the _hello.impl_ project. The file {{src/main/java/ipojo/example/hello/impl/HelloImpl.java}} contains the following service implementation:
+    {code:java}
+    /**
+     * Component implementing the Hello service.
+     * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
+     */
+    public class HelloImpl implements Hello {
+    
+        /**
+         * Returns an 'Hello' message.
+         * @param name : name
+         * @return Hello message
+         * @see ipojo.example.hello.Hello#sayHello(java.lang.String)
+         */
+        public String sayHello(String name) { return "hello " + name;  }
+    }
+
+To manage the component, iPOJO needs some metadata to understand that the component provides the *Hello* service. iPOJO metadata file is at the root of the *hello.impl* project ("metadata.xml"). It contains the following metadata (Note: iPOJO also supports a JAR manifest-based syntax):
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    <ipojo 
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="org.apache.felix.ipojo http://felix.apache.org/ipojo/schemas/CURRENT/core.xsd" 
+        xmlns="org.apache.felix.ipojo">
+          
+      <component classname="ipojo.example.hello.impl.HelloImpl"
+        name="HelloProvider">
+        <provides />
+      </component>
+      
+      <instance component="HelloProvider" name="HelloService" />
+    </ipojo>
+
+In the above XML-based metadata, the *component* element has a mandatory '*classname'*attribute. This attribute tells iPOJO the implementation class of the component. Since the component in this example provides a service, the component element also specifies a child '*provides*' element. The '*provides*' element informs iPOJO that it must manage the publishing of a service. When the '*provides*' element does not contain an interface attribute, as is the case in this example, iPOJO will expose all implemented interfaces of the component as a service; it is also possible to specify the precise service interface. The '*instance*' element asks iPOJO to create an instance of your component when the bundle is started.
+
+Finally, the "pom.xml" file contains instructions to build the bundle:
+{div:class=pom}
+<project>
+&nbsp;&nbsp;<modelVersion>4.0.0</modelVersion>
+&nbsp; <packaging>bundle</packaging>
+&nbsp;&nbsp;{color:red}<groupId>ipojo.example</groupId>{color}
+{color:red}&nbsp;&nbsp;<artifactId>hello.impl</artifactId>{color}
+{color:red}&nbsp;&nbsp;<version>1.0.0</version>{color}
+
+&nbsp;&nbsp;{color:red}<name>Hello Service Provider</name>{color}
+
+{color:red}&nbsp; <dependencies>{color}
+{color:red}&nbsp;&nbsp; &nbsp;<dependency> <!--Compilation (i.e. class) dependency on the service interface -->{color}
+{color:red}&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;<groupId>ipojo.example</groupId>{color}
+{color:red}&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;<artifactId>hello.service</artifactId>{color}
+{color:red}&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;<version>{color}{color:#ff0000}1.0.0{color}{color:red}</version>{color}
+{color:red}&nbsp;&nbsp; &nbsp;</dependency>{color}
+{color:red}&nbsp; </dependencies>{color}
+
+
+&nbsp;&nbsp;<build>
+&nbsp;&nbsp; <plugins>
+&nbsp;&nbsp;&nbsp;&nbsp; <plugin>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <groupId>org.apache.felix</groupId>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <artifactId>maven-bundle-plugin</artifactId>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <version>2.0.1</version>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <extensions>true</extensions>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <configuration>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <instructions>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <Bundle-SymbolicName>$\{pom.artifactId}</Bundle-SymbolicName>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:red}<Private-Package>ipojo.example.hello.impl</Private-Package>{color}
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </instructions>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </configuration>
+&nbsp;&nbsp;&nbsp;&nbsp; </plugin>
+&nbsp;&nbsp;&nbsp;&nbsp; <plugin>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <groupId>org.apache.felix</groupId>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <artifactId>maven-ipojo-plugin</artifactId>
+&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; <version>1.6.0</version>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<executions>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <execution>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <goals>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <goal>ipojo-bundle</goal>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </goals>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;</execution>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </executions>
+&nbsp;&nbsp;&nbsp;&nbsp; </plugin>
+&nbsp;&nbsp; </plugins>
+&nbsp;</build>
+</project>
+{div}
+The text highlighted in {color:red}{*}red{*}{color} above indicates the important information related to the project. The first part of the POM file indicates that the packaging format is an iPOJO bundle and also includes some information about the project (name, groupId, and artifactId). This information is not used by iPOJO, but is used by Maven. The rest of the POM file contains the bundle configuration. In the *instructions* element, you need to enter the bundle name, the bundle description, and the exported packages. The service provider bundle exports the package of *Hello* interface.
+
+Then, the project is ready to be built issuing the following Maven command inside the project directory:
+
+    mvn clean install
+
+Maven should report that the build was a success; if an error was reported then verify the previous steps. Upon success the *Hello* service component JAR file is installed into the local Maven repository. A copy of the bundle JAR file will also be present in the "target" directory inside the project directory.
+
+### Hello Service Client
+
+The Hello service consumer is inside the *hello.client* project. The file `src/main/java/ipojo/example/hello/client/HelloClient.java` contains the following *Hello* service client:
+{code:java}
+package ipojo.example.hello.client;
+
+import ipojo.example.hello.Hello;
+
+/**
+ * Hello Service simple client.
+ * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
+ */
+public class HelloClient implements Runnable {
+
+    /**
+     *  Delay between two invocations.
+     */
+    private static final int DELAY = 10000;
+
+    /**
+     * Hello services.
+     * Injected by the container.
+     * */
+    private Hello[]({{ refs..path }}) m_hello;
+
+    /**
+     * End flag.
+     *  */
+    private boolean m_end;
+
+    /**
+     * Run method.
+     * @see java.lang.Runnable#run()
+     */
+    public void run() {
+        while (!m_end) {
+            try {
+                invokeHelloServices();
+                Thread.sleep(DELAY);
+            } catch (InterruptedException ie) {
+                /* will recheck end */
+            }
+        }
+    }
+
+    /**
+     * Invoke hello services.
+     */
+    public void invokeHelloServices() {
+        for (int i = 0; i < m_hello.length; i++) {
+            // Update with your name.
+            System.out.println(m_hello[i]({{ refs.i.path }}).sayHello("world"));
+        }
+    }
+
+    /**
+     * Starting.
+     */
+    public void starting() {
+        Thread thread = new Thread(this);
+        m_end = false;
+        thread.start();
+    }
+
+    /**
+     * Stopping.
+     */
+    public void stopping() {
+        m_end = true;
+    }
+}
+
+    The _Hello_ service client creates a thread that periodically invokes the available _Hello_ services. The thread starts when at least one _Hello_ service provider is present using iPOJO's call back mechanism. In the client code, to use the _hello_ the component implementation simply declares a field of the type of the service and then simply uses it directly in its code. In this example, it is the m_hello field is declared as the service field; notice that the field is an array of _Hello_. In iPOJO an array of services represents an aggregate or multiple cardinality dependency, whereas if a scalar value represents a singular or unary cardinality dependency. In other words, for a singular dependency simply remove the array brackets from the example (e.g., HelloService m_hello\[\]. After declaring a field for the service, the rest of the component code can simply assume that the service field will be initialized, e.g., m_hello\[i\].sayHello("world").
+    
+    Notice that iPOJO manages service synchronization too. So, the service invocations do not require synchronization blocks. This synchronization is maintained on a per thread basis, where each method that accesses a service is instrumented to attach the given service instance to the thread so that the thread will continue to see the same service instances even across nested method invocations. The thread will not see different service instances until it completely exits from the first method it entered which used a services. Thus, you would not want to access services in the {{run()}} method above, because the thread would always see the same service instance.
+    
+    The component provides two callback methods for its activation and deactivation, starting() and stopping(), respectively. Callbacks are used when the component needs to be informed about a component state change. In iPOJO, the component state is either *INVALID* (i.e., not all of the component's constraints are satisfied) or *VALID* (i.e., all of the component's constraints are satisfied). In this example, the starting callback method creates and starts a thread; the stopping callback method stops the thread. The component metadata will instruct iPOJO to invoke these methods when the component's state changes to *VALID* or *INVALID* respectively.
+    
+    The iPOJO metadata file describing the component is "metadata.xml" and contains the following metadata:
+    {code:xml}
+    <?xml version="1.0" encoding="UTF-8"?>
+    <ipojo 
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="org.apache.felix.ipojo http://felix.apache.org/ipojo/schemas/CURRENT/core.xsd" 
+        xmlns="org.apache.felix.ipojo">
+    
+      <component classname="ipojo.example.hello.client.HelloClient">
+        <requires field="m_hello" />
+        <callback transition="validate" method="starting" />
+        <callback transition="invalidate" method="stopping" />
+        <properties>
+          <property field="m_name" name="hello.name" />
+        </properties>
+      </component>
+    
+      <instance component="ipojo.example.hello.client.HelloClient">
+        <property name="hello.name" value="clement" />
+      </instance>
+    </ipojo>
+
+The component element again has the '*classname'* attribute that refers to the component implementation class. The '*requires*' element describes the *Hello* service dependency by simply specifying its associated component field. The '*callback'*elements describe which method to invoke when the component's state changes. Then the '*instance*' element asks iPOJO to create an instance of the component (notice that no instance name is provided here, iPOJO will give an instance name to the instance automatically).
+
+Finally, the "pom.xml" file contains instructions to build the bundle:
+{div:class=pom}
+<project>
+&nbsp;&nbsp;<modelVersion>4.0.0</modelVersion>
+&nbsp;&nbsp;<packaging>bundle</packaging>
+&nbsp;&nbsp;{color:red}<groupId>ipojo.example</groupId>{color}
+{color:red}&nbsp;&nbsp;<artifactId>hello.client</artifactId>{color}
+{color:red}&nbsp;&nbsp;<version>1.0.0</version>{color}
+{color:red}&nbsp;&nbsp;<name>Hello Client</name>{color}
+
+{color:red}&nbsp;&nbsp;<dependencies>{color}
+{color:red}&nbsp;&nbsp; &nbsp;<dependency> <\!-\-{color} {color:red}Compilation (i.e. class) dependency on the service interface \-\-{color}{color:red}>{color}
+{color:red}&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;<groupId>ipojo.example</groupId>{color}
+{color:red}&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;<artifactId>hello.service</artifactId>{color}
+{color:red}&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;<version>{color}{color:#ff0000}1.0.0{color}{color:red}</version>{color}
+{color:red}&nbsp;&nbsp; &nbsp;</dependency>{color}
+{color:red}&nbsp; </dependencies>{color}
+
+&nbsp; <build>
+&nbsp;&nbsp;&nbsp;&nbsp; <plugins>
+&nbsp;&nbsp;&nbsp;&nbsp; <plugin>
+&nbsp;&nbsp;&nbsp;&nbsp; <groupId>org.apache.felix</groupId>
+&nbsp;&nbsp;&nbsp;&nbsp; <artifactId>maven-bundle-plugin</artifactId>
+&nbsp;&nbsp;&nbsp;&nbsp; <version>2.0.1</version>
+&nbsp;&nbsp;&nbsp;&nbsp; <extensions>true</extensions>
+&nbsp;&nbsp;&nbsp;&nbsp; <configuration>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <instructions>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <Bundle-SymbolicName>$\{pom.artifactId}</Bundle-SymbolicName>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:red}<Private-Package>ipojo.example.hello.client</Private-Package>{color}
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </instructions>
+&nbsp;&nbsp;&nbsp;&nbsp; </configuration>
+&nbsp;&nbsp; </plugin>
+&nbsp;&nbsp; <plugin>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <groupId>org.apache.felix</groupId>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <artifactId>maven-ipojo-plugin</artifactId>
+&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; <version>1.6.0</version>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <executions>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <execution>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <goals>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <goal>ipojo-bundle</goal>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </goals>
+&nbsp;&nbsp;&nbsp;&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; </execution>
+&nbsp; &nbsp; &nbsp; &nbsp;&nbsp; </executions>
+&nbsp;&nbsp; </plugin>
+&nbsp;</plugins>
+&nbsp; </build>
+</project>
+{div}
+The text highlighted in {color:red}{*}red{*}{color} above indicates the information related to the project. The *dependencies* element tells Maven that the client bundle has a compilation dependency on the service provider bundle. In this case, the client bundle needs the *Hello* service interface to compile. After building the service provider bundle JAR file, Maven installs it into a local repository on your machine. To resolve compilation dependencies, Maven looks in the local repository to find required JAR files.
+After the skeleton "pom.xml" file is modified, the project is ready to be built issuing the following Maven command inside the project directory:
+mvn clean install
+Maven should report that the build was a success; if an error was reported then verify the previous steps. Upon success the *Hello* service component JAR file is installed into the local Maven repository. A copy of the bundle JAR file will also be present in the "target" directory inside the project directory.
+
+## Running the example
+
+To run the example, start Felix. A distribution of Felix is provided in the felix-1.0.3 directory. This version is configured to launch iPOJO automatically. From the Felix directory, launch the following command to start the framework
+
+    java -jar bin/felix.jar
+
+You can check installed bundles by using the '*ps'* command:
+
+    -> ps
+    START LEVEL 1
+       ID   State         Level  Name
+    [   0] [Active     ] [    0] System Bundle (2.0.5)
+    [   1] [Active     ] [    1] Apache Felix Bundle Repository (1.4.3)
+    [   2] [Active     ] [    1] Apache Felix iPOJO (1.6.0)
+    [   3] [Active     ] [    1] Apache Felix iPOJO Arch Command (1.6.0)
+    [   4] [Active     ] [    1] Apache Felix Shell Service (1.4.2)
+    [   5] [Active     ] [    1] Apache Felix Shell TUI (1.4.1)
+    ->
+
+iPOJO runtime is the bundle 4. The bundle 5 is a Felix shell command allowing the introspection of iPOJO component instances (see herefor further information).
+
+Install the Hello service bundle, the *Hello* service provider and the client that were created above:
+{div:class=shell}
+start file:../hello.service/target/hello.service-1.0.0.jar
+start file:../hello.impl/target/hello.impl-1.0.0.jar
+start file:../hello.client/target/hello.client-1.0.0.jar
+{div}
+By starting the *Hello* service provider bundle, the client component will automatically be activated. So, the *'hello world'* messages are displayed.
+{div:class=shell}
+\-> hello world
+hello world
+{div}
+Stop the provider (with the '*stop 7*' command) and the client will automatically be deactivated since its dependency is no longer valid. If multiple Hello services are deployed, the client will connect to all of them. If you restart the bundle (with the *start 7* command), the client becomes valid.
+
+During these operations, you can use the arch command to check the state of instances.
+{div:class=shell}
+\-> stop 7
+\-> arch
+Instance ArchCommand \-> valid
+{color:red}Instance ipojo.example.hello.client.HelloClient-0 \-> invalid{color}
+\-> arch \-instance ipojo.example.hello.client.HelloClient-0
+instance name="ipojo.example.hello.client.HelloClient-0" 
+&nbsp;component.type="ipojo.example.hello.client.HelloClient" 
+&nbsp;state="{color:red}invalid{color}" bundle="8"
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; object name="ipojo.example.hello.client.HelloClient@137c60d"
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:red}handler name="org.apache.felix.ipojo.handlers.dependency.DependencyHandler" state="invalid"{color}
+{color:red}&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{color}{color:red}requires aggregate="true" optional="false" state="resolved" specification="ipojo.example.hello.Hello"{color}
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; handler name="org.apache.felix.ipojo.handlers.lifecycle.callback.LifecycleCallbackHandler" state="valid"
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; handler name="org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler" state="valid"
+\-> start 7
+hello world
+\-> arch
+Instance ArchCommand \-> valid
+{color:red}Instance ipojo.example.hello.client.HelloClient-0 \-> valid{color}
+Instance HelloService \-> valid
+\-> arch \-instance ipojo.example.hello.client.HelloClient-0
+instance name="ipojo.example.hello.client.HelloClient-0" 
+&nbsp;component.type="ipojo.example.hello.client.HelloClient"
+&nbsp; state="valid" bundle="8"
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; object name="ipojo.example.hello.client.HelloClient@137c60d"
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:red}handler name="org.apache.felix.ipojo.handlers.dependency.DependencyHandler" state="valid"{color}
+{color:red}&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{color}{color:red}requires aggregate="true" optional="false" state="resolved" specification="ipojo.example.hello.Hello"{color}
+{color:red}&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{color} {color:red}uses service.id="38" instance.name="HelloService"{color}
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; handler name="org.apache.felix.ipojo.handlers.lifecycle.callback.LifecycleCallbackHandler" state="valid"
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; handler name="org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler" state="valid"
+{div}
+
+## Conclusion
+We saw how to use easily iPOJO to build service-oriented components. Subscribe to the Felix users mailing list by sending a message to [mailto:users-subscribe@felix.apache.org]({{ refs.mailto-users-subscribe-felix-apache-org.path }}); after subscribing, email questions or feedback to [mailto:users@felix.apache.org].
+  
+  
+  
+  
+{include:apache-felix-ipojo-footer}
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-in-10-minutes.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-in-10-minutes.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-in-10-minutes.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-in-10-minutes.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,438 @@
+Title: iPOJO in 10 minutes
+
+{include:apache-felix-ipojo-header}
+
+<div class="content">
+
+
+# iPOJO in 10 minutes
+
+*This page presents how to use the iPOJO runtime and its associated service component model. The concepts of the service component model are introduced, followed by a simple example that demonstrates the features of iPOJO. This tutorial uses XML to describe components.  However, iPOJO also supports* *[annotations]({{ refs.how-to-use-ipojo-annotations.path }})* *and a Java* *[API|apache-felix-ipojo-api]* *for this purpose.*
+
+## Introduction
+
+iPOJO aims to simplify service-oriented programming on OSGi frameworks; the name iPOJO is an abbreviation for *injected POJO*. iPOJO provides a new way to develop OSGi service components, simplifying service component implementation by transparently managing the dynamics of the environment as well as other non-functional requirements. The iPOJO framework allows developers to more clearly separate functional code (i.e., POJOs) from the non-functional code (i.e., dependency management, service provision, configuration, etc.).  At run time, iPOJO combines the functional and non-functional aspects. To achieve this, iPOJO provides a simple and extensible service component model based on POJOs.
+
+## The POJO concept
+
+"POJO" is just an acronym for Plain Old Java Object, but it embodies a concept that the simpler and less intrusive the design of a given framework, the better. The name is used to emphasize that a given object is not somehow special, but is an ordinary Java Object. Martin Fowler, Rebecca Parsons and Josh Mackenzie coined the term POJO in September 2000: "We wondered why people were so against using regular objects in their systems and concluded that it was because simple objects lacked a fancy name. So we gave them one, and it's caught on very nicely." From a developer's perspective, the iPOJO framework strives as much as possible to only require POJOs.
+
+## iPOJO service component overview
+
+A service component is able to provide and/or require services, where a service is an object that implements a given Java interface. In addition, iPOJO introduces a callback concept to notify a component about various state changes.
+
+The component is a central concept in iPOJO. In the core iPOJO model, a component describes service dependencies, provided services, and callbacks; this information is recorded in the component's metadata. After components, the next most important concept in iPOJO is the component instance. A component instance is a special *version* of a component. By merging component metadata and instance configuration, the iPOJO runtime is able to discover and inject required services, publish provided services, and manage the component's life cycle.
+
+## A simple example
+
+In this tutorial we will present how to:
+* Publish an OSGi service
+* Require an OSGi service
+* Use lifecycle callbacks to activate and deactivate components
+
+### Presentation of the *Spell* application
+
+To illustrate iPOJO features, we will implement a very simple application. This application is composed by three components:
+* A component implementing a dictionary service
+* A component requiring the dictionary service and providing a spellchecker service
+* A component requiring the spellchecker and providing an user interface
+
+!spell.png!
+
+### Preparing the tutorial
+
+This tutorial is based on Ant. So, you need to have the Ant program accessible in your path (see [here](http://ant.apache.org/) to download and install Ant). Download the tutorial archive available [here|http://people.apache.org/~clement/ipojo/tutorials/10min/tutorial.zip] and then unzip it. The archive contains seven directories:
+* spell.services contains service interfaces used by the applications
+* spell.english contains an implementation of the Dictionary service (containing English words)
+* spell.checker contains an implementation of a Spell Checker. The spell checker requires a dictionary service and check if an input passage is correct (according to the words contained in the dictionary).
+* spell.gui contains a very simple user interface. This component uses a spell checker service. Then the user can interact with the spell checker with this user interface.
+* The task directory contains Ant tasks used to build the project
+* The solution directory contains an already developed version of the application.
+* Finally, the felix folder contains a configured version of the Felix runtime
+
+### The spell.services project
+
+The spell.services project contains only service interfaces. It is not an iPOJO powered bundle.
+
+Go inside the Spell.services directory and create the file "src/spell/services/DictionaryService.java" for the following *Dictionary* service interface:
+{code:java}
+package spell.services;
+/**
+ * A simple service interface that defines a dictionary service.
+ * A dictionary service simply verifies the existence of a word.
+**/
+public interface DictionaryService {
+    /**
+     * Check for the existence of a word.
+     * @param word the word to be checked.
+     * @return true if the word is in the dictionary,
+     *         false otherwise.
+     **/
+    public boolean checkWord(String word);
+}
+
+    Then, create the file {{src/spell/services/SpellChecker.java}} for the following _Spell Checker_ service interface:
+    {code:java}
+    package spell.services;
+    /**
+     * A simple service interface that defines a spell checker service.
+     * A spell checker service checks the spelling of all words in a
+     * given passage. A passage is any number of words separated by
+     * a space character and the following punctuation marks: comma,
+     * period, exclamation mark, question mark, semi-colon, and colon.
+    **/
+    public interface SpellChecker {
+        /**
+         * Checks a given passage for spelling errors. A passage is any
+         * number of words separated by a space and any of the following
+         * punctuation marks: comma (,), period (.), exclamation mark (!),
+         * question mark (?), semi-colon (;), and colon(:).
+         * @param passage the passage to spell check.
+         * @return An array of misspelled words or null if no
+         *         words are misspelled.
+        **/
+        public String[] check(String passage);
+    }
+
+Once created, you can build the project by launching Ant from the project directory.
+{code:none}
+$ ant
+Buildfile: build.xml
+clean:
+compile:
+    [mkdir]({{ refs.mkdir.path }}) Created dir: d:\clement\workspaces\sandbox\ipojo\examples\tutorial-ant\
+            spell.services\output
+    [mkdir]({{ refs.mkdir.path }}) Created dir: d:\clement\workspaces\sandbox\ipojo\examples\tutorial-ant\
+            spell.services\output\classes
+    [javac]({{ refs.javac.path }}) Compiling 2 source files to d:\clement\workspaces\sandbox\ipojo\examples\
+            tutorial-ant\spell.services\output\classes
+package:
+      [bnd]({{ refs.bnd.path }}) spell.services 2
+BUILD SUCCESSFUL
+Total time: 0 seconds
+
+    The created bundle is inside the output directory (spell.services.jar). The build process use [BND|http://www.aqute.biz/Code/Bnd]. The bundle manifest is described in the spell.services.bnd file.
+    Once this project is done, we are able to implement a Dictionary service.
+    
+    h3. The spell.english project: Providing an OSGi service
+    
+    The spell.english project is a simple dictionary implementation of the Dictionary service. It contains few English words. This implementation is an iPOJO component.
+    The first step is to implement the service. Create the "src/spell/english/EnglishDictionary.java" file for the following _Dictionary service_ implementation:
+    {code:java}
+    package spell.english;
+    import spell.services.DictionaryService;
+    /**
+     * An implementation of the Dictionary service containing English words
+     * see DictionaryService for details of the service.
+     **/
+    public class EnglishDictionary implements DictionaryService {
+        // The set of words contained in the dictionary.
+        String[] m_dictionary = { "welcome", "to", "the", "ipojo", "tutorial" };
+        /**
+         * Implements DictionaryService.checkWord(). Determines
+         * if the passed in word is contained in the dictionary.
+         * @param word the word to be checked.
+         * @return true if the word is in the dictionary,
+         *         false otherwise.
+         **/
+        public boolean checkWord(String word) {
+            word = word.toLowerCase();
+            // This is very inefficient
+            for (int i = 0; i < m_dictionary.length; i++) {
+                if (m_dictionary[i].equals(word)) {
+                    return true;
+                }
+            }
+            return false;
+        }
+    }
+
+Notice that this class does not contains neither OSGi nor iPOJO specific code. It is just an implementation of the Dictionary Service interface.
+Once created, we need to describe this component to ask iPOJO to manage it. To achieve this, create the "metadata.xml" file in the spell.english directory:
+
+    <ipojo>
+    <component classname="spell.english.EnglishDictionary">
+    	<provides/>
+    </component>
+    <instance component="spell.english.EnglishDictionary"/>
+    </ipojo>
+
+This file describes the Dictionary service implementation. First it creates a *component*. This component has a *classname* attribute containing the implementation class name. The *'provides'* element indicates that the component provide a service. Provided service interfaces are computed by iPOJO, so it is not necessary to indicate them. The *instance* element asks iPOJO to create an instance of the described component when the bundle starts. The relation between components and instances is the same than between classes and objects in the object oriented programming. The *component* attribute indicates which component needs to be instantiated. By default, component type name is the implementation class (i.e. the classname attribute).
+
+Then, we are able to create the bundle. In the spell.english directory launch the ant command:
+{code:none}
+$ ant
+Buildfile: build.xml
+clean:
+   [delete]({{ refs.delete.path }}) Deleting directory d:\clement\workspaces\sandbox\ipojo\examples\
+            tutorial-ant\spell.english\output\classes
+   [delete]({{ refs.delete.path }}) Deleting directory d:\clement\workspaces\sandbox\ipojo\examples\
+            tutorial-ant\spell.english\output
+buildclasspath:
+compile:
+    [mkdir]({{ refs.mkdir.path }}) Created dir: d:\clement\workspaces\sandbox\ipojo\examples\
+            tutorial-ant\spell.english\output
+    [mkdir]({{ refs.mkdir.path }}) Created dir: d:\clement\workspaces\sandbox\ipojo\examples\
+            tutorial-ant\spell.english\output\classes
+    [javac]({{ refs.javac.path }}) Compiling 1 source file to d:\clement\workspaces\sandbox\ipojo\examples\
+            tutorial-ant\spell.english\output\classes
+package:
+      [bnd]({{ refs.bnd.path }}) spell.english 1
+    [ipojo]({{ refs.ipojo.path }}) Input Bundle File : d:\clement\workspaces\sandbox\ipojo\examples\
+            tutorial-ant\spell.english\output\spell.english.jar
+    [ipojo]({{ refs.ipojo.path }}) Metadata File : d:\clement\workspaces\sandbox\ipojo\examples\
+            tutorial-ant\spell.english\metadata.xml
+    [ipojo]({{ refs.ipojo.path }}) Start bundle manipulation
+    [ipojo]({{ refs.ipojo.path }}) Bundle manipulation - SUCCESS
+    [ipojo]({{ refs.ipojo.path }}) Output File : d:\clement\workspaces\sandbox\ipojo\examples\
+            tutorial-ant\spell.english\output\spell.english.jar
+BUILD SUCCESSFUL
+Total time: 1 second
+
+    The created bundle is inside the output directory (spell.english.jar). The build process is based on BND and on the iPOJO Ant task. The manifest of the bundle is described in the {{spell.english.bnd}} file.
+    
+    h3. The spell.checker project: Requiring an OSGi service
+    
+    The spell.checker project aims to provide a _spell checker_ service. However, to serve this service, this implementation requires a _dictionary_ service. During this step, we will create an iPOJO component requiring a Dictionary service and providing the Spell Checker service.
+    
+    First create the file "src/spell/checker/SpellCheck.java" in the spell.checker directory for the following _Check Speller service_ implementation:
+    {code:java}
+    package spell.checker;
+    import java.util.ArrayList;
+    import java.util.List;
+    import java.util.StringTokenizer;
+    import spell.services.DictionaryService;
+    import spell.services.SpellChecker;
+    public class SpellCheck implements SpellChecker {
+        private DictionaryService m_dictionary;
+        /**
+         * Implements SpellChecker.check(). Checks the given passage for misspelled words.
+         * @param passage the passage to spell check.
+         * @return An array of misspelled words or null if no words are misspelled.
+         */
+        public String[] check(String passage) {
+            // No misspelled words for an empty string.
+            if ((passage == null) || (passage.length() == 0)) { return null; }
+            List errorList = new ArrayList();
+            // Tokenize the passage using spaces and punctuation.
+            StringTokenizer st = new StringTokenizer(passage, " ,.!?;:");
+            // Loop through each word in the passage.
+            while (st.hasMoreTokens()) {
+                String word = st.nextToken();
+                // Check the current word.
+                if (! m_dictionary.checkWord(word)) {
+                    // If the word is not correct, then add it
+                    // to the incorrect word list.
+                    errorList.add(word);
+                }
+            }
+            // Return null if no words are incorrect.
+            if (errorList.size() == 0) { return null; }
+            // Return the array of incorrect words.
+            return (String[]) errorList.toArray(new String[errorList.size()]);
+        }
+    }
+
+This class implements the SpellChecker service interface as it will provide it. Moreover, it has a *special* field "*m*dictionary_". This field represents the required service. iPOJO will inject a Dictionary service when needed. So, the class can use it directly. Notice that this class as no OSGi specific code, both the service providing and the requiring are managed by iPOJO. If the used dictionary service leaves, iPOJO will try to find another provider. If no more providers are available, the instance is invalidated, and the provided service is withdrawn from the service registry.
+
+Once implemented, we need to describe this component. Create the "metadata.xml" file in the spell.checker directory for the following component descriptor:
+
+    <ipojo>
+    <component classname="spell.checker.SpellCheck">
+    	<requires field="m_dictionary"/>
+    	<provides/>
+    </component>
+    <instance component="spell.checker.SpellCheck"/>
+    </ipojo>
+
+This description contains a '*requires'* element. This element indicates to iPOJO to manage the service dependency. The *field* attributes describe in which member of the class the service need to be injected. It is not necessary to write the required service as it is computed by iPOJO. Notice that iPOJO can inject required service by invoking methods too.
+
+Finally, we are able to build the bundle. As for previous projects, launch Ant from the project directory.
+
+### The spell.checker.gui project
+
+The spell.check.gui project contains a very simple user interface (in Swing) allowing a user to interact with a *spell checker* service.
+
+Create the "src\spell\gui\SpellCheckerGui.java" for the following implementation:
+{code:java}
+package spell.gui;
+import javax.swing.JButton;
+import javax.swing.JFrame;
+import javax.swing.JLabel;
+import javax.swing.JTextField;
+import spell.services.SpellChecker;
+/**
+ * A very simple Gui interacting with the CheckSpeller service
+ */
+public class SpellCheckerGui extends JFrame {
+    /**
+     * Swing component where the user write the passage to check.
+     */
+    private JTextField m_passage = null;
+
+    /**
+     * Check button
+     */
+    private JButton m_checkButton = null;
+
+    /**
+     * Area where the result is displayed.
+     */
+    private JLabel m_result = null;
+    /**
+     * Service dependency on the SpellChecker.
+     */
+    private SpellChecker m_checker;
+
+    /**
+     * Constructor.
+     * Initialize the GUI.
+     */
+    public SpellCheckerGui() {
+        super();
+        initComponents();
+        this.setTitle("Spellchecker Gui");
+    }
+    /**
+     * Initialize the Swing Gui.
+     */
+    private void initComponents() {
+        java.awt.GridBagConstraints gridBagConstraints;
+        m_checkButton = new javax.swing.JButton();
+        m_result = new javax.swing.JLabel();
+        m_passage = new javax.swing.JTextField();
+        setDefaultCloseOperation(javax.swing.WindowConstants.EXIT*ON*CLOSE); //Stop Felix
+        getContentPane().setLayout(new java.awt.GridBagLayout());
+        m_checkButton.setText("Check");
+        m_checkButton.addActionListener(new java.awt.event.ActionListener() {
+            public void actionPerformed(java.awt.event.ActionEvent e) {
+                check();
+            }
+        });
+        gridBagConstraints = new java.awt.GridBagConstraints();
+        gridBagConstraints.gridx = 0;
+        gridBagConstraints.gridy = 1;
+        gridBagConstraints.insets = new java.awt.Insets(2, 2, 2, 2);
+        getContentPane().add(m_checkButton, gridBagConstraints);
+        m_result.setPreferredSize(new java.awt.Dimension(175, 20));
+        gridBagConstraints = new java.awt.GridBagConstraints();
+        gridBagConstraints.gridx = 0;
+        gridBagConstraints.gridy = 2;
+        gridBagConstraints.fill = java.awt.GridBagConstraints.HORIZONTAL;
+        gridBagConstraints.insets = new java.awt.Insets(2, 2, 2, 2);
+        getContentPane().add(m_result, gridBagConstraints);
+        m_passage.setPreferredSize(new java.awt.Dimension(175, 20));
+        gridBagConstraints = new java.awt.GridBagConstraints();
+        gridBagConstraints.gridx = 0;
+        gridBagConstraints.gridy = 0;
+        gridBagConstraints.fill = java.awt.GridBagConstraints.HORIZONTAL;
+        gridBagConstraints.insets = new java.awt.Insets(2, 2, 2, 2);
+        getContentPane().add(m_passage, gridBagConstraints);
+        pack();
+    }
+    /**
+     * Check Button action.
+     * Collects the user input and checks it.
+     */
+    private void check() {
+        String[]({{ refs..path }}) result = m*checker.check(m*passage.getText());
+        if (result != null) {
+            m_result.setText(result.length + " word(s) are mispelled");
+        } else {
+            m_result.setText("All words are correct");
+        }
+    }
+    /**
+     * Start callback.
+     * This method will be called when the instance becomes valid.
+     * It set the Gui visibility to true.
+     */
+    public void start() {
+        this.setVisible(true);
+    }
+    /**
+     * Stop callback.
+     *  This method will be called when the instance becomes invalid or stops.
+     *  It deletes the Gui.
+     */
+    public void stop() {
+        this.dispose();
+    }
+}
+
+    Look at the three last methods. The _check_ methods collect the user input and use a _Check speller_ service to check this input. This method is called when the button is pressed by the user. The _start_ and _stop_ methods are lifecycle callbacks. As we need to display the user interface when the instance is created and to delete it when the instance stops, we need a way to be notified when we need to execute these actions. iPOJO provide an easy way to do this. The component provides two callback methods for its activation and deactivation, start and stop, respectively. Callbacks are used when the component needs to be informed about a component state change. In iPOJO, the component state is either *INVALID* (i.e., not all of the component's constraints are satisfied) or *VALID* (i.e., all of the component's constraints are satisfied). In this example, the start callback method set the GUI visibility to true; the stop callback method deletes the GUI. The component metada
 ta will instruct iPOJO to invoke these methods when the component's state changes to *VALID* or *INVALID* respectively.
+    
+    Create the _metadata.xml_ file in the spell.chercker.gui directory with the following content:
+    {code:xml}
+    <ipojo>
+    <component classname="spell.gui.SpellCheckerGui">
+    	<requires field="m_checker"/>
+    	<callback transition="validate" method="start"/>
+    	<callback transition="invalidate" method="stop"/>
+    </component>
+    <instance component="spell.gui.SpellCheckerGui"/>
+    </ipojo>
+
+The component element again has the '*classname'* attribute that refers to the component implementation class. The '*requires*' element describes the *Check Speller* service dependency by simply specifying its associated component field. The '*callback'* elements describe which method to invoke when the component's state changes. Then the *'instance'* element asks iPOJO to create an instance of the component.
+
+Once this file is created, you can compile the project by launching *ant* in the spell.checker.gui directory.
+
+## Running the application
+
+To run the example, start Felix. A distribution of Felix is provided in the felix directory. This version is configured to launch iPOJO automatically. From the Felix directory, launch the following command to start the framework. Then enter a profile name.
+{code:none}
+java -jar bin/felix.jar
+
+    You can check installed bundles by using the '_ps_' command:
+    {code:none}
+    -> ps
+    START LEVEL 1
+       ID   State        Level  Name
+    [   0] [Active     ] [    0] System Bundle (2.0.5)
+    [   1] [Active     ] [    1] Apache Felix Bundle Repository (1.4.3)
+    [   2] [Active     ] [    1] Apache Felix iPOJO (1.6.0)
+    [   3] [Active     ] [    1] Apache Felix iPOJO Arch Command (1.6.0)
+    [   4] [Active     ] [    1] Apache Felix Shell Service (1.4.2)
+    [   5] [Active     ] [    1] Apache Felix Shell TUI (1.4.1)
+    ->
+
+iPOJO runtime is the bundle 4. Once started, install the four created bundles as above:
+{code:none}
+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
+
+    When starting the GUI bundle, the user interface appears. Indeed, the _Check Speller_ service is provided. You can interact with this service by entering a passage and clicking on the check button:
+    !ss.png!
+    Then, stop the _Dictionary_ service provider (with the _stop 7_) command. The GUI disappears. Indeed, Spell Checker service cannot be provided as it depends on the Dictionary service.
+    !spell2.png!
+    Then, restart the Dictionary service provider with the _start 7_ command. The GUI reappears immediately. You can try to stop the _check speller_ service provider without stopping the _dictionary_ service provider with the _stop 8_ command. As for the last manipulation, the GUI disappears.
+    !spell3.png!
+    To go further in the exploration, modify the spell.checker implementation. For example, add a simple trace, printing wrong words:
+    {code:java}
+            // ...
+            // Return null if no words are incorrect.
+            if (errorList.size() == 0) { return null; }
+    
+            // Return the array of incorrect words.
+            System.out.println("Wrong words:" + errorList); // <-- Add this line
+            return (String[]) errorList.toArray(new String[errorList.size()]);
+
+
+Then rebuild the spell.checker bundle and update it (with the 'update 8' command). You will see the gui "blinking". In fact, the gui was stopped as the required spell checker service was no more available. As soon as it was back, the gui restarts. The gui didn't lose its state. The other services weren't stopped during the update.
+You can uninstall the check service bundle and then re-install a new one (or the same one), you will see the same behavior.
+
+## Conclusion
+
+We saw how to use easily iPOJO to build service-oriented component. In this tutorial, we have demonstrated how to:
+* Publish OSGi services
+* Require OSGi services
+* Use lifecycle callbacks to activate and deactivate components
+
+iPOJO provides a lot of others features that you can try in the others available tutorials. Subscribe to the Felix users mailing list by sending a message to [mailto:users-subscribe@felix.apache.org]({{ refs.mailto-users-subscribe-felix-apache-org.path }}); after subscribing, email questions or feedback to [mailto:users@felix.apache.org].
+  
+  
+  
+  
+{include:apache-felix-ipojo-footer}
\ No newline at end of file



Mime
View raw message