Modified: 
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/dm-lambda.html
==============================================================================
--- 
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/dm-lambda.html
 (original)
+++ 
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/dm-lambda.html
 Wed Feb 24 00:19:46 2016
@@ -152,7 +152,7 @@ DependencyManager object.</p>
         <span class="c1">// Declare our Consumer component</span>
 
         <span class="n">component</span><span class="o">(</span><span 
class="n">comp</span> <span class="o">-&gt;</span> <span 
class="n">comp</span><span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">ServiceConsumer</span><span 
class="o">.</span><span class="na">class</span><span class="o">)</span>
-            <span class="o">.</span><span class="na">withSvc</span><span 
class="o">(</span><span class="n">ServiceProvider</span><span 
class="o">.</span><span class="na">class</span><span class="o">,</span> <span 
class="n">srv</span> <span class="o">-&gt;</span> <span 
class="n">srv</span><span class="o">.</span><span class="na">filter</span><span 
class="o">(</span><span class="s">&quot;(p1=v1)&quot;</span><span 
class="o">).</span><span class="na">add</span><span class="o">(</span><span 
class="nl">ServiceConsumer:</span><span class="o">:</span><span 
class="n">setProvider</span><span class="o">))</span>
+            <span class="o">.</span><span class="na">withSvc</span><span 
class="o">(</span><span class="n">ServiceProvider</span><span 
class="o">.</span><span class="na">class</span><span class="o">,</span> <span 
class="n">svc</span> <span class="o">-&gt;</span> <span 
class="n">svc</span><span class="o">.</span><span class="na">filter</span><span 
class="o">(</span><span class="s">&quot;(p1=v1)&quot;</span><span 
class="o">).</span><span class="na">add</span><span class="o">(</span><span 
class="nl">ServiceConsumer:</span><span class="o">:</span><span 
class="n">setProvider</span><span class="o">))</span>
             <span class="o">.</span><span class="na">withCnf</span><span 
class="o">(</span><span class="n">ServiceConsumer</span><span 
class="o">.</span><span class="na">class</span><span class="o">.</span><span 
class="na">getName</span><span class="o">()));</span>
 
         <span class="c1">// Declare our ServiceProvider service 
component:</span>
@@ -228,7 +228,7 @@ The constructed Component is then automa
 </pre></div>
 
 
-<p>And to reduce the "code ceremony", here is a more concise version where the 
type of the lambda parameter is not declared:</p>
+<p>Here is a more concise version with less "code ceremony" where the type of 
the type of the lambda parameter is not declared:</p>
 <div class="codehilite"><pre><span class="kn">import</span> <span 
class="nn">org.apache.felix.dm.lambda.DependencyManagerActivator</span><span 
class="o">;</span>
 
 <span class="kd">public</span> <span class="kd">class</span> <span 
class="nc">Activator</span> <span class="kd">extends</span> <span 
class="n">DependencyManagerActivator</span> <span class="o">{</span>
@@ -240,9 +240,12 @@ The constructed Component is then automa
 </pre></div>
 
 
-<h2 id="adding-service-dependencies">Adding service dependencies<a 
class="headerlink" href="#adding-service-dependencies" title="Permanent 
link">&para;</a></h2>
-<p>You can add a dependency using the <code>withSvc</code> methods available 
from the ComponentBuilder interface.
-Such method accepts a <code>Consumer&lt;ServiceDependencyBuilder&gt;</code> 
lambda expression, which may then configure the dependency using a chain of 
method calls (filter/callbacks,autoconfig, etc ...):</p>
+<h2 id="adding-service-dependencies-injected-in-class-fields">Adding service 
dependencies injected in class fields.<a class="headerlink" 
href="#adding-service-dependencies-injected-in-class-fields" title="Permanent 
link">&para;</a></h2>
+<p>You can add a dependency using the "<code>withSvc</code>" methods available 
from the ComponentBuilder interface.
+Such method accepts a <code>Consumer&lt;ServiceDependencyBuilder&gt;</code> 
lambda expression, which may then configure the dependency using a chain of 
method calls (filter/callbacks,autoconfig, etc ...):
+When you don't specify callbacks, services are injected in class fields with 
compatible service dependency type, but you can specify a field name.
+Unavailable optional dependencies are injected as "<code>Null 
Objects</code>".</p>
+<p>The following example adds a service dependency on a LogService with a 
service filter.</p>
 <div class="codehilite"><pre><span class="kn">import</span> <span 
class="nn">org.apache.felix.dm.lambda.DependencyManagerActivator</span><span 
class="o">;</span>
 <span class="kn">import</span> <span 
class="nn">org.apache.felix.dm.lambda.ServiceDependencyBuilder</span><span 
class="o">;</span>
 
@@ -250,19 +253,19 @@ Such method accepts a <code>Consumer&lt;
     <span class="nd">@Override</span>
     <span class="kd">public</span> <span class="kt">void</span> <span 
class="nf">init</span><span class="o">(</span><span 
class="n">BundleContext</span> <span class="n">ctx</span><span 
class="o">,</span> <span class="n">DependencyManager</span> <span 
class="n">dm</span><span class="o">)</span> <span class="kd">throws</span> 
<span class="n">Exception</span> <span class="o">{</span>
         <span class="n">component</span><span class="o">(</span><span 
class="n">comp</span> <span class="o">-&gt;</span> <span 
class="n">comp</span><span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">Hello</span><span class="o">.</span><span 
class="na">class</span><span class="o">)</span>
-            <span class="o">.</span><span class="na">withSvc</span><span 
class="o">(</span><span class="n">LogService</span><span 
class="o">.</span><span class="na">class</span><span class="o">,</span> <span 
class="o">(</span><span class="n">ServiceDependencyBuilder</span> <span 
class="n">srv</span><span class="o">)</span> <span class="o">-&gt;</span> <span 
class="n">srv</span><span class="o">.</span><span class="na">filter</span><span 
class="o">(</span><span class="s">&quot;(vendor=apache)&quot;</span><span 
class="o">)));</span>
+            <span class="o">.</span><span class="na">withSvc</span><span 
class="o">(</span><span class="n">LogService</span><span 
class="o">.</span><span class="na">class</span><span class="o">,</span> <span 
class="o">(</span><span class="n">ServiceDependencyBuilder</span> <span 
class="n">svc</span><span class="o">)</span> <span class="o">-&gt;</span> <span 
class="n">svc</span><span class="o">.</span><span class="na">filter</span><span 
class="o">(</span><span class="s">&quot;(vendor=apache)&quot;</span><span 
class="o">)));</span>
     <span class="o">}</span>
 <span class="o">}</span>
 </pre></div>
 
 
