Promise (Sirius Kernel 3.3 API)

java.lang.Object
- sirius.kernel.async.Promise<V>

Type Parameters:

V - contains the type of the value which is to be computed

Direct Known Subclasses:

Future
```
public class Promise<V>
extends Object
```
Represents a value which is computed by another task or thread.
This is the core mechanism of non-blocking communication between different threads or systems. A value which is not immediately available is returned as Promise. This promise is either successfully fulfilled or supplied with a failure. In any case a CompletionHandler can be attached which is notified once the computation is completed.
Since promises can be chained (chain(Promise), failChain(Promise, sirius.kernel.commons.Callback)) or aggregated (Tasks.sequence(java.util.List), Barrier) complex computations can be glued together using simple components.

Constructor Summary

Constructors
Constructor and Description

Promise()

Constructors
Constructor and Description
`Promise()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`await(java.time.Duration timeout)` Waits until the promise is completed.
`void`	`chain(Promise<V> promise)` Chains this promise to the given one.
`Promise<V>`	`doNotLogErrors()` Disables the error logging even if no failure handlers are present.
`void`	`fail(Throwable exception)` Marks the promise as failed due to the given error.
`<X> Promise<V>`	`failChain(Promise<X> promise, Callback<V> successHandler)` Forwards failures to the given promise, while sending successful value to the given successHandler.
`<X> Promise<X>`	`flatMap(java.util.function.Function<V,Promise<X>> mapper)` Uses to result of this promise to generate a new promise using the given mapper.
`V`	`get()` Returns the value of the promise or `null` if not completed yet.
`Throwable`	`getFailure()` Returns the failure which was the reason for this promise to have failed.
`Promise<V>`	`handleErrors(Log log)` Adds an error handler, which handles failures by logging them to the given `Log` By default, if no explicit completion handler is present, all failures are logged using the `async` logger.
`boolean`	`isCompleted()` Determines if the promise is completed yet.
`boolean`	`isFailed()` Determines if the promise is failed.
`boolean`	`isSuccessful()` Determines if the promise was successfully completed yet.
`<X> Promise<X>`	`map(java.util.function.Function<V,X> mapper)` Used the result of this promise to create a new one by passing the resulting value into the given mapper.
`<X> void`	`mapChain(Promise<X> promise, java.util.function.Function<V,X> mapper)` Chains this promise to the given one, by transforming the result value of this promise using the given mapper.
`Promise<V>`	`onComplete(CompletionHandler<V> handler)` Adds a completion handler to this promise.
`Promise<V>`	`onFailure(java.util.function.Consumer<Throwable> failureHandler)` Adds a completion handler to this promise which only handles the failed completion of the promise.
`Promise<V>`	`onFailureCallback(Callback<Throwable> failureHandler)` Adds a completion handler to this promise which only handles the failed completion of the promise.
`Promise<V>`	`onSuccess(java.util.function.Consumer<V> successHandler)` Adds a completion handler to this promise which only handles the successful completion of the promise.
`Promise<V>`	`onSuccessCallback(Callback<V> successHandler)` Adds a completion handler to this promise which only handles the successful completion of the promise.
`void`	`success(V value)` Marks the promise as successful and completed with the given value.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Promise
```
public Promise()
```
- Method Detail
  - get
```
public V get()
```
    Returns the value of the promise or null if not completed yet.
    
    Returns:
    
    the value of the promised computation. This method will not block, so null is returned if the computation has not finished (or failed) yet.
  - success
```
public void success(@Nullable
                    V value)
```
    Marks the promise as successful and completed with the given value.
    
    Parameters:
    
    value - the value to be used as promised result.
  - fail
```
public void fail(@Nonnull
                 Throwable exception)
```
    Marks the promise as failed due to the given error.
    
    Parameters:
    
    exception - the error to be used as reason for failure.
  - isCompleted
```
public boolean isCompleted()
```
    Determines if the promise is completed yet.
    
    Returns:
    
    true if the promise has either successfully completed or failed yet, false otherwise.
  - isFailed
```
public boolean isFailed()
```
    Determines if the promise is failed.
    
    Returns:
    
    true if the promise failed, false otherwise.
  - isSuccessful
```
public boolean isSuccessful()
```
    Determines if the promise was successfully completed yet.
    
    Returns:
    
    true if the promise was successfully completed, false otherwise.
  - await
```
public boolean await(java.time.Duration timeout)
```
    Waits until the promise is completed.
    
    Parameters:
    
    timeout - the maximal time to wait for the completion of this promise.
    
    Returns:
    
    true if the promise was completed within the given timeout, false otherwise
  - getFailure
```
public Throwable getFailure()
```
    Returns the failure which was the reason for this promise to have failed.
    
    Returns:
    
    the error which made this promise fail, or null if the promnise is still running or not completed yet.
  - map
```
@Nonnull
public <X> Promise<X> map(@Nonnull
                                   java.util.function.Function<V,X> mapper)
