Async
Date: 2016-06-25

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<java.lang.Void>` | `execute()` Invoke the last method call registered by a mediated object as a "fire-and-forget" asynchronous task.
    `<T> T` | `mediate(org.osgi.framework.ServiceReference<? extends T> target, java.lang.Class<T> iface)` Create a mediator for the specified service.
    `<T> T` | `mediate(T target, java.lang.Class<T> iface)` Create a mediator for the specified object.

- - ### Method Detail

    - #### mediate

          <T> T mediate(T target,
                      java.lang.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:
        `java.lang.IllegalArgumentException` - If the type represented by iface cannot be mediated.

    - #### mediate

          <T> T mediate(org.osgi.framework.ServiceReference<? extends T> target,
                      java.lang.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:
        `java.lang.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<java.lang.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.