Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Tutorial: Building your first Asynchronous OSGi Remote Service"

(Consumer: Discover and Use the CompletableFuture Asynchronous Remote Service)
(Define the Asynchronous Remote Service)
Line 108: Line 108:
 
Note the following about this interface:
 
Note the following about this interface:
  
#The name of the asynchronous remote service interface is '''ITimeServiceAsync''', which is the same as '''ITimeService''' + '''Async'''.  In general, this async remote service interface must be named '''OriginalServiceInterfaceNameAsync'''.
+
#The name of the asynchronous remote service interface is '''ITimeServiceAsync''', which is the same as ITimeService + Async.  In general, this async remote service interface must be named '''OriginalServiceInterfaceNameAsync'''.
#The name of the method is '''getCurrentTimeAsync''', which is the same oas '''getCurrentTime''' and '''Async'''Like the name of the service interface, in general the async method must be named '''OriginalServiceMethodNameAsync'''
+
#The name of the method is '''getCurrentTimeAsync''', which is the same as getCurrentTime and Async.  In general the async method must be named '''originalServiceMethodNameAsync'''
#The return value is of type '''Future<Long>'''.  This uses the Java Concurrent API '''Future''' class along with the original type returned by the '''getCurrentTime''' method (Long) as the generic qualifier for the Future class.  In general, the pattern here must be '''Future<OriginalType>'''.  Note that the '''Void'' type can be used for methods that return '''void'''...e.g. '''Future<Void>'''.
+
#The return value is of type '''Future<Long>'''.  This uses the Java Concurrent API [http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Future.html Future] class along with the type returned by the getCurrentTime method (Long) as the generic qualifier for the Future class.  In general, the pattern here must be Future<OriginalType> or unqualified...e.g. Future.  Note that the '''Void''' type can be used for methods that return void...e.g. Future<Void>.
#The contract for this asynchronous remote service is that '''getCurrentTimeAsync''' will not block, and immediately return a non-null instance of '''Future<Long>'''.  At the discretion of the caller, the Future<Long> instance may be queried about the availability of the result/completion of the call, and then able to access the underlying result via the methods exposed by the '''Future''' class.
+
#The contract for this asynchronous remote service is that getCurrentTimeAsync will not block, and immediately return a non-null instance of Future<Long>.  At the discretion of the caller, the Future<Long> instance may be queried about the availability of the result/completion of the call, and then able to access the underlying result via the methods exposed by the Future class.
  
This single asynchronous service interface is all that is needed for the remote service host to expose non-blocking access to the '''ITimeService.getCurrentTime()''' method to consumers.  '''No''' actual implementation is necessary, since it's provided automatically by ECF Remote Services implementation when discovered on the consumer.
+
This single asynchronous service interface is all that is needed for the remote service host to expose non-blocking access to the getCurrentTime() method to consumers.  '''No''' actual implementation is necessary, since it's provided automatically by ECF Remote Services implementation when discovered on the consumer.
  
 
==Source Code==
 
==Source Code==

Revision as of 18:15, 17 April 2014


Introduction

In a previous tutorial, we went through how to define, implement, and execute a simple OSGi Remote Service using ECF's Remote Service implementation. By definition, Remote Services require communication between processes/frameworks since local OSGi services are based upon synchronous invocation of a service method (i.e. the calling thread blocks while the service method is being invoked, and only continues after the service method returns). With Remote Services, this means that the calling thread can block as the remote method invocation is sent over a network, handled by the remote service, and then the response (method return value) is returned over the network. As well, the remote method invocation may fail outright...because of a network partition, or the remote service host failure. The handling of such failures may block the calling thread for a significant length of time.

To support asynchronous (non-blocking) remote service invocation, ECF's implementation of OSGi Remote Services ECF has created Asynchronous Remote Services. This provides developers of Remote Services the option to expose non-blocking/asynchronous remote method invocation to consumers of their remote service, without any additional programming. This tutorial will step through the process of defining and using an asynchronous remote service.

Define the Asynchronous Remote Service

In the previous tutorial a simple time service was defined:

package com.mycorp.examples.timeservice;
 
