T
- the type being provided by the stagepublic interface Stage<T>
All methods are thread-safe guaranteeing that interactions with the stage are atomic.
A stage has four states:
The last three states are characterized as end states, a stage can only
transition into one of these, and when in an end-state will never go into another state. If a
stage is in and end state it is considered done, as is indicated by the
isDone()
method.
Naming conventions of methods are the following:
is*
, methods that query if the stage has reached a certain state.when*
, method that will be called once the stage reaches a certain state, but
otherwise has no effect on the stage. The returned stage does not have to wait for the operation
provided to end.then*
, method that will be called once the stage reaches a certain state, and
modifies the stage when that state has been reachedwith*
, method that will be called once the stage reaches a certain state, but does
modify the stage. But, the resulting stage must wait for the operation provided to the method
to end.Completable
Modifier and Type | Field and Description |
---|---|
static String |
CANCELLED |
static String |
COMPLETED |
static String |
FAILED |
static String |
PENDING |
Modifier and Type | Method and Description |
---|---|
boolean |
cancel()
Cancel the current stage.
|
Throwable |
cause()
Get the cause of a failed stage.
|
Stage<T> |
handle(Handle<? super T> handle)
Register a listener that is called on all three types of events for the current stage; completed,
failed, and cancelled.
|
boolean |
isCancelled()
Check if stage is in the cancelled state.
|
boolean |
isCompleted()
Check if stage is completed.
|
boolean |
isDone()
Indicates if the stage is done
|
boolean |
isFailed()
Check if the stage was exceptionally completed.
|
T |
join()
Join the result of the current stage.
|
T |
join(long timeout,
TimeUnit unit)
Join the result of the current stage with a timeout.
|
T |
joinNow()
Join the result of the current stage, or fail if it's state is still running.
|
<U> Stage<U> |
thenApply(Function<? super T,? extends U> fn)
Transform the value of the current stage into another type using an immediate function.
|
Stage<T> |
thenApplyFailed(Function<? super Throwable,? extends T> fn)
Apply a failed stage.
|
<U> Stage<U> |
thenCancel()
Build a stage is cancelled, but waits until the current stage completes.
|
<U> Stage<U> |
thenComplete(U result)
Build a stage is completed, but waits until the current stage completes.
|
<U> Stage<U> |
thenCompose(Function<? super T,? extends Stage<U>> fn)
Compose the current stage with the given function.
|
Stage<T> |
thenComposeCaught(Function<? super Throwable,? extends Stage<T>> fn)
Compose a failed stage.
|
<U> Stage<U> |
thenFail(Throwable cause)
Build a stage is failed, but waits until the current stage completes.
|
Stage<T> |
whenCancelled(Runnable runnable)
Register an listener to be called when the current stage is cancelled.
|
Stage<T> |
whenComplete(Consumer<? super T> consumer)
Register a listener to be called when the current stage is completed.
|
Stage<T> |
whenDone(Runnable runnable)
Register a listener to be called when the current stage finishes for any reason.
|
Stage<T> |
whenFailed(Consumer<? super Throwable> consumer)
Register a listener that is called when a stage is failed.
|
Stage<T> |
withCloser(Supplier<? extends Stage<Void>> complete,
Supplier<? extends Stage<Void>> notComplete)
Run one of the provided stages when this stage ends up in a given state.
|
Stage<T> |
withComplete(Supplier<? extends Stage<Void>> supplier)
Run the provided stage when the current stage has completed.
|
Stage<T> |
withNotComplete(Supplier<? extends Stage<Void>> supplier)
Run the provided stage when the current stage ends, but does not complete.
|
static final String PENDING
static final String COMPLETED
static final String FAILED
static final String CANCELLED
boolean cancel()
true
if the stage was cancelled by this callT join() throws ExecutionException, InterruptedException
ExecutionException
- when the underlying computation throws an exceptionCancellationException
- when the computation was cancelledInterruptedException
- when this thread is interruptedT join(long timeout, TimeUnit unit) throws ExecutionException, InterruptedException, TimeoutException
timeout
- timeout after which TimeoutException
will be
thrown.unit
- unit of the timeoutExecutionException
- when the underlying computation throws an exceptionCancellationException
- if the computation was cancelledTimeoutException
- when the computation does not finish within the given timeoutInterruptedException
- when this thread is interruptedT joinNow() throws ExecutionException
IllegalStateException
- if the result is not availableExecutionException
- when the underlying computation throws an exceptionCancellationException
- if the computation was cancelledboolean isDone()
true
if the stage is completed, failed, or cancelledboolean isCompleted()
true
if the stage is in a completed state, otherwise false
.boolean isFailed()
true
if the stage is exceptionally completedCompletable.fail(Throwable)
boolean isCancelled()
true
if the stage is in a cancelled state, otherwise false
.Throwable cause()
IllegalStateException
- if the stage is not in the failed stateisFailed()
Stage<T> handle(Handle<? super T> handle)
handle
- handle to registerStage<T> whenDone(Runnable runnable)
runnable
- function to be firedStage<T> whenComplete(Consumer<? super T> consumer)
consumer
- listener to registerStage<T> whenFailed(Consumer<? super Throwable> consumer)
consumer
- listener to registerStage<T> whenCancelled(Runnable runnable)
runnable
- listener to register<U> Stage<U> thenApply(Function<? super T,? extends U> fn)
Translates the result of a completed stage as it becomes available:
operation().thenApply(result -> result / 2);
U
- the type of the newly applied stagefn
- transformation to use<U> Stage<U> thenCompose(Function<? super T,? extends Stage<U>> fn)
When the current stage has completed, calls the given function with the result of the current stage.
Stage<A> a = op1();
Stage<B> a.thenCompose(result -> op2(result));
U
- type of the composed stagefn
- the function to use when transforming the valueStage<T> thenApplyFailed(Function<? super Throwable,? extends T> fn)
This acts like a try-catch, where the provided function is the catch operation.
fn
- the transformation to useStage<T> thenComposeCaught(Function<? super Throwable,? extends Stage<T>> fn)
This acts like a try-catch, where the composed stage is the catch operation.
If the intent is to re-throw after running the catch operation, use
withNotComplete(java.util.function.Supplier)
fn
- the transformation to use<U> Stage<U> thenFail(Throwable cause)
U
- target typecause
- error to fail with<U> Stage<U> thenCancel()
U
- target type<U> Stage<U> thenComplete(U result)
U
- target typeresult
- result to complete withStage<T> withCloser(Supplier<? extends Stage<Void>> complete, Supplier<? extends Stage<Void>> notComplete)
This is typically used to implement catch-then-rethrow style operations, like the following example:
beginTransaction().thenCompose(tx -> {
return oper2(tx).withCloser(tx::commit, tx::rollback);
});
complete
- stage to run when this stage ends in a complete statenotComplete
- stage to run when this stage ends in a non-complete state, if the state is
failed, any exception thrown in this block will suppress the original exceptionStage<T> withComplete(Supplier<? extends Stage<Void>> supplier)
supplier
- supplier of the stage to runCopyright © 2017. All rights reserved.