-<p>The above example adds a service dependency on a LogService with a service 
filter. Here is a more concise version where the type of the <code>srv</code> 
lambda parameter is not declared:</p>
+<p>Here is a more concise version where the type of the <code>svc</code> 
lambda parameter is not declared:</p>
 <div class="codehilite"><pre><span class="kn">import</span> <span 
class="nn">org.apache.felix.dm.lambda.DependencyManagerActivator</span><span 
class="o">;</span>
 
 <span class="kd">public</span> <span class="kd">class</span> <span 
class="nc">Activator</span> <span class="kd">extends</span> <span 
class="n">DependencyManagerActivator</span> <span class="o">{</span>
     <span class="nd">@Override</span>
     <span class="kd">public</span> <span class="kt">void</span> <span 
class="nf">init</span><span class="o">(</span><span 
class="n">BundleContext</span> <span class="n">ctx</span><span 
class="o">,</span> <span class="n">DependencyManager</span> <span 
class="n">dm</span><span class="o">)</span> <span class="kd">throws</span> 
<span class="n">Exception</span> <span class="o">{</span>
-        <span class="n">component</span><span class="o">(</span><span 
class="n">comp</span> <span class="o">-&gt;</span> <span 
class="n">comp</span><span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">Hello</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">withSvc</span><span class="o">(</span><span 
class="n">LogService</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span class="n">srv</span> 
<span class="o">-&gt;</span> <span class="n">srv</span><span 
class="o">.</span><span class="na">filter</span><span class="o">(</span><span 
class="s">&quot;(vendor=apache)&quot;</span><span class="o">)));</span>
+        <span class="n">component</span><span class="o">(</span><span 
class="n">comp</span> <span class="o">-&gt;</span> <span 
class="n">comp</span><span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">Hello</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">withSvc</span><span class="o">(</span><span 
class="n">LogService</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span class="n">svc</span> 
<span class="o">-&gt;</span> <span class="n">svc</span><span 
class="o">.</span><span class="na">filter</span><span class="o">(</span><span 
class="s">&quot;(vendor=apache)&quot;</span><span class="o">)));</span>
     <span class="o">}</span>
 <span class="o">}</span>
 </pre></div>
@@ -296,15 +299,30 @@ dependency that is not needing a Service
 </pre></div>
 
 
-<h2 id="service-dependency-component-callbacks">Service Dependency Component 
callbacks<a class="headerlink" href="#service-dependency-component-callbacks" 
title="Permanent link">&para;</a></h2>
-<p>By default, service dependencies are auto injected in class fields (you can 
configure the name of the class field where the dependency should be injected).
-But like in the current DM API, you can specify callbacks on the component 
implementation class using the "<code>add/change/remove/swap</code>" 
<code>ServiceDependencyBuilder</code> methods:</p>
+<p>Dependency services can be injected in the following kind of fields:</p>
+<ul>
+<li>a field having the same type as the dependency. If the field may be 
accessed by anythread, then the field should be declared 
+volatile, in order to ensure visibility when the field is auto injected 
concurrently.</li>
+<li>a field which is assignable to an <code>Iterable&lt;T&gt;</code> where T 
must match the dependency type. In this case, an Iterable will be 
+injected by DependencyManager before the start callback is called. The 
Iterable field may then be traversed to inspect the 
+currently available dependency services. The Iterable can possibly be set to a 
final value so you can choose the Iterable implementation of your choice (for 
example, a CopyOnWrite ArrayList, or a ConcurrentLinkedQueue).</li>
+<li>a <code>Map&lt;K,V&gt;</code> where K must match the dependency type and V 
must exactly equals Dictionary class. In this case, a 
+ConcurrentHashMap will be injected by DependencyManager before the start 
callback is called. 
+The Map may then be consulted to lookup current available dependency services, 
including the dependency service properties 
+(the map key holds the dependency services, and the map value holds the 
dependency service properties). 
+The Map field may be set to a final value so you can choose a Map of your 
choice (Typically a ConcurrentHashMap). 
+A ConcurrentHashMap is "weakly consistent", meaning that when traversing the 
elements, you may or may not see any concurrent 
+updates made on the map. So, take care to traverse the map using an iterator 
on the map entry set, 
+which allows to atomically lookup pairs of Dependency service/Service 
properties. </li>
+</ul>
+<h2 id="service-dependency-callbacks">Service Dependency callbacks<a 
class="headerlink" href="#service-dependency-callbacks" title="Permanent 
link">&para;</a></h2>
+<p>You can specify callbacks on the component implementation class using the 
"<code>add/change/remove/swap</code>" <code>ServiceDependencyBuilder</code> 
methods:</p>
 <div class="codehilite"><pre><span class="kn">import</span> <span 
