Package com.ibm.asyncutil.util

Class StageSupport

java.lang.Object

com.ibm.asyncutil.util.StageSupport

public class StageSupport
extends Object

Utility methods for creating and composing CompletionStages

Method Summary

Modifier and Type	Method	Description
static <T> CompletionStage<T>	completedStage(T t)	Creates a CompletionStage that is already completed with the given value.
static <T> CompletionStage<T>	exceptionalStage(Throwable ex)	Creates a CompletionStage that is already completed exceptionally.
static <T,U> CompletionStage<U>	thenComposeOrRecover(CompletionStage<T> stage, BiFunction<? super T,Throwable,? extends CompletionStage<U>> fn)	Uses the possibly exceptional result of stage to produce a new stage.
static <T,R extends AutoCloseable> CompletionStage<T>	tryComposeWith(CompletionStage<R> resource, Function<? super R,? extends CompletionStage<T>> fn)	Performs an asynchronous function with an asynchronously acquired AutoCloseable, ensuring that the resource is closed after the stage returned by the function completes.
static <T,R extends AsyncCloseable> CompletionStage<T>	tryComposeWith(R resource, Function<? super R,? extends CompletionStage<T>> fn)	Performs an asynchronous function with an AsyncCloseable resource, ensuring that the resource is AsyncCloseable.close() closed} after the stage returned by the function completes.
static <T,R extends AutoCloseable> CompletionStage<T>	tryWith(CompletionStage<R> resource, Function<? super R,? extends T> fn)	Performs a function with an asynchronously acquired auto closeable, ensuring that the resource is closed after the function runs.
static <T,R extends AsyncCloseable> CompletionStage<T>	tryWith(R resource, Function<? super R,? extends T> fn)	Performs a function with an AsyncCloseable resource, ensuring that the resource is AsyncCloseable.close() closed} after the function completes.
static <T> CompletionStage<Void>	voided(CompletionStage<T> stage)	Creates a CompletionStage that completes when stage completes but ignores the result.
static CompletionStage<Void>	voidStage()	Gets an already completed CompletionStage of Void.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

voidStage

public static CompletionStage<Void> voidStage()

Gets an already completed CompletionStage of Void. This common static instance can be used as an alternative to StageSupport.<Void>completedStage(null)

This has a few advantages:

• Depending on context, StageSupport.completedStage(null) could either mean a CompletionStage<Void> or an CompletionStage<T>. Using this method clearly indicates that we are returning a void future, not a T future with a null result.
• Immediately completed null futures are very common. Since they are final and static, we can just reuse a single object and save allocations

Returns:

An immediately completed CompletionStage of Void

voided

public static <T> CompletionStage<Void> voided(CompletionStage<T> stage)

Creates a CompletionStage that completes when stage completes but ignores the result.

Parameters:

stage - a non-void CompletionStage

Returns:

a CompletionStage of type Void which completes when stage completes

completedStage

public static <T> CompletionStage<T> completedStage(T t)

Creates a CompletionStage that is already completed with the given value.

Non-Async methods on the returned stage will run their dependent actions immediately on the calling thread.

