Annotation Interface Asynchronous
RequestScoped
must be active during the method invocation, which means the method with the @Asynchronous
annotation is
allowed to use the beans with RequestScoped
. Any methods marked with this
annotation must return one of:
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, callingFuture.get()
on the Future returned in Thread A will throw anExecutionException
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;
});