Interface Promise<T>

Type Parameters:
T - The result type of the underlying Future.
All Known Implementing Classes:
PromiseImpl
public interface Promise<T>
A Promise is a write-once wrapper around a read-only Future which can complete the underlying Future with a value or an exception.

The underlying Executor is used to execute asynchronous handlers, e.g. via promise.future().onComplete(...).

Creation

Promise offers static factory methods to create new promises which hasn't been fulfilled yet:

And we may create new promises that are already finished: All the static factory methods mentioned above have additional versions which take an Executor as argument. This gives us more control over thread creation and thread pool sizes.

One-shot API

The main purpose of a Promise is to complete its underlying Future. When only a single Thread will eventually complete the Promise, we use one of these methods. Calls will throw if the Promise is already completed.

API for competing threads

When multiple Threads may complete our Promise, we typically use one of these methods. Calls will gracefully return false if the Promise is already completed.

  • Method Details

    • failed

      static <T> Promise<T> failed(Throwable exception)
      Creates a failed Promise, backed by the Future.DEFAULT_EXECUTOR.
      Type Parameters:
      T - The value type of a successful result.
      Parameters:
      exception - The reason why it failed.
      Returns:
      A failed Promise.
      Throws:
      NullPointerException - if exception is null

    • failed

      static <T> Promise<T> failed(Executor executor, Throwable exception)
      Creates a failed Promise, backed by the given Executor.
      Type Parameters:
      T - The value type of a successful result.
      Parameters:
      executor - An Executor passed to the underlying Future.
      exception - The reason why it failed.
      Returns:
      A failed Promise.
      Throws:
      NullPointerException - if executor or exception is null

    • fromTry

      static <T> Promise<T> fromTry(Try<? extends T> result)
      Creates a Promise from a Try, backed by the Future.DEFAULT_EXECUTOR.
      Type Parameters:
      T - The value type of a successful result.
      Parameters:
      result - The result.
      Returns:
      A completed Promise which contains either a Success or a Failure.
      Throws:
      NullPointerException - if result is null

    • fromTry

      static <T> Promise<T> fromTry(Executor executor, Try<? extends T> result)
      Creates a Promise from a Try, backed by the given Executor.
      Type Parameters:
      T - The value type of a successful result.
      Parameters:
      executor - An Executor passed to the underlying Future.
      result - The result.
      Returns:
      A completed Promise which contains either a Success or a Failure.
      Throws:
      NullPointerException - if executor or result is null

    • make

      static <T> Promise<T> make()
      Makes a Promise that isn't fulfilled yet, backed by the Future.DEFAULT_EXECUTOR. ForkJoinPool.commonPool().
      Type Parameters:
      T - Result type of the Promise.
      Returns:
      A new Promise.

    • make

      static <T> Promise<T> make(Executor executor)
      Makes a Promise that isn't fulfilled yet, backed by the given Executor.
      Type Parameters:
      T - Result type of the Promise.
      Parameters:
      executor - An Executor passed to the underlying Future.
      Returns:
      A new Promise.
      Throws:
      NullPointerException - if executor is null

    • narrow

      static <T> Promise<T> narrow(Promise<? extends T> promise)
      Narrows a widened Promise<? extends T> to Promise<T> by performing a type-safe cast. This is eligible because immutable/read-only collections are covariant.
      Type Parameters:
      T - Component type of the Promise.
      Parameters:
      promise - A Promise.
      Returns:
      the given promise instance as narrowed type Promise<T>.

    • successful

      static <T> Promise<T> successful(T result)
      Creates a succeeded Promise, backed by the Future.DEFAULT_EXECUTOR.
      Type Parameters:
      T - The value type of a successful result.
      Parameters:
      result - The result.
      Returns:
      A succeeded Promise.

    • successful

      static <T> Promise<T> successful(Executor executor, T result)
      Creates a succeeded Promise, backed by the given Executor.
      Type Parameters:
      T - The value type of a successful result.
      Parameters:
      executor - An Executor passed to the underlying Future.
      result - The result.
      Returns:
      A succeeded Promise.
      Throws:
      NullPointerException - if executor is null

    • executor

      default Executor executor()
      Returns the Executor used by the underlying Future of this Promise.
      Returns:
      The underlying Executor.

    • executorService

      @Deprecated ExecutorService executorService()
      Deprecated.
      Removed starting with Vavr 0.10.0, use executor() instead.
      This method is deprecated.

      THE DEFAULT IMPLEMENTATION (obtained by one of the Promise factory methods) MIGHT THROW AN UnsupportedOperationException AT RUNTIME, DEPENDING ON WHAT Future.executorService() returns.

      Returns:
      (never)
      Throws:
      UnsupportedOperationException - if the underlying Executor isn't an ExecutorService.

    • future

      Future<T> future()
      Returns the underlying Future of this Promise.
      Returns:
      The Future.

    • isCompleted

      default boolean isCompleted()
      Checks if this Promise is completed, i.e. has a value.
      Returns:
      true, if the computation successfully finished or failed, false otherwise.

    • complete

      default Promise<T> complete(Try<? extends T> value)
      Completes this Promise with the given value.
      Parameters:
      value - Either a Try.Success containing the result or a Try.Failure containing an exception.
      Returns:
      This Promise.
      Throws:
      IllegalStateException - if this Promise has already been completed.

    • tryComplete

      boolean tryComplete(Try<? extends T> value)
      Attempts to completes this Promise with the given value.
      Parameters:
      value - Either a Try.Success containing the result or a Try.Failure containing an exception.
      Returns:
      false if this Promise has already been completed, true otherwise.
      Throws:
      IllegalStateException - if this Promise has already been completed.

    • completeWith

      default Promise<T> completeWith(Future<? extends T> other)
      Completes this Promise with the given Future, once that Future is completed.
      Parameters:
      other - Another Future to react on.
      Returns:
      This Promise.

    • tryCompleteWith

      default Promise<T> tryCompleteWith(Future<? extends T> other)
      Attempts to complete this Promise with the specified Future, once that Future is completed.
      Parameters:
      other - Another Future to react on.
      Returns:
      This Promise.

    • success

      default Promise<T> success(T value)
      Completes this Promise with the given value.
      Parameters:
      value - A value.
      Returns:
      This Promise.
      Throws:
      IllegalStateException - if this Promise has already been completed.

    • trySuccess

      default boolean trySuccess(T value)
      Completes this Promise with the given value.
      Parameters:
      value - A value.
      Returns:
      false if this Promise has already been completed, true otherwise.

    • failure

      default Promise<T> failure(Throwable exception)
      Completes this Promise with the given exception.
      Parameters:
      exception - An exception.
      Returns:
      This Promise.
      Throws:
      IllegalStateException - if this Promise has already been completed.

    • tryFailure

      default boolean tryFailure(Throwable exception)
      Completes this Promise with the given exception.
      Parameters:
      exception - An exception.
      Returns:
      false if this Promise has already been completed, true otherwise.