Async methods which do not supply an executor (and don't involve another stage) will use the same default executor as used by CompletableFuture. If another stage is involved (e.g. thenAcceptBothAsync) then the other stage's default execution facility is used.

A completed exceptional stage can be similarly created with the method exceptionalStage(Throwable)

Parameters:

t - the value to be held by the returned stage

Returns:

a CompletionStage that has already been completed with t

See Also:

exceptionalStage(Throwable)

exceptionalStage

public static <T> CompletionStage<T> exceptionalStage(Throwable ex)

Creates a CompletionStage that is already completed exceptionally. This is the exceptional analog of completedStage(Object).

Non-Async methods on the returned stage will run their dependent actions immediately on the calling thread.

Async methods which do not supply an executor (and don't involve another stage) will use the same default executor as used by CompletableFuture. If another stage is involved (e.g. thenAcceptBothAsync) then the other stage's default execution facility is used.

Parameters:

ex - the exception that completes the returned stage

Returns:

a CompletionStage that has already been completed exceptionally with ex

See Also:

completedStage(Object)

tryWith

public static <T,R extends AutoCloseable> CompletionStage<T> tryWith(CompletionStage<R> resource,
                                                                     Function<? super R,? extends T> fn)

Performs a function with an asynchronously acquired auto closeable, ensuring that the resource is closed after the function runs. Similar to a try-with-resources block, the resource will be closed even if fn throws an exception.

The returned stage will complete exceptionally in the following scenarios

1. resource completes exceptionally
2. fn throws an exception
3. AutoCloseable.close() throws an exception

Of these cases, only 2 and 3 can happen simultaneously - in this case, the exception thrown by close will be added to the exception from fn as a suppressed exception. If AutoCloseable.close() throws a non-runtime exception, it will be wrapped in a CompletionException.

Type Parameters:

T - the result type of fn

R - the AutoCloseable resource type

Parameters:

resource - a CompletionStage that completes with an AutoCloseable

fn - an function to perform that uses result of resource to produce a value

Returns:

a CompletionStage that completes with the result of fn or completes exceptionally

tryComposeWith

public static <T,R extends AutoCloseable> CompletionStage<T> tryComposeWith(CompletionStage<R> resource,
                                                                            Function<? super R,? extends CompletionStage<T>> fn)

Performs an asynchronous function with an asynchronously acquired AutoCloseable, ensuring that the resource is closed after the stage returned by the function completes. Similar to a try-with-resources block, the resource will be closed even if fn throws an exception or if the returned stage completes exceptionally.

The returned stage will complete exceptionally in the following scenarios

1. resource completes exceptionally
2. fn throws an exception
3. fn returns an stage that completes exceptionally
4. AutoCloseable.close() throws an exception

Of these cases, (2 and 4) and (3 and 4) can happen simultaneously - in these cases, the exception thrown by close will be added to the exception from fn as a suppressed exception. If AutoCloseable.close() throws a non-runtime exception, it will be wrapped in a CompletionException.

Type Parameters:

T - the type of the CompletionStage produced by fn

R - the AutoCloseable resource type

Parameters:

resource - a CompletionStage that completes with an AutoCloseable which will be {AutoCloseable.close() closed} when the stage returned by fn completes.

fn - an function to perform that uses result of resource to produce a new CompletionStage

Returns:

a CompletionStage that completes with the result of fn or completes exceptionally

tryWith

public static <T,R extends AsyncCloseable> CompletionStage<T> tryWith(R resource,
                                                                      Function<? super R,? extends T> fn)

Performs a function with an AsyncCloseable resource, ensuring that the resource is AsyncCloseable.close() closed} after the function completes. The returned stage will complete when the close stage has completed. Similar to a try-with-resources block, the resource will be closed even if fn throws an exception.

The returned stage will complete exceptionally in the following scenarios

1. fn throws an exception
2. AutoCloseable.close() throws an exception
3. AutoCloseable.close() returns a stage that completes exceptionally

If the function produces an exception and AsyncCloseable.close() produces an exception the exception produced by close will be added to the exception from fn as a suppressed exception.

Type Parameters:

T - the type produced by fn

R - the AsyncCloseable resource type

Parameters:

resource - an AsyncCloseable which will be {AsyncCloseable.close() closed} after fn is run

fn - a function to perform that uses resource to produce a result

Returns:

a CompletionStage that completes with the result of fn after close has completed or completes exceptionally

tryComposeWith

public static <T,R extends AsyncCloseable> CompletionStage<T> tryComposeWith(R resource,
                                                                             Function<? super R,? extends CompletionStage<T>> fn)

Performs an asynchronous function with an AsyncCloseable resource, ensuring that the resource is AsyncCloseable.close() closed} after the stage returned by the function completes. The returned stage will complete when the close stage has completed. Similar to a try-with-resources block, the resource will be closed even if fn throws an exception or if its returned stage completes exceptionally.

The returned stage will complete exceptionally in the following scenarios

1. fn throws an exception
2. fn returns a stage that completes exceptionally
3. AutoCloseable.close() throws an exception
4. AutoCloseable.close() returns a stage that completes exceptionally

If the function produces an exception (cases 1 or 2) and AsyncCloseable.close() produces an exception (cases 3 or 4) the exception produced by close will be added to the exception from fn as a suppressed exception.

Type Parameters:

T - the type of the CompletionStage produced by fn

R - the AsyncCloseable resource type

Parameters:

resource - an AsyncCloseable which will be {AsyncCloseable.close() closed} when the stage returned by fn completes.

fn - a function to perform that uses resource to produce a new CompletionStage

Returns:

a CompletionStage that completes with the result of fn after close has completed or completes exceptionally

thenComposeOrRecover

public static <T,U> CompletionStage<U> thenComposeOrRecover(CompletionStage<T> stage,
                                                            BiFunction<? super T,Throwable,? extends CompletionStage<U>> fn)

Uses the possibly exceptional result of stage to produce a new stage.

When stage completes, fn will be applied with the result of the stage (or null if it completed exceptionally) and the exception from the stage (or null if it completed normally) to produce a new stage. The returned stage will be completed with the outcome of the stage produced by fn.

 
 CompletionStage<Integer> backupValue(){...};
 int compute(int i) {
    if (i % 2 == 0)
        return i / 2;
    else
        throw new OddException();
 }
 // get a stage that has the computed value if compute completes normally,
 // or asynchronously computes the backup value otherwise.
 CompletionStage<Optional<Integer>> optionalStage = thenComposeOrRecover(
    () -> CompletableFuture.supplyAsync(compute(myInt)),
    (result, throwable) -> throwable == null ? backupValue() : CompletableFuture.completedOf(result));
 
 

Type Parameters:

T - the type stage

U - the type of the returned CompletionStage

Parameters:

stage - a CompletionStage that may complete exceptionally

fn - a function that will run with the outcome of stage to produce a new CompletionStage

Returns:

a CompletionStage which will complete with the result of fn

See Also:

CompletionStage.handle(BiFunction)