public interface ITimeService {
 
	public Long getCurrentTime();
}

As described above, when the consumer calls/invokes the getCurrentTime() method, without any implementation error it's possible for this method to block for a relatively long time...and/or throw a runtime exception...because the communication failed between the consumer and the remote service host.

ECF uniquely supports the creation of an Asynchronous Remote Service interface...that will automatically be available to clients of Remote Services. For example, here is the asynchronous service interface for the ITimeService given above:

package com.mycorp.examples.timeservice;
 
import java.util.concurrent.CompletableFuture;
 
public interface ITimeServiceAsync {
 
	public CompletableFuture<Long> getCurrentTimeAsync();
}

Note the following about this interface:

  1. The name of the asynchronous remote service interface is ITimeServiceAsync, which is the same as ITimeService + Async. In general, this async remote service interface must be named OriginalServiceInterfaceNameAsync.
  2. The name of the method is getCurrentTimeAsync, which is the same as getCurrentTime and Async. In general the async method must be named originalServiceMethodNameAsync
  3. The return value is of type Future<Long>. This uses the Java Concurrent API Future class along with the type returned by the getCurrentTime method (Long) as the generic qualifier for the Future class. In general, the pattern here must be Future<OriginalType> or unqualified...e.g. Future. Note that the Void type can be used for methods that return void...e.g. Future<Void>.
  4. The contract for this asynchronous remote service is that getCurrentTimeAsync will not block, and immediately return a non-null instance of Future<Long>. At the discretion of the caller, the Future<Long> instance may be queried about the availability of the result/completion of the call, and then able to access the underlying result via the methods exposed by the Future class.

This single asynchronous service interface is all that is needed for the remote service host to expose non-blocking access to the getCurrentTime() method to consumers. No actual implementation is necessary, since it's provided automatically by ECF Remote Services implementation when discovered on the consumer.

Source Code

The source code for the ITimeService and ITimeServiceAsync are available as an example project in the ECF git repo in the com.mycorp.examples.timeservice project.

Registering the Remote Service

In the initial tutorial, the host exports the remote service by setting some standardized service properties, and registering the service...here is the remote service registration from the previous tutorial

Dictionary<String, String> props = new Hashtable<String, String>();
props.put("service.exported.interfaces", "*");
props.put("service.exported.configs","ecf.generic.server");
 
bundleContext.registerService(ITimeService.class, new TimeServiceImpl(), props);

To allow the remote service consumer access to the Asynchronous Remote Service (e.g. ITimeServiceAsync) a new/additional service property must be set:

Dictionary<String, String> props = new Hashtable<String, String>();
props.put("service.exported.interfaces", "*");
props.put("service.exported.configs","ecf.generic.server");
// ECF RS property allowing ITimeServiceAsync interface to be automatically 
// exposed to consumers of the ITimeService by ECF RS implementation
props.put("ecf.exported.async.interfaces","*");
 
bundleContext.registerService(ITimeService.class, new TimeServiceImpl(), props);

The ecf.exported.async.interfaces service property, similar to the service.exported.interfaces standard property, tells the ECF Remote Service implementation to instrument the consumer's proxy for asynchronous access via the asynchronous remote service interface.

Source Code

The source code for the time service host is available as an example project in the ECF git repo in the com.mycorp.examples.timeservice.host project.

Consumer: Discover and Use the Asynchronous Remote Service

To invoke methods on a remote service, the consumer must first discover the service. Asynchronous Remote Service discovery works exactly the same as normal remote service discovery and so for details of that process see the previous tutorial.

In the previous tutorial, upon discovery, the ITimeService instance is injected in the consumer via the bindTimeService method:

package com.mycorp.examples.timeservice.consumer.ds;
 
import com.mycorp.examples.timeservice.ITimeService;
 
public class TimeServiceComponent {
 
	void bindTimeService(ITimeService timeService) {
		System.out.println("Discovered ITimeService via DS");
		// Call the service and print out result!
		System.out.println("Current time is: " + timeService.getCurrentTime());  // Call the ITimeService remote service
	}
}

