felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fmesc...@apache.org
Subject svn commit: r1421893 [12/24] - in /felix/site/trunk/content: ./ documentation/ documentation/community/ documentation/development/ documentation/faqs/ documentation/subprojects/ documentation/subprojects/apache-felix-commons/ documentation/subprojects/...
Date Fri, 14 Dec 2012 14:30:22 GMT
Added: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/temporal-service-dependency.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/temporal-service-dependency.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/temporal-service-dependency.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/temporal-service-dependency.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,148 @@
+Title: Temporal Service Dependency
+
+{include:apache-felix-ipojo-header}
+
+<div class="content">
+
+# The temporal dependency handler
+
+*Regular service dependencies participate to the instance lifecycle. Moreover, the injected service object is either available or not available. A temporal dependency handler is a little different and provides a different resolution pattern. Indeed, the temporal dependency does not invalidate the instance. Moreover, if not available, the temporal dependency waits (and so blocks the current thread) for a provider. Of course, the maximum waiting time can be specified. If a timeout occurs, the handler throws a Runtime Exception.*
+
+{div:class=toc}
+[TOC]
+{div}
+
+## Using the handler
+
+First of all, you need to configure the component type to use the handler such as:
+
+    <iPOJO xmlns:temporal="org.apache.felix.ipojo.handler.temporal">
+    <component
+        className="org.apache.felix.ipojo.example.Temporal">
+    
+        <!-- Temporal dependency configuration -->
+        <temporal:requires field="mytemporal"/>
+    
+        <provides/>
+    
+    </component>
+    </iPOJO>
+
+Notice that, this handler is an external handler. So, it uses the "org.apache.felix.ipojo.handler.temporal" namespace.
+Once described, you can implement your component. The specified field will be mapped to the temporal dependency. As for regular field injection, aggregation, targeted service specification (i.e. interface) is discovered automatically. Filter, comparator and binding policy are also supported. However, the optional attribute is not supported. In fact, this attribute is meaningless in the case of a temporal dependency.
+Using the field in your code will try to find a matching service provider. If a provider is available, the field receives the service object immediately. Else, the thread is stopped and waits for a provider. The default wait time is 3s (you can also specify this time). If no provider is available after this time, the thread throws a RuntimeException. If a provider becomes available during this time, the field receives immediately the value and the execution can continue.
+
+You can also use annotations:
+
+    @Component
+    public class Temporal {
+    
+        @Temporal // was org.apache.felix.ipojo.handler.temporal.Requires before the 1.7.0
+        private FooService mytemporal;
+    
+    }
+
+
+## Configuration
+
+The handler has only one mandatory attributes:
+* Field: the implementation field supporting the dependency (not needed with annotations)
+
+The handler supports on specific optional attributes:
+* Timeout: the maximum time waited in order to find a provider (default: 3s). For an infinite timeout, the timeout value is either "infinite" or "-1".
+* OnTimeout: specifies the action to do when the timeout occurs. Four actions are supported: null, nullable, empty-array, default-implementation. By default, no action is specified, and an exception occurs when the timeout is reached.
+
+The attributes from "regular" dependencies are also supported (like filter).
+OnTimeout actions
+
+When a timeout occurs, you can specify what the handler must do. By default, it throws a runtime exception. However, four others actions can be set in the 'onTimeout' attribute.
+* The null action (onTimeout="null") will return "null" instead of the service object.
+* The "nullable" action (onTimeout="nullable") will return a "Nullable" object instead of the service object. This object is a fake but can be used a regular service object. However, invoking actions on this object will do nothing. In the case of aggregate dependency, an array containing a "nullable" object is returned.
+* The empty action is only supported for aggregate dependency (the field must be an array). In this case, an empty-array is returned. (In the 1.2.0 version, the `empty-array` attribute became `empty`)
+* The default-implementation action is a little different. Instead of specifying the action, you need to specify the default-implementation (the qualified class name) that you want to use. For example onTimeout="o.a.f.i.MyDefaultLogServiceImpl". In this case, the handler will inject an instance of this object instead of a real service object. On aggregate dependency, an array with one default-implementation object is returned.
+
+
+    <iPOJO xmlns:temporal="org.apache.felix.ipojo.handler.temporal">
+    <component
+        className="org.apache.felix.ipojo.example.Temporal">
+    
+        <!-- Temporal dependency configuration -->
+        <temporal:requires field="fs" timeout="300" ontimeout="nullable"/>
+    
+        <provides/>
+    
+    </component>
+    </iPOJO>
+
+
+This is equivalent to:
+
+    @Component
+    public class Temporal {
+    
+        @Temporal(timeout=300, ontimeout="nullable")
+        private FooService mytemporal;
+    
+    }
+
+
+## Collection injection
+Temporal dependencies can also be injected inside Collection. To achieve this, the 'specification' attribute must indicates the looked specification, and the field must be a Collection.
+
+    <iPOJO xmlns:temporal="org.apache.felix.ipojo.handler.temporal">
+    <component
+        className="org.apache.felix.ipojo.example.Temporal">
+    
+        <!-- Temporal dependency configuration -->
+        <temporal:requires field="mycollection" specification="my.service.specification"/>
+    
+        <provides/>
+    
+    </component>
+    </iPOJO>
+
+
+This is equivalent to:
+
+    @Component
+    public class Temporal {
+    
+        @Temporal(specification="my.service.specification")
+        private List<FooService> mycollection;
+    
+    }
+
+
+## Proxy injection
+Temporal dependencies can also be injected as proxies. So it is possible to give the temporal dependency to helper object.
+On 'scalar' dependencies, the service lookup is executed during an operation invocation. Timeout policies are also executed is the lookup failed.
+On aggregate dependencies (necessary Collection), the service lookup is executed when the iterator(), and toArray(...) methods are invoked. Timeout policies 
+are also executed if the lookup failed. Proxies are enabled by default since the 1.7.0 version.
+
+To set a temporal dependency as a proxy, just add the `proxy` attribute as follows:
+
+    <iPOJO xmlns:temporal="org.apache.felix.ipojo.handler.temporal">
+    <component
+        className="org.apache.felix.ipojo.example.Temporal">
+    
+        <!-- Temporal dependencies configuration -->
+        <temporal:requires proxy="true" field="fs"/>
+        <temporal:requires proxy="true" field="mycollection" specification="my.service.specification"/>
+    
+        <provides/>
+    
+    </component>
+    </iPOJO>
+
+
+By default, proxies are *enabled*. Setting proxy to `false` disables them.
+
+## Download 
+
+The handler is available on the [download]({{ refs.download.path }}) page.
+Sources are available on the Felix trunk at the following location: [http://svn.apache.org/repos/asf/felix/trunk/ipojo/handler/temporal](http://svn.apache.org/repos/asf/felix/trunk/ipojo/handler/temporal).
+  
+  
+  
+  
+{include:apache-felix-ipojo-footer}
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/white-board-pattern-handler.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/white-board-pattern-handler.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/white-board-pattern-handler.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/white-board-pattern-handler.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,160 @@
+Title: White Board Pattern Handler
+
+{include:apache-felix-ipojo-header}
+
+<div class="content">
+
+#  The white board pattern handler
+The objective of this handler is to simplify the development of white-board architecture. This architecture-style is based is very close to the extender architecture style but relies on services instead of bundles.
+
+{div:class=toc}
+[TOC]
+{div}
+
+<div class="info" markdown="1">
+**Change in the 1.2.0**
+The 1.2.0 uses the namespace `org.apache.felix.ipojo.whiteboard` instead of `org.apache.felix.ipojo.white-board-pattern`
+</div>
+
+<div class="info" markdown="1">
+** Change in the 1.7.0**
+The 1.7.0 has introduced a new annotations allowing to declare several whiteboard patterns in the same class. The ``@Whiteboards}} annotation is not available in previous version.
+</div>
+
+## The whiteboard pattern
+A whiteboard is based on two different roles:
+* A consumer looking to special services or a services published with a special mark
+* Looked services
+
+More information on this pattern is available in this [document](http://www.osgi.org/wiki/uploads/Links/whiteboard.pdf)
+Implementing a white board pattern could be complex as the extender needs to track these services dynamically. Indeed looked services can be highly dynamic; they can arrive, leave or be modified at runtime. Several services specified in the OSGi specification use white board pattern such as the Device Access Manager.
+
+## Using the handler
+First of all, you need to configure the component type to use the handler such as:
+
+    <ipojo xmlns:wbp="org.apache.felix.ipojo.whiteboard">
+         <component 
+              className="org.apache.felix.ipojo.test.FooWhiteBoardPattern"
+          >
+            <wbp:wbp 
+       	      filter="(my.property=1)" 
+                  onArrival="onArrival" 
+                  onDeparture="onDeparture" 
+                  onModification="onModification"
+             />
+           
+          </component>
+
+Notice that, this handler is an external handler. So, it uses the "org.apache.felix.ipojo.whiteboard" namespace.
+Once described, you can implement your component. The methods specified methods will be called when a matching services arrives or leaves or are modified. The modification callback is optional. A matching service is detected by confronting the service reference against the specified filter.
+The filter can target specific service interface (with the objectclass property) or property values.
+In the previous example, these methods could be: 
+
+    public class FooWhiteBoardPattern {
+        List list = new ArrayList();
+        int modifications = 0;    
+        public synchronized void onArrival(ServiceReference ref) {
+            list.add(ref);
+        }    
+        public synchronized void onDeparture(ServiceReference ref) {
+            list.remove(ref);
+        }    
+        public synchronized void onModification(ServiceReference ref) {
+            // ...
+        } 
+
+All methods received the arriving, leaving or modified service reference.
+
+You can also use annotation to declare the same component:
+
+    @Component
+    @Wbp(
+      filter="my.property=1", 
+      onArrival="onArrival" 
+      onDeparture="onDeparture" 
+      onModification="onModification")
+    public class FooWhiteBoardPattern {
+        List list = new ArrayList();
+    
+        public synchronized void onArrival(ServiceReference ref) {
+            list.add(ref);
+        }    
+        public synchronized void onDeparture(ServiceReference ref) {
+            list.remove(ref);
+        }    
+        public synchronized void onModification(ServiceReference ref) {
+    	   //...
+        }
+
+
+
+## Configuration
+The handler has only three mandatory attributes:
+* Filter: filter use to discover matching filter.
+* onArrival: declaring the method to invoke when a matching service arrives
+* onDeparture: declaring the method to invoke when a matching service leaves
+
+The onModification attribute is optional. This method is called when an injected service reference is modified but stills valid against the filter.
+<div class="note" markdown="1">
+**Notifications**
+The implementation will be notified of arrivals, modifications and departures, despite the instance is invalid. Indeed, the implementation must release all objects created from another bundle as soon it leaves.
+</div>
+## Configuring the handler with annotations
+
+It is possible to configure the handler with a simple annotation available in the annotation pack ('annotation' project in the iPOJO trunk). Here is an example of usage:
+{code:java}
+import org.apache.felix.ipojo.annotations.Component;
+import org.osgi.framework.ServiceReference;
+
+@Component
+@org.apache.felix.ipojo.whiteboard.Wbp(filter="(foo=true)", 
+        onArrival="onArrival", 
+        onDeparture="onDeparture",
+        onModification="onModification")
+public class WhiteBoardExemple {
+    
+    public void onArrival(ServiceReference ref) {
+        // do something
+    }
+    
+    public void onDeparture(ServiceReference ref) {
+        // do something
+    }
+    
+    public void onModification(ServiceReference ref) {
+        // do something
+    }
+
+}
+
+    
+    The {{onModification}} attribute is optional.The {{filter}} attribute allows setting the service filter.
+    
+    In the 1.7.0, a new annotation was introduced to support the declaration of several whiteboard patterns in the same component:
+
+@Component
+@Whiteboards(whiteboards={
+     @Wbp(filter="(foo=true)", 
+        onArrival="onArrival", 
+        onDeparture="onDeparture",
+        onModification="onModification"),
+     @Wbp(filter="(bar=true)", 
+        onArrival="onArrival2", 
+        onDeparture="onDeparture2")}
+)
+public class WhiteBoardExemple {
+    
+    // ...
+
+}
+
+
+
+## Download
+The handler is available on the [download]({{ refs.download.path }}) page.
+Sources are available on the Felix trunk at the following location: [http://svn.apache.org/repos/asf/felix/trunk/ipojo/handler/whiteboard](http://svn.apache.org/repos/asf/felix/trunk/ipojo/handler/whiteboard).
+  
+  
+  
+  
+{include:apache-felix-ipojo-footer}
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/how-to-use-ipojo-annotations.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/how-to-use-ipojo-annotations.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/how-to-use-ipojo-annotations.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/how-to-use-ipojo-annotations.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,392 @@
+Title: How to use iPOJO Annotations
+
+{include:apache-felix-ipojo-header}
+
+<div class="content">
+
+# How to use iPOJO annotations
+
+*You can use annotations to define your component types. This page presents supported annotations.*
+
+{div:class=toc}
+[TOC]
+{div}
+
+## Getting iPOJO Annotations:
+
+iPOJO Annotations are defines inside the org.apache.felix.ipojo.annotations project. You can download the Jar file of this project from the [download]({{ refs.download.path }}) page. Sources are available on the [Felix trunk|http://felix.apache.org/site/sourcecode.html].
+Once added to your class path / build path / dependencies, you can use the annotations as normal annotations. These annotations are automatically processed by the iPOJO manipulator.
+
+### In Eclipse
+
+Add the org.apache.felix.ipojo.annotations jar file in your build path. Do not forget to use a Java compiler accepting annotations (1.5 or higher).
+
+### In Maven
+
+Add the following dependency:
+
+    <dependency>
+          <groupId>org.apache.felix</groupId>
+          <artifactId>org.apache.felix.ipojo.annotations</artifactId>
+          <version>1.8.0</version>
+    </dependency>
+
+Moreover, you need to set that the source code and the target code are Java 1.5 code. To achieve this, just add the following plugin in your plugins section:
+
+    <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+    	<artifactId>maven-compiler-plugin</artifactId>
+    	<configuration>
+    	  <source>1.5</source>
+    	  <target>1.5</target>
+    	</configuration>
+    </plugin>
+
+
+### In Ant
+
+Just add the org.apache.felix.ipojo.annotations jar file  in your class path.
+
+## An example of usage
+
+To illustrate annotations usage, let taking the tutorial example. In this tutorial, there are two components:
+* The first one provides the hello service
+* The second one uses the provided hello service
+You can download the archive containing the examples and a preconfigured version of Felix [here](http://people.apache.org/~clement/ipojo/tutorials/annotations/annotation-tutorial.zip).
+
+### Hello Service Provider
+
+The provider uses two annotations. The "component" annotation is mandatory and defines that the class defines a component type. Then the "provides" annotation just declare that the defined component type provides a service.
+
+    package ipojo.example.hello.impl;
+    
+    import ipojo.example.hello.Hello;
+    
+    import org.apache.felix.ipojo.annotations.Component;
+    import org.apache.felix.ipojo.annotations.Provides;
+    
+    /**
+      * Component implementing the Hello service.
+     **/
+    @Component
+    @Provides
+    public class HelloImpl implements Hello {
+        public String sayHello(String name) { 
+         return "hello " + name; 
+        }
+    }
+
+
+### Hello Service Consumer
+
+The Hello Service Consumer use more annotations. First it used the component annotation. To defines its "immediate" behavior, it add the 'immediate' attribute.
+Then, it uses the requires annotation to define a service dependency. Finally, it uses the validate and invalidate annotations to define lifecycle callbacks.
+
+    package ipojo.example.hello.client;
+    
+    import org.apache.felix.ipojo.annotations.Component;
+    import org.apache.felix.ipojo.annotations.Invalidate;
+    import org.apache.felix.ipojo.annotations.Requires;
+    import org.apache.felix.ipojo.annotations.Validate;
+    
+    import ipojo.example.hello.Hello;
+    
+    @Component(name="AnnotedHelloClient", immediate=true)
+    public class HelloClient implements Runnable {
+    
+    @Requires
+    private Hello[] m_hello; // Service Dependency
+    
+    private final static int DELAY=10000;
+    private boolean end;
+    
+     public void run() {
+        while (!end) {
+                   try {
+    		invoke();
+                    Thread.sleep(DELAY);
+                  } catch (InterruptedException ie) { }
+                  /* will recheck end */
+         }
+    }
+    
+    public void invoke() {
+    	for (int i = 0; i < m_hello.length; i++) { 
+              System.out.println(m_hello[i].
+                 sayHello("Clement")); 
+            }
+    }
+    
+     @Validate
+     public void starting() {    
+        Thread T = new Thread(this);     
+        end = false;     
+        T.start(); 
+     }
+    
+     @Invalidate
+     public void stopping() {    
+         end = true; 
+     }
+    }
+
+
+## Defined Annotations
+
+This section lists defined annotations and how to use them.
+
+### @Component
+
+*Goal:* Defines a component type
+*Target:* The component implementation class
+*Attributes:*
+* name : defines the component type name (optional, default = the class name)
+* immediate: defines the component type as immediate (optional, default = "false")
+* architecture: enable the architecture exposition (optional, default = "false")
+* propagation: enable configuration property propagation (on provided services) (optional, default = "false")
+* managedservice : set the Managed Service PID. (optional, default = no PID (i.e. the managed service will not be exposed)). 
+* factoryMethod : set the factory-method. The specified method must be a static method and  return a pojo object.(optional,  default = iPOJO uses the 'regular' constructor). 
+* publicFactory : set if the component type is public. (optional, default = true). 
+
+### @Provides
+
+*Goal:* Defines that the component type provide services
+*Target:* The component implementation class
+*Attributes:*
+* specifications: defines the provided interface (optional, default = all implemented interfaces)
+* strategy : the service object creation strategy. Possible values : SINGLETON, SERVICE, METHOD, INSTANCE or the strategy class name. With SINGLETON there is only one POJO per component instance, SERVICE means OSGi Service factory,  METHOD delegates the creation to the factory-method of the component, INSTANCE creates one service object per requiring instance. For other strategies, specify the qualified name of the CreationStrategy class. (optional, default =  SINGLETON) 
+* properties : array containing `@StaticServiceProperties` defining service properties not attached to fields.
+
+
+<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>OSGi Service Factory</b>
+	</div>
+	</div>
+	<div class="box-blue-content">
+The <tt>SERVICE</tt> strategy refers to the OSGi service factory. So, one service object per asking bundle will be created.
+	</div>
+	<div class="box-blue-footer"></div>
+</div>
+
+
+
+
+<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>Changes between the 1.0.0 and the 1.2.0</b>
+	</div>
+	</div>
+	<div class="box-blue-content">
+The <tt>factory</tt> attribute became <tt>strategy</tt>. A third policy is now available (<tt>instance</tt>) allowing to create one service object per asking instance. Moreover, it is also possible to indicates the <tt>CreationStrategy</tt> class name. 
+	</div>
+	<div class="box-blue-footer"></div>
+</div>
+
+
+### @Requires
+
+*Goal:* Defines a service dependency
+*Target:* Field
+*Attributes:*
+* Filter: defines the LDAP filter (optional)
+* Optional: defines if the dependency is optional (optional, default = "false")
+* Id: defines the dependency Id (useful to identify bind & unbind methods) (optional, default = field name) (if a dependency with the same id is already created (by a @bind or @unbind annotation), it merges the dependencies).
+* Nullable: enable or disable the Null Object injection when the dependency is optional and no providers are available (optional, default = "true")
+* Defaultimplementation: set the Default-Implmentation (optional, by default iPOJO uses a Null object)
+* Policy: defines the binding policy (accepted value : dynamic, static, dynamic-priority) (optional, default = "dynamic")
+* Comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)
+* From : defines the specific provider to use
+* Specification : the required service specification. This attribute is required for Collection field. (optional, default = annotated field type). 
+* Proxy : enables / disables the proxy injection (enabled by default)
+
+### @ServiceProperty
+
+*Goal:* Defines a service property
+*Target:* Field
+*Attributes:*
+* name: property name (optional, default=field name
+* value: property value (optional, default=no value)
+* mandatory : is the property mandatory? (optional, default=false)
+
+
+<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>Mandatory property</b>
+	</div>
+	</div>
+	<div class="box-blue-content">
+A mandatory property must receive a value either from the component type description (<tt>value</tt> attribute, or the instance configuration.
+	</div>
+	<div class="box-blue-footer"></div>
+</div>
+
+
+### @ServiceController
+
+*Goal:* Control the service exposition
+*Target:* Field (Boolean)
+*Attributes:*
+* value : the default value. If set to false, it disables the initial exposition
+* specification : set the target of the controller, must be an exposed service interface. By default, the controller targets all services.
+
+
+### @Property
+
+*Goal:* Defines a property
+*Target:* Field or Method
+*Attributes:*
+* name: property name (optional, default=field name computed by removing "set" from the method name (for instance setFoo(String ff) will get the Foo name))
+* value: property value (optional, default=no value)
+* mandatory : is the property mandatory? (optional, default=false)
+
+
+<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>Field and Method</b>
+	</div>
+	</div>
+	<div class="box-blue-content">
+If another property with the same name is defined the method or the field is added to the existing property.
+	</div>
+	<div class="box-blue-footer"></div>
+</div>
+
+
+### @Updated
+*Goal:* Defines method called when a reconfiguration is completed.
+*Target:* a method (receiving a dictionary in argument)
+
+### @Bind
+
+*Goal:* Defines a bind method
+*Target:* Method
+*Attributes:*
+* Id: Dependency Id, if the id is already defines in a "@requires " or "@unbind" annotation, it adds this method as a bind method of the already created dependency. (optional, default= no id, compute an id if the method name begin by "bind" (for instance "bindFoo" will have the "Foo" id))
+* Specification : required dependency (optional)
+* Aggregate : is the dependency an aggregate dependency (optional, default= "false")
+* Optional: is the dependency an optional dependency (optional, default= "false")
+* Filter: dependency LDAP filter (optional)
+* Policy: defines the binding policy (accepted value : dynamic, static, dynamic-priority) (optional, default = "dynamic")
+* Comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)
+* From : defines the specific provider to use
+
+
+### @Unbind
+
+*Goal:* Defines an unbind method
+*Target:* Method
+*Attributes:*
+* Id: Dependency Id, if the id is already defines in a "@requires" or "@bind" annotation, it adds this method as an unbind method of the already created dependency. (optional, default= no id, compute an id if the method name begin by "unbind" (for instance "unbindFoo" will have the "Foo" id))
+* Specification : required dependency (optional)
+* Aggregate : is the dependency an aggregate dependency (optional, default= "false")
+* Optional: is the dependency an optional dependency (optional, default= "false")
+* Filter: dependency LDAP filter (optional)
+* Policy: defines the binding policy (accepted value : dynamic, static, dynamic-priority) (optional, default = "dynamic")
+* Comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)
+* From : defines the specific provider to use
+
+### @Modified
+
+*Goal:* Defines an `modified` method, called when a bound service is udpated.
+*Target:* Method
+*Attributes:*
+* Id: Dependency Id, if the id is already defines in a "@requires" or "@bind" annotation, it adds this method as an unbind method of the already created dependency. (optional, default= no id, compute an id if the method name begin by "unbind" (for instance "unbindFoo" will have the "Foo" id))
+* Specification : required dependency (optional)
+* Aggregate : is the dependency an aggregate dependency (optional, default= "false")
+* Optional: is the dependency an optional dependency (optional, default= "false")
+* Filter: dependency LDAP filter (optional)
+* Policy: defines the binding policy (accepted value : dynamic, static, dynamic-priority) (optional, default = "dynamic")
+* Comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)
+* From : defines the specific provider to use
+
+### @Validate
+
+*Goal:* defines a validate lifecycle callback
+*Target:* method
+
+### @Invalidate
+
+*Goal:* defines a validate lifecycle callback
+*Target:* method
+
+### @PostRegistration
+
+*Goal:* defines a callback invoked after service registration. The callback must have the following signature : `public void name(ServiceReference ref)`
+*Target:* method
+
+### @PostUnregistration
+
+*Goal:* defines a callback invoked after service unregistration. The callback must have the following signature : `public void name(ServiceReference ref)`
+*Target:* method
+
+### @Instantiate
+
+*Goal:* declare a simple instance (this is equivalent to `<instance component="..."></instance>`
+*Target:* class
+*Attribute:*
+* name: the instance name (optional)
+
+### Temporal Dependencies (external handler)
+
+The temporal dependency handler is an external handler. However, it can be used with an annotation defined in the iPOJO annotations jar file. 
+The annotation is org.apache.felix.ipojo.handler.temporal.Requires and targets a field. 
+*Attributes:*
+ * filter : specify the dependency filter
+ * timeout : specify the dependency timeout (optional)
+ * onTimeout : specify the onTimeout action (null, nullable, empty-array, default-implementation (specify the class name in this case) (optional).
+ * specification : the required service specification. This attribute is required for Collection field. (optional, default = annotated field type). 
+ * proxy :  Inject a proxy instead of the real object. This allows passing this reference to collaborators. (Default = false) 
+
+
+
+### Exposing instances as a JMX MBean (external handler)
+
+The JMX Handler allows exposing an instance as a JMX MBean. To configure the JMX handler directly from your code, three annotations are provided. They are in the `org.apache.felix.ipojo.handlers.jmx` package
+
+The `@org.apache.felix.ipojo.handlers.jmx.Config` (`@Config` if the package it correctly imported) annotation is a type annotation (so placed on the `class` element. This annotation indicates that the instance will be exposed as an MBean. This annotation supports:
+* usesMOSGi: set to `true` to use MOSGi. Otherwise, the MBean will be exposed in the MBean Platform Server (default: `false`).
+* objectname: set the MBean objectname. The objectname must follow JMX specification. (default: `package-name:factory-name:instance-name`)
+* domain: set the MBean domain. (default: `package-name`)
+* name: set the MBean name. (default: `instance-name`).
+
+The `@org.apache.felix.ipojo.handlers.jmx.Property` (`@Property`) annotation is a field annotation indicating that the field is exposed in the MBean. The supported attributes are:
+* name: set the property name
+* rights: set the access permission. Possible values are `r` (read only) and `w` (read and write). By default, properties are in read-only mode.
+* notification: enables notification on this property. By default notifications are disabled.
+
+The `@org.apache.felix.ipojo.handlers.jmx.Method` (`@Method`) annotation is a method annotation indicating that the method is exposed in the MBean. Only one attribute can be customized:
+* description: set the method description.
+
+
+## Advanced topics and FAQ
+
+### Metadata file and annotation merge
+
+It is possible to defines component type both in the metadata file (in XML) and by using annotation. However, if a component type defined by using annotations has the same name than a type define in the XML file, the XML descriptor override the annotation defined type. However, a warning message is launched during the manipulation.
+
+### Instance creation
+
+The @Instantiate annotation allows creating an instance, but this declaration is limited:
+* it does not support configuration
+* it does not allow naming
+* the instance is created in the global scope (so no composition)
+
+To define instances, you should use the XML descriptor. Instance can refer to annotated types by referring to their names.
+
+    <instance component="ipojo.example.hello.impl.HelloImpl"/>
+    <instance component="AnnotedHelloClient"/>
+
+
+### Using Custom Annotations
+
+External handlers can provides their own annotations. Using these annotations just requires to add them to your build path. To external handlers annotations, please refer to the external handler documentation.
+  
+  
+  
+  
+{include:apache-felix-ipojo-footer}
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,19 @@
+Title: iPOJO Advanced Topics
+
+{include:apache-felix-ipojo-header}
+
+<div class="content">
+
+# Advanced Topics
+
+*This page presents some advanced features.*
+
+* [Combining iPOJO and Configuration Admin]({{ refs.combining-ipojo-and-configuration-admin.path }})
+* [Constructing POJO objects with factory methods]({{ refs.constructing-pojo-objects-with-factory-methods.path }})
+* [How-to use iPOJO factories]({{ refs.how-to-use-ipojo-factories.path }})
+* [iPOJO Hierarchical Composition Overview]({{ refs.ipojo-hierarchical-composition-overview.path }})
+  
+  
+  
+  
+{include:apache-felix-ipojo-footer}

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/combining-ipojo-and-configuration-admin.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/combining-ipojo-and-configuration-admin.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/combining-ipojo-and-configuration-admin.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/combining-ipojo-and-configuration-admin.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,286 @@
+Title: Combining iPOJO and Configuration Admin
+
+{include:apache-felix-ipojo-header}
+
+<div class="content">
+
+# Combining iPOJO and Configuration Admin
+
+*This page presents how creating, reconfiguring and destroying iPOJO component instance with the OSGi Configuration Admin.*
+
+{div:class=toc}
+[TOC]
+{div}
+
+## Configuration Admin
+
+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.
+
+## Why using Configuration Admin with iPOJO
+
+As the configuration admin offer an administration support, it seems reasonable to combine iPOJO and the Configuration Admin to control the gateway. Indeed, thanks to the configuration admin it should be possible to:
+* Create new component instances
+* Configuring / reconfiguring these instances
+* Destroying these instances
+* Reconfiguring instances by using Managed Services (not addressed in this page, see [here]({{ refs.configuration-handler.path }}) 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.
+
+## Combining iPOJO and the Configuration Admin
+
+iPOJO has a component type concept. For each (public) component type, a `ManagedServiceFactory` is published. For each configurations matching with the component type from the Configuration Admin, a new component instance is created. Moreover, when this configuration is updated, the instance is dynamically reconfigured. If the configuration is removed, the instance is disposed.
+
+If a new Configuration is created:
+* If the factory is available or an instance is create immediately,
+* Else the factory is not available and the instance will be created as soon as the factory appears.
+
+## Examples
+
+This section presents 3 examples about the management of iPOJO instances with the configuration admin:
+* A simple instantiation example and destruction
+* An instantiation with property injection and dynamic reconfiguration
+* A property propagation example
+
+All these examples are downloadable [here](http://people.apache.org/~clement/ipojo/tutorials/ca/config.admin.tutorial.zip). 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` directory:
+
+    Java -jar bin/felix.jar
+
+
+### 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.
+
+Moreover iPOJO and an implementation of the Configuration Admin must be deployed on the gateway:
+
+    -> ps
+    START LEVEL 1
+       ID   State         Level  Name
+    [   0] [Active     ] [    0] System Bundle (1.0.3)
+    [   1] [Active     ] [    1] Apache Felix Shell Service (1.0.0)
+    [   2] [Active     ] [    1] Apache Felix Shell TUI (1.0.0)
+    [   3] [Active     ] [    1] Apache Felix Bundle Repository (1.0.2)
+    [   4] [Active     ] [    1] Apache Felix Configuration Admin Service (1.0.10) 
+    [   5] [Active     ] [    1] Apache Felix iPOJO (1.2.0) 
+    [   6] [Active     ] [    1] Apache Felix iPOJO Arch Command (1.2.0) 
+
+
+### Simple Instantiation
+
+Imagine the following very simple component implementation:
+{code:java}
+public class Hello1 {
+    public Hello1() {
+        System.out.println("Hello");
+    }
+}
+
+    The component type is defined with following metadata:
+    {code:xml}
+    <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 (note that bundle need to be already compiled):
+
+    -> start file:..\config.admin.tutorial\output\config.admin.tutorial.jar
+    -> create_conf org.apache.felix.ipojo.example.ca.component.Hello1 
+    Insert the configuration : {org.apache.felix.ipojo.example.ca.component.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 org.apache.felix.ipojo.example.ca.component.Hello1.e40fe80a-2c0d-4c51-b00b-a82565874cd8 -> valid 
+    -> 
+    -> arch -instance 
+    org.apache.felix.ipojo.example.ca.component.Hello1.e40fe80a-2c0d-4c51-b00b-a82565874cd8 
+    instance name=
+        "org.apache.felix.ipojo.example.ca.component.Hello1.e40fe80a-2c0d-4c51-b00b-a82565874cd8" 
+            component.type="hello1" 
+            state="valid" bundle="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" 
+    ->
+
+So, the instance is correctly created. The name of the instance was created by the configuration admin. It could change according to your configuration admin implementation.
+Then, we can delete the instance by removing the configuration from the configuration admin:
+
+    -> delete_conf 
+    org.apache.felix.ipojo.example.ca.component.Hello1.e40fe80a-2c0d-4c51-b00b-a82565874cd8 
+    Delete the configuration : 
+    org.apache.felix.ipojo.example.ca.component.Hello1.e40fe80a-2c0d-4c51-b00b-a82565874cd8 
+    -> arch 
+    Instance ArchCommand -> valid
+
+So, arch does no more displayed any *hello* instances, the created instance was disposed.
+
+### Reconfiguring instances with the Configuration Admin
+
+Imagine the following component implementation:
+{code:java}
+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:
+    {code:xml}
+    <component 
+            classname="org.apache.felix.ipojo.example.ca.component.Hello2" 
+            factory="hello2" immediate="true" architecture="true">
+    	<callback transition="validate" 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 a Hello2 instance
+* Update the instance configuration
+* Kill the created instance
+
+
+    -> create_conf org.apache.felix.ipojo.example.ca.component.Hello2 to=ipojo 
+    Insert the configuration : 
+    {service.factoryPid=org.apache.felix.ipojo.example.ca.component.Hello2, to=ipojo} 
+    Created configuration: 
+    org.apache.felix.ipojo.example.ca.component.Hello2.75082279-9b4b-4c49-b0e0-8efb38b67aa3 
+    Hello ipojo 
+    -> list_conf 
+    org.apache.felix.ipojo.example.ca.component.Hello2.75082279-9b4b-4c49-b0e0-8efb38b67aa3 : 
+     {service.pid=org.apache.felix.ipojo.example.ca.component.Hello2.75082279-9b4b-4c49-b0e0-8efb38b67aa3, 
+      service.factorypid=org.apache.felix.ipojo.example.ca.component.Hello2, 
+    to=ipojo} 
+    -> update_conf 
+    org.apache.felix.ipojo.example.ca.component.Hello2.75082279-9b4b-4c49-b0e0-8efb38b67aa3 to=felix 
+    Update: 
+    pid=org.apache.felix.ipojo.example.ca.component.Hello2.75082279-9b4b-4c49-b0e0-8efb38b67aa3 
+    Update the configuration : {to=felix} 
+    Hello felix 
+    -> delete_conf 
+    org.apache.felix.ipojo.example.ca.component.Hello2.75082279-9b4b-4c49-b0e0-8efb38b67aa3 
+    Delete the configuration : 
+    org.apache.felix.ipojo.example.ca.component.Hello2.75082279-9b4b-4c49-b0e0-8efb38b67aa3 
+    Good by felix-> list_conf
+
+In this simple scenario, we see that when the 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 org.apache.felix.ipojo.example.ca.component.Hello2 to=ipojo 
+    Insert the configuration : 
+    {service.factoryPid=org.apache.felix.ipojo.example.ca.component.Hello2, to=ipojo} 
+    Hello ipojo 
+    -> create_conf org.apache.felix.ipojo.example.ca.component.Hello2 to=felix 
+    Insert the configuration : 
+    {service.factoryPid=org.apache.felix.ipojo.example.ca.component.Hello2, to=felix} 
+    Hello felix 
+    -> arch 
+    Instance ArchCommand -> valid 
+    Instance org.apache.felix.ipojo.example.ca.component.Hello2.aaf1927c-1a81-490d-bd7b-21b13d454987 -> valid 
+    Instance org.apache.felix.ipojo.example.ca.component.Hello2.9344fdbe-c35e-4afc-b839-f7ad0ea59a9d -> valid
+
+The 'arch' command displays the two created instances.
+
+<div class="info" markdown="1">
+**Delete configurations**
+you can delete all created configurations with the *delete*conf all_ command
+</div>
+
+### Property Propagation
+
+It is possible to propagate the instance configuration to the published service properties. To activate property propagation you need to write the *'propagation'* attribute in the 'properties' element as in
+
+    <component 
+        classname="org.apache.felix.ipojo.example.ca.component.Hello3"
+        factory="hello3" architecture="true">
+    	<provides/>
+    	<properties propagation="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.
+So create an instance of the Hello3 component type as follow:
+
+    -> create_conf  org.apache.felix.ipojo.example.ca.component.Hello3 
+    Insert the configuration : 
+    {service.factoryPid=org.apache.felix.ipojo.example.ca.component.Hello3}
+
+Then, you can check provided services with the *services 7* command
+
+    -> services 7 
+    // Factories and Managed Service factories // 
+    ---- 
+    factory.name = org.apache.felix.ipojo.example.ca.component.Hello3 
+    instance.name = 
+    org.apache.felix.ipojo.example.ca.component.Hello3.a5ca5901-6e20-4636-8805-fbca2db1d68b 
+    objectClass = org.apache.felix.ipojo.example.ca.service.Hello 
+    service.factoryPid = org.apache.felix.ipojo.example.ca.component.Hello3 
+    service.id = 69 
+    -> 
+
+Now, we update the instance configuration with a new property 'p1':
+
+    -> update_conf 
+    org.apache.felix.ipojo.example.ca.component.Hello3.a5ca5901-6e20-4636-8805-fbca2db1d68b p1=v1 
+    Update the configuration : {p1=v1} 
+    -> services 7 
+    config.admin.tutorial (7) provides: 
+    // Factories and Managed Service factories // 
+    ---- 
+    factory.name = org.apache.felix.ipojo.example.ca.component.Hello3 
+    instance.name = 
+    org.apache.felix.ipojo.example.ca.component.Hello3.a5ca5901-6e20-4636-8805-fbca2db1d68b 
+    objectClass = org.apache.felix.ipojo.example.ca.service.Hello 
+    p1 = v1 
+    service.factoryPid = org.apache.felix.ipojo.example.ca.component.Hello3 
+    service.id = 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 
+    org.apache.felix.ipojo.example.ca.component.Hello3.a5ca5901-6e20-4636-8805-fbca2db1d68b 
+    Update the configuration : {} 
+    -> services 7 
+    ConfigAdminExample (8) provides: 
+    // Factories and Managed Service factories // 
+    ---- 
+    factory.name = org.apache.felix.ipojo.example.ca.component.Hello3 
+    instance.name = 
+    org.apache.felix.ipojo.example.ca.component.Hello3.a5ca5901-6e20-4636-8805-fbca2db1d68b 
+    objectClass = org.apache.felix.ipojo.example.ca.service.Hello 
+    service.factoryPid = org.apache.felix.ipojo.example.ca.component.Hello3 
+    service.id = 69 
+
+The service does no more publish the `p1` property.
+
+## Conclusion
+
+This page has presented how to combine the configuration admin and iPOJO. You can also use [FileInstall in combination with iPOJO and the Configuration Admin](http://ipojo-dark-side.blogspot.com/2009/04/ipojo-and-file-install-configuring.html). Subscribe to the Felix users mailing list by sending a message to [mailto:users-subscribe@felix.apache.org]; 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-userguide/ipojo-advanced-topics/constructing-pojo-objects-with-factory-methods.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/constructing-pojo-objects-with-factory-methods.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/constructing-pojo-objects-with-factory-methods.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/constructing-pojo-objects-with-factory-methods.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,50 @@
+Title: Constructing POJO objects with factory methods
+
+{include:apache-felix-ipojo-header}
+
+<div class="content">
+
+# Using a factory method to create POJO object
+
+*By default, iPOJO calls the POJO constructor to create objects. This constructor can either has no argument or receive the bundle context. However sometimes, you may want a more sophisticated object creation policy.*
+
+iPOJO allows you describing a factory method called to create POJO objects instead of the  constructor. So, every time that iPOJO needs to create an instance of your POJO class, this method will be called to obtain the object.
+
+To use this feature you need to add the `factory-method` attribute in the Component element as illustrated below:
+
+    <component
+    	className="org.apache.felix.ipojo.test.scenarios.component.FooProvider"
+            factory-method="createProvider"
+    >
+    	...
+    </component>
+
+
+The specified method must be a *static* method of the implementation class returning an *instance of this implementation class*. The following code shows an example of usage:
+
+        public static FooProvider createProvider() {
+            if (singleton == null) {
+                singleton = new FooProvider();
+            }
+            return singleton;
+        }
+
+
+This method must then call any valid constructor (potentially private) of the implementation class. 
+
+However, be aware that if you create an instance by using a `factory-method`, the called constructor hasn't access to values injected by the iPOJO container. So, the called constructor must not try accessing to services, properties... These objects will be accessible when the constructor returns.
+
+As for "normal" constructor, the method-factory can receive the bundle context in argument, such as in:
+
+        public static FooProvider createProvider (BundleContext bc) {
+            if (singleton == null) {
+                singleton = new FooProvider(bc);
+            }
+            return singleton;
+        }
+
+  
+  
+  
+  
+{include:apache-felix-ipojo-footer}
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/how-to-use-ipojo-factories.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/how-to-use-ipojo-factories.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/how-to-use-ipojo-factories.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/how-to-use-ipojo-factories.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,231 @@
+Title: How-to use iPOJO factories
+
+{include:apache-felix-ipojo-header}
+
+<div class="content">
+
+# iPOJO Factories Principles
+
+*iPOJO defines a factory for each declared component type. These factories are used to create component instances. This document presents how to declare instances and configure them. The API to create, dispose and reconfigure instances is also explained.*
+
+{div:class=toc}
+[TOC]
+{div}
+
+## Preliminary Concepts
+### Component Type
+A component type is a kind of instance template. If we compare component concepts with object oriented programming, component types are classes and component instances are objects. A component type is declared inside a metadata file (generally named 'metadata.xml'). The next snippet shows you a component type declaration: 
+
+    <component className="..." name="MyFactory">
+        ...
+        <!--component type configuration -->
+        ...
+    </component>
+
+A component type declaration begins generally by '<component>' and is composed by:
+* An implementation class ('className', mandatory). The 'className' attribute indicates the qualified name of the class implementing the component.
+* A name ('name')
+* Handler configuration (see handler guide)
+
+The 'name' attribute contains the factory name. If not specified, the 'className' attribute is used as the factory name. This factory name is used to refer to the factory (and consequently to the component type). 
+A factory can be public or private. A public factory allows creating instances dynamically and from other bundles. A private factory can only be used to create instances by declaring them in the same metadata.xml file that defines the instances' component type (i.e. in the same bundle). By default, factories are public. To set the factory to private add the 'public="false"'' attribute in the '<component>' element, such as: 
+
+    <component className="..." name="MyPrivateFactory" public="false">
+        ...
+        <!--component type configuration -->
+        ...
+    </component>
+
+Public factories offer different ways to create instances:
+* Instances can be declared in iPOJO descriptor in any bundle (i.e. from any metadata.xml file)
+* Instances can be created dynamically by using the API. Two APIs are provided the iPOJO Factory API and the OSGi Configuration Admin API
+
+Indeed, iPOJO will publish two services to access the factory through the API:
+* org.apache.felix.ipojo.Factory : iPOJO Factory Interface
+* org.osgi.service.cm.ManagedServiceFactory : Config Admin Interface
+
+The factory name will be used as the `service.pid` property for those services. The `service.pid` is unique and persists between framework restarts. The service.pid of the factory equals the factory name. This allows identifying factories exposed in the service registry.
+Factories are either valid or invalid. You can't create instances until a factory becomes valid. A factory is invalid if required handlers are missing. This issue occurs only if the component type uses external handlers.
+
+### Component Instance
+A component instance is an instance of a component type. For example, if a component type declares 'providing' and 'requiring' services, then the component instances will actually expose and require those services. Several instances can be created from one factory, but all these instances will be managed as different entities, and so are independent. A component instance is characterized by:
+* a component type (the factory name)
+* an instance name (used to identify the instance, is unique)
+* a configuration : a set of <key, value> couple
+
+A factory keeps a reference to each created instance. If the factory stops, goes away, or becomes invalid, all created instances are stopped and are destroyed.
+To create an instance, the creation request (describing the instance to create) must refer to the factory (by using the factory name), and provide the instance configuration. This configuration can specify the instance name ('instance.name' property). Be aware that this name must be unique. If not specified, iPOJO will generate a unique name.
+A factory can refuse the creation if the configuration is not acceptable or if the factory is invalid. An unacceptable configuration is a not suitable configuration in regard to component type. Reasons for unacceptable configuration are: 
+* The instance name is not set or not unique
+* A property required by the component type is missing inside the configuration
+* A pushed property has a wrong type
+
+## How-to declare instances inside metadata files
+The main way to create instances is to declare those instances inside the iPOJO descriptor file (i.e. 'metadata.xml'). Those declarations can use either public factories from any bundle, or private factories from the same bundle. Private factories are generally used to guaranty singleton instance as instances can only be created inside the same bundle. 
+When a instance declaration targets an external public factory, it will wait until the factory becomes available. So, the instance will be created only when the factory appears and is valid. If the factory disappears after the instance creation, the instance is disposed and will be recreated as soon as the factory comes back.
+The next snippet shows how to declare an instance in the metadata:
+
+    <instance component="component factory name" name = "instance name" >
+       <property name="a property name" value="a string form of the value"/>
+       <property name="another prop name" value="the string form value "/>
+    </instance>
+
+
+An instance declaration must contain the 'component' attribute. This attribute specifies the factory name (i.e. the component type). It can use either the factory name or the class name. The 'name' attribute allows setting the instance name. If not set, iPOJO will generate a unique name for you. Then, instances can declare properties. Those property are mostly key-value pair.  The key refer to a property name from the component type declaration such as in:
+
+    <component className="..." name="my-factory">
+        <properties>
+            <property name="foo" field="m_foo"/>
+        </properties>
+    </component>
+    <instance component="my-factory ">
+       <property name="foo" value="bla bla bla"/>
+    </instance>
+
+
+The string-form of the property value will be use to create the real object at runtime. If an unacceptable configuration is set, the instance is not created, and an error message appears to the console (and in the Log Service if present).
+Instance declaration properties can be more complex than only 'key-value'. It can contains structure like list, map, dictionary and arrays such as in:
+
+    <instance component="a.factory" name="complex-props">
+            <!--Creates a string array-->
+    	<property name="array" type="array"> 
+    		<property value="a"/>
+    		<property value="b"/>
+    	</property>
+            <!--Creates a list containing string-->
+    	<property name="list" type="list"> 
+    		<property value="a"/>
+    		<property value="b"/>
+    	</property>
+            <!--Creates a dictionary containing string-->
+    	<property name="dict" type="dictionary">
+    		<property name="a" value="a"/>
+    		<property name="b" value="b"/>
+    	</property>
+            <!--Creates a map containing string-->
+    	<property name="map" type="map"> 
+    		<property name="a" value="a"/>
+    		<property name="b" value="b"/>
+    	</property>
+    <!--A complex type can contains any other complex objects:-->
+    	<property name="complex-array" type="array">
+    		<property type="list">
+    			<property value="a"/>
+    			<property value="b"/>
+    		</property>
+    		<property type="list">
+    			<property value="c"/>
+    			<property value="d"/>
+    		</property>
+    	</property>
+    	<!--Empty structures will create empty objects-->
+    	<property name="empty-array" type="array"/>
+    	<property name="empty-list" type="list"/>
+    	<property name="empty-map" type="map"/>
+    </instance>
+
+
+<div class="info" markdown="1">
+**Instance name and factory name**
+The `instance.name` and `factory.name` property should not be set directly. iPOJO will manage those properties. The `instance.name` is simply created from the `instance.name` attribute of the instance declaration or from the `factory-name`-X where X is an integer.
+</div>
+
+## Creating, disposing and reconfiguring instances with the API
+A public factory is accessible through an exposed service ([org.apache.felix.ipojo.Factory ](http://felix.apache.org/ipojo/api/1.2.0/org/apache/felix/ipojo/Factory.html)). This service is accessible as any other OSGi service, and could be an iPOJO dependency using a LDAP filter or the 'from' attribute such as in:
+
+    <component classname="...">
+            <!-- These two requirement descriptions are equivalent -->
+    	<requires field="a_field" filter="(factory.name=factory-name)"/>
+    	<requires field="another_field" from="another-factory"/>
+    </component>
+
+### Creating instances
+Once you have a reference on the factory you can create instance with the 'createComponentInstance' method.
+
+    ComponentInstance createComponentInstance(java.util.Dictionary configuration)
+                                              throws UnacceptableConfiguration,
+                                                     MissingHandlerException,
+                                                     ConfigurationException
+
+This method returns a reference on the created instance. As you see, the method receives a dictionary containing the instance configuration. This configuration contains key-value pairs. However, values are either object (of the adequate type) of String used to create objects. This configuration can be 'null' if no properties have to be pushed.
+
+<div class="info" markdown="1">
+**Instance Name**
+The 'instance.name' property can be used to specify the instance name.
+</div>
+
+Instances are automatically started when created. However, the instance can be invalid, if at least one handler is not valid). 
+The instance creation process can fail. Three exceptions can be thrown during the creation:
+* UnacceptableConfiguration means that mandatory properties are missing in the instance configuration
+* MissingHandlerException means that the factory is not valid (i.e. an external handler is missing)
+* ConfigurationException means that the instance configuration has failed. The cause can be either an issue in the component type description or an invalid property type.
+
+
+If an error occurs, a comprehensive message is reported in order to solve the issue.
+The next snippet shows an example of instance creation:
+
+      	// Assume we get a Factory in the fact field
+            Properties props = new Properties();
+            props.put("instance.name","instance-name");
+            props.put("foo", "blablabla");
+            try {
+                instance = fact.createComponentInstance(props);
+            } catch(Exception e) {
+               fail("Cannot create the instance : " + e.getMessage());
+            }
+
+
+### Disposing created instance
+You can only disposed instances that you created. To dispose an instance, just call the 'dispose' method on the ComponentInstance object (returned by the createComponentInstance method).
+
+    instance.dispose();
+
+
+### Reconfiguring instance
+To reconfigure an instance, call the 'reconfigure' method on the ComponentInstance object. This method receives the new set of properties. Be aware that the 'instance.name' property cannot be changed.
+
+    Properties props2 = new Properties();
+    props2.put("foo", "abc");
+    instance.reconfigure(props2);
+
+
+### Accessing services exposed by created instances
+You can obviously access services exposed by an instance that you create. 
+To do this just use the OSGi API and the bundle context in order to query service references in the service registry such as in
+
+        ComponentInstance instance = ...
+        // ... 
+        try {
+            ServiceReference[] refs = 
+                  context.getServiceReferences(YourServiceInterface.class.getName(), 
+                  "(instance.name=" + instance.getInstanceName() +")");
+            if (refs != null) {
+                Foo your_object = (Foo) context.getService(refs[0]);
+            }
+        } catch (InvalidSyntaxException e) {
+            // Should not happen
+        }
+
+
+The LDAP filter allows selecting the service provided by your instance. Be care that this service can be not accessible if the instance is not valid. Once you get the service reference, you can ask the service registry to get the service object (i.e. the object contained in your instance). 
+
+If your instance does not provide services, you can access to the instance by following principles illustrated in the next snippet:
+
+        if (instance.getState() == ComponentInstance.VALID) {
+           ImplementationClass object = 
+              (ImplementationClass) ((InstanceManager) instance).getPojoObject();
+        } else {
+           System.out.println("Cannot get an implementation object from an invalid instance");
+        }
+
+Take care to check the instance state before accessing the object. Indeed, the behavior of an invalid instance is not guaranty. The 'getPojoObject' method will return an already created implementation (pojo) object or create a new one (if none already created).
+
+
+## How to use the ManagedServiceFactory to create, disposed and reconfigure instances
+The principle of the ManagedServiceFactory is the same as the iPOJO Factory Service. So, you can create, dispose and reconfigure instances with the Configuration Admin. For further information, read the OSGi R4.x Compendium - Configuration Admin chapter.
+Be aware that the `updated` method is used both for instance creation (if the given configuration is new) and to reconfigure an existing instance. The `deleted` method is used to dispose instances.
+  
+  
+  
+  
+{include:apache-felix-ipojo-footer}

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-hierarchical-composition-overview.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-hierarchical-composition-overview.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-hierarchical-composition-overview.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-hierarchical-composition-overview.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,253 @@
+Title: iPOJO Hierarchical Composition Overview
+
+{include:apache-felix-ipojo-header}
+
+<div class="content">
+
+# Introduction
+
+*iPOJO is an extensible, service-oriented component model implemented on the top of the OSGi framework that aims to simplify the development of OSGi™ applications. iPOJO follows a POJO-based component approach using external metadata to describe how POJO components should be managed by the iPOJO runtime. Some of the standard features of iPOJO include automatic service dependency management, service publication, and configuration property injection.*
+
+Another feature of iPOJO is component factories. As stated previously, an iPOJO component is described by its metadata. In iPOJO, the metadata describes a component type. For each component type, iPOJO registers a factory service that can be used to create instances of the component type described by the metadata.
+
+In addition to these features, iPOJO also provides a service-oriented composition model. iPOJO's composition model tries to merge:
+* Component-based composition and
+* Dynamic service flexibility.
+
+This document presents iPOJO's hierarchical service composition concepts and a simple example to illustrate them.
+
+# Motivation
+
+Component composition occurs in two fashions:
+* Horizontal composition: A provided interface from one component instance is bound to corresponding required interface of another component instance.
+* Vertical composition: Component instances are contained inside of another component instance.
+
+Typically, at runtime, a component composition is an unmodifiable set of connected component instances. The main motivation of iPOJO is to remove this limitation and introduce a more dynamic and flexible approach. iPOJO achieves its goals by applying service-oriented concepts to component orientation. Dynamic horizontal composition is supported by iPOJO's dependency injection mechanism described elsewhere ([How to write your own handler]({{ refs.how-to-write-your-own-handler.path }})) and dynamic vertical composition is supported by iPOJO's hierarchical composition mechanism described below.
+
+iPOJO hierarchical composition tries to merge component composition and dynamic service flexibility to allow:
+* Run-time/late binding.
+* Service run-time dynamics.
+* Implementation evolution.
+
+The result is a flexible, yet easy-to-use service-oriented component model.
+
+# Hierachical Service Composition
+
+iPOJO essentially provides a kind of service-oriented architecture definition language (ADL). This service-oriented ADL allows you to define *composite* components. The main differences between a traditional component-oriented composite and an iPOJO composite is that the iPOJO composite's constituent entities are described in terms of abstract service interfaces instead of specific component types/instances and bindings are inferred from dependency metadata data rather than explicitly declared. This approach means that composite components in iPOJO are not concrete component implementations; rather, they are abstract implementations whose precise implementation selection is deferred until run time.
+
+Unlike a POJO component in iPOJO that has code associated with it, a composite component is completely described by its metadata. Similar to a POJO component, however, the metadata describes a component type for which iPOJO registers a factory service that can be used to create instances of the composite component.
+
+A composite can be thought of as a service registry or a scoping mechanism of the global OSGi™ service registry. Composites can contain other composite, creating a hierarchy of service registries. The OSGi™ service registry is the root composite.
+
+A composite can:
+* Contain services.
+* Require services from its parent composite.
+* Provide services to its parent composite.
+
+A service contained in a composite is a *sub-service*, which is isomorphic to sub-components in traditional component-oriented composites. A sub-service is a service instance created from a component factory. Sub-services are not visible outside of the composite and can only see other services that reside in the composite service registry. The set of services in the composite service registry are all sub-services as well as all required services. Sub-services are not aware of the fact that they are inside of a composite and provide and use services normally within their composite.
+
+# "Hello World" Composite
+
+This section describes a simple composite example that requires an aggregated set of services from the parent composite, contains 3 sub-services, and provides one service to the parent composite.
+
+## The "Killer" Application
+
+To illustrate composite we design a "Hello World" application named *HelloComposition*. This composite offers a service for dispatching a "Hello" message to each person listed in a Directory service. Each person is published as a service and is used by the composition to get the name of the person in order to write the message.!compo1.jpg|align=center!
+The composite provides the HelloDispatcher service:
+
+    public interface HelloDispatcher {
+        public void dispatch();
+        public String getLanguage();
+        public List<Person> getPersons();
+    }
+
+The next section describes the abstract composite implementation.
+
+## Composite Design
+
+To implement this composite, we reuse existing service implementations;we have three off-the-shelf services:
+* Hello service: Returns a "Hello" message in a particular language.
+* Directory service: Aggregates Person services.
+* Dispatch service: Requires Hello and Directory services to dispatch a "Hello" message to each person contained in the Directory.!compo2.jpg|align=center!
+The following code snippet shows the Hello service interface:
+
+    public interface Hello {
+        public void hello(String name);
+        public String getLanguage();
+    }
+
+The following code snippet shows the Directory service interface:
+
+    public interface Directory {
+        public Person getPerson(String name);
+        public List<Person> getPersons();
+        public void addPerson(String name, String address);
+        public void removePerson(String name);
+    }
+
+The following code snippet shows the Person service interface:
+
+    public interface Person {
+        public String getName();
+        public String getAddress();
+    }
+
+The following code snippet shows the Dispatch service interface:
+
+    public interface Dispatcher {
+        public void dispatch();
+    }
+
+These services define the overall abstract implementation of the composite.
+
+## Composite Description
+
+To describe our composite, we use the iPOJO service-oriented ADL:
+
+    <composite name="HelloComposition">
+        <requires specification="org.apache.felix.ipojo.composition.ex1.person.Person" aggregate="true"/>
+        <service specification="org.apache.felix.ipojo.composition.ex1.hello.Hello"/>
+        <service specification="org.apache.felix.ipojo.composition.ex1.say.Dispatcher"/>
+        <service specification="org.apache.felix.ipojo.composition.ex1.directory.Directory"/>
+        <provides specification="org.apache.felix.ipojo.composition.ex1.compo.HelloDispatcher"/>
+    </composite>
+
+The composite is described in term of service specification, resulting in an abstract component implementation; it declares:
+* An requirement for all available Person services from the parent composite.
+* Sub-services for Hello, Dispatcher, and Directory services.
+* A provided HelloDispatcher service to the parent composite.
+
+When this composite is instantiated, all Person services from the parent composite are made available in the composite service registry and instances of the Hello, Dispatcher, and Directory are created from available factory services and their corresponding services are published in the composite service registry. The provided HelloDispatcher service is based on method delagation to sub-service specifications as depicted in the following image:!compo3.jpg|align=center!
+The delegation of HelloDispatcher service methods to sub-service methods is automatically performed by iPOJO based on method name and method parameter matching.
+
+### Composite Description Future Work
+
+The composite description presented here does not entirely conform to the ideal model proposed in the earlier sections of this document. Specifically, while the composite is defined in terms of services, the composition as described only really makes sense if we were aware of implementation-specific dependencies of the eventual Dispatcher component type. In other words, for us to choose the Hello and Directory sub-services, we had to know that the eventual implementation of the Dispatcher sub-service would have dependencies on these other sub-services. Unfortunately, this violates the goal of iPOJO to define composites purely in terms of abstract services.
+
+The main reason for this limitation is that OSGi service specifications are comprised of only two parts:
+1. A human-readable document.
+1. A Java service interface definition.
+
+To realize iPOJO, OSGi service specifications must be extended to contain other information. For example, services must be able to declare specification-level dependencies on other services. Services with specification-level dependencies are referred to as *composable services*, since it is possible to compose them with other service. In the core OSGi framework, all service dependencies are at the implementation level, thus only component instances are composable.
+
+Composable services are interesting because they make it possible to define services with parameterized behavior or algorithms. For example, a service to select something from a table could have a specification-level dependency on a sorting service, so that sort order is configurable externally. It might appear as if such a scenario were possible with standard OSGi services, but it is not possible unless you make assumptions about the component implementations.
+
+For example, in standard OSGi if component implementation A provides service Foo and requires service Bar, it is not possible to know whether component implementation B, which also provides Foo and requires Bar, uses Bar for the same purpose as A. Composable services makes this possible, since the purpose of such service dependencies can be defined in the service specification. The resulting model obeys two levels of service dependencies:
+* Specification-level dependencies: Dependencies that are imposed on all implementations and whose purpose is well defined.
+* Implementation-level dependencies: Dependencies that are arbitrarily selected by the component developer for a specific component implementation and whose purpose is unknown.
+
+As part of the ongoing work of iPOJO, specification-level dependencies (as well as other service specification improvements) will be introduced to the iPOJO model to further refine its service-oriented component model. Using the current example as an illustration, the current approach under investigation for specification-level dependencies looks like this:
+
+[Coming soon...]({{ refs.coming-soon.path }})
+
+## Packaging
+
+A composite component type is described in the metadata.xml file of an iPOJO bundle which means that iPOJO creates a factory service for the composite, like all iPOJO components. Also like all iPOJO components, it is possible to create an instance of the composite in the metadata file by declaring an instance, such as:
+
+    <instance component="HelloComposition" name="hello-composition"/>
+
+
+## Run Time
+
+Imagine at run time you have:
+* Two factories that can create Hello service provider instances.
+* A factory that can create Dispatcher service provider instances.
+* A factory that can create Directory service provider instances.
+* Several existing Person service instances.
+
+When you deploy the example composition and create an instance of it, all aspects of it are automatically managed by iPOJO:
+* All available Person services from the parent composite are imported into the composite.
+* One Hello service provider, one Directory service provider, and one Dispatcher service provider are instantiated inside the composite.
+* The HelloDispatcher service method calls are wired to the constituent sub-services and it is provided into the parent composite.
+
+If the factory which creates the Hello provider disappears (i.e., its instances become invalid), the composite will automatically switch to the second one to validate the composite service. If the second Hello provider disappears too, then the composite will be invalidated (i.e., the provided service will be revoked) and it will wait for new factory providing Hello service instances, which may themselves also be composite implementations.
+
+When a Person service appears in the parent composite, it is automatically inserted into the composite. Likewise, if a Person service disappears from the parent composite, it is automatically removed from the composite.
+
+A [flash demo](http://clement.plop-plop.net/animations/composite/composite.htm) of this composition is available.
+
+# Composite Concepts and Features
+
+The following subsections define the various concepts and features of iPOJO's composite components.
+
+## Service Requirement
+
+The composite can require services from the parent composite. Each requirement is describe by an `<requires>` element in the composite description. An imported service must specify the target service specification. Additionally, required sub-services can specify:
+* Cardinality: Indicates whether a single provider instance is imported or an aggregated set of the available providers instances is imported.
+* Optionality: Indicates whether the imported sub-service is optional or mandatory.
+* Filtering: Indicates how the services available in the parent composite can be further filtered using an LDAP expression evaluated over their service properties.
+
+
+    <requires specification="org.apache.felix.ipojo.test.scenarios.service.Hello"
+     optional="true" aggregate="true" filter="(language=en)"/>
+
+
+## Service Provisioning
+
+The composite can provide services to its parent composite. Each provided service is described by a `<provides>` element in the composite description. A provide service must specify provided service specification.
+
+Service provision is realized by delegating method invocations on the service interface to methods on the sub-service instances contained in the composition. A delegation mapping is automatically created by matching method names and arguments types. If a delegation mapping cannot be determined, the composition is invalidated.
+
+Service specifications can also declare certain methods as optional in the service interface; this is done by declaring that a method throws an `UnsupportedOperationException`. Optional methods need not have a mapping for delegation purposes. If a non-optional service method does not have a mapping for delegation, then a warning message is issued.
+
+    <provides specification="org.apache.felix.ipojo.composition.ex1.service.HelloDispatcher"/>
+
+
+## Sub-Service Instantiation
+
+A composite can contain sub-services, which result in private service instances at run time. The composite will track factories able to create targeted specification providers. The created service instances are accessible only inside the composite. Sub-service instances may also be composites. Each sub-service to instantiate is represented in the composite description by a `<service>` element. The sub-services must specify the desired service specification for the sub-service. Additionally, the sub-service may specify:
+* Cardinality: Indicates whether a single provider instance is created or an aggregated set of the available provider instances is imported.
+* Optionality: Indicates whether the created sub-service instance is optional or mandatory.
+* Filtering: Indicates how the service factories available in the parent composite can be further filtered using an LDAP expression evaluated over their service properties.
+* Configuration: Indicates the configuration to inject in the created instances.
+
+
+    <composite name="composite.bar ">
+        <service specification="org.apache.felix.ipojo.test.scenarios.service.Hello">
+            <property name="language" value="en"/>
+        </service>
+    </composite>
+
+
+## Instance injection
+
+A composite can contain instances. These instances does not need to provide any service and are identified by their component types. The composite will track the corresponding factories and create the instances. The instances are accessible only inside the composite and their service requirements are resolved inside the composite too. Each instance to instantiate is represented in the composite description by a `<instance>` element. The instance can specify the desired configuration. The following code snippet will inject an instance of the Hello factory with the configuration : language=en.
+
+    <composite name="composite.bar ">
+        <instance component="Hello">
+            <property name="language" value="en"/>
+        </instance>
+    </composite>
+
+Instance injection can be use for front end. However, these instances can be used to help a composite to provide a service (despite the instance does not provide a service). Indeed, these instances can be used as glue code to provide a service, containing method implementations of the provided service. For example, in the previous instance we had a Dispatcher service dispatching Hello message to Persons. Instead of this sub-service it is possible to inject in instance containing the *dispatch* method with a customized dispatching algorithm. A glue code instance can require services as any other iPOJO component.
+
+    <composite name="HelloComposition">
+        <requires specification="org.apache.felix.ipojo.composition.ex1.person.Person" aggregate="true"/>
+        <service specification="org.apache.felix.ipojo.composition.ex1.hello.Hello"/>
+        <service specification="org.apache.felix.ipojo.composition.ex1.directory.Directory"/>
+        <instance component="MyDispatcher"/>
+        <provides specification="org.apache.felix.ipojo.composition.ex1.compo.HelloDispatcher"/>
+    </composite>
+
+*Note:* To use instances as glue code be sure that your bundle, containing your composite, imports the implementation of the component type. Moreover, the factory allowing to create the instance must be available when starting your bundle to compute correctly the delegation mapping.
+
+## Architecture
+
+iPOJO composites can expose their internal architecture for reflection. This can be useful, for example, when debugging to understand why a given composite is currently invalid, such as when a given import cannot be satisfied. For a composite to expose its internal architecture, it must set the architecture flag, such as:
+
+    <composite name="composite.bar " architecture="true">
+        <service specification="org.apache.felix.ipojo.test.scenarios.service.Hello">
+            <property name="language" value="en"/>
+        </service>
+    </composite>
+
+With this flag set, iPOJO publishes an architecture service for the composite. The architecture of the composite can be examined using the "arch" shell command for Felix.
+
+## Composition Model Extensibility
+
+Like the rest of iPOJO, the composition model is extensible. The composite container is composed of a "composite handler", which is a special handler designed to support composite components. More documentation to come on this feature.
+  
+  
+  
+  
+{include:apache-felix-ipojo-footer}
\ No newline at end of file



Mime
View raw message