aries-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r956696 - in /websites/staging/aries/trunk/content: ./ modules/async-svcs.html
Date Thu, 02 Jul 2015 15:39:29 GMT
Author: buildbot
Date: Thu Jul  2 15:39:29 2015
New Revision: 956696

Log:
Staging update by buildbot for aries

Modified:
    websites/staging/aries/trunk/content/   (props changed)
    websites/staging/aries/trunk/content/modules/async-svcs.html

Propchange: websites/staging/aries/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Jul  2 15:39:29 2015
@@ -1 +1 @@
-1688108
+1688849

Modified: websites/staging/aries/trunk/content/modules/async-svcs.html
==============================================================================
--- websites/staging/aries/trunk/content/modules/async-svcs.html (original)
+++ websites/staging/aries/trunk/content/modules/async-svcs.html Thu Jul  2 15:39:29 2015
@@ -23,7 +23,7 @@
   <meta name="keywords" content="..."/>
   <meta name="description" content="..." />
     <title>
-    Apache Aries - Asynchronous Services
+    Apache Aries - 
     </title>
   </head>
 <body onload="SetMenu()">
@@ -281,9 +281,135 @@
           </td>
           <td height="100%" width="100%">
             <!-- Content -->
-            <div class="wiki-content"><h1 id="osgi-asynchronous-services">OSGi
Asynchronous Services</h1>
-<h2 id="introduction">Introduction</h2>
-<p>... tbd ...</p></div>
+            <div class="wiki-content"><p>Title: Asynchronous Services</p>
+<h1 id="introduction">Introduction</h1>
+<p>The R6 OSGi specifications include support for Asynchronous programming using OSGi
services. 
+Apache Aries aims to provide small, compliant implementations of these specifications to
enable asynchronous
+programming in enterprise applications. The two key specifications are OSGi Promises and
the Async service.</p>
+<h1 id="osgi-promises">OSGi Promises</h1>
+<p>One of the fundamental pieces of an asynchronous programming system is the <em>Promise</em>.
A Promise is a holder type that 
+represents an asynchronous calcluation. Since Java 5 the JDK has contained <em>java.util.concurrent.Future</em>
to perform this 
+function. Java's Future type is, however, fatally flawed as it has no callback to notify
the user when it resolves. Instead the
+user must make a blocking call to <em>get()</em>.</p>
+<p>OSGi promises fix this problem by defining a Promise interface which allows the
user to register callbacks which will be
+called when the promise <em>resolves</em>. These callbacks are lambda friendly
SAM types, but the Promise API itself has no
+dependencies on Java 8. The Aries version (org.apache.aries.async.promise.api) has a minimum
requirement of JDK 6.</p>
+<h2 id="creating-osgi-promises">Creating OSGi Promises</h2>
+<p>Creating a Promise is easy. The <em>org.osgi.util.promise.Deferred</em>
type is a factory for a single promise, and can also be used to
+resolve or fail the promise:</p>
+<div class="codehilite"><pre><span class="n">Deferred</span><span
class="o">&lt;</span><span class="n">Integer</span><span class="o">&gt;</span>
<span class="n">deferred</span> <span class="p">=</span> <span
class="n">new</span> <span class="n">Deferred</span><span class="o">&lt;&gt;</span><span
class="p">();</span>
+<span class="n">new</span> <span class="n">Thread</span><span
class="p">(()</span> <span class="o">-&gt;</span> <span class="p">{</span>
+        <span class="n">int</span> <span class="n">result</span>
<span class="p">=</span> <span class="n">calculateReallyHardSum</span><span
class="p">();</span>
+        <span class="n">deferred</span><span class="p">.</span><span
class="n">resolve</span><span class="p">(</span><span class="n">result</span><span
class="p">);</span>
+    <span class="p">}).</span><span class="n">start</span><span
class="p">();</span>
+
+<span class="n">Promise</span><span class="o">&lt;</span><span
class="n">Integer</span><span class="o">&gt;</span> <span class="n">p</span>
<span class="p">=</span> <span class="n">deferred</span><span class="p">.</span><span
class="n">getPromise</span><span class="p">();</span>
+<span class="p">...</span>
+</pre></div>
+
+
+<p>But wait - what if something goes wrong? How do we signal to the user that there
was a problem and the result is never coming?
+The answer is very easy - Promises have the concept of <em>failure</em>. A promise
will <em>either</em> resolve <em>or</em> fail at most once. For well

