View source for ECF/Asynchronous Remote Services

<!-- This CSS wraps code blocks in pretty boxes -->
<css>
.mw-code { 
  background-color: #fafafa; 
  padding: 20px; 
  border-color: #ddd; 
  border-width: 3px; 
  border-style: solid; 
  border-radius: 5px; 
  margin-left: 10px; 
  margin-right: 10px; 
  overflow-x: auto; [[File:Example.jpg]]
}

.mw-headline {
  font-family: Helvetica Neue,Helvetica,Arial,sans-serif;
  color: rgb(51, 51, 51);
}

p {
  font-family: Helvetica Neue,Helvetica,Arial,sans-serif;
  text-align: justify;
}

h1 {
  border-bottom-color: rgb(238, 238, 238);
  font-weight: bold;
  padding-bottom: 17px;
  font-size: 30px;
  line-height: 36px;
}

h2 {
  border-bottom-color: rgb(238, 238, 238);
  padding-bottom: 12px;
  font-weight: bold;
  font-size: 24px;
  line-height: 36px;
}

h3 {
  border-bottom-width: 1px;
  border-bottom-style: solid;
  border-bottom-color: rgb(238, 238, 238);
  padding-bottom: 8px;
  font-size: 18px;
  line-height: 27px;
}

h4 {
  font-size: 14px;
}

h5 {
  font-size: 12px;
}

h6 {
  font-size: 11px;
  color: #EBEBEB;
  text-transform: uppercase;
}

a {
  color: rgb(0, 105, 214);
  font-family: Helvetica Neue,Helvetica,Arial,sans-serif;
}

a:visited {
  color: rgb(0, 105, 214);
}
</css>
===Synchronous Remote Services===

Whether a remote or local OSGi service, a service is invoked by calling a method on the service interface.  For example, consider a simple IHello service interface:

<source lang="java">package org.eclipse.ecf.examples.remoteservices.hello;

public interface IHello {

	public String hello(String from);
	
}
</source>

Once the consumer gets a valid service instance (i.e. through ServiceTracker, injection via declarative services (DS) or other injection framework, BundleContext.getServiceReference or other methods), it can actually invoke by calling the service interface method:

<source lang="java">
String response = helloService.hello("slewis");
</source>

With remote services, the helloService instance will typically be a proxy.  When invoked/called, the proxy will marshall any arguments (i.e. 'slewis' String in this case), communicate with the remote service host via some protocol, the host will execute the associated code, and if there is a result, it will be unmarshalled and the result value returned to the caller thread.  As per typical java call-return semantics, the thread that calls 'hello' will block until this entire process is complete.

===Asynchronous Remote Services===

ECF has added the ability for the service host to declare asynchronous access to a remote method, so that the consumer can be guaranteed that invoking/calling the service will not block.  For example, it's possible for a consumer to make a non-blocking call to the IHello service like this

<source lang="java">
Future<String> future = helloAsyncService.helloAsync("slewis");
</source>

With ECF asynchronous proxies (AP), the consumer thread that calls helloAsyncService.helloAsync is guaranteed '''not''' to block, and the returned Future&gt;String&lt;
can be used to subsequently access the String result (or exception/failure).

With ECF's AP support, neither the consumer nor the host have to implement this asynchronous behavior.  The proxy is automatically and dynamically constructed by the ECF remote services implementation on the consumer.

You might ask:  How is the asynchronous proxy defined?  i.e. where does the '''helloAsyncService''' come from?

The answer is that it is defined in a new/second service interface...called the '''asynchronous service interface'''.  For example, here is how to declare an asynchronous service interface for the '''IHello''' service:

<source lang="java">

public interface IHelloAsync {

	public Future<String> helloAsync(String from);
}

</source>

Notice that this declaration resembles the IHello service interface declaration, but differs from it in several important ways:

<ol><li>The name of the asynchronous service interface is <b>IHelloAsync</b> rather than <b>IHello</b>
<li>The method name(s) is/are <b>helloAsync</b> rather than <b>hello</b></li>
<li>The return value is '''Future&lt;String&gt;''' (or with Java 8 '''CompletableFuture&lt;String&gt;''' see below) rather than String</li>
</ol>

With ECF remote services, on the consumer when a IHello proxy is created, the proxy will also automatically implement the IHelloAsync interface, and the consumer is able to use either the synchronous IHello service interface or the IHelloAsync asynchronous service interface.  So, for example

<source lang="java">

IHello helloService = ...get service via DS/injections, ServiceTracker or otherServiceTracker, or other...
if (helloService instanceof IHelloAsync) {
   IHelloAsync helloServiceAsync = (IHelloAsync) helloService;
   // call it asynchronously...no blocking
   Future<String> future = helloAsync("slewis");
   // do other things
   String result = future.get();
   // do something with result...
}

</source>

or

<source lang="java">

IHelloAsync helloAsyncService = ...get service via DS/injections, ServiceTracker or other
// call it asynchronously...no blocking
Future<String> future = helloAsync("slewis");
// do other things
String result = future.get();
// do something with result...

</source>

Having both the synchronous (IHello) and asynchronous (IHelloAsync) service types gives the consumer flexibility in determining how a given remote invocation will occur (i.e. synchronously/blocking or asynchronously/non-blocking).  Synchronous, asynchronous, or both invocation methods may be used as appropriate for the consumer's use case(s) for the service.

===Java 8 CompletableFuture===

Java 8 introduces a new type of Future called '''[http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html java.util.concurrent.CompletableFuture]'''.  With ECF 3.8.1/[https://wiki.eclipse.org/Luna/Simultaneous_Release_Plan Luna] remote services, it's now possible for asynchronous service interfaces to return a CompletableFuture:

<source lang="java">package my.package;
import java.util.concurrent.CompletableFuture;

public interface IHelloAsync {

    public CompletableFuture<String> helloAsync(String from);
}
</source>

with CompletableFuture it's not necessary for the consumer to call Future.get (and possibly block) directly...but rather you can write succinct, simple, and '''guaranteed to be non-blocking''' calls such as:

<source lang="java">

IHelloAsync helloAsync = ...get remote service via DS/injections, ServiceTracker or other

CompletableFuture<String> cf = helloAsync("slewis");

cf.thenAccept((response) -> System.out.println("response to slewis helloAsync was: " + response));

</source>

The use of CompletableFuture has some very nice properties for service design, as well as some nice guarantees for the service consumer.  For remote service designers, they may declare and implement normal OSGi remote services (IHello) without having to concern themselves with the consumer's invocation style (synchronous or asynchronous).

Remote service consumers can be assured that there will be no blocking in their code (via the guarantees of CompletableFuture).  They may also use lambda to succinctly express arbitrary eventual execution...guaranteed to be done asynchronously when the response becomes available.  

Note that with ECF remote services there is no need for either the host implementation or the consumer to implement the asynchronous service interface.  The dynamically constructed proxy will automatically have/expose the asynchronous service interface to the consumer, and this proxy will provide the underlying implementation.

Note another advantage...for both the service designer and consumer...is that there are no extra class dependencies in the synchronous or asynchronous service interfaces (e.g. IHello and IHelloAsync).  That is, there are no dependencies on OSGi, OSGi Remote Services, or ECF classes...meaning that if they wish to use/reuse these services in other runtime contexts (e.g. outside of OSGi, OSGi Remote Services, and/or ECF) in the service interfaces or in any client code.  The only dependencies are to other service types and java.util.concurrent.CompletableFuture or java.util.concurrent.Future.

<references/>

{{ECF}}

[[Category:Eclipse Communication Framework]]
[[Category:ECF]]