Package io.smallrye.faulttolerance.core

Interface Future<T>

Type Parameters:
T - type of the result of the computation
public interface Future<T>
Represents a computation that may still be running, and allows obtaining a result of the computation once available.

When the computation is still running, we say that the future is pending. Once the computation finishes, we say that the future is complete. Alternatively, after successful cancellation, we say the future is cancelled. The computation may finish with two kinds of outcomes: success, producing a value, and failure, producing an error.

To obtain the result, consumers of the future are expected to register a completion callback using Future.then(). The callback is called with a pair [value, error] once the future completes. To distinguish a sucessful outcome from a failure, the error should be tested. If the error is null, the outcome is successful. Note that a success may still produce a null value.

The callback may be registered before or after the future completes, and is guaranteed to be called exactly once. The thread on which the callback is called is not specified; it may be the thread that completes the future or the thread that registers the callback. Only one callback may be registered; attempts to register a second callback end up with an exception.

Future objects are created by a Completer. The Completer is also the only way through which the future may be completed. For convenience, static factory methods are provided to construct already complete futures: Future.of(), Future.ofError(), and Future.from().

A future consumer may request cancellation of the computation by calling Future.cancel(). This is only possible while the future is pending; when the future is already complete, this is a noop.

Unlike common Future abstractions, this one is fairly limited. There may only be one completion callback, and there are no combinators such as map or flatMap.

  • Method Summary

    Modifier and Type
    Method
    Description
    T
    awaitBlocking()
    Blocks the calling thread until this future is complete or cancelled, and then returns the value of this future or throws the error, or throws CancellationException.
    void
    cancel()
    Requests cancellation of the computation represented by this future.
    static <T> Future<T>
    from(Callable<T> callable)
    Returns a future that is already complete with the outcome of given callable (which may be a returned value or a thrown error).
    boolean
    isCancelled()
    Returns whether this future is cancelled.
    boolean
    isComplete()
    Returns whether this future is complete.
    static <T> Future<T>
    of(T value)
    Returns a future that is already complete with given value.
    static <T> Future<T>
    ofError(Throwable error)
    Returns a future that is already complete with given error.
    void
    then(BiConsumer<T,Throwable> callback)
    Registers a completion callback with this future.
    void
    thenComplete(Completer<T> completer)
    Registers a completion callback with this future.

  • Method Details

    • of

      static <T> Future<T> of(T value)
      Returns a future that is already complete with given value.
      Type Parameters:
      T - type of the value
      Parameters:
      value - the value; may be null
      Returns:
      the future that is already complete with the value; never null

    • ofError

      static <T> Future<T> ofError(Throwable error)
      Returns a future that is already complete with given error.
      Type Parameters:
      T - type of hypothetical result; only for type inference
      Parameters:
      error - the error; must not be null
      Returns:
      the future that is already complete with the error; never null

    • from

      static <T> Future<T> from(Callable<T> callable)
      Returns a future that is already complete with the outcome of given callable (which may be a returned value or a thrown error).
      Type Parameters:
      T - type of the result of given callable
      Parameters:
      callable - the callable to call; must not be null
      Returns:
      the future that is complete with the outcome of the callable; never null

    • then

      void then(BiConsumer<T,Throwable> callback)
      Registers a completion callback with this future. The first argument of the BiConsumer is the value of the future, the second argument is the error.

      Value may be null in case of a success, but error is never null in case of a failure. Therefore, idiomatic usage looks like: 

       future.then((value, error) -> {
     if (error == null) {
         ... use value ...
     } else {
         ... use error ...
     }
 });
      Parameters:
      callback - the completion callback to be registered; must not be null

    • thenComplete

      void thenComplete(Completer<T> completer)
      Registers a completion callback with this future. The callback forwards the result of this future into the given completer.
      Parameters:
      completer - the completer to which the result of this future is forwarded; must not be null

    • isComplete

      boolean isComplete()
      Returns whether this future is complete.
      Returns:
      true if this future is complete, false otherwise

    • isCancelled

      boolean isCancelled()
      Returns whether this future is cancelled.
      Returns:
      true if this future is cancelled, false otherwise

    • awaitBlocking

      T awaitBlocking() throws Throwable
      Blocks the calling thread until this future is complete or cancelled, and then returns the value of this future or throws the error, or throws CancellationException. In case this future is already complete or cancelled when this method is called, no blocking occurs.

      The blocked thread may be interrupted, in which case this method throws InterruptedException.

      This method should rarely be used without previous checking with isComplete() or isCancelled().

      Returns:
      the value of this future; may be null
      Throws:
      Throwable - the error of this future, CancellationException or InterruptedException

    • cancel

      void cancel()
      Requests cancellation of the computation represented by this future.
      See Also: