dm-lambda.html

buildbot Sun, 28 Feb 2016 12:04:06 -0800

Author: buildbot
Date: Sun Feb 28 20:03:21 2016
New Revision: 981348

Log:
Staging update by buildbot for felix


Modified:
    websites/staging/felix/trunk/content/   (props changed)
    
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/dm-lambda.html

Propchange: websites/staging/felix/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Sun Feb 28 20:03:21 2016
@@ -1 +1 @@
-1732781
+1732786

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
 Sun Feb 28 20:03:21 2016
@@ -90,7 +90,6 @@ h2:hover > .headerlink, h3:hover > .head
 h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, 
h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, 
dt:hover > .elementid-permalink { visibility: visible }</style>
 <hr />
 <p><strong>Welcome to Felix Dependency Manager Lambda.</strong></p>
-<p>(TODO: update this document in order to explain that dependencies are 
optional by default, and not required).</p>
 <h2 id="introduction">Introduction<a class="headerlink" href="#introduction" 
title="Permanent link">&para;</a></h2>
 <p>Since the R7 version, a new dm-lambda library has been introduced in the DM 
distribution. This new library allows to programmatically declare OSGi 
components
 using a new style based on java8 lambda expressions and other goodies like 
method references.</p>
@@ -153,19 +152,18 @@ 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">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">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">required</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>
 
         <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">ServiceProviderImpl</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">ServiceProvider</span><span 
class="o">.</span><span class="na">class</span><span class="o">,</span> <span 
class="n">p1</span> <span class="o">-&gt;</span> <span 
class="s">&quot;v1&quot;</span><span class="o">,</span> <span 
class="n">p2</span> <span class="o">-&gt;</span> <span 
class="mi">123</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">EventAdmin</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="kc">true</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">EventAdmin</span><span class="o">.</span><span 
class="na">class</span><span class="o">));</span>
 <span class="o">}</span>
 </pre></div>
 
 
-<p>(all dependencies are required by default, if they are not explicitly 
declared as optional or required).</p>
 <h1 id="principle">Principle<a class="headerlink" href="#principle" 
title="Permanent link">&para;</a></h1>
 <p>The new API is provided by the 
<code>org.apache.felix.dependencymanager.lambda.jar</code> bundle. The 
following builders are currently supported:</p>
 <ul>
@@ -196,7 +194,7 @@ for dm-lambda activators:</p>
 </pre></div>
 
 
-<p>The <code>component()</code> method returns a <code>ComponentBuilder</code> 
and the call to <code>build</code> at the end of the call chain returns the 
actual DM Component object.</p>
+<p>The <code>component()</code> method returns a <code>ComponentBuilder</code> 
and the call to <code>build</code> at the end of the method calls chain returns 
the actual DM Component object.</p>
 <p>Here is a shorter version:</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.Component</span><span class="o">;</span>
@@ -241,9 +239,16 @@ The constructed Component is then automa
 </pre></div>
 
 
+<h2 id="dependency-default-mode-required-or-optional">Dependency default mode 
(required or optional ?)<a class="headerlink" 
href="#dependency-default-mode-required-or-optional" title="Permanent 
link">&para;</a></h2>
+<p>When you declare a dependency without explicitly invoking 
<code>optional()</code>, <code>required()</code>, or 
<code>required(boolean)</code>, then by default,
+the dependency is assumed to be optional. This is in line with the behavior of 
the Dependency Manager API.</p>
+<p>Now, you can change this default behavior by configuring the 
"<code>org.apache.felix.dependencymanager.lambda.defaultRequiredDependency</code>"
+system property. This property can be set with a list of java package prefixes 
(comma separated).
+When a component implementation class starts with one of the package prefixes 
specified in the above property, then dependencies will be 
+assumed to be required by default.</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 ...):
+Such methods accept 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>
@@ -272,31 +277,31 @@ Unavailable optional dependencies are in
 </pre></div>
 
 
