Top Description Methods
org.osgi.service.async

public Interface Async

Annotations
@ProviderType
Imports
org.osgi.annotation.versioning.ProviderType, org.osgi.framework.ServiceReference, org.osgi.util.promise.Promise
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

Modifier and TypeMethod and Description
public <R> Promise<R>

Returns:

A Promise which can be used to retrieve the result of the asynchronous task.
call(R
The return value of the mediated call, used for type information.
r)

Invoke the last method call registered by a mediated object as an asynchronous task.

public Promise<?>

Returns:

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

Invoke the last method call registered by a mediated object as an asynchronous task.

public Promise<Void>

Returns:

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

Invoke the last method call registered by a mediated object as a "fire-and-forget" asynchronous task.

public <T> T

Returns:

A mediator for the service object.
mediate(T
The service object to mediate.
target, Class<T>
The type that the mediated object should provide.
iface)

Create a mediator for the specified object.

public <T> T

Returns:

A mediator for the service object.
mediate(ServiceReference<? extends T>
The service reference to mediate.
target, Class<T>
The type that the mediated object should provide.
iface)

Create a mediator for the specified service.

Method Detail

callback to summary
public <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:R

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

Returns:Promise<R>

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

callback to summary
public 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:Promise<?>

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

executeback to summary
public 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:Promise<Void>

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

mediateback to summary
public <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:T

The service object to mediate.

iface:Class<T>

The type that the mediated object should provide.

Returns:T

A mediator for the service object.

Exceptions
IllegalArgumentException:
If the type represented by iface cannot be mediated.
mediateback to summary
public <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:ServiceReference<? extends T>

The service reference to mediate.

iface:Class<T>

The type that the mediated object should provide.

Returns:T

A mediator for the service object.

Exceptions
IllegalArgumentException:
If the type represented by iface cannot be mediated.