org.osgi.service.async

Interface Async

@ProviderType
public interface Async

The Asynchronous Execution Service. This can be used to make asynchronous invocations on OSGi services and objects through the use of a mediator object.

Typical usage:

   Async async = ctx.getService(asyncRef);
   
   ServiceReference<MyService> ref = ctx.getServiceReference(MyService.class);
   
   MyService mediator = async.mediate(ref, MyService.class);
   
   Promise<BigInteger> result = async.call(mediator.getSumOverAllValues());
 

The Promise API allows callbacks to be made when asynchronous tasks complete, and can be used to chain Promises.

Multiple asynchronous tasks can be started concurrently, and will run in parallel if the Async Service has threads available.

Method Summary

Methods

Modifier and Type	Method and Description
Promise<?>	call() Invoke the last method call registered by a mediated object as an asynchronous task.
<R> Promise<R>	call(R r) Invoke the last method call registered by a mediated object as an asynchronous task.
Promise<Void>	execute() Invoke the last method call registered by a mediated object as a "fire-and-forget" asynchronous task.
<T> T	mediate(ServiceReference<? extends T> target, Class<T> iface) Create a mediator for the specified service.
<T> T	mediate(T target, Class<T> iface) Create a mediator for the specified object.

Method Detail

mediate

<T> T mediate(T target,
            Class<T> iface)

Create a mediator for the specified object. The mediator is a generated object that registers the method calls made against it. The registered method calls can then be run asynchronously using either the call(Object), call(), or execute() method.

The values returned by method calls made on a mediated object are opaque and should not be interpreted.

Normal usage:

 I s = ...;
 I i = async.mediate(s, I.class);
 Promise<String> p = async.call(i.foo());
 

Parameters:

target - The service object to mediate.

iface - The type that the mediated object should provide.

Returns:

A mediator for the service object.

Throws:

IllegalArgumentException - If the type represented by iface cannot be mediated.

mediate

<T> T mediate(ServiceReference<? extends T> target,
            Class<T> iface)

Create a mediator for the specified service. The mediator is a generated object that registers the method calls made against it. The registered method calls can then be run asynchronously using either the call(Object), call(), or execute() method.

The values returned by method calls made on a mediated object are opaque and should not be interpreted.

This method differs from mediate(Object, Class) in that it can track the availability of the specified service. This is recommended as the preferred option for mediating OSGi services as asynchronous tasks may not start executing until some time after they are requested. Tracking the validity of the ServiceReference for the service ensures that these tasks do not proceed with an invalid object.

Normal usage:

 ServiceReference<I> s = ...;
 I i = async.mediate(s, I.class);
 Promise<String> p = async.call(i.foo());
 

Parameters:

target - The service reference to mediate.

iface - The type that the mediated object should provide.

Returns:

A mediator for the service object.

Throws:

IllegalArgumentException - If the type represented by iface cannot be mediated.

call

<R> Promise<R> call(R r)

Invoke the last method call registered by a mediated object as an asynchronous task. The result of the task can be obtained using the returned Promise.

Typically the parameter for this method will be supplied inline like this:

 ServiceReference<I> s = ...;
 I i = async.mediate(s, I.class);
 Promise<String> p = async.call(i.foo());
 

Parameters:

r - The return value of the mediated call, used for type information.

Returns:

A Promise which can be used to retrieve the result of the asynchronous task.

call

Promise<?> call()

Invoke the last method call registered by a mediated object as an asynchronous task. The result of the task can be obtained using the returned Promise.

Generally it is preferable to use call(Object) like this:

 ServiceReference<I> s = ...;
 I i = async.mediate(s, I.class);
 Promise<String> p = async.call(i.foo());
 

However this pattern does not work for void methods. Void methods can therefore be handled like this:

 ServiceReference<I> s = ...;
 I i = async.mediate(s, I.class);
 i.voidMethod()
 Promise<?> p = async.call();
 

Returns:

A Promise which can be used to retrieve the result of the asynchronous task.

execute

Promise<Void> execute()

Invoke the last method call registered by a mediated object as a "fire-and-forget" asynchronous task. This method should be used by clients in preference to call() and call(Object) when no callbacks, or other features of Promise, are needed.

The advantage of this method is that it allows for greater optimization of the underlying asynchronous task. Clients are therefore likely to see better performance when using this method compared to using call(Object) or call() and ignoring the returned Promise. The Promise returned by this method is different from the Promise returned by call(Object) or call(), in that the returned Promise will resolve when the fire-and-forget task is successfully started, or fail if the task cannot be started. Note that there is no happens-before relationship and the returned Promise may resolve before or after the fire-and-forget task starts, or completes.

Typically this method is used like call():

 ServiceReference<I> s = ...;
 I i = async.mediate(s, I.class);
 i.someMethod()
 Promise<Void> p = async.execute();
 

Returns:

A Promise representing whether the fire-and-forget task was able to start.