AsyncDelegate
Date: 2016-06-25

org.osgi.service.async.delegate

## Interface AsyncDelegate

-     @ConsumerType
      public interface AsyncDelegate

  This interface is used by services to allow them to optimize Asynchronous calls where they are capable of executing more efficiently.

  This may mean that the service has access to its own thread pool, or that it can delegate work to a remote node, or act in some other way to reduce the load on the Asynchronous Services implementation when making an asynchronous call.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Promise<?>` | `async(java.lang.reflect.Method m, java.lang.Object[] args)` Invoke the specified method as an asynchronous task with the specified arguments.
    `boolean` | `execute(java.lang.reflect.Method m, java.lang.Object[] args)` Invoke the specified method as a "fire-and-forget" asynchronous task with the specified arguments.

- - ### Method Detail

    - #### async

          Promise<?> async(java.lang.reflect.Method m,
                         java.lang.Object[] args)
                           throws java.lang.Exception

      Invoke the specified method as an asynchronous task with the specified arguments.

      This method can be used by clients, or the Async Service, to optimize Asynchronous execution of methods.

      When called, this method should invoke the supplied method using the supplied arguments asynchronously, returning a Promise that can be used to access the result.

      If the method cannot be executed asynchronously by this method then `null` must be returned.

      Parameters:
        `m` - The method to be asynchronously invoked.
        `args` - The arguments to be used to invoke the method.
      Returns:
        A Promise representing the asynchronous result, or `null` if this method cannot be asynchronously invoked.
      Throws:
        `java.lang.Exception` - An exception should be thrown only if there was a serious error that prevented the asynchronous task from starting. For example, the specified method does not exist on this object. Exceptions must not be thrown to indicate that the call does not support asynchronous invocation. Instead this method must return `null`. Exceptions must also not be thrown to indicate a failure from the execution of the underlying method. This must be handled by failing the returned Promise.

    - #### execute

          boolean execute(java.lang.reflect.Method m,
                        java.lang.Object[] args)
                          throws java.lang.Exception

      Invoke the specified method as a "fire-and-forget" asynchronous task with the specified arguments.

      This method can be used by clients, or the Async Service, to optimize Asynchronous execution of methods.

      When called, this method should invoke the specified method using the specified arguments asynchronously. This method differs from `async(Method, Object[])` in that it does not return a Promise. This method therefore allows the implementation to perform more aggressive optimizations because the end result of the invocation does not need to be returned to the caller.

      If the method cannot be executed asynchronously by this method then `false` must be returned.

      Parameters:
        `m` - The method to be asynchronously invoked.
        `args` - The arguments to be used to invoke the method.
      Returns:
        `true` if the asynchronous execution request has been accepted, or `false` if this method cannot be asynchronously invoked by the AsyncDelegate.
      Throws:
        `java.lang.Exception` - An exception should be thrown only if there was a serious error that prevented the asynchronous task from starting. For example, the specified method does not exist on this object. Exceptions must not be thrown to indicate that the call does not support asynchronous invocation. Instead this method must return `false`. Exceptions must also not be thrown to indicate a failure from the execution of the underlying method.