All that is necessary to access the ITimeServiceAsync methods is to query the injected timeService instance for the desired asynchronous remote service interface. For example:

void bindTimeService(ITimeService timeService) {
    if (timeService instanceof ITimeServiceAsync) {
        ITimeServiceAsync asyncTimeService = (ITimeServiceAsync) timeService;
        System.out.println("Discovered ITimeServiceAsync via DS");
        // Call the asynchronous remote service.  Unlike the synchronous getTimeService(),
        // this method will not block
        Future<Long> currentTimeFuture = asyncTimeService.getCurrentTimeAsync();
        // potentially do other operations here...
        System.out.println("Current time is: " + currentTimeFuture.get());  
    }
}

With ECF's implementation of remote services, if an ITimeService proxy is created for the consumer, and an asynchronous service interface (i.e. ITimeServiceAsync) is present then the proxy will implement the asynchronous service interface. The actual implementation is provided directly by ECF Remote Services, and neither the host nor the consumer must do anything further for the asynchronous remote service to be usable by consumers. All that's necessary is to declare the asynchronous remote service (ITimeServiceAsync) in the same package as the original (ITimeService), and export a host instance of the remote service as described by the previous tutorial.

Source Code

The source code for the time service consumer is available as an example project in the ECF git repo in the com.mycorp.examples.timeservice.consumer.ds project.

Using Java8 CompletableFuture

In Java 8, in addition to lambdas, streams and other features, a new type of Future was introduced, called CompletableFuture. Unlike java.util.concurrent.Future, CompletableFuture can be used in a way guaranteed not to block, whereas calling Future.get() can block...if the underlying result does not yet exist.

In ECF 3.8.1/Luna support for CompletableFuture has been added. As shown above, async proxy interfaces can return either java.util.concurrent.Future as above...or java8's java.util.concurrent.CompletableFuture. For example, ITimeServiceAsync can be defined to return CompletableFuture rather than Future:

package com.mycorp.examples.timeservice;
 
import java.util.concurrent.CompletableFuture;
 
public interface ITimeServiceAsync {
 
	public CompletableFuture<Long> getCurrentTimeAsync();
}

Source Code

The source code for Java8 asynchronous time service is available as an example project in the ECF git repo in the com.mycorp.examples.timeservice.async project.

Consumer: Discover and Use the CompletableFuture Asynchronous Remote Service

With the remote service host's use of the ecf.exported.async.interfaces service property (as described in Registering the Remote Service above, it's possible on the consumer to have the ITimeServiceAsync, when discovered, to be injected directly into a declarative services component

void bindTimeService(ITimeServiceAsync timeService) {
	System.out.println("Discovered ITimeServiceAsync via DS");
	// Get the CompletableFuture...no blocking here
	CompletableFuture<Long> cf = timeService.getCurrentTimeAsync();
	// print out time when done...no blocking anywhere!
	cf.thenAccept((time) -> System.out.println("Remote time is: " + time));
}

In this line:

CompletableFuture<Long> cf = timeService.getCurrentTimeAsync();

the asynchronous remote service is being called, and CompletableFuture instance is returned. The implementation of this method is provided by the ECF Remote Service proxy, constructed automatically as part of the Remote Service implementation.

The client may then call CompletableFuture.thenAccept to execute a given block of code

cf.thenAccept((time) -> System.out.println("Remote time is: " + time));

Note that the given System.out.println("Remote time is: " + time)); is only executed when the underlying remote access is completed, and a time result is available. This means that there is no blocking...i.e. no matter how long the remote service takes to complete, the thread that calls timeService.getCurrentTimeAsync and cf.thenAccept is guaranteed not to block.

Source Code

The source code for Java8 asynchronous time service consumer is available as an example project in the ECF git repo in the com.mycorp.examples.timeservice.consumer.ds.async project.

Background and Related Articles

Asynchronous Proxies for Remote Services

Getting Started with ECF's OSGi Remote Services Implementation

OSGi Remote Services and ECF

Static File-based Discovery of Remote Service Endpoints

Download ECF Remote Services/RSA Implementation

How to Add Remote Services/RSA to Your Target Platform

Back to the top