V
- contains the type of the value which is to be computedpublic class Promise<V> extends Object
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 and Description |
---|
Promise() |
Modifier and Type | Method and Description |
---|---|
boolean |
await(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.
|
Promise<V> |
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(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(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,
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(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(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.
|
Promise<V> |
success(V value)
Marks the promise as successful and completed with the given value.
|
public V get()
public Promise<V> success(@Nullable V value)
value
- the value to be used as promised result.public Promise<V> fail(@Nonnull Throwable exception)
exception
- the error to be used as reason for failure.public boolean isCompleted()
public boolean isFailed()
public boolean isSuccessful()
public boolean await(Duration timeout)
timeout
- the maximal time to wait for the completion of this promise.public Throwable getFailure()
@Nonnull public <X> Promise<X> map(@Nonnull Function<V,X> mapper)
X
- the resulting type of the mappermapper
- the mapper to transform the promised value of this promise.@Nonnull public <X> Promise<X> flatMap(@Nonnull Function<V,Promise<X>> mapper)
X
- the resulting type of the mappermapper
- the mapper to transform the promised value of this promise.public void chain(@Nonnull Promise<V> promise)
Connects both, the successful path as well as the failure handling of this promise to the given one.
promise
- the promise to be used as completion handler for this.public <X> void mapChain(@Nonnull Promise<X> promise, @Nonnull Function<V,X> mapper)
X
- type of the value expected by the given promise.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.@Nonnull public <X> Promise<V> failChain(@Nonnull Promise<X> promise, @Nonnull Callback<V> successHandler)
X
- type of promised value of the given promise.promise
- the promise to be supplied with any failure of this promise.successHandler
- the handler used to process successfully computed values.@Nonnull public Promise<V> onComplete(@Nonnull CompletionHandler<V> handler)
If the promise is already completed, the handler is immediately invoked.
handler
- the handler to be notified once the promise is completed. A promise can notify more than one
handler.@Nonnull public Promise<V> onSuccessCallback(@Nonnull Callback<V> successHandler)
If the promise is already completed, the handler is immediately invoked.
successHandler
- the handler to be notified once the promise is completed. A promise can notify more than
one handler.@Nonnull public Promise<V> onSuccess(@Nonnull Consumer<V> successHandler)
If the promise is already completed, the handler is immediately invoked.
successHandler
- the handler to be notified once the promise is completed. A promise can notify more than
one handler.@Nonnull public Promise<V> onFailureCallback(@Nonnull Callback<Throwable> failureHandler)
If the promise is already completed, the handler is immediately invoked.
failureHandler
- the handler to be notified once the promise is completed. A promise can notify more than
one handler.@Nonnull public Promise<V> onFailure(@Nonnull Consumer<Throwable> failureHandler)
If the promise is already completed, the handler is immediately invoked.
failureHandler
- the handler to be notified once the promise is completed. A promise can notify more than
one handler.public Promise<V> doNotLogErrors()
@Nonnull public Promise<V> handleErrors(@Nonnull Log log)
Log
By default, if no explicit completion handler is present, all failures are logged using the async logger.
log
- the logger to be used when logging an error.Copyright © 2018. All rights reserved.