Class Asynchronous.Result

  • Enclosing class:
    Asynchronous

    public static final class Asynchronous.Result
    extends java.lang.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
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static java.lang.ThreadLocal<java.util.concurrent.CompletableFuture<?>> FUTURES  
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private Result()  
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static <T> java.util.concurrent.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> java.util.concurrent.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​(java.util.concurrent.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
    • Field Detail

      • FUTURES

        private static final java.lang.ThreadLocal<java.util.concurrent.CompletableFuture<?>> FUTURES
    • Constructor Detail

      • Result

        private Result()
    • Method Detail

      • complete

        public static <T> java.util.concurrent.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:
        java.lang.IllegalStateException - if the CompletableFuture for an asynchronous method is not present on the thread.
      • getFuture

        public static <T> java.util.concurrent.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:
        java.lang.IllegalStateException - if the CompletableFuture for an asynchronous method is not present on the thread.
      • setFuture

        public static <T> void setFuture​(java.util.concurrent.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.