-<p>If you depend on multiple services (without filters), you can declare the 
services in one shot like this
-(the dependencies will be injected in compatible class fields, by 
reflection):</p>
-<div class="codehilite"><pre><span class="kn">import</span> <span 
class="nn">org.apache.felix.dm.lambda.DependencyManagerActivator</span><span 
class="o">;</span>
+<p>When injecting services in class fields (auto config mode), there are 
shotcuts that avoid using a lambda when defining a service dependency.
+These shortcuts are available from the ComponentBuilder interface.</p>
+<p>Examples:</p>
+<h4 
id="declaring-multiple-auto-config-dependencies-in-one-shot-using-varargs-of-interfaces">Declaring
 multiple auto config dependencies in one shot (using varargs of interfaces):<a 
class="headerlink" 
href="#declaring-multiple-auto-config-dependencies-in-one-shot-using-varargs-of-interfaces"
 title="Permanent link">&para;</a></h4>
+<div class="codehilite"><pre><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">ConfigurationAdmin</span><span class="o">.</span><span 
class="na">class</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">MetatypeService</span><span class="o">.</span><span 
class="na">class</span><span class="o">));</span>
+</pre></div>
 
-<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="c1">// using a varargs of service dependencies ...</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">EventAdmin</span><span class="o">.</span><span 
class="na">class</span><span class="o">));</span> 
-    <span class="o">}</span>
-<span class="o">}</span>
+
+<h4 
id="declaring-multiple-auto-config-dependencies-in-one-shot-with-a-required-flag">Declaring
 multiple auto config dependencies in one shot with a <code>required</code> 
flag:<a class="headerlink" 
href="#declaring-multiple-auto-config-dependencies-in-one-shot-with-a-required-flag"
 title="Permanent link">&para;</a></h4>
+<div class="codehilite"><pre><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="kc">true</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="n">EventAdmin</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span 
class="n">MetatypeService</span><span class="o">.</span><span 
class="na">class</span><span class="o">));</span>
 </pre></div>
 
 
-<p>When you want to inject a service in a class field, but using a filter, you 
can also define a one-liner 
-dependency that is not needing a ServiceDependencyBuilder lambda:</p>
-<div class="codehilite"><pre><span class="kn">import</span> <span 
class="nn">org.apache.felix.dm.lambda.DependencyManagerActivator</span><span 
class="o">;</span>
+<h4 id="declaring-an-autoconfig-dependency-with-a-required-flag">Declaring an 
autoconfig dependency with a <code>required</code> flag:<a class="headerlink" 
href="#declaring-an-autoconfig-dependency-with-a-required-flag" 
title="Permanent link">&para;</a></h4>
+<div class="codehilite"><pre><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">ConfigurationAdmin</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span 
class="kc">true</span><span class="o">));</span>
+</pre></div>
 
-<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="c1">// using a varargs of service dependencies ...</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="s">&quot;(vendor=apache)&quot;</span><span class="o">));</span> 
-    <span class="o">}</span>
-<span class="o">}</span>
+
+<h4 
id="declaring-an-autoconfig-dependency-with-a-filter-and-required-flag">Declaring
 an autoconfig dependency with a <code>filter</code> and <code>required</code> 
flag:<a class="headerlink" 
href="#declaring-an-autoconfig-dependency-with-a-filter-and-required-flag" 
title="Permanent link">&para;</a></h4>
+<div class="codehilite"><pre><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">ConfigurationAdmin</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="kc">true</span><span class="o">));</span>
+</pre></div>
+
+
+<h4 
id="declaring-a-autoconfig-dependency-with-a-filter-an-explicit-class-field-and-required-flag">Declaring
 a autoconfig dependency with a <code>filter</code>, an explicit class field, 
and <code>required</code> flag:<a class="headerlink" 
href="#declaring-a-autoconfig-dependency-with-a-filter-an-explicit-class-field-and-required-flag"
 title="Permanent link">&para;</a></h4>
+<div class="codehilite"><pre><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">ConfigurationAdmin</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="s">&quot;configadmin&quot;</span><span class="o">,</span> <span 
class="kc">true</span><span class="o">));</span>
 </pre></div>
 
 
@@ -467,26 +472,24 @@ As proxies are injected, no implementati
 <li>for other interface types that are treated as configuration type a 
null-object is returned. </li>
 </ul>
 <h3 id="multiple-ways-to-define-a-configuration-dependency">multiple ways to 
