org.eclipse.microprofile.faulttolerance

## Annotation Type Asynchronous

    @Documented
     @Retention(value=RUNTIME)
     @Target(value={METHOD,TYPE})
     @InterceptorBinding
     @Inherited
    public @interface Asynchronous

Wrap the execution and invoke it asynchronously. The context for `javax.enterprise.context.RequestScoped` must be active during the method invocation, which means the method with the `@Asynchronous` annotation is allowed to use the beans with `javax.enterprise.context.RequestScoped`. Any methods marked with this annotation must return one of:

- `Future`
- `CompletionStage`

Otherwise, `FaultToleranceDefinitionException` occurs during deployment. The return type `CompletionStage` is preferred over `Future` as a `Future` that completes exceptionally will not trigger other Fault Tolerance operations even if specified (e.g. Retry), while a `CompletionStage` that completes exceptionally will trigger other Fault Tolerance capabilities if specified (e.g. Retry).

When a method marked with this annotation is called from one thread (which we will call Thread A), the method call is intercepted, and execution of the method is submitted to run asynchronously on another thread (which we will call Thread B).

On Thread A, a Future or CompletionStage is returned immediately and can be used to get the result of the execution taking place on Thread B, once it is complete.

Before the execution on Thread B completes, the Future or CompletionStage returned in Thread A will report itself as incomplete. At this point, `Future` can be used to abort the execution.

Once the execution on Thread B is complete, the Future or CompletionStage returned in Thread A behaves differently depending on whether the execution in Thread B threw an exception:

- If the execution threw an exception, the Future or CompletionStage will be completed with that exception.
- If the execution returned normally, the Future or CompletionStage returned in Thread A will behave in the same way as the Future or CompletionStage returned from the execution in Thread B, i.e. it can be:
  - not complete yet
  - completed successfully with a return value
  - completed exceptionally

  At this point, any calls to the Future or CompletionStage returned in Thread A will be delegated to the Future or CompletionStage returned from the execution in Thread B.

The call made on Thread A will never throw an exception, even if the method declares that it throws checked exceptions, because the execution is going to occur on Thread B and hasn't happened yet. To avoid unnecessary `try..catch` blocks around these method calls, it's recommended that methods annotated with `@Asynchronous` do not declare that they throw checked exceptions.

Any exception thrown from the execution on Thread B, or raised by another Fault Tolerance component such as `Bulkhead` or `CircuitBreaker`, can be retrieved in the following ways:

- If the method declares `Future` as the return type, calling `Future` on the Future returned in Thread A will throw an `ExecutionException` wrapping the original exception.
- If the method declares `CompletionStage` as the return type, the CompletionStage returned in Thread A is completed exceptionally with the exception.

If a class is annotated with this annotation, all class methods are treated as if they were marked with this annotation. If one of the methods doesn't return either Future or CompletionStage, `FaultToleranceDefinitionException` occurs (at deploy time if the bean is discovered during deployment).

Example usage:

     @Asynchronous
     public CompletionStage<String> getString() {
      return CompletableFuture.completedFuture("hello");
     }

Example call with exception handling:

     CompletionStage stage = getString().exceptionally(e -> {
         handleException(e);
         return null;
     });

Author:
  Emily Jiang