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">-></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">-></span> <span
class="n">srv</span><span class="o">.</span><span class="na">filter</span><span
class="o">(</span><span class="s">"(p1=v1)"</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">-></span> <span
class="n">svc</span><span class="o">.</span><span class="na">filter</span><span
class="o">(</span><span class="s">"(p1=v1)"</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">¶</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<ServiceDependencyBuilder></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">¶</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<ServiceDependencyBuilder></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<
<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">-></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">-></span> <span
class="n">srv</span><span class="o">.</span><span class="na">filter</span><span
class="o">(</span><span class="s">"(vendor=apache)"</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">-></span> <span
class="n">svc</span><span class="o">.</span><span class="na">filter</span><span
class="o">(</span><span class="s">"(vendor=apache)"</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">-></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">-></span> <span class="n">srv</span><span
class="o">.</span><span class="na">filter</span><span class="o">(</span><span
class="s">"(vendor=apache)"</span><span class="o">)));</span>
+ <span class="n">component</span><span class="o">(</span><span
class="n">comp</span> <span class="o">-></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">-></span> <span class="n">svc</span><span
class="o">.</span><span class="na">filter</span><span class="o">(</span><span
class="s">"(vendor=apache)"</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">¶</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<T></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<K,V></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">¶</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">-></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">-></span> <span class="n">srv</span><span
class="o">.</span><span class="na">add</span><span class="o">(</span><span
class="s">"setLog"</span><span class="o">)));</span>
+ <span class="n">component</span><span class="o">(</span><span
class="n">comp</span> <span class="o">-></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">-></span> <span class="n">svc</span><span
class="o">.</span><span class="na">add</span><span class="o">(</span><span
class="s">"setLog"</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">-></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">-></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">-></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">-></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">-></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">-></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">-></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">-></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">-></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">-></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">"setLog"</span><span class="o">)));</span>
+ <span class="n">component</span><span class="o">(</span><span
class="n">comp</span> <span class="o">-></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">-></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">"setLog"</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">-></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">-></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">-></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">-></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">-></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">-></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">-></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">-></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">"some.xml.configuration"</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">-></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">¶</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">-></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">-></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">-></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">-></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">-></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">-></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">-></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">¶</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">-></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">"foo.bar"</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">-></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"><</span><span class="n">String</span><span class="o">></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">-></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">"foo.bar"</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">-></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">¶</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">-></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">"(vendor=apache)"</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">"(vendor=apache)"</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">¶</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">-></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">"foo.pid"</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">-></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">"foo.pid"</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">-></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">¶</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