Stage (async-api 0.1.0 API)

Type Parameters:

T - the type being provided by the stage

All Known Subinterfaces:

Completable<T>
```
public interface Stage<T>
```
An interface that defines a contract with a computation that could be asynchronous.
All methods are thread-safe guaranteeing that interactions with the stage are atomic.
A stage has four states:
- pending, which indicates that the stage is awaiting completion.
- completed, which indicates that the stage has been completed.
- failed, the stage has failed to be completed.
- cancelled, the stage has been cancelled.
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 reached
- with*, 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.
See Also:

Completable

Field Summary

Fields
Modifier and Type Field and Description

static String CANCELLED

static String COMPLETED

static String FAILED

static String PENDING

Fields
Modifier and Type	Field and Description
`static String`	`CANCELLED`
`static String`	`COMPLETED`
`static String`	`FAILED`
`static String`	`PENDING`

Method Summary

All Methods Instance Methods Abstract Methods
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.

- Field Detail
 - PENDING
```
static final String PENDING
```
 See Also:
 
 Constant Field Values
 - COMPLETED
```
static final String COMPLETED
```
 See Also:
 
 Constant Field Values
 - FAILED
```
static final String FAILED
```
 See Also:
 
 Constant Field Values
 - CANCELLED
```
static final String CANCELLED
```
 See Also:
 
 Constant Field Values
- Method Detail
 - cancel
```
boolean cancel()
```
 Cancel the current stage.
 
 Returns:
 
 true if the stage was cancelled by this call
 - join
```
T join()
throws ExecutionException,
 InterruptedException
```
 Join the result of the current stage.
 
 Returns:
 
 the result of the computation
 
 Throws:
 
 ExecutionException - when the underlying computation throws an exception
 
 CancellationException - when the computation was cancelled
 
 InterruptedException - when this thread is interrupted
 - join
```
T join(long timeout,
 TimeUnit unit)
throws ExecutionException,
 InterruptedException,
 TimeoutException
```
 Join the result of the current stage with a timeout.
 
 Parameters:
 
 timeout - timeout after which TimeoutException will be thrown.
 
 unit - unit of the timeout
 
 Returns:
 
 the result of the computation
 
 Throws:
 
 ExecutionException - when the underlying computation throws an exception
 
 CancellationException - if the computation was cancelled
 
 TimeoutException - when the computation does not finish within the given timeout
 
 InterruptedException - when this thread is interrupted
 - joinNow
```
T joinNow()
 throws ExecutionException
```
 Join the result of the current stage, or fail if it's state is still running.
 
 Returns:
 
 the result of the computation
 
 Throws:
 
 IllegalStateException - if the result is not available
 
 ExecutionException - when the underlying computation throws an exception
 
 CancellationException - if the computation was cancelled
 - isDone
```
boolean isDone()
```
 Indicates if the stage is done
 
 Returns:
 
 true if the stage is completed, failed, or cancelled
 - isCompleted
```
boolean isCompleted()
```
 Check if stage is completed.
 
 Returns:
 
 true if the stage is in a completed state, otherwise false.
 - isFailed
```
boolean isFailed()
```
 Check if the stage was exceptionally completed.
 
 Returns:
 
 true if the stage is exceptionally completed
 
 See Also:
 
 Completable.fail(Throwable)
 - isCancelled
```
boolean isCancelled()
```
 Check if stage is in the cancelled state.
 
 Returns:
 
 true if the stage is in a cancelled state, otherwise false.
 - cause
```
Throwable cause()
```
 Get the cause of a failed stage.
 
 Returns:
 
 the exception that cause the stage to fail
 
 Throws:
 
 IllegalStateException - if the stage is not in the failed state
 
 See Also:
 
 isFailed()
 - handle