class="nn">org.apache.felix.dm.lambda.DependencyManagerActivator</span><span 
class="o">;</span>
 
 <span class="kd">public</span> <span class="kd">class</span> <span 
class="nc">Activator</span> <span class="kd">extends</span> <span 
class="n">DependencyManagerActivator</span> <span class="o">{</span>
     <span class="nd">@Override</span>
     <span class="kd">public</span> <span class="kt">void</span> <span 
class="nf">init</span><span class="o">(</span><span 
class="n">BundleContext</span> <span class="n">ctx</span><span 
class="o">,</span> <span class="n">DependencyManager</span> <span 
class="n">dm</span><span class="o">)</span> <span class="kd">throws</span> 
<span class="n">Exception</span> <span class="o">{</span>
-        <span class="n">component</span><span class="o">(</span><span 
class="n">comp</span> <span class="o">-&gt;</span> <span 
class="n">comp</span><span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">Hello</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">withSvc</span><span class="o">(</span><span 
class="n">LogService</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span class="n">srv</span> 
<span class="o">-&gt;</span> <span class="n">srv</span><span 
class="o">.</span><span class="na">add</span><span class="o">(</span><span 
class="s">&quot;setLog&quot;</span><span class="o">)));</span>
+        <span class="n">component</span><span class="o">(</span><span 
class="n">comp</span> <span class="o">-&gt;</span> <span 
class="n">comp</span><span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">Hello</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">withSvc</span><span class="o">(</span><span 
class="n">LogService</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span class="n">svc</span> 
<span class="o">-&gt;</span> <span class="n">svc</span><span 
class="o">.</span><span class="na">add</span><span class="o">(</span><span 
class="s">&quot;setLog&quot;</span><span class="o">)));</span>
     <span class="o">}</span>
 <span class="o">}</span>
 </pre></div>
@@ -316,7 +334,7 @@ But like in the current DM API, you can
 <span class="kd">public</span> <span class="kd">class</span> <span 
class="nc">Activator</span> <span class="kd">extends</span> <span 
class="n">DependencyManagerActivator</span> <span class="o">{</span>
     <span class="nd">@Override</span>
     <span class="kd">public</span> <span class="kt">void</span> <span 
class="nf">init</span><span class="o">(</span><span 
class="n">BundleContext</span> <span class="n">ctx</span><span 
class="o">,</span> <span class="n">DependencyManager</span> <span 
class="n">dm</span><span class="o">)</span> <span class="kd">throws</span> 
<span class="n">Exception</span> <span class="o">{</span>
-        <span class="n">component</span><span class="o">(</span><span 
class="n">comp</span> <span class="o">-&gt;</span> <span 
class="n">comp</span><span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">Hello</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">withSvc</span><span class="o">(</span><span 
class="n">LogService</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span class="n">srv</span> 
<span class="o">-&gt;</span> <span class="n">srv</span><span 
class="o">.</span><span class="na">add</span><span class="o">(</span><span 
class="nl">Hello:</span><span class="o">:</span><span 
class="n">setLog</span><span class="o">)));</span>
+        <span class="n">component</span><span class="o">(</span><span 
class="n">comp</span> <span class="o">-&gt;</span> <span 
class="n">comp</span><span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">Hello</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">withSvc</span><span class="o">(</span><span 
class="n">LogService</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span class="n">svc</span> 
<span class="o">-&gt;</span> <span class="n">svc</span><span 
class="o">.</span><span class="na">add</span><span class="o">(</span><span 
class="nl">Hello:</span><span class="o">:</span><span 
class="n">setLog</span><span class="o">)));</span>
     <span class="o">}</span>
 <span class="o">}</span>
 </pre></div>
@@ -328,7 +346,7 @@ But like in the current DM API, you can
 <span class="kd">public</span> <span class="kd">class</span> <span 
class="nc">Activator</span> <span class="kd">extends</span> <span 
class="n">DependencyManagerActivator</span> <span class="o">{</span>
     <span class="nd">@Override</span>
     <span class="kd">public</span> <span class="kt">void</span> <span 
class="nf">init</span><span class="o">(</span><span 
class="n">BundleContext</span> <span class="n">ctx</span><span 
class="o">,</span> <span class="n">DependencyManager</span> <span 
class="n">dm</span><span class="o">)</span> <span class="kd">throws</span> 
<span class="n">Exception</span> <span class="o">{</span>
-        <span class="n">component</span><span class="o">(</span><span 
class="n">comp</span> <span class="o">-&gt;</span> <span 
class="n">comp</span><span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">Hello</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">withSvc</span><span class="o">(</span><span 
class="n">LogService</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span class="n">srv</span> 
<span class="o">-&gt;</span> <span class="n">srv</span><span 
class="o">.</span><span class="na">add</span><span class="o">(</span><span 
class="nl">Hello:</span><span class="o">:</span><span 
class="n">setLog</span><span class="o">).</span><span 
class="na">remove</span><span class="o">(</span><span 
class="nl">Hello:</span><span class="o">:</span><span 
class="n">unsetLog</span><span class="o">)));</span>
+        <span class="n">component</span><span class="o">(</span><span 
class="n">comp</span> <span class="o">-&gt;</span> <span 
class="n">comp</span><span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">Hello</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">withSvc</span><span class="o">(</span><span 
class="n">LogService</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span class="n">svc</span> 
<span class="o">-&gt;</span> <span class="n">svc</span><span 
class="o">.</span><span class="na">add</span><span class="o">(</span><span 
class="nl">Hello:</span><span class="o">:</span><span 
class="n">setLog</span><span class="o">).</span><span 
class="na">remove</span><span class="o">(</span><span 
class="nl">Hello:</span><span class="o">:</span><span 
class="n">unsetLog</span><span class="o">)));</span>
     <span class="o">}</span>
 <span class="o">}</span>
 </pre></div>