define a configuration dependency<a class="headerlink" 
href="#multiple-ways-to-define-a-configuration-dependency" title="Permanent 
link">&para;</a></h3>
-<p>You can first pass a configuration pid to the <code>withCnf</code> 
method:</p>
+<p>You can first pass a configuration pid to the <code>withCnf</code> method. 
In this example, the Hello component has an "<code>updated(Dictionary 
properties)</code>" method called when configuration is available or 
updated.</p>
 <div class="codehilite"><pre><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">withCnf</span><span class="o">(</span><span 
class="s">&quot;my.pid&quot;</span><span class="o">))</span>
 </pre></div>
 
 
-<p>The above example assumes that your Hello component has an 
"<code>updated(Dictionary properties)</code>" method and will call it when 
configuration is available or updated.</p>
-<p>You can pass a "<code>configuration type</code>" to the 
<code>withCnf</code> method:</p>
+<p>You can pass a "<code>configuration type</code>" to the 
<code>withCnf</code> method. The pid is assumed to be the fqdn of the type 
passed to the <code>withCnf</code> method, and the callback is assumed to be 
"<code>updated</code>"
+and to accept as argument an implementation of the specified configuration 
type:</p>
 <div class="codehilite"><pre><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">withCnf</span><span class="o">(</span><span 
class="n">MyConfiguration</span><span class="o">.</span><span 
class="na">class</span><span class="o">))</span>
 </pre></div>
 
 
-<p>In the above example, the pid is assumed to be the fqdn of the type passed 
to the <code>withCnf</code> method, and the callback is assumed to be 
"<code>updated</code>"
-and to accept as argument an implementation of the specified configuration 
type.</p>
 <p>You can define the updated callback method explicitly using a 
ConfigurationDependencyBuilder lambda that you can pass to the 
"<code>withCnf</code>"
 method:</p>
 <div class="codehilite"><pre><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">withCnf</span><span class="o">((</span><span 
class="n">ConfigurationDependencyBuilder</span> <span class="n">cnf</span><span 
class="o">)</span> <span class="o">-&gt;</span> <span class="n">cnf</span><span 
class="o">.</span><span class="na">pid</span><span class="o">(</span><span 
class="s">&quot;my.pid&quot;</span><span class="o">).</span><span 
class="na">update</span><span class="o">(</span><span 
class="s">&quot;modified&quot;</span><span class="o">)));</span>
 </pre></div>
 
 
-<p>shorter version which does not declare the type of the lambda passed to the 
<code>withCnf</code> method:</p>
+<p>Here is shorter version which does not declare the type of the lambda 
passed to the <code>withCnf</code> method:</p>
 <div class="codehilite"><pre><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">withCnf</span><span class="o">(</span><span class="n">cnf</span> 
<span class="o">-&gt;</span> <span class="n">cnf</span><span 
class="o">.</span><span class="na">pid</span><span class="o">(</span><span 
class="s">&quot;my.pid&quot;</span><span class="o">).</span><span 
class="na">update</span><span class="o">(</span><span 
class="s">&quot;modified&quot;</span><span class="o">)));</span>
 </pre></div>
 
@@ -496,7 +499,7 @@ method:</p>
 </pre></div>
 
 
-<p>And finally, you can define a configuration type, and callback using a 
method reference. Here, the updated callback has to take 
+<p>And finally, you can define a configuration type, and a callback using a 
method reference. Here, the updated callback has to take 
 in argument the configuration type parameter (the pid is assumed to be the 
fqdn of the configuration type):</p>
 <div class="codehilite"><pre><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">withCnf</span><span class="o">(</span><span class="n">cnf</span> 
<span class="o">-&gt;</span> <span class="n">cnf</span><span 
class="o">.</span><span class="na">update</span><span class="o">(</span><span 
class="n">MyConfiguration</span><span class="o">.</span><span 
class="na">class</span><span class="o">,</span> <span 
class="nl">Hello:</span><span class="o">:</span><span 
class="n">modified</span><span class="o">)));</span>
 
@@ -643,6 +646,48 @@ what it has parsed, it will possibly add
 </pre></div>
 
 