```
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.
 
 Parameters:
 
 handle - handle to register
 
 Returns:
 
 the current stage
 - whenDone
```
Stage<T> whenDone(Runnable runnable)
```
 Register a listener to be called when the current stage finishes for any reason.
 
 Parameters:
 
 runnable - function to be fired
 
 Returns:
 
 the current stage
 - whenComplete
```
Stage<T> whenComplete(Consumer<? super T> consumer)
```
 Register a listener to be called when the current stage is completed.
 
 Parameters:
 
 consumer - listener to register
 
 Returns:
 
 the current stage
 - whenFailed
```
Stage<T> whenFailed(Consumer<? super Throwable> consumer)
```
 Register a listener that is called when a stage is failed.
 
 Parameters:
 
 consumer - listener to register
 
 Returns:
 
 the current stage
 - whenCancelled
```
Stage<T> whenCancelled(Runnable runnable)
```
 Register an listener to be called when the current stage is cancelled.
 
 Parameters:
 
 runnable - listener to register
 
 Returns:
 
 the current stage
 - thenApply
```
 Stage thenApply(Function<? super T,? extends U> fn)
```
 Transform the value of the current stage into another type using an immediate function.
 Translates the result of a completed stage as it becomes available:
```
 operation().thenApply(result -> result / 2);
 
```
 Type Parameters:
 
 U - the type of the newly applied stage
 
 Parameters:
 
 fn - transformation to use
 
 Returns:
 
 the applied stage
 - thenCompose
```
 Stage thenCompose(Function<? super T,? extends Stage> fn)
```
 Compose the current stage with the given function.
 When the current stage has completed, calls the given function with the result of the current stage.
```
 Stage<A> a = op1();
 Stage a.thenCompose(result -> op2(result));
 
```
 Type Parameters:
 
 U - type of the composed stage
 
 Parameters:
 
 fn - the function to use when transforming the value
 
 Returns:
 
 the composed stage
 - thenApplyFailed
```
Stage<T> thenApplyFailed(Function<? super Throwable,? extends T> fn)
```
 Apply a failed stage.
 This acts like a try-catch, where the provided function is the catch operation.
 
 Parameters:
 
 fn - the transformation to use
 
 Returns:
 
 the applied stage
 - thenComposeCaught
```
Stage<T> thenComposeCaught(Function<? super Throwable,? extends Stage<T>> fn)
```
 Compose a failed stage.
 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)
 
 Parameters:
 
 fn - the transformation to use
 
 Returns:
 
 the composed stage
 - thenFail
```
 Stage thenFail(Throwable cause)
```
 Build a stage is failed, but waits until the current stage completes.
 
 Type Parameters:
 
 U - target type
 
 Parameters:
 
 cause - error to fail with
 
 Returns:
 
 a stage that will be failed
 - thenCancel
```
 Stage thenCancel()
```
 Build a stage is cancelled, but waits until the current stage completes.
 
 Type Parameters:
 
 U - target type
 
 Returns:
 
 a stage that will be cancelled
 - thenComplete
```
 Stage thenComplete(U result)
```
 Build a stage is completed, but waits until the current stage completes.
 
 Type Parameters:
 
 U - target type
 
 Parameters:
 
 result - result to complete with
 
 Returns:
 
 a stage that will be completed
 - withCloser
```
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.
 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);
 });
 
```
 Parameters:
 
 complete - stage to run when this stage ends in a complete state
 
 notComplete - 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 exception
 
 Returns:
 
 a new stage that depends on the supplied stage
 - withComplete
```
Stage<T> withComplete(Supplier<? extends Stage<Void>> supplier)
```
 Run the provided stage when the current stage has completed.
 
 Parameters:
 
 supplier - supplier of the stage to run
 
 Returns:
 
 a stage that depends on the current stage and the supplied stage
 - withNotComplete
```
Stage<T> withNotComplete(Supplier<? extends Stage<Void>> supplier)
```
 Run the provided stage when the current stage ends, but does not complete.
 
 Parameters:
 
 supplier - supplier of the stage to run
 
 Returns:
 
 a stage that depends on the current stage and the supplied stage

Interface Stage<T>

Field Summary

Method Summary

Field Detail

PENDING

COMPLETED

FAILED

CANCELLED

Method Detail

cancel

join

join

joinNow

isDone

isCompleted

isFailed

isCancelled

cause

handle

whenDone

whenComplete

whenFailed

whenCancelled

thenApply

thenCompose

thenApplyFailed

thenComposeCaught

thenFail

thenCancel

thenComplete

withCloser

withComplete

withNotComplete