@@ -362,7 +380,7 @@ For example, the following example injec
     <span class="nd">@Override</span>
     <span class="kd">public</span> <span class="kt">void</span> <span 
class="nf">init</span><span class="o">(</span><span 
class="n">BundleContext</span> <span class="n">ctx</span><span 
class="o">,</span> <span class="n">DependencyManager</span> <span 
class="n">dm</span><span class="o">)</span> <span class="kd">throws</span> 
<span class="n">Exception</span> <span class="o">{</span>
         <span class="n">DependencyHandler</span> <span 
class="n">depHandler</span> <span class="o">=</span> <span class="k">new</span> 
<span class="n">DependencyHandler</span><span class="o">();</span>
-        <span class="n">component</span><span class="o">(</span><span 
class="n">comp</span> <span class="o">-&gt;</span> <span 
class="n">comp</span><span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">Hello</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">withSvc</span><span class="o">(</span><span 
class="n">LogService</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span class="n">srv</span> 
<span class="o">-&gt;</span> <span class="n">srv</span><span 
class="o">.</span><span class="na">add</span><span class="o">(</span><span 
class="n">depHandler</span><span class="o">,</span> <span 
class="s">&quot;setLog&quot;</span><span class="o">)));</span>
+        <span class="n">component</span><span class="o">(</span><span 
class="n">comp</span> <span class="o">-&gt;</span> <span 
class="n">comp</span><span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">Hello</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">withSvc</span><span class="o">(</span><span 
class="n">LogService</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span class="n">svc</span> 
<span class="o">-&gt;</span> <span class="n">svc</span><span 
class="o">.</span><span class="na">add</span><span class="o">(</span><span 
class="n">depHandler</span><span class="o">,</span> <span 
class="s">&quot;setLog&quot;</span><span class="o">)));</span>
     <span class="o">}</span>
 <span class="o">}</span>
 </pre></div>
@@ -375,7 +393,7 @@ For example, the following example injec
     <span class="nd">@Override</span>
     <span class="kd">public</span> <span class="kt">void</span> <span 
class="nf">init</span><span class="o">(</span><span 
class="n">BundleContext</span> <span class="n">ctx</span><span 
class="o">,</span> <span class="n">DependencyManager</span> <span 
class="n">dm</span><span class="o">)</span> <span class="kd">throws</span> 
<span class="n">Exception</span> <span class="o">{</span>
         <span class="n">DependencyHandler</span> <span 
class="n">depHandler</span> <span class="o">=</span> <span class="k">new</span> 
<span class="n">DependencyHandler</span><span class="o">();</span>
-        <span class="n">component</span><span class="o">(</span><span 
class="n">comp</span> <span class="o">-&gt;</span> <span 
class="n">comp</span><span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">Hello</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">withSvc</span><span class="o">(</span><span 
class="n">LogService</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span class="n">srv</span> 
<span class="o">-&gt;</span> <span class="n">srv</span><span 
class="o">.</span><span class="na">add</span><span class="o">(</span><span 
class="nl">depHandler:</span><span class="o">:</span><span 
class="n">setLog</span><span class="o">)));</span>
+        <span class="n">component</span><span class="o">(</span><span 
class="n">comp</span> <span class="o">-&gt;</span> <span 
class="n">comp</span><span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">Hello</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">withSvc</span><span class="o">(</span><span 
class="n">LogService</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span class="n">svc</span> 
<span class="o">-&gt;</span> <span class="n">svc</span><span 
class="o">.</span><span class="na">add</span><span class="o">(</span><span 
class="nl">depHandler:</span><span class="o">:</span><span 
class="n">setLog</span><span class="o">)));</span>
     <span class="o">}</span>
 <span class="o">}</span>
 </pre></div>
@@ -388,7 +406,7 @@ For example, the following example injec
     <span class="nd">@Override</span>
     <span class="kd">public</span> <span class="kt">void</span> <span 
class="nf">init</span><span class="o">(</span><span 
class="n">BundleContext</span> <span class="n">ctx</span><span 
class="o">,</span> <span class="n">DependencyManager</span> <span 
class="n">dm</span><span class="o">)</span> <span class="kd">throws</span> 
<span class="n">Exception</span> <span class="o">{</span>
         <span class="n">DependencyHandler</span> <span 
class="n">depHandler</span> <span class="o">=</span> <span class="k">new</span> 
<span class="n">DependencyHandler</span><span class="o">();</span>
-        <span class="n">component</span><span class="o">(</span><span 
class="n">comp</span> <span class="o">-&gt;</span> <span 
class="n">comp</span><span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">Hello</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">withSvc</span><span class="o">(</span><span 
class="n">LogService</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span class="n">srv</span> 
<span class="o">-&gt;</span> <span class="n">srv</span><span 
class="o">.</span><span class="na">add</span><span class="o">(</span><span 
class="nl">Hello:</span><span class="o">:</span><span 
class="n">setLog</span><span class="o">).</span><span 
class="na">add</span><span class="o">(</span><span 
class="nl">depHandler:</span><span class="o">:</span><span 
class="n">setLog</span><span class="o">)));</span>
+        <span class="n">component</span><span class="o">(</span><span 
class="n">comp</span> <span class="o">-&gt;</span> <span 
class="n">comp</span><span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">Hello</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">withSvc</span><span class="o">(</span><span 
class="n">LogService</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span class="n">svc</span> 
<span class="o">-&gt;</span> <span class="n">svc</span><span 
class="o">.</span><span class="na">add</span><span class="o">(</span><span 
class="nl">Hello:</span><span class="o">:</span><span 
class="n">setLog</span><span class="o">).</span><span 
class="na">add</span><span class="o">(</span><span 
class="nl">depHandler:</span><span class="o">:</span><span 
class="n">setLog</span><span class="o">)));</span>
     <span class="o">}</span>
 <span class="o">}</span>
 </pre></div>
