Interface Promise<T>

Type Parameters:
T - the type of the value that completes the underlying Future
All Known Implementing Classes:
PromiseImpl
public interface Promise<T>
A Promise is a write-once container for a read-only Future, allowing the underlying Future to be completed with a value or an exception.

The associated Executor is used to run asynchronous handlers, for example, via promise.future().onComplete(...).

Creation

Promise provides static factory methods to create new promises:

All factory methods also have variants that accept an Executor, allowing finer control over thread usage and thread pool configuration.

One-shot API

When a single Thread is responsible for completing the Promise, use one of the following methods. Calls will throw an exception if the Promise has already been completed:

API for concurrent completion

When multiple Threads may attempt to complete the Promise, use one of the following "try" methods. Calls will return false if the Promise is already completed:

  • Method Summary

    Modifier and Type
    Method
    Description
    default Promise<T>
    complete(@NonNull Try<? extends T> value)
    Completes this Promise with the given value.
    default Promise<T>
    completeWith(@NonNull Future<? extends T> other)
    Completes this Promise with the result of the given Future once it is completed.
    default Executor
    executor()
    Returns the Executor used by the underlying Future of this Promise.
    ExecutorService
    executorService()
    Deprecated.
    Removed starting with Vavr 0.10.0, use executor() instead.
    static <T> Promise<T>
    failed(@NonNull Throwable exception)
    Creates a Promise that is already completed with a failure, using the Future.DEFAULT_EXECUTOR for asynchronous operations.
    static <T> Promise<T>
    failed(@NonNull Executor executor, @NonNull Throwable exception)
    Creates a Promise that is already completed with a failure, using the specified Executor for asynchronous operations.
    default Promise<T>
    failure(@NonNull Throwable exception)
    Completes this Promise with the given exception.
    static <T> Promise<T>
    fromTry(@NonNull Try<? extends T> result)
    Creates a Promise from the given Try, using the Future.DEFAULT_EXECUTOR for asynchronous operations.
    static <T> Promise<T>
    fromTry(@NonNull Executor executor, @NonNull Try<? extends T> result)
    Creates a Promise from the given Try, using the specified Executor for asynchronous operations.
    Future<T>
    future()
    Returns the underlying Future associated with this Promise.
    default boolean
    isCompleted()
    Checks whether this Promise has been completed, either successfully or with a failure.
    static <T> Promise<T>
    make()
    Creates a new Promise that is not yet completed, using the Future.DEFAULT_EXECUTOR (typically ForkJoinPool.commonPool()) for asynchronous operations.
    static <T> Promise<T>
    make(@NonNull Executor executor)
    Creates a new Promise that is not yet completed, using the specified Executor for asynchronous operations.
    static <T> Promise<T>
    narrow(Promise<? extends T> promise)
    Narrows a Promise<? extends T> to Promise<T> through a type-safe cast.
    default Promise<T>
    success(T value)
    Completes this Promise with the given value.
    static <T> Promise<T>
    successful(@NonNull Executor executor, T result)
    Creates a Promise that is already completed successfully, using the specified Executor for asynchronous operations.
    static <T> Promise<T>
    successful(T result)
    Creates a Promise that is already completed successfully, using the Future.DEFAULT_EXECUTOR for asynchronous operations.
    boolean
    tryComplete(@NonNull Try<? extends T> value)
    Attempts to complete this Promise with the given value.
    default Promise<T>
    tryCompleteWith(@NonNull Future<? extends T> other)
    Attempts to complete this Promise with the result of the given Future once it is completed.
    default boolean
    tryFailure(@NonNull Throwable exception)
    Attempts to complete this Promise with the given exception.
    default boolean
    trySuccess(T value)
    Attempts to complete this Promise with the given value.

  • Method Details

    • failed

      static <T> Promise<T> failed(@NonNull Throwable exception)
      Creates a Promise that is already completed with a failure, using the Future.DEFAULT_EXECUTOR for asynchronous operations.
      Type Parameters:
      T - the type of the value that would have been returned on success
      Parameters:
      exception - the cause of the failure
      Returns:
      a Promise completed with the given failure
      Throws:
      NullPointerException - if exception is null

    • failed

      static <T> Promise<T> failed(@NonNull Executor executor, @NonNull Throwable exception)
      Creates a Promise that is already completed with a failure, using the specified Executor for asynchronous operations.
      Type Parameters:
      T - the type of the value that would have been returned on success
      Parameters:
      executor - the Executor used by the underlying Future
      exception - the cause of the failure
      Returns:
      a Promise completed with the given failure
      Throws:
      NullPointerException - if executor or exception is null

    • fromTry

      static <T> Promise<T> fromTry(@NonNull Try<? extends T> result)
      Creates a Promise from the given Try, using the Future.DEFAULT_EXECUTOR for asynchronous operations.
      Type Parameters:
      T - the type of the value in case of success
      Parameters:
      result - the Try representing a success or failure
      Returns:
      a Promise already completed with the given Try result
      Throws:
      NullPointerException - if result is null

    • fromTry

      static <T> Promise<T> fromTry(@NonNull Executor executor, @NonNull Try<? extends T> result)
      Creates a Promise from the given Try, using the specified Executor for asynchronous operations.
      Type Parameters:
      T - the type of the value in case of success
      Parameters:
      executor - the Executor used by the underlying Future
      result - the Try representing a success or failure
      Returns:
      a Promise already completed with the given Try result
      Throws:
      NullPointerException - if executor or result is null

    • make

      static <T> Promise<T> make()
      Creates a new Promise that is not yet completed, using the Future.DEFAULT_EXECUTOR (typically ForkJoinPool.commonPool()) for asynchronous operations.
      Type Parameters:
      T - the type of the value that will complete the Promise
      Returns:
      a new, uncompleted Promise

    • make

      static <T> Promise<T> make(@NonNull Executor executor)
      Creates a new Promise that is not yet completed, using the specified Executor for asynchronous operations.
      Type Parameters:
      T - the type of the value that will complete the Promise
      Parameters:
      executor - the Executor used by the underlying Future
      Returns:
      a new, uncompleted Promise
      Throws:
      NullPointerException - if executor is null

    • narrow

      static <T> Promise<T> narrow(Promise<? extends T> promise)
      Narrows a Promise<? extends T> to Promise<T> through a type-safe cast. This is safe because immutable or read-only collections are covariant.
      Type Parameters:
      T - the component type of the Promise
      Parameters:
      promise - the Promise to narrow
      Returns:
      the same promise instance, cast to Promise<T>

    • successful

      static <T> Promise<T> successful(T result)
      Creates a Promise that is already completed successfully, using the Future.DEFAULT_EXECUTOR for asynchronous operations.
      Type Parameters:
      T - the type of the value
      Parameters:
      result - the value of the successful result
      Returns:
      a Promise already completed with the given result

    • successful

      static <T> Promise<T> successful(@NonNull Executor executor, T result)
      Creates a Promise that is already completed successfully, using the specified Executor for asynchronous operations.
      Type Parameters:
      T - the type of the value
      Parameters:
      executor - the Executor used by the underlying Future
      result - the value of the successful result
      Returns:
      a Promise already completed with the given result
      Throws:
      NullPointerException - if executor is null

    • executor

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

    • 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 associated with this Promise.
      Returns:
      the underlying Future

    • isCompleted

      default boolean isCompleted()
      Checks whether this Promise has been completed, either successfully or with a failure.
      Returns:
      true if the Promise is completed, false otherwise

    • complete

      default Promise<T> complete(@NonNull Try<? extends T> value)
      Completes this Promise with the given value.
      Parameters:
      value - 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(@NonNull Try<? extends T> value)
      Attempts to complete this Promise with the given value.
      Parameters:
      value - a Try.Success containing the result or a Try.Failure containing an exception
      Returns:
      true if the Promise was completed successfully, false if it was already completed

    • completeWith

      default Promise<T> completeWith(@NonNull Future<? extends T> other)
      Completes this Promise with the result of the given Future once it is completed.
      Parameters:
      other - the Future whose result or failure will complete this Promise
      Returns:
      this Promise

    • tryCompleteWith

      default Promise<T> tryCompleteWith(@NonNull Future<? extends T> other)
      Attempts to complete this Promise with the result of the given Future once it is completed.
      Parameters:
      other - the Future whose result or failure may complete this Promise
      Returns:
      true if this Promise was completed by other, false if it was already completed

    • success

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

    • trySuccess

      default boolean trySuccess(T value)
      Attempts to complete this Promise with the given value.
      Parameters:
      value - the value to complete this Promise with
      Returns:
      true if the Promise was completed successfully, false if it was already completed

    • failure

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

    • tryFailure

      default boolean tryFailure(@NonNull Throwable exception)
      Attempts to complete this Promise with the given exception.
      Parameters:
      exception - the exception to complete this Promise with
      Returns:
      true if the Promise was completed successfully, false if it was already completed