Author: buildbot
Date: Tue Feb 2 23:35:37 2016
New Revision: 979328
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 Tue Feb 2 23:35:37 2016
@@ -1 +1 @@
-1728232
+1728237
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
Tue Feb 2 23:35:37 2016
@@ -347,30 +347,77 @@ what it has parsed, it will possibly add
<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; you can now make your component
depend on the result of a jdk8 <code>CompletableFuture</code>.
+<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,
like if they were service dependencies.</p>
-<p>Assume you develop an Http Service and you want to register it in the OSGi
service registry only once the service is listening on port 80.
-Now, you want to use for example Vertx.io which allows to build reactive
applications on the JVM. This library wraps asynchronous events behind a
CompletableFuture.</p>
-<p>So, naturally, you can write from your init() method something like
this:</p>
-<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">class</span> <span class="nc">HttpServiceImpl</span> <span
class="kd">implements</span> <span class="n">HttpService</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="n">CompletableFuture</span><span
class="o"><</span><span class="n">HttpServer</span><span
class="o">></span> <span class="n">futureServer</span> <span
class="o">=</span> <span class="n">createServer</span><span
class="o">().</span><span class="na">listenFuture</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">withFuture</span><span class="o">(</span><span
class="n">futureService</span><span class="o">,</span> <span
class="n">future</span> <span class="o">-></span> <span
class="n">future</span><span class="o">.</span><span class="na">cbi</span><span
class="o">(</span><span class="k">this</span><span class="o">::</span><span
class="n">serverReady</span><span class="o">)));</span>
+<p>Let's explose this new dependency using an advanced example: assume you
develop a component that needs to
+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<String></code>.</p>
+<p>So, from your component init() method, you can just declare a
FutureDependency on the result of the
<code>CompletableFuture<String></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>
+<p>So, the Activator looks like this:</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">DependencyActivatorBase</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">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">withSrv</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="o">.</span><span class="na">withSrv</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">cb</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>
+
+
+<p>Now, here is the implementation for our component which downloads the URL
from its init method. The init method will declare a "FutureDependency"
+for the result of the <code>CompletableFuture<String></code> returned by
the HttpClient. And once the result is injected
+in the setPage callback, then the start() callback will be called, and
finally, any registered Tracked service will be
+injected in the "bindTracked" method:</p>
+<div class="codehilite"><pre><span class="kn">import</span> <span
class="nn">static</span> <span class="n">org</span><span
class="o">.</span><span class="na">apache</span><span class="o">.</span><span
class="na">felix</span><span class="o">.</span><span class="na">dm</span><span
class="o">.</span><span class="na">lambda</span><span class="o">.</span><span
class="na">DependencyManagerActivator</span><span class="o">.*;</span>
+
+<span class="kd">public</span> <span class="kd">class</span> <span
class="nc">Pojo</span> <span class="kd">implements</span> <span
class="n">PojoService</span> <span class="o">{</span>
+ <span class="n">HttpClient</span> <span class="n">m_httpClient</span><span
class="o">;</span> <span class="c1">// injected.</span>
+ <span class="n">String</span> <span class="n">m_url</span><span
class="o">;</span> <span class="c1">// the URL to download using the http
client.</span>
+
+ <span class="kt">void</span> <span class="nf">updated</span><span
class="o">(</span><span class="n">Dictionary</span><span
class="o"><</span><span class="n">String</span><span class="o">,</span>
<span class="n">Object</span> <span class="n">conf</span><span
class="o">)</span> <span class="kd">throws</span> <span
class="n">Exception</span> <span class="o">{</span>
+ <span class="n">m_url</span> <span class="o">=</span> <span
class="o">(</span><span class="n">String</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">"download.url"</span><span
class="o">);</span>
<span class="o">}</span>
- <span class="c1">// Inject our HttpServer that is listening</span>
- <span class="kt">void</span> <span class="nf">serverReady</span><span
class="o">(</span><span class="n">HttpServer</span> <span
class="n">server</span><span class="o">)</span> <span class="o">{</span> <span
class="o">...</span> <span class="o">}</span>
+ <span class="c1">// lifecycle dm callback that allows you to add more
dependencies. start will be called once the webpage has been downloaded.</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">// Let's schedule a download for our web
page.</span>
+ <span class="n">CompletableFuture</span><span
class="o"><</span><span class="n">String</span><span class="o">></span>
<span class="n">futurePage</span> <span class="o">=</span> <span
class="n">m_httpClient</span><span class="o">.</span><span
class="na">doGET</span><span class="o">(</span><span
class="n">m_url</span><span class="o">);</span>
+
+ <span class="c1">// Add a required dependency to the result of the CF,
and inject the result in our setPage method.</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">withFuture</span><span class="o">(</span><span
class="n">futurePage</span><span class="o">,</span> <span
class="n">future</span> <span class="o">-></span> <span
class="n">future</span><span class="o">.</span><span class="na">cbi</span><span
class="o">(</span><span class="k">this</span><span class="o">::</span><span
class="n">setPage</span><span class="o">)));</span>
+ <span class="o">}</span>
+
+ <span class="kt">void</span> <span class="nf">setPage</span><span
class="o">(</span><span class="n">String</span> <span
class="n">content</span><span class="o">)</span> <span class="o">{</span>
+ <span class="c1">// Called when the CompletableFuture has
completed</span>
+ <span class="o">}</span>
<span class="kt">void</span> <span class="nf">start</span><span
class="o">()</span> <span class="o">{</span>
- <span class="c1">// at this point we are fully started</span>
- <span class="o">}</span>
+ <span class="c1">// We have downloaded the page, our component is
starting and is about to be registered</span>
+ <span class="o">}</span>
+
+ <span class="kt">void</span> <span class="nf">bind</span><span
class="o">(</span><span class="n">Tracked</span> <span
class="n">service</span><span class="o">)</span> <span class="o">{</span>
+ <span class="c1">// a Tracked service is injected, we can handle it
because we are fully initialized.</span>
+ <span class="c1">// (optional service callbacks are always invoked
after the start callback).</span>
+ <span class="o">}</span>
<span class="o">}</span>
</pre></div>
-<p>and your HttpService will be call in <code>start</code> and registered only
once the server is listening.</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
+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 have been downloaded.</p>
+<p>Also, notice that when the page is injected in the setPage() method, you
absolutely don't need to deal with
+synchronization at all because in DM, all lifecycle and dependency callbacks
are safely scheduled in a "serial queue" associated to the
+component.</p>
<h2 id="comparing-two-activators-using-old-and-new-api">Comparing two
activators using old and new API:<a class="headerlink"
href="#comparing-two-activators-using-old-and-new-api" title="Permanent
link">¶</a></h2>
<p>Assume we have a <code>ServiceConsumer</code> which depends on the
following services:</p>
<ul>
@@ -493,7 +540,7 @@ and the service is registered.</p>
<p>Caution: if you are using a corporate http proxy, you have to fix the
Activator in order to configure the ip addr and port number of your
http proxy.</p>
<div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
- Rev. 1728231 by pderop on Tue, 2 Feb 2016 22:19:46 +0000
+ Rev. 1728237 by pderop on Tue, 2 Feb 2016 23:35:22 +0000
</div>
<div class="trademarkFooter">
Apache Felix, Felix, Apache, the Apache feather logo, and the Apache
Felix project