@@ -525,7 +543,7 @@ what it has parsed, it will possibly add
         <span class="n">parseXml</span><span class="o">(</span><span 
class="n">conf</span><span class="o">.</span><span class="na">get</span><span 
class="o">(</span><span 
class="s">&quot;some.xml.configuration&quot;</span><span class="o">));</span>
     <span class="o">}</span>
 
-    <span class="kt">void</span> <span class="nf">init</span><span 
class="o">(</span><span class="n">Component</span> <span 
class="n">c</span><span class="o">)</span> <span class="o">{</span> <span 
class="c1">// lifecycle dm callback that allow you to add more 
dependencies</span>
+    <span class="kt">void</span> <span class="nf">init</span><span 
class="o">(</span><span class="n">Component</span> <span 
class="n">c</span><span class="o">)</span> <span class="o">{</span> <span 
class="c1">// lifecycle dm callback that allows you to add more 
dependencies</span>
         <span class="k">if</span> <span class="o">(</span><span 
class="n">xmlConfigurationRequiresEventAdmin</span><span class="o">)</span> 
<span class="o">{</span>
             <span class="n">component</span><span class="o">(</span><span 
class="n">c</span><span class="o">,</span> <span class="n">comp</span> <span 
class="o">-&gt;</span> <span class="n">comp</span><span class="o">.</span><span 
class="na">withSvc</span><span class="o">(</span><span 
class="n">EventAdmin</span><span class="o">.</span><span 
class="na">class</span><span class="o">));</span>
         <span class="o">}</span>
@@ -571,15 +589,15 @@ what it has parsed, it will possibly add
 
 
 <h2 id="creating-aspect-components">Creating Aspect Components<a 
class="headerlink" href="#creating-aspect-components" title="Permanent 
link">&para;</a></h2>
-<p>Like with the original DM API, you can create aspects (service 
interceptors), using the "<code>aspect</code>" factory method.
+<p>Like with the original DM API, you can create a chain of aspects (service 
interceptors) ordered by a ranking attribute, using the "<code>aspect</code>" 
factory method.
 This method accepts in argument a ServiceAspectBuilder.</p>
 <p>Code example which provides a "LogService" aspect that performs 
spell-checking of each log message. The aspect decorates a LogService. 
-The aspect also depends on an Dictionary service that is internally used to 
perform log spell checking. 
-The LogService and Dictionary services are injected in the aspect 
implementation using reflection on class 
+The aspect also depends on a DictionaryService that is internally used to 
perform log spell checking. 
+The LogService and DictionaryService services are injected in the aspect 
implementation using reflection on class 
 fields:</p>
 <div class="codehilite"><pre><span class="kd">public</span> <span 
class="kd">class</span> <span class="nc">Activator</span> <span 
class="kd">extends</span> <span class="n">DependencyManagerActivator</span> 
<span class="o">{</span>
     <span class="kd">public</span> <span class="kt">void</span> <span 
class="nf">init</span><span class="o">(</span><span 
class="n">BundleContext</span> <span class="n">ctx</span><span 
class="o">,</span> <span class="n">DependencyManager</span> <span 
class="n">dm</span><span class="o">)</span> <span class="kd">throws</span> 
<span class="n">Exception</span> <span class="o">{</span> 
-        <span class="n">aspect</span><span class="o">(</span><span 
class="n">LogService</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span class="o">(</span><span 
class="n">ServiceAspectBuilder</span> <span class="n">asp</span><span 
class="o">)</span> <span class="o">-&gt;</span> <span class="n">asp</span><span 
class="o">.</span><span class="na">impl</span><span class="o">(</span><span 
class="n">SpellCheckLogAspect</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">rank</span><span class="o">(</span><span class="mi">10</span><span 
class="o">).</span><span class="na">withSvc</span><span class="o">(</span><span 
class="n">Dictionary</span><span class="o">.</span><span 
class="na">class</span><span class="o">));</span>
+        <span class="n">aspect</span><span class="o">(</span><span 
class="n">LogService</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span class="o">(</span><span 
class="n">ServiceAspectBuilder</span> <span class="n">asp</span><span 
class="o">)</span> <span class="o">-&gt;</span> <span class="n">asp</span><span 
class="o">.</span><span class="na">impl</span><span class="o">(</span><span 
class="n">SpellCheckLogAspect</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">rank</span><span class="o">(</span><span class="mi">10</span><span 
class="o">).</span><span class="na">withSvc</span><span class="o">(</span><span 
class="n">DictionaryService</span><span class="o">.</span><span 
class="na">class</span><span class="o">));</span>
     <span class="o">}</span>
 <span class="o">}</span>
 </pre></div>
@@ -588,19 +606,19 @@ fields:</p>
 <p>Same more concise example which does not declare the type of the lambda 
builder argument:</p>
 <div class="codehilite"><pre><span class="kd">public</span> <span 
class="kd">class</span> <span class="nc">Activator</span> <span 
class="kd">extends</span> <span class="n">DependencyManagerActivator</span> 
<span class="o">{</span>
     <span class="kd">public</span> <span class="kt">void</span> <span 
class="nf">init</span><span class="o">(</span><span 
class="n">BundleContext</span> <span class="n">ctx</span><span 
class="o">,</span> <span class="n">DependencyManager</span> <span 
class="n">dm</span><span class="o">)</span> <span class="kd">throws</span> 
<span class="n">Exception</span> <span class="o">{</span> 
-        <span class="n">aspect</span><span class="o">(</span><span 
class="n">LogService</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span class="n">asp</span> 
<span class="o">-&gt;</span> <span class="n">asp</span><span 
class="o">.</span><span class="na">impl</span><span class="o">(</span><span 
class="n">SpellCheckLogAspect</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">rank</span><span class="o">(</span><span class="mi">10</span><span 
class="o">).</span><span class="na">withSvc</span><span class="o">(</span><span 
class="n">Dictionary</span><span class="o">.</span><span 
class="na">class</span><span class="o">));</span>
+        <span class="n">aspect</span><span class="o">(</span><span 
class="n">LogService</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span class="n">asp</span> 
<span class="o">-&gt;</span> <span class="n">asp</span><span 
class="o">.</span><span class="na">impl</span><span class="o">(</span><span 
class="n">SpellCheckLogAspect</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">rank</span><span class="o">(</span><span class="mi">10</span><span 
class="o">).</span><span class="na">withSvc</span><span class="o">(</span><span 
class="n">DictionaryService</span><span class="o">.</span><span 
class="na">class</span><span class="o">));</span>
     <span class="o">}</span>
 <span class="o">}</span>
 </pre></div>
 
 
-<p>Same example, but using callbacks for injecting LogService and Dictionary 
services in the aspect implementation class:</p>
+<p>Same example, but using callbacks for injecting LogService and 
DictionaryService in the aspect implementation class:</p>
 <div class="codehilite"><pre><span class="kd">public</span> <span 
class="kd">class</span> <span class="nc">Activator</span> <span 
class="kd">extends</span> <span class="n">DependencyManagerActivator</span> 
<span class="o">{</span>
     <span class="kd">public</span> <span class="kt">void</span> <span 
class="nf">init</span><span class="o">(</span><span 
class="n">BundleContext</span> <span class="n">ctx</span><span 
class="o">,</span> <span class="n">DependencyManager</span> <span 
class="n">dm</span><span class="o">)</span> <span class="kd">throws</span> 
<span class="n">Exception</span> <span class="o">{</span> 
        <span class="n">aspect</span><span class="o">(</span><span 
class="n">LogService</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span class="n">asp</span> 
<span class="o">-&gt;</span> <span class="n">asp</span>
           <span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">SpellCheckLogAspect</span><span 
class="o">.</span><span class="na">class</span><span class="o">).</span><span 
class="na">rank</span><span class="o">(</span><span class="mi">10</span><span 
class="o">)</span>
           <span class="o">.</span><span class="na">add</span><span 
class="o">(</span><span class="nl">SpellCheckLogAspect:</span><span 
class="o">:</span><span class="n">setLogService</span><span class="o">)</span>
-          <span class="o">.</span><span class="na">withSvc</span><span 
class="o">(</span><span class="n">Dictionary</span><span 
class="o">.</span><span class="na">class</span><span class="o">,</span> <span 
class="n">svc</span> <span class="o">-&gt;</span> <span 
class="n">svc</span><span class="o">.</span><span class="na">add</span><span 
class="o">(</span><span class="nl">SpellCheckLogAspect:</span><span 
class="o">:</span><span class="n">setDictionary</span><span 
class="o">)));</span>
+          <span class="o">.</span><span class="na">withSvc</span><span 
class="o">(</span><span class="n">DictionaryService</span><span 
class="o">.</span><span class="na">class</span><span class="o">,</span> <span 
class="n">svc</span> <span class="o">-&gt;</span> <span 
class="n">svc</span><span class="o">.</span><span class="na">add</span><span 
class="o">(</span><span class="nl">SpellCheckLogAspect:</span><span 
class="o">:</span><span class="n">setDictionary</span><span 
class="o">)));</span>
     <span class="o">}</span>
 <span class="o">}</span>
 </pre></div>
