Promise (Vavr 0.9.2 API)

Type Parameters:

T - The result type of the underlying Future.
```
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 ExecutorService 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:
- create new promises: make()
And we may create new promises that are already finished:
All the static factory methods mentioned above have additional versions which take an ExecutorService 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.
Author:

Daniel Dietrich

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`default Promise<T>`	`complete(Try<? extends T> value)` Completes this `Promise` with the given `value`.
`default Promise<T>`	`completeWith(Future<? extends T> other)` Completes this `Promise` with the given `Future`, once that `Future` is completed.
`ExecutorService`	`executorService()` Returns the `ExecutorService` used by this `Future`.
`static <T> Promise<T>`	`failed(ExecutorService executorService, Throwable exception)` Creates a failed `Promise`, backed by the given `ExecutorService`.
`static <T> Promise<T>`	`failed(Throwable exception)` Creates a failed `Promise`, backed by the `Future.DEFAULT_EXECUTOR_SERVICE`.
`default Promise<T>`	`failure(Throwable exception)` Completes this `Promise` with the given `exception`.
`static <T> Promise<T>`	`fromTry(ExecutorService executorService, Try<? extends T> result)` Creates a `Promise` from a `Try`, backed by the given `ExecutorService`.
`static <T> Promise<T>`	`fromTry(Try<? extends T> result)` Creates a `Promise` from a `Try`, backed by the `Future.DEFAULT_EXECUTOR_SERVICE`.
`Future<T>`	`future()` Returns the underlying `Future` of this `Promise`.
`default boolean`	`isCompleted()` Checks if this `Promise` is completed, i.e.
`static <T> Promise<T>`	`make()` Makes a `Promise` that isn't fulfilled yet, backed by the `Future.DEFAULT_EXECUTOR_SERVICE`.
`static <T> Promise<T>`	`make(ExecutorService executorService)` Makes a `Promise` that isn't fulfilled yet, backed by the given `ExecutorService`.
`static <T> Promise<T>`	`narrow(Promise<? extends T> promise)` Narrows a widened `Promise<? extends T>` to `Promise<T>` by performing a type-safe cast.
`default Promise<T>`	`success(T value)` Completes this `Promise` with the given `value`.
`static <T> Promise<T>`	`successful(ExecutorService executorService, T result)` Creates a succeeded `Promise`, backed by the given `ExecutorService`.
`static <T> Promise<T>`	`successful(T result)` Creates a succeeded `Promise`, backed by the `Future.DEFAULT_EXECUTOR_SERVICE`.
`boolean`	`tryComplete(Try<? extends T> value)` Attempts to completes this `Promise` with the given `value`.
`default Promise<T>`	`tryCompleteWith(Future<? extends T> other)` Attempts to complete this `Promise` with the specified `Future`, once that `Future` is completed.
`default boolean`	`tryFailure(Throwable exception)` Completes this `Promise` with the given `exception`.
`default boolean`	`trySuccess(T value)` Completes this `Promise` with the given `value`.

- Method Detail
  - failed
```
static <T> Promise<T> failed(Throwable exception)
```
    Creates a failed Promise, backed by the Future.DEFAULT_EXECUTOR_SERVICE.
    
    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(ExecutorService executorService,
                             Throwable exception)
```
    Creates a failed Promise, backed by the given ExecutorService.
    
    Type Parameters:
    
    T - The value type of a successful result.
    
    Parameters:
    
    executorService - An ExecutorService passed to the underlying Future.
    
    exception - The reason why it failed.
    
    Returns:
    
    A failed Promise.
    
    Throws:
    
    NullPointerException - if executorService 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_SERVICE.
    
    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(ExecutorService executorService,
                              Try<? extends T> result)
```
    Creates a Promise from a Try, backed by the given ExecutorService.
    
    Type Parameters:
    
    T - The value type of a successful result.
    
    Parameters:
    
    executorService - An ExecutorService passed to the underlying Future.
    
    result - The result.
    
    Returns:
    
    A completed Promise which contains either a Success or a Failure.
    
    Throws:
    
    NullPointerException - if executorService or result is null
  - make
```
static <T> Promise<T> make()
```
    Makes a Promise that isn't fulfilled yet, backed by the Future.DEFAULT_EXECUTOR_SERVICE. ForkJoinPool.commonPool().
    
    Type Parameters:
    
    T - Result type of the Promise.
    
    Returns:
    
    A new Promise.
  - make
```
static <T> Promise<T> make(ExecutorService executorService)
```
    Makes a Promise that isn't fulfilled yet, backed by the given ExecutorService.
    
    Type Parameters:
    
    T - Result type of the Promise.
    
    Parameters:
    
    executorService - An ExecutorService passed to the underlying Future.
    
    Returns:
    
    A new Promise.
    
    Throws:
    
    NullPointerException - if executorService 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_SERVICE.
    
    Type Parameters:
    
    T - The value type of a successful result.
    
    Parameters:
    
    result - The result.
    
    Returns:
    
    A succeeded Promise.
  - successful
```
static <T> Promise<T> successful(ExecutorService executorService,
                                 T result)
```
    Creates a succeeded Promise, backed by the given ExecutorService.
    
    Type Parameters:
    
    T - The value type of a successful result.
    
    Parameters:
    
    executorService - An ExecutorService passed to the underlying Future.
    
    result - The result.
    
    Returns:
    
    A succeeded Promise.
    
    Throws:
    
    NullPointerException - if executorService is null
  - executorService
```
ExecutorService executorService()
```
    Returns the ExecutorService used by this Future.
    
    Returns:
    
    The underlying 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.

Interface Promise<T>

Creation

One-shot API

API for competing threads

Method Summary

Method Detail

failed

failed

fromTry

fromTry

make

make

narrow

successful

successful

executorService

future

isCompleted

complete

tryComplete

completeWith

tryCompleteWith

success

trySuccess

failure

tryFailure