+written code this rule is usually the same as "A promise will either resolve or fail <em>exactly</em>
once". Promises are thread safe and
+effectively immutable, meaning they can be shared with other code.</p>
+<div class="codehilite"><pre><span class="n">Deferred</span><span
class="o">&lt;</span><span class="n">Integer</span><span class="o">&gt;</span>
<span class="n">deferred</span> <span class="p">=</span> <span
class="n">new</span> <span class="n">Deferred</span><span class="o">&lt;&gt;</span><span
class="p">();</span>
+<span class="n">new</span> <span class="n">Thread</span><span
class="p">(()</span> <span class="o">-&gt;</span> <span class="p">{</span>
+        <span class="k">try</span> <span class="p">{</span>
+            <span class="n">int</span> <span class="n">result</span>
<span class="p">=</span> <span class="n">calculateErrorProneSum</span><span
class="p">();</span>
+            <span class="n">deferred</span><span class="p">.</span><span
class="n">resolve</span><span class="p">(</span><span class="n">result</span><span
class="p">);</span>
+        <span class="p">}</span> <span class="k">catch</span> <span
class="p">(</span><span class="n">Exception</span> <span class="n">e</span><span
class="p">)</span> <span class="p">{</span>
+            <span class="n">deferred</span><span class="p">.</span><span
class="n">fail</span><span class="p">(</span><span class="n">e</span><span
class="p">);</span>
+        <span class="p">}</span>
+    <span class="p">}).</span><span class="n">start</span><span
class="p">();</span>
+
+<span class="n">Promise</span><span class="o">&lt;</span><span
class="n">Integer</span><span class="o">&gt;</span> <span class="n">p</span>
<span class="p">=</span> <span class="n">deferred</span><span class="p">.</span><span
class="n">getPromise</span><span class="p">();</span>
+<span class="p">...</span>
+</pre></div>
+
+
+<h2 id="using-osgi-promises">Using OSGi Promises</h2>
+<p>Once you have a promise, what do you do with it? It's easy to get the value from
a promise using the <em>getValue()</em> method,
+or you can use the <em>getFailure()</em> method to get the failure cause. Unfortunately
both of these methods block until the promise
+resolves, and whilst the <em>isDone()</em> method does tell you if the Promise
has completed they really aren't the right way to use a
+Promise.</p>
+<p>Promises work best when you register callbacks and/or transformations. The Promise
API has a variety of useful methods for
+doing work with the Promise when it resolves. For example we can run a task after the promise
completes successfully:</p>
+<div class="codehilite"><pre><span class="n">Promise</span><span
class="o">&lt;</span><span class="n">Integer</span><span class="o">&gt;</span>
<span class="n">promise</span> <span class="p">=</span> <span class="p">...</span>
+<span class="n">promise</span><span class="p">.</span><span class="n">then</span><span
class="p">(</span><span class="n">p</span> <span class="o">-&gt;</span>
<span class="p">{</span>
+        <span class="n">System</span><span class="p">.</span><span
class="n">out</span><span class="p">.</span><span class="n">println</span><span
class="p">(</span>&quot;<span class="n">The</span> <span class="n">calculator</span>
<span class="n">returned</span> &quot; <span class="o">+</span>
<span class="n">p</span><span class="p">.</span><span class="n">getValue</span><span
class="p">());</span>
+        <span class="k">return</span> <span class="n">null</span><span
class="p">;</span>
+    <span class="p">});</span>
+</pre></div>
+
+
+<p>We can also register callbacks to handle failures:</p>
+<div class="codehilite"><pre><span class="n">Promise</span><span
class="o">&lt;</span><span class="n">Integer</span><span class="o">&gt;</span>
<span class="n">promise</span> <span class="p">=</span> <span class="p">...</span>
+<span class="n">promise</span><span class="p">.</span><span class="n">then</span><span
class="p">(</span><span class="n">p</span> <span class="o">-&gt;</span>
<span class="p">{</span>
+        <span class="n">System</span><span class="p">.</span><span
class="n">out</span><span class="p">.</span><span class="n">println</span><span
class="p">(</span>&quot;<span class="n">The</span> <span class="n">calculator</span>
<span class="n">returned</span> &quot; <span class="o">+</span>
<span class="n">p</span><span class="p">.</span><span class="n">getValue</span><span
class="p">());</span>
+        <span class="k">return</span> <span class="n">null</span><span
class="p">;</span>
+    <span class="p">},</span> <span class="n">p</span> <span class="o">-&gt;</span>
<span class="n">p</span><span class="p">.</span><span class="n">getFailure</span><span
class="p">().</span><span class="n">printStackTrace</span><span class="p">());</span>
+</pre></div>
+
+
+<h3 id="chaining-osgi-promises">Chaining OSGi Promises</h3>
+<p>In the previous examples our success callback returned <em>null</em>
- why? Well the return value from a success callback is always
+a promise (null is a shortcut for a promise resolved with null). The promise returned by
the callback represents an asynchronous 
+execution flow in a process known as "chaining". The overall completion of this chain is
represented by a third promise, returned
+to the caller of the <em>then()</em> method.</p>
+<ol>
+<li>The caller registers a success callback, and receives a "chained" promise</li>
+<li>The original promise completes successfully</li>
+<li>The success callback runs and returns a promise representing another piece of asynchronous
work</li>
+<li>The promise returned by the success callback completes successfully</li>
+<li>The "chained" promise completes with the same value as the promise from step 4.</li>
+</ol>
+<h2 id="other-promise-behaviours">Other Promise behaviours</h2>
+<p>As well as simple callbacks Promises also provide advanced mapping and recovery
features. For example a promise can be
+wrapped so that if the original work fails then a new value can be supplied using a recovery
function.</p>
+<p>The <em>org.osgi.util.promise.Promises</em> utility class also provides
useful functions for working with promises. For example helper
+methods to wrap an existing value or failure in a Promise, or a way of aggregating a group
of promises into a single promise.</p>
+<h1 id="the-async-service">The Async service</h1>
+<p>Most OSGi services have a synchronous API. This is usually the easiest way to think
about, write, and use services. The main
+problem with this is that long running service calls can cause applications to run slowly,
and making the calls asynchronous is
+both verbose and error-prone.</p>
+<p>The Async service is designed to take away the boilerplate code needed to invoke
a service asynchronously, and to convert any
+synchronous API into an asynchronous API, returning promises instead of values.</p>
+<h2 id="using-the-async-service">Using the Async service</h2>
+<p>The Async service is available in the service registry and is very easy to use -
first we need to mediate the service. 
+Mediating is a bit like creating a mock object, the mediator records method calls made against
it so that they can be 
+transformed into asynchronous calls. Mediating can apply to a concrete object, or to a ServiceReference.
It is better to 
+use a ServiceReference when one is available, as the Async service can track the availability
of the backing service.</p>
+<div class="codehilite"><pre><span class="n">Async</span> <span
class="n">async</span> <span class="p">=</span> <span class="p">...;</span>
+<span class="n">ServiceReference</span><span class="o">&lt;</span><span
class="n">MyService</span><span class="o">&gt;</span> <span class="n">ref</span>
<span class="p">=</span> <span class="p">...;</span>
+<span class="n">MyService</span> <span class="n">mediator</span>
<span class="p">=</span> <span class="n">async</span><span class="p">.</span><span
class="n">mediate</span><span class="p">(</span><span class="n">ref</span><span
class="p">,</span> <span class="n">MyService</span><span class="p">.</span><span
class="n">class</span><span class="p">);</span>
+</pre></div>
+
+
+<p><em>or</em></p>
+<div class="codehilite"><pre><span class="n">Async</span> <span
class="n">async</span> <span class="p">=</span> <span class="p">...;</span>
+<span class="n">MyService</span> <span class="n">svc</span> <span
class="p">=</span> <span class="p">...;</span>
+<span class="n">MyService</span> <span class="n">mediator</span>
<span class="p">=</span> <span class="n">async</span><span class="p">.</span><span
class="n">mediate</span><span class="p">(</span><span class="n">svc</span><span
class="p">,</span> <span class="n">MyService</span><span class="p">.</span><span
class="n">class</span><span class="p">);</span>
+</pre></div>
+
+
+<p>Once a service has been mediated the mediator should be called just like the real
service object, and the return value passed to
+the Async service's <em>call()</em> method. This returns a promise representing
the asynchronous work.</p>
+<div class="codehilite"><pre><span class="n">Promise</span><span
class="o">&lt;</span><span class="n">Integer</span><span class="o">&gt;</span>
<span class="n">promise</span> <span class="p">=</span>  <span
class="n">async</span><span class="p">.</span><span class="n">call</span><span
class="p">(</span><span class="n">mediator</span><span class="p">.</span><span
class="n">calculateReallyHardSum</span><span class="p">());</span>
+</pre></div>
+
+
+<h3 id="void-methods">Void methods</h3>
+<p>Void methods don't have a return value to pass to the async service, and should
use the no-args version of call instead.</p>
+<div class="codehilite"><pre><span class="nx">mediator</span><span
class="p">.</span><span class="nx">longRunningVoidMethod</span><span
class="p">()</span>
+<span class="nx">Promise</span><span class="cp">&lt;?</span><span
class="o">&gt;</span> <span class="nx">promise</span> <span class="o">=</span>
 <span class="nx">async</span><span class="o">.</span><span class="nx">call</span><span
class="p">();</span>
+</pre></div>
+
+
+<h3 id="fire-and-forget-calls">Fire and Forget calls</h3>
+<p>Sometimes the user does not care when a piece of work finishes, or what value it
returns, or even whether it was successful.
+These sorts of calls are called "fire and forget" calls, and are also supported by the async
service using the <em>execute()</em> method.</p>
+<p>The execute method still returns a promise, however this promise represents whether
the fire and forget call successfully started
+or not, not whether it has completed.</p></div>
             <!-- Content -->
           </td>
         </tr>



Mime
View raw message