@@ -628,6 +646,37 @@ can be used to construct a DM adapter co
 </pre></div>
 
 
+<h2 id="creating-factory-configuration-adapter-components">Creating Factory 
Configuration Adapter Components<a class="headerlink" 
href="#creating-factory-configuration-adapter-components" title="Permanent 
link">&para;</a></h2>
+<p>A Factory Configuration Adapter allows to create many instances of the same 
service, each time a configuration instance is created for a given factory pid.
+To declare a factory pid configuration adapter, use the 
<code>factoryPid</code> method available from the DependencyManagerActivator 
class and pass to it
+a lambda for the FactoryPidAdapterBuilder argument:</p>
+<p>Example that defines a factory configuration adapter service for the 
"foo.bar" factory pid. For each factory pid instance, an instance of the 
DictionaryImpl component will be created:</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span 
class="kd">class</span> <span class="nc">Activator</span> <span 
class="kd">extends</span> <span class="n">DependencyManagerActivator</span> 
<span class="o">{</span>
+    <span class="kd">public</span> <span class="kt">void</span> <span 
class="nf">init</span><span class="o">(</span><span 
class="n">BundleContext</span> <span class="n">ctx</span><span 
class="o">,</span> <span class="n">DependencyManager</span> <span 
class="n">dm</span><span class="o">)</span> <span class="kd">throws</span> 
<span class="n">Exception</span> <span class="o">{</span> 
+       <span class="n">factoryPidAdapter</span><span class="o">(</span><span 
class="n">adapter</span> <span class="o">-&gt;</span> <span 
class="n">adapter</span>
+          <span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">DictionaryImpl</span><span 
class="o">.</span><span class="na">class</span><span class="o">).</span><span 
class="na">factoryPid</span><span class="o">(</span><span 
class="s">&quot;foo.bar&quot;</span><span class="o">).</span><span 
class="na">propagate</span><span class="o">().</span><span 
class="na">update</span><span class="o">(</span><span 
class="nl">ServiceImpl:</span><span class="o">:</span><span 
class="n">updated</span><span class="o">)</span>
+          <span class="o">.</span><span class="na">withSvc</span><span 
class="o">(</span><span class="n">LogService</span><span 
class="o">.</span><span class="na">class</span><span class="o">,</span> <span 
class="n">log</span> <span class="o">-&gt;</span> <span 
class="n">log</span><span class="o">.</span><span 
class="na">optional</span><span class="o">()));</span>
+    <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Example that defines a factory configuration adapter using a user defined 
configuration type (the pid is by default assumed to match the fqdn of the 
configuration type):</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span 
class="kd">interface</span> <span class="nc">DictionaryConfiguration</span> 
<span class="o">{</span>
+    <span class="kd">public</span> <span class="n">String</span> <span 
class="nf">getLanguage</span><span class="o">();</span>
+    <span class="kd">public</span> <span class="n">List</span><span 
class="o">&lt;</span><span class="n">String</span><span class="o">&gt;</span> 
<span class="n">getWords</span><span class="o">();</span>
+<span class="o">}</span>
+
+<span class="kd">public</span> <span class="kd">class</span> <span 
class="nc">Activator</span> <span class="kd">extends</span> <span 
class="n">DependencyManagerActivator</span> <span class="o">{</span>
+    <span class="kd">public</span> <span class="kt">void</span> <span 
class="nf">init</span><span class="o">(</span><span 
class="n">BundleContext</span> <span class="n">ctx</span><span 
class="o">,</span> <span class="n">DependencyManager</span> <span 
class="n">dm</span><span class="o">)</span> <span class="kd">throws</span> 
<span class="n">Exception</span> <span class="o">{</span> 
+        <span class="n">factoryPidAdapter</span><span class="o">(</span><span 
class="n">adapter</span> <span class="o">-&gt;</span> <span 
class="n">adapter</span>
+            <span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">DictionaryImpl</span><span 
class="o">.</span><span class="na">class</span><span class="o">).</span><span 
class="na">factoryPid</span><span class="o">(</span><span 
class="s">&quot;foo.bar&quot;</span><span class="o">).</span><span 
class="na">propagate</span><span class="o">().</span><span 
class="na">update</span><span class="o">(</span><span 
class="n">DictionaryConfiguration</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span 
class="nl">ServiceImpl:</span><span class="o">:</span><span 
class="n">updated</span><span class="o">)</span>               
+            <span class="o">.</span><span class="na">withSvc</span><span 
class="o">(</span><span class="n">LogService</span><span 
class="o">.</span><span class="na">class</span><span class="o">,</span> <span 
class="n">log</span> <span class="o">-&gt;</span> <span 
class="n">log</span><span class="o">.</span><span 
class="na">optional</span><span class="o">()));</span>
+    <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
 <h2 id="creating-a-bundle-adapter-component">Creating a Bundle Adapter 
component<a class="headerlink" href="#creating-a-bundle-adapter-component" 
title="Permanent link">&para;</a></h2>
 <p>A Bundle Adapter is used to create a Component when a bundle that matches a 
given filter is found.
 To build a DM adapter, you can use the "<code>bundleAdapter</code>" factory 
method: it takes in argument a consumer of a
@@ -636,18 +685,14 @@ BundleAdapterBuilder object, which is us
 <div class="codehilite"><pre><span class="kd">public</span> <span 
class="kd">class</span> <span class="nc">Activator</span> <span 
class="kd">extends</span> <span class="n">DependencyManagerActivator</span> 
<span class="o">{</span>
     <span class="kd">public</span> <span class="kt">void</span> <span 
class="nf">init</span><span class="o">(</span><span 
class="n">BundleContext</span> <span class="n">ctx</span><span 
class="o">,</span> <span class="n">DependencyManager</span> <span 
class="n">dm</span><span class="o">)</span> <span class="kd">throws</span> 
<span class="n">Exception</span> <span class="o">{</span> 
        <span class="n">bundleAdapter</span><span class="o">(</span><span 
class="n">adapt</span> <span class="o">-&gt;</span> <span class="n">adapt</span>
-           <span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">BundleAdapterImpl</span><span 
class="o">.</span><span class="na">class</span><span class="o">)</span>
-           <span class="o">.</span><span class="na">provides</span><span 
class="o">(</span><span class="n">BundleAdapter</span><span 
class="o">.</span><span class="na">class</span><span class="o">)</span>
-           <span class="o">.</span><span class="na">mask</span><span 
class="o">(</span><span class="n">Bundle</span><span class="o">.</span><span 
class="na">INSTALLED</span> <span class="o">|</span> <span 
class="n">Bundle</span><span class="o">.</span><span class="na">RESOLVED</span> 
<span class="o">|</span> <span class="n">Bundle</span><span 
class="o">.</span><span class="na">ACTIVE</span><span class="o">)</span>
+           <span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">BundleAdapterImpl</span><span 
class="o">.</span><span class="na">class</span><span class="o">).</span><span 
class="na">provides</span><span class="o">(</span><span 
class="n">BundleAdapter</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">mask</span><span class="o">(</span><span 
class="n">Bundle</span><span class="o">.</span><span 
class="na">INSTALLED</span><span class="o">|</span><span 
class="n">Bundle</span><span class="o">.</span><span 
class="na">RESOLVED</span><span class="o">|</span><span 
class="n">Bundle</span><span class="o">.</span><span 
class="na">ACTIVE</span><span class="o">)</span>               
            <span class="o">.</span><span class="na">add</span><span 
class="o">(</span><span class="nl">BundleAdapterImpl:</span><span 
class="o">:</span><span class="n">bundleStarted</span><span class="o">)</span>
-           <span class="o">.</span><span class="na">withSvc</span><span 
class="o">(</span><span class="n">LogService</span><span 
class="o">.</span><span class="na">class</span><span class="o">,</span> <span 
class="s">&quot;(vendor=apache)&quot;</span><span class="o">)</span>
-           <span class="o">.</span><span class="na">withSvc</span><span 
class="o">(</span><span class="n">EventAdmin</span><span 
class="o">.</span><span class="na">class</span><span class="o">,</span> <span 
class="n">ConfigurationAdmin</span><span class="o">.</span><span 
class="na">class</span><span class="o">));</span>
+           <span class="o">.</span><span class="na">withSvc</span><span 
class="o">(</span><span class="n">LogService</span><span 
class="o">.</span><span class="na">class</span><span class="o">,</span> <span 
class="s">&quot;(vendor=apache)&quot;</span><span class="o">));</span>          
    
     <span class="o">}</span>
 <span class="o">}</span>
 </pre></div>
 
 
