Difference between revisions of "ECF/Asynchronous Remote Services"

Revision as of 17:58, 8 April 2014

ECF's Remote Services API, which is used to implement OSGi remote services and remote service admin specifications, has the ability for consumers/clients to use asynchronous/non-block remote method calls.

Normal/Synchronous OSGi (Remote) Services

When an OSGi service is actually invoked today, this is done by the caller calling a method on the service. For example, consider a simple 'hello' service:

package org.eclipse.ecf.examples.remoteservices.hello;
 
public interface IHello {
 
	public String hello(String from);
 
}

Once a consumer of this service gets a valid service reference (i.e. through ServiceTracker, injection via declarative services (DS) or other injection framework, BundleContext.getServiceReference or others), it can actually invoke/use the service via a method call on 'hello':

String response = helloService.hello("slewis");

With OSGi remote services, this 'helloService' may actually be a proxy. If invoked as above a proxy will marshall the method arguments (i.e. 'slewis' String in this case), and communicate with the remote service host via some network (i.e. via some protocol). If there is a result of the call, then it will then be unmarshalled and returned to the caller thread. With synchronous invocation the thread that calls 'hello' will block until this entire process is complete.

Asynchronous Remote Services

ECF has added the ability to declare asynchronous access to a remote method, so that the consumer can ge guaranteed that calling the service will not block. So, for example, it's now possible to make a non-blocking call to the hello service like this

Future future = helloAsyncService.helloAsync("slewis");

With an ECF created asynchronous proxy, the consumer thread that calls helloAsyncService.helloAsync is guaranteed not to block, and the returned Future can be used to access the value at some later point.

With ECF's asynchronous proxies, neither the consumer nor the host have to actually implement the asynchronous proxy behavior. The proxy is automatically constructed by the ECF remote services implementation when accessed by a consumer.

At this point, you might ask: But how is the asynchronous proxy defined? i.e. where does the helloAsyncService come from?

The answer to this is that it is defined in a new/second service interface...called the asynchronous service interface that is related to the IHello service interface:

public interface IHelloAsync {
 
	public Future<String> helloAsync(String from);
}

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

1. The name is IHelloAsync rather than IHello
2. The method name is helloAsync rather than hello
3. The return value is Future<String>

With ECF remote services, when a IHello proxy is created, the proxy will also implement the IHelloAsync interface. So, for example

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

or

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

This gives the consumer maximum flexibility in determining how a given invocation will occur (i.e. synchronously or asynchronously. The caller can use the synchronous service proxy, or the asynchronous service proxy. Or both invocation methods may be used.

All that's required is for the service interface to declare an *Async service type class using these rules:

1. Class name must be [service interface classname]Async
   • Example: IHello -> IHelloAsync
2. For any methods that should be exposed to the consumer via the asynchronous proxy
   • Name the method [methodName]Async
     • Example: hello -> helloAsync
   • The return value should always be of type java.util.concurrent.Future with the actual return type via the Future generic type...e.g. Future<String>

Another Example

Original Service Interface

package my.package;
 
public interface IFoo {
 
	public String bar(URI uri, String something);
}

Asynchronous Service Interface

package my.package;
import java.util.concurrent.Future;
 
public interface IFooAsync {
 
    public Future<String> barAsync(URI uri, String something);
}

Notes