Module jakarta.concurrency

Package jakarta.enterprise.concurrent

Class Asynchronous.Result

java.lang.Object

jakarta.enterprise.concurrent.Asynchronous.Result

Enclosing class:

Asynchronous

public static final class Asynchronous.Result
extends Object

Mechanism by which the Jakarta EE Product Provider makes available to the asynchronous method implementation the same CompletableFuture instance that the Jakarta EE Product Provider supplies to the caller of the asynchronous method.

Before invoking the asynchronous method implementation on a thread, the Jakarta EE Product Provider invokes the setFuture(java.util.concurrent.CompletableFuture<T>) method which makes available to the asynchronous method implementation the same CompletableFuture that the Jakarta EE Product Provider returns to the caller.

The asynchronous method implementation invokes the getFuture() method to obtain the same CompletableFuture that the Jakarta EE Product Provider returns to the caller. The asynchronous method implementation can choose to complete this future (normally or exceptionally) or otherwise arrange for its completion, for example upon completion of a pipeline of completion stages. Having this same CompletableFuture also enables the asynchronous method implementation to determine if the caller has forcibly completed (such as by cancellation or any other means) the CompletableFuture, in which case the asynchronous method implementation could decide to end immediately rather than continue processing.

For example,

 @Asynchronous
 public CompletableFuture<Double> hoursWorked(LocalDateTime from, LocalDateTime to) {
     CompletableFuture<Double> future = Asynchronous.Result.getFuture();
     if (future.isDone())
         return future;

     try (Connection con = ((DataSource) InitialContext.doLookup(
         "java:comp/env/jdbc/timesheetDB")).getConnection()) {
         ...
         for (ResultSet result = stmt.executeQuery(); result.next() && !future.isDone(); )
             ...
         future.complete(total);
     } catch (NamingException | SQLException x) {
         future.completeExceptionally(x);
     }
     return future;
 }
 

After the asynchronous method completes, the Jakarta EE Product Provider invokes the setFuture(java.util.concurrent.CompletableFuture<T>) method with a null value to clear it from the thread.

Since:

3.0

Method Summary

Modifier and Type	Method	Description
static <T> CompletableFuture<T>	complete(T result)	Completes the CompletableFuture instance that the Jakarta EE Product Provider supplies to the caller of the asynchronous method.
static <T> CompletableFuture<T>	getFuture()	Obtains the same CompletableFuture instance that the Jakarta EE Product Provider supplies to the caller of the asynchronous method.
static <T> void	setFuture(CompletableFuture<T> future)	Before invoking the asynchronous method implementation on a thread, the Jakarta EE Product Provider invokes this method to make available to the asynchronous method implementation the same CompletableFuture that the Jakarta EE Product Provider returns to the caller.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

complete

public static <T> CompletableFuture<T> complete(T result)

Completes the CompletableFuture instance that the Jakarta EE Product Provider supplies to the caller of the asynchronous method.

This method must only be invoked by the asynchronous method implementation.

Type Parameters:

T - type of result returned by the asynchronous method's CompletableFuture.

Parameters:

result - result with which to complete the asynchronous method's CompletableFuture.

Returns:

the same CompletableFuture that the container returns to the caller.

Throws:

IllegalStateException - if the CompletableFuture for an asynchronous method is not present on the thread.

getFuture

public static <T> CompletableFuture<T> getFuture()

Obtains the same CompletableFuture instance that the Jakarta EE Product Provider supplies to the caller of the asynchronous method.

This method must only be invoked by the asynchronous method implementation.

Type Parameters:

T - type of result returned by the asynchronous method's CompletableFuture.

Returns:

the same CompletableFuture that the container returns to the caller.

Throws:

IllegalStateException - if the CompletableFuture for an asynchronous method is not present on the thread.

setFuture

public static <T> void setFuture(CompletableFuture<T> future)

Before invoking the asynchronous method implementation on a thread, the Jakarta EE Product Provider invokes this method to make available to the asynchronous method implementation the same CompletableFuture that the Jakarta EE Product Provider returns to the caller.

After the asynchronous method completes, the Jakarta EE Product Provider invokes this method with a null value to clear it from the thread.

This method must only be invoked by the Jakarta EE Product Provider.

Type Parameters:

T - type of result returned by the asynchronous method's CompletableFuture.

Parameters:

future - CompletableFuture that the container returns to the caller, or null to clear it.