```
    Used the result of this promise to create a new one by passing the resulting value into the given mapper.
    
    Type Parameters:
    
    X - the resulting type of the mapper
    
    Parameters:
    
    mapper - the mapper to transform the promised value of this promise.
    
    Returns:
    
    a new promise which will be either contain the mapped value or which fails if either this promise fails or if the mapper throws an exception.
  - flatMap
```
@Nonnull
public <X> Promise<X> flatMap(@Nonnull
                                       java.util.function.Function<V,Promise<X>> mapper)
```
    Uses to result of this promise to generate a new promise using the given mapper.
    
    Type Parameters:
    
    X - the resulting type of the mapper
    
    Parameters:
    
    mapper - the mapper to transform the promised value of this promise.
    
    Returns:
    
    a new promise which will be either contain the mapped value or which fails if either this promise fails or if the mapper throws an exception.
  - chain
```
public void chain(@Nonnull
                  Promise<V> promise)
```
    Chains this promise to the given one.
    Connects both, the successful path as well as the failure handling of this promise to the given one.
    
    Parameters:
    
    promise - the promise to be used as completion handler for this.
  - mapChain
```
public <X> void mapChain(@Nonnull
                         Promise<X> promise,
                         @Nonnull
                         java.util.function.Function<V,X> mapper)
```
    Chains this promise to the given one, by transforming the result value of this promise using the given mapper.
    
    Type Parameters:
    
    X - type of the value expected by the given promise.
    
    Parameters:
    
    promise - the promise to be used as completion handler for this.
    
    mapper - the mapper to be used to convert the result of this promise to the value used to the given promise.
  - failChain
```
@Nonnull
public <X> Promise<V> failChain(@Nonnull
                                         Promise<X> promise,
                                         @Nonnull
                                         Callback<V> successHandler)
```
    Forwards failures to the given promise, while sending successful value to the given successHandler.
    
    Type Parameters:
    
    X - type of promised value of the given promise.
    
    Parameters:
    
    promise - the promise to be supplied with any failure of this promise.
    
    successHandler - the handler used to process successfully computed values.
    
    Returns:
    
    this for fluent method chaining
  - onComplete
```
@Nonnull
public Promise<V> onComplete(@Nonnull
                                      CompletionHandler<V> handler)
```
    Adds a completion handler to this promise.
    If the promise is already completed, the handler is immediately invoked.
    
    Parameters:
    
    handler - the handler to be notified once the promise is completed. A promise can notify more than one handler.
    
    Returns:
    
    this for fluent method chaining
  - onSuccessCallback
```
@Nonnull
public Promise<V> onSuccessCallback(@Nonnull
                                             Callback<V> successHandler)
```
    Adds a completion handler to this promise which only handles the successful completion of the promise.
    If the promise is already completed, the handler is immediately invoked.
    
    Parameters:
    
    successHandler - the handler to be notified once the promise is completed. A promise can notify more than one handler.
    
    Returns:
    
    this for fluent method chaining
  - onSuccess
```
@Nonnull
public Promise<V> onSuccess(@Nonnull
                                     java.util.function.Consumer<V> successHandler)
```
    Adds a completion handler to this promise which only handles the successful completion of the promise.
    If the promise is already completed, the handler is immediately invoked.
    
    Parameters:
    
    successHandler - the handler to be notified once the promise is completed. A promise can notify more than one handler.
    
    Returns:
    
    this for fluent method chaining
  - onFailureCallback
```
@Nonnull
public Promise<V> onFailureCallback(@Nonnull
                                             Callback<Throwable> failureHandler)
```
    Adds a completion handler to this promise which only handles the failed completion of the promise.
    If the promise is already completed, the handler is immediately invoked.
    
    Parameters:
    
    failureHandler - the handler to be notified once the promise is completed. A promise can notify more than one handler.
    
    Returns:
    
    this for fluent method chaining
  - onFailure
```
@Nonnull
public Promise<V> onFailure(@Nonnull
                                     java.util.function.Consumer<Throwable> failureHandler)
```
    Adds a completion handler to this promise which only handles the failed completion of the promise.
    If the promise is already completed, the handler is immediately invoked.
    
    Parameters:
    
    failureHandler - the handler to be notified once the promise is completed. A promise can notify more than one handler.
    
    Returns:
    
    this for fluent method chaining
  - doNotLogErrors
```
public Promise<V> doNotLogErrors()
```
    Disables the error logging even if no failure handlers are present.
    
    Returns:
    
    this for fluent method chaining
  - handleErrors
```
@Nonnull
public Promise<V> handleErrors(@Nonnull
                                        Log log)
```
    Adds an error handler, which handles failures by logging them to the given Log
    By default, if no explicit completion handler is present, all failures are logged using the async logger.
    
    Parameters:
    
    log - the logger to be used when logging an error.
    
    Returns:
    
    this for fluent method chaining

Class Promise<V>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Promise

Method Detail

get

success

fail

isCompleted

isFailed

isSuccessful

await

getFailure

map

flatMap

chain

mapChain

failChain

onComplete

onSuccessCallback

onSuccess

onFailureCallback

onFailure

doNotLogErrors

handleErrors