@Documented
 @Retention(value=RUNTIME)
 @Target(value={METHOD,TYPE})
 @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.cancel(boolean) 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.get() 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;
 });