+<h2 id="component-lifecycle-callbacks">Component Lifecycle Callbacks<a 
class="headerlink" href="#component-lifecycle-callbacks" title="Permanent 
link">&para;</a></h2>
+<p>Like with DM API, default lifecycle callbacks are the following:</p>
+<ul>
+<li>"init": the method is called on the component implementation class(es) 
once all required dependencies declared in the Activator 
+have been injected. This method can then be used to possibly add more 
dependencies dynamically.</li>
+<li>"start": the method is called on the component implementation class(es) 
once all required dependencies (including the ones added 
+from the "init" callback) have been injected. Then the optional dependency 
callbacks are invoked (after the start callback).</li>
+<li>"stop": the method is called on the component implementation class(es) 
when some required dependencies are being lost
+or when the component's bundle is stopping.</li>
+<li>"destroy": the component is destroyed and may be re-created and 
re-initialized in case some required dependencies comes up again.</li>
+</ul>
+<p>You can change the callback names using the "init"/"start"/"stop"/"destroy" 
methods from the ComponentBuilder interface. For example:</p>
+<div class="codehilite"><pre><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="o">.</span><span class="na">init</span><span 
class="o">(</span><span class="s">&quot;initialize&quot;</span><span 
class="o">)</span>
+    <span class="o">.</span><span class="na">start</span><span 
class="o">(</span><span class="s">&quot;activate&quot;</span><span 
class="o">)</span>
+    <span class="o">.</span><span class="na">stop</span><span 
class="o">(</span><span class="s">&quot;deactivate&quot;</span><span 
class="o">)</span>
+    <span class="o">.</span><span class="na">destroy</span><span 
class="o">(</span><span class="s">&quot;shutdown&quot;</span><span 
class="o">));</span>
+</pre></div>
+
+
+<p>Same example, but with some specific callback instance on which the 
callback should be invoked:</p>
+<div class="codehilite"><pre><span class="n">CallbackHandler</span> <span 
class="n">handler</span> <span class="p">=</span> <span class="n">new</span> 
<span class="n">CallbackHandler</span><span class="p">();</span>
+<span class="n">component</span><span class="p">(</span><span 
class="n">comp</span> <span class="o">-&gt;</span> <span 
class="n">comp</span><span class="p">.</span><span class="n">impl</span><span 
class="p">(</span><span class="n">Pojo</span><span class="p">.</span><span 
class="n">class</span><span class="p">)</span>
+    <span class="p">.</span><span class="n">init</span><span 
class="p">(</span><span class="n">handler</span><span class="p">,</span> 
&quot;<span class="n">initialize</span>&quot;<span class="p">)</span>
+    <span class="p">.</span><span class="n">start</span><span 
class="p">(</span><span class="n">handler</span><span class="p">,</span> 
&quot;<span class="n">activate</span>&quot;<span class="p">)</span>
+    <span class="p">.</span><span class="n">stop</span><span 
class="p">(</span><span class="n">handler</span><span class="p">,</span> 
&quot;<span class="n">deactivate</span>&quot;<span class="p">)</span>
+    <span class="p">.</span><span class="n">destroy</span><span 
class="p">(</span><span class="n">handler</span><span class="p">,</span> 
&quot;<span class="n">shutdown</span>&quot;<span class="p">));</span>
+</pre></div>
+
+
+<p>When using callback instances, you can also use method references using the 
callback instance object:</p>
+<div class="codehilite"><pre><span class="n">CallbackHandler</span> <span 
class="n">handler</span> <span class="p">=</span> <span class="n">new</span> 
<span class="n">CallbackHandler</span><span class="p">();</span>
+<span class="n">component</span><span class="p">(</span><span 
class="n">comp</span> <span class="o">-&gt;</span> <span 
class="n">comp</span><span class="p">.</span><span class="n">impl</span><span 
class="p">(</span><span class="n">Pojo</span><span class="p">.</span><span 
class="n">class</span><span class="p">)</span>
+    <span class="p">.</span><span class="n">init</span><span 
class="p">(</span><span class="n">handler</span><span class="p">::</span><span 
class="n">initialize</span><span class="p">)</span>
+    <span class="p">.</span><span class="n">start</span><span 
class="p">(</span><span class="n">handler</span><span class="p">::</span><span 
class="n">activate</span><span class="p">)</span>
+    <span class="p">.</span><span class="n">stop</span><span 
class="p">(</span><span class="n">handler</span><span class="p">::</span><span 
class="n">deactivate</span><span class="p">)</span>
+    <span class="p">.</span><span class="n">destroy</span><span 
class="p">(</span><span class="n">handler</span><span class="p">::</span><span 
class="n">shutdown</span><span class="p">));</span>
+</pre></div>
+
+
+<p>Callbacks are empty-args, or may take a DM Component in argument.</p>
+<p>Method Reference for Component implementations class are not supported.</p>
 <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 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>