-<p>Notice that the adapter also depends on three services (LogService, 
EventAdmin, and ConfigurationAdmin services).</p>
 <h2 id="completablefuture-dependency">CompletableFuture dependency.<a 
class="headerlink" href="#completablefuture-dependency" title="Permanent 
link">&para;</a></h2>
 <p>The new library provides a new feature which allows your component to 
depend on the result of a jdk8 <code>CompletableFuture</code>.
 CompletableFuture java8 class provides an asynchronous event-driven model and 
you can now define dependencies on any asynchronous events,
@@ -669,7 +714,7 @@ be injected (using DM, optional service
     <span class="nd">@Override</span>
     <span class="kd">public</span> <span class="kt">void</span> <span 
class="nf">init</span><span class="o">(</span><span 
class="n">BundleContext</span> <span class="n">ctx</span><span 
class="o">,</span> <span class="n">DependencyManager</span> <span 
class="n">dm</span><span class="o">)</span> <span class="kd">throws</span> 
<span class="n">Exception</span> <span class="o">{</span>
         <span class="n">component</span><span class="o">(</span><span 
class="n">comp</span> <span class="o">-&gt;</span> <span 
class="n">comp</span><span class="o">.</span><span class="na">impl</span><span 
class="o">(</span><span class="n">Pojo</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">provides</span><span class="o">(</span><span 
class="n">PojoService</span><span class="o">)</span>
-           <span class="o">.</span><span class="na">withCnf</span><span 
class="o">(</span><span class="s">&quot;foo.pid&quot;</span><span 
class="o">).</span><span class="na">withSvc</span><span class="o">(</span><span 
class="n">HttpClient</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">withSvc</span><span class="o">(</span><span 
class="n">Tracked</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span class="n">srv</span> 
<span class="o">-&gt;</span> <span class="n">srv</span><span 
class="o">.</span><span class="na">optional</span><span 
class="o">().</span><span class="na">add</span><span class="o">(</span><span 
class="nl">Pojo:</span><span class="o">:</span><span 
class="n">bindTracked</span><span class="o">));</span>
+           <span class="o">.</span><span class="na">withCnf</span><span 
class="o">(</span><span class="s">&quot;foo.pid&quot;</span><span 
class="o">).</span><span class="na">withSvc</span><span class="o">(</span><span 
class="n">HttpClient</span><span class="o">.</span><span 
class="na">class</span><span class="o">).</span><span 
class="na">withSvc</span><span class="o">(</span><span 
class="n">Tracked</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span class="n">svc</span> 
<span class="o">-&gt;</span> <span class="n">svc</span><span 
class="o">.</span><span class="na">optional</span><span 
class="o">().</span><span class="na">add</span><span class="o">(</span><span 
class="nl">Pojo:</span><span class="o">:</span><span 
class="n">bindTracked</span><span class="o">));</span>
     <span class="o">}</span>
 <span class="o">}</span>
 </pre></div>
@@ -716,7 +761,7 @@ injected in the "bindTracked" method:</p
 
 
 <p>So, using the Future Dependency we can nicely reuse the jdk 
CompletableFuture as a required dependency. Without using the FutureDependency
-on the CompletableFuture returned by the HttpClient, we would then have to 
manually register our service using bundleContext.registerService(), and we 
+on the CompletableFuture returned by the HttpClient, we would then have to 
manually register our service using bundleContext.registerService (once the web 
page has been downloaded), and we 
 would then have to check if the webpage has been downloaded each time a 
Tracked service is injected. And in case the page is not available, we would 
 then have to cache the injected Tracked service and process it later, once the 
page has been downloaded.</p>
 <p>Also, notice that when the page is injected in the setPage() method, you 
absolutely don't need to deal with
@@ -781,7 +826,7 @@ http proxy.</p>
 <h2 id="javadoc">Javadoc<a class="headerlink" href="#javadoc" title="Permanent 
link">&para;</a></h2>
 <p>You can find the javadoc for the new Dependency Manager Lambda library <a 
href="../../../../apidocs/">here</a>.</p>
       <div class="timestamp" style="margin-top: 30px; font-size: 80%; 
text-align: right;">
-        Rev. 1731482 by pderop on Sat, 20 Feb 2016 21:53:18 +0000
+        Rev. 1731996 by pderop on Wed, 24 Feb 2016 00:14:11 +0000
       </div>
       <div class="trademarkFooter"> 
         Apache Felix, Felix, Apache, the Apache feather logo, and the Apache 
Felix project


Reply via email to