ECF/Asynchronous Remote Services

ECF's Remote Services API, which is used to implement OSGi 4.2 remote services, has had the ability for consumers/clients to use asynchronous/non-block remote method calls for at least the last 2 years.

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

helloService.hello("slewis");

With OSGi remote services, this 'helloService' may actually be a proxy. If invoked as above, under the covers, a proxy will marshall the method arguments (i.e. 'slewis' String in this case), and then 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 return to the caller thread. With synchronous invocation the thread that calls 'hello' will block until this entire process is complete.

Asynchronous Services

ECF has just 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 indefinitely. So, for example, it's now possible to make a call to the hello service like this

With an ECF created asynchronous proxy, the consumer thread that calls helloAsyncService.helloAsync is guaranteed not to block, and the appropriate IAsyncCallback method will be executed when the remote call completes (with either success or failure). The callback is called (by an arbitrary ECF thread) sometime after the helloAsync method completes.

A nice thing is that neither the consumer nor the host have to actually implement the asynchronous proxy. 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 the helloAsyncService come from?

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

Notice that this async interface declaration resembles the IHello service interface declaration, but differs from it in a couple of ways:

The name is IHelloAsync rather than IHello

It extends IAsyncRemoteServiceProxy

The method name is helloAsync rather than hello

The method arguments are String and IAsyncCallback rather than just String

With ECF 3.3 remote services, when a proxy is created, iff an interface class with the name [fq service interface name]Async can be loaded and it extends IAsyncRemoteServiceProxy then the proxy will implement that interface. So, for our hello example the proxy service reference will implement both the IHello and IHelloAsync methods, and the consumer can use either of the methods declared. So, for example

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 proxy, or simply cast to the asynchronous proxy. Or both invocation methods can be used as desired.

All that's required to get this automatic creation of an asynchronous proxy is for the service interface creator to declare an *Async class using these rules:

Future Results

IAsyncCallback is one approach to achieving asynchronous invocation of remote services. Another that is also supported by ECF 3.3 remote services is futures. Future objects allow the consumer to perform operations in between initiating a remote call and receiving a result.
So, for example, here is a use of a future result to initiate a remote call, perform some additional local operations and then get a result from the future.

// This will not block/return immediately
IFuture future = fooServiceAsync.barAsync(uri,something);// ...do other local computation here...// get resultString result =(String) future.get();// ...

ECF 3.3 remote service supports asynchronous access via either IAsyncCallback or futures, or both. To expose the IHello.hello method for asynchronous access via both callback and future approaches the IHelloAsync class would be declared like this

The return type should be org.eclipse.equinox.concurrent.future.IFuture

Example: String hello(String) -> IFuture helloAsync(String)

Full Example with Source

A full, working example of the hello world remote service, including the IHello service declaration, the IHelloAsync asynchronous service declaration, as well as the server host impl, consumer, and code showing the use of both synchronous proxy andasynchronous proxies (both callback and future-based) is available here: Getting Started with ECF's OSGi Remote Services Implementation