@@ -680,7 +725,7 @@ fields:</p>
 
 
 <h2 id="creating-service-adapter-components">Creating Service Adapter 
Components<a class="headerlink" href="#creating-service-adapter-components" 
title="Permanent link">&para;</a></h2>
-<p>DM service adapters allows to create adapter services when a given type of 
adapted service is found in the OSGI registry.
+<p>DM service adapters allow to create adapter services when a given type of 
adapted service is found in the OSGI registry.
 Using the "<code>adapter</code>" factory method, you can pass to it consumer 
of an <code>ServiceAdapterBuilder</code> that
 can be used to construct a DM adapter component.</p>
 <p>Code example that adapts a "Device" service to an HttpServlet service. The 
adapter is created using a ServiceAdapterBuilder that is passed to the 
lambda.</p>
@@ -708,6 +753,17 @@ a lambda for the FactoryPidAdapterBuilde
 <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">FactoryPidAdapterBuilder</span> <span class="n">adapter</span><span 
class="o">)</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>Same more concise example that is not declaring the type of the lambda 
type:</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>
@@ -756,9 +812,10 @@ like if they were service dependencies.<
 track any "Tracked" services registered in the Registry, using a classic 
whiteboard pattern. But before, you need to
 download a web page at initialization, before you component is started. The 
downloaded webpage is required to be able to 
 handle Tracked services. Now, you don't want to block the initialization of 
your component because in a reactive word,
-it is forbidden to block on the current thread.
-So, you use an HttpClient which allows to asynchronously download a web page, 
and when you schedule doGET() on the
-client, the method returns to you a 
<code>CompletableFuture&lt;String&gt;</code>.</p>
+it is forbidden to block on the current thread.</p>
+<p>So, you use an <code>HttpClient</code> which allows to asynchronously 
download a web page: this service is assumed to provide a doGET() method
+which does not block the current thread, but instead returns 
<code>CompletableFuture&lt;String&gt;</code>
+which represents the future result of the asynchronously downloaded page.</p>
 <p>So, from your component init() method, you can just declare a 
FutureDependency on the result of the 
<code>CompletableFuture&lt;String&gt;</code></p>
 <p>And once the result will be completed, you will then be called in your 
start() callback, and at this point, the Tracked services will then
 be injected (using DM, optional service callbacks are always invoked after the 
start() callback, never before).</p>
@@ -769,7 +826,9 @@ 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">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="na">withCnf</span><span 
class="o">(</span><span class="n">cnf</span> <span class="o">-&gt;</span> <span 
class="n">cnf</span><span class="o">.</span><span class="na">pid</span><span 
class="o">(</span><span class="s">&quot;foo.pid&quot;</span><span 
class="o">))</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="n">svc</span> <span class="o">-&gt;</span> <span 
class="n">svc</span><span class="o">.</span><span 
class="na">required</span><span class="o">())</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>
@@ -881,7 +940,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. 1732331 by pderop on Thu, 25 Feb 2016 16:39:54 +0000
+        Rev. 1732786 by pderop on Sun, 28 Feb 2016 20:03:05 +0000
       </div>
       <div class="trademarkFooter"> 
         Apache Felix, Felix, Apache, the Apache feather logo, and the Apache 
Felix project

svn commit: r981348 - in /websites/staging/felix/trunk/content: ./ documentation/subprojects/apache-felix-dependency-manager/guides/dm-lambda.html

Reply via email to