Class StageChain<T,R>
- java.lang.Object
-
- de.xima.fc.stage.StageChain<T,R>
-
- Type Parameters:
T
- Type of the intermediate result.R
- Type of the final result.
public final class StageChain<T,R> extends Object
Decorates aCompletableFuture
and introduces the idea of an eventual return value that one wishes to obtain eventually.This allows for additional methods such as methods for an "
early return
" (i.e. so that further chains are not evaluated anymore) oropened resources
closed when the chain completes). This can be very useful when you need to do complex processing withStageChain
s. In combination withLocalVariables
, this lets you write code like this:// x1 => storeAvailable // x2 => pluginName // x3 => pluginVersionItem // x4 => pluginChangeLogList // x5 => updateAvailability // x6 => updatedPlugin // x7 => updateVersion return StageChain.<PluginUpdateMetadata> begin() // .thenCompose(v -> v.next(PromaManager.isPluginStoreAvailable(pc))) // .returnIf(v -> !v.x1, v -> new PluginUpdateMetadata()) // .thenCompose(v -> v.next(getPluginName(pc, pluginKey, manifest, locale))) // .thenCompose(v -> v.next(getPluginVersionItem(pc, pluginKey, manifest, locale))) // .thenCompose(v -> v.next(createPluginChangelog(pc, pluginKey, manifest, locale))) // .thenCompose(v -> v.next(fetchPluginUpdateStatus(pc, pluginKey, locale, manifest, runtime))) // .returnIf( // v -> v.x5 != EPluginUpdateAvailability.UPDATE_AVAILABLE, // v -> { final var currentVersion = v.x3 != null ? v.x3.getName() : ""; final var desc = v.x3 != null ? v.x3.getDescription() : ""; return new PluginUpdateMetadata(v.x2, v.x5, currentVersion, pluginKey, desc, v.x4, ""); }) // .thenCompose(v -> v.next(getUpdatedPlugin(pc, pluginKey, manifest, locale))) // .thenApply(v -> v.next(v.x6 != null ? v.x6.getUpdateVersion().getName() : "")) // .thenApply(v -> { final var currentVersion = v.x3 != null ? v.x3.getName() : ""; final var desc = v.x3 != null ? v.x3.getDescription() : ""; return new PluginUpdateMetadata(v.x2, v.x5, currentVersion, pluginKey, desc, v.x4, v.x7); }) // .exceptionally(error -> { LOG.error("Error while creating the plugin meta data!", error); return new PluginUpdateMetadata(); }) // .finish(Function.identity());
instead of your code looking like this:PromaManager.isPluginStoreAvailable(pc) // .thenCompose(storeAvailable -> { if (!storeAvailable) { return completedFuture(new PluginUpdateMetadata()); } return getPluginName(pc, pluginKey, manifest, locale) // .thenCompose(pluginName -> { return getPluginVersionItem(pc, pluginKey, manifest, locale) // .thenCompose(pluginVersionItem -> { final var currentVersion = pluginVersionItem != null ? pluginVersionItem.getName() : ""; final var desc = pluginVersionItem != null ? pluginVersionItem.getDescription() : ""; return createPluginChangelog(pc, pluginKey, manifest, locale) // .thenCompose(pluginChangeLogList -> { return fetchPluginUpdateStatus(pc, pluginKey, locale, manifest, runtime) // .thenCompose(updateAvailability -> { if (updateAvailability == EPluginUpdateAvailability.UPDATE_AVAILABLE) { return getUpdatedPlugin(pc, pluginKey, manifest, locale) // .thenApply(updatedPlugin -> { return updatedPlugin != null ? updatedPlugin.getUpdateVersion().getName() : ""; }) // .thenApply(updateVersion -> { return new PluginUpdateMetadata( // pluginName, updateAvailability, currentVersion, // pluginKey, desc, pluginChangeLogList, updateVersion // ); }); } else { return completedFuture(new PluginUpdateMetadata( // pluginName, updateAvailability, currentVersion, // pluginKey, desc, pluginChangeLogList, "" // )); } }); }); }); }); }) /// .exceptionally(error -> { LOG.error("Error while creating the plugin meta data!", error); return new PluginUpdateMetadata(); });
- Since:
- 8.0.0
- Author:
- XIMA MEDIA GmbH
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description CompletableFuture<R>
__rawFinishToStage(Function<? super T,? extends R> fn)
Similar tonext(Function)
.CompletableFuture<R>
__rawFinishToStageAsync(Function<? super T,? extends R> fn, Executor executor)
Similar tonextAsync(Function, Executor)
.static <R> StageChain<LocalVariables,R>
begin(Executor defaultAsyncExecutor)
Starts a new chain with an empty set ofLocalVariables
.static <T,R>
StageChain<T,R>begin(T value, Executor defaultAsyncExecutor)
Starts a new chain initialized with the given current value.StageChain<T,R>
exceptionally(Class<? extends Throwable> errorClass, Function<Throwable,? extends T> fn)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.StageChain<T,R>
exceptionally(Function<Throwable,? extends T> fn)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.StageChain<T,R>
exceptionallyAsync(Class<? extends Throwable> errorClass, Function<Throwable,? extends T> fn, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.StageChain<T,R>
exceptionallyAsync(Function<Throwable,? extends T> fn, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.static <R> StageChain<Void,R>
expect(Executor defaultAsyncExecutor)
Starts a new chain with the current value set tonull
.static <T,R>
StageChain<T,R>failed(Throwable error, Executor defaultAsyncExecutor)
Starts a new chain that is completed exceptionally with given exception.protected CompletableFuture<de.xima.fc.stage.StageChain.State<R,R>>
finishToState(Function<? super T,? extends R> fn)
protected CompletableFuture<de.xima.fc.stage.StageChain.State<R,R>>
finishToStateAsync(Function<? super T,? extends R> fn, Executor executor)
<U> StageChain<R,U>
next(Function<? super T,? extends R> fn)
Finishes this chain and produces a new chain the eventual return value from the current value.<U> StageChain<R,U>
nextAsync(Function<? super T,? extends R> fn, Executor executor)
Finishes this chain and produces a new chain the eventual return value from the current value.StageChain<T,R>
orTimeout(Duration timeout)
Exceptionally completes this StageChain with aTimeoutException
if not otherwise completed before the given timeout.StageChain<T,R>
orTimeoutAsync(Duration timeout, Executor executor)
Exceptionally completes this StageChain with aTimeoutException
if not otherwise completed before the given timeout.static <T,R>
StageChain<T,R>resume(CompletableFuture<T> stage, Executor defaultAsyncExecutor)
Starts a new chain initialized with the state of the given stage.StageChain<T,R>
returnIf(Predicate<? super T> test, Function<? super T,? extends R> fn)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.StageChain<T,R>
returnIfAsync(Predicate<? super T> test, Function<? super T,? extends R> fn, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.StageChain<T,R>
returnIfCompose(Predicate<? super T> test, Function<? super T,? extends StageChain<R,R>> fn)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.StageChain<T,R>
returnIfComposeAsync(Predicate<? super T> test, Function<? super T,? extends StageChain<R,R>> fn, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.StageChain<T,R>
returnNullIf(Predicate<? super T> test)
Same asreturnIf(Predicate, Function)
, but always returnsnull
.StageChain<T,R>
returnNullIf(Predicate<? super T> test, Consumer<? super T> action)
Same asreturnIf(Predicate, Function)
, but always returnsnull
.StageChain<T,R>
returnNullIfAsync(Predicate<? super T> test, Executor executor)
Same asreturnIf(Predicate, Function)
, but always returnsnull
.StageChain<T,R>
returnNullIfAsync(Predicate<? super T> test, Consumer<? super T> action, Executor executor)
Same asreturnIf(Predicate, Function)
, but always returnsnull
.<U> StageChain<T,R>
returnNullIfCompose(Predicate<? super T> test, Function<? super T,? extends StageChain<U,U>> fn)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.<U> StageChain<T,R>
returnNullIfComposeAsync(Predicate<? super T> test, Function<? super T,? extends StageChain<U,U>> fn, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.StageChain<Void,R>
thenAccept(Consumer<? super T> action)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.StageChain<Void,R>
thenAcceptAsync(Consumer<? super T> action, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.<U> StageChain<U,R>
thenApply(Function<? super T,? extends U> fn)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.<U> StageChain<U,R>
thenApplyAsync(Function<? super T,? extends U> fn, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.<U> StageChain<U,R>
thenCompose(Function<? super T,? extends StageChain<U,R>> fn)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.<U> StageChain<U,R>
thenComposeAsync(Function<? super T,? extends StageChain<U,R>> fn, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.<U> StageChain<U,R>
thenComposeStage(Function<? super T,? extends CompletionStage<U>> fn)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.<U> StageChain<U,R>
thenComposeStageAsync(Function<? super T,? extends CompletionStage<U>> fn, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.StageChain<Void,R>
thenDiscard()
Same as thenAccept, but simply discards the current result without running any action.StageChain<Void,R>
thenDiscardAsync(Executor executor)
Same as thenAccept, but simply discards the current result without running any action.<U> StageChain<U,R>
thenHandle(BiFunction<? super T,Throwable,? extends U> fn)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.<U> StageChain<U,R>
thenHandleAsync(BiFunction<? super T,Throwable,? extends U> fn, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.StageChain<T,R>
whenCompleteAccept(BiConsumer<? super T,Throwable> action)
StageChain<T,R>
whenCompleteAcceptAsync(BiConsumer<? super T,Throwable> action, Executor executor)
StageChain<T,R>
whenCompleteCompose(BiFunction<? super T,Throwable,? extends StageChain<?,R>> action)
StageChain<T,R>
whenCompleteComposeAsync(BiFunction<? super T,Throwable,? extends StageChain<?,R>> action, Executor executor)
StageChain<T,R>
whenSuccessfulAccept(Consumer<? super T> action)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.StageChain<T,R>
whenSuccessfulAcceptAsync(Consumer<? super T> action, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.StageChain<T,R>
whenSuccessfulCompose(Function<? super T,? extends StageChain<?,R>> action)
StageChain<T,R>
whenSuccessfulComposeAsync(Function<? super T,? extends StageChain<?,R>> action, Executor executor)
StageChain<T,R>
whenSuccessfulComposeStage(Function<? super T,? extends CompletionStage<?>> action)
If this chain has already returned: does nothing and returns a StageChain that returns with the same return value.StageChain<T,R>
whenSuccessfulComposeStageAsync(Function<? super T,? extends CompletionStage<?>> action, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.StageChain<T,R>
withDefaultExecutor(Executor defaultAsyncExecutor)
<A,U>
StageChain<U,R>withResource(IResourceOpenFunction<? super T,? extends A> resource, IResourceCloseAction<? super A> close, BiFunction<? super T,? super A,? extends U> combiner)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.<A extends AutoCloseable,U>
StageChain<U,R>withResource(IResourceOpenFunction<? super T,? extends A> resource, BiFunction<? super T,? super A,? extends U> combiner)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.<A,U>
StageChain<U,R>withResourceAsync(IResourceOpenFunction<? super T,? extends A> open, IResourceCloseAction<? super A> close, BiFunction<? super T,? super A,? extends U> combiner, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.<A extends AutoCloseable,U>
StageChain<U,R>withResourceAsync(IResourceOpenFunction<? super T,? extends A> resource, BiFunction<? super T,? super A,? extends U> combiner, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.<U> StageChain<U,R>
withResourceFile(IResourceOpenFunction<? super T,File> resource, BiFunction<? super T,File,? extends U> combiner)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.<U> StageChain<U,R>
withResourceFileAsync(IResourceOpenFunction<? super T,? extends File> resource, BiFunction<? super T,? super File,? extends U> combiner, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.<U> StageChain<U,R>
withResourcePath(IResourceOpenFunction<? super T,? extends Path> resource, BiFunction<? super T,? super Path,? extends U> combiner)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.<U> StageChain<U,R>
withResourcePathAsync(IResourceOpenFunction<? super T,? extends Path> resource, BiFunction<? super T,? super Path,? extends U> combiner, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value.
-
-
-
Method Detail
-
__rawFinishToStage
public CompletableFuture<R> __rawFinishToStage(Function<? super T,? extends R> fn)
Similar tonext(Function)
. Can be used to access the underlyingCompletableFuture
directly. This is a low level-method and should be treated as such. Closes all open resources and returns a stage with the eventual return value.- Parameters:
fn
- Function that transform the current value to the final value.- Returns:
- A stage that completes with the eventual return value.
-
__rawFinishToStageAsync
public CompletableFuture<R> __rawFinishToStageAsync(Function<? super T,? extends R> fn, Executor executor)
Similar tonextAsync(Function, Executor)
. Can be used to access the underlyingCompletableFuture
directly. This is a low level-method and should be treated as such. Closes all open resources and returns a stage with the eventual return value.- Parameters:
fn
- Function that transform the current value to the final value.executor
- The executor to use for asynchronous execution- Returns:
- A stage that completes with the eventual return value.
-
exceptionally
public StageChain<T,R> exceptionally(Class<? extends Throwable> errorClass, Function<Throwable,? extends T> fn)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new StageChain that, when this chain completes exceptionally with an exception of the given type, is executed with this chain's exception as the argument to the supplied function. Otherwise, if this chain completes normally, then the returned chain also completes normally with the same value.
- Parameters:
errorClass
- Type of the exception for which to apply the transformation function.fn
- The function to use to compute the value of the returned StageChain if this StageChain completed exceptionally- Returns:
- The new StageChain
-
exceptionally
public StageChain<T,R> exceptionally(Function<Throwable,? extends T> fn)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new StageChain that, when this chain completes exceptionally, is executed with this chain's exception as the argument to the supplied function. Otherwise, if this chain completes normally, then the returned chain also completes normally with the same value.
- Parameters:
fn
- The function to use to compute the value of the returned StageChain if this StageChain completed exceptionally- Returns:
- The new StageChain
-
exceptionallyAsync
public StageChain<T,R> exceptionallyAsync(Class<? extends Throwable> errorClass, Function<Throwable,? extends T> fn, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new StageChain that, when this chain completes exceptionally with an exception of the given type, is executed with this chain's exception as the argument to the supplied function. Otherwise, if this chain completes normally, then the returned chain also completes normally with the same value.
- Parameters:
errorClass
- Type of the exception for which to apply the transformation function.fn
- The function to use to compute the value of the returned StageChain if this StageChain completed exceptionallyexecutor
- The executor to use for asynchronous execution- Returns:
- The new StageChain
-
exceptionallyAsync
public StageChain<T,R> exceptionallyAsync(Function<Throwable,? extends T> fn, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new StageChain that, when this chain completes exceptionally, is executed with this chain's exception as the argument to the supplied function running in the given executor. Otherwise, if this chain completes normally, then the returned chain also completes normally with the same value.
- Parameters:
fn
- The function to use to compute the value of the returned StageChain if this StageChain completed exceptionallyexecutor
- The executor to use for asynchronous execution- Returns:
- The new StageChain
-
next
public <U> StageChain<R,U> next(Function<? super T,? extends R> fn)
Finishes this chain and produces a new chain the eventual return value from the current value. All resources that were opened viawithResource(IResourceOpenFunction, IResourceCloseAction, BiFunction)
are applied when the returned stage completes (either normally or exceptionally).When this chain has returned already: Returns a StageChain that completes with that return value.
Otherwise: Returns a StageChain that, when this chain completes normally, is executed with this chain result as the argument to the supplied function.
Most of the time, the type of this chain's current value will already be equal to the type of the eventual return value. In that case, simply pass
identity()
as the argument to this method.public StageChain<String> someMethod(StageChain<String> stage) { return StageChain.resume(stage) // .returnIf(x -> x == null, x -> "empty") // .thenApply(x -> x + x) // .next(identity()); }
- Parameters:
fn
- The function to use to compute the eventual return value from this chain's current value, if this chain has not yet returned.- Returns:
- The new StageChain.
-
nextAsync
public <U> StageChain<R,U> nextAsync(Function<? super T,? extends R> fn, Executor executor)
Finishes this chain and produces a new chain the eventual return value from the current value. All resources that were opened viawithResource(IResourceOpenFunction, IResourceCloseAction, BiFunction)
are applied when the returned stage completes (either normally or exceptionally).When this chain has returned already: Returns a StageChain that completes with that return value.
Otherwise: Returns a StageChain that, when this chain completes normally, is executed with this chain result as the argument to the supplied function.
Most of the time, the type of this chain's current value will already be equal to the type of the eventual return value. In that case, simply pass
identity()
as the argument to this method.public StageChain<String> someMethod(StageChain<String> stage) { return StageChain.resume(stage) // .returnIf(x -> x == null, x -> "empty") // .thenApply(x -> x + x) // .nextAsync(identity(), someExecutor); }
- Parameters:
fn
- The function to use to compute the eventual return value from this chain's current value, if this chain has not yet returned.executor
- The executor to use for asynchronous execution- Returns:
- The new StageChain.
-
orTimeout
public StageChain<T,R> orTimeout(Duration timeout)
Exceptionally completes this StageChain with aTimeoutException
if not otherwise completed before the given timeout.- Parameters:
timeout
- How long to wait before completing exceptionally with a TimeoutException.- Returns:
- The new StageChain
-
orTimeoutAsync
public StageChain<T,R> orTimeoutAsync(Duration timeout, Executor executor)
Exceptionally completes this StageChain with aTimeoutException
if not otherwise completed before the given timeout.- Parameters:
timeout
- How long to wait before completing exceptionally with a TimeoutException.executor
- The executor to use for asynchronous execution- Returns:
- The new StageChain
-
returnIf
public StageChain<T,R> returnIf(Predicate<? super T> test, Function<? super T,? extends R> fn)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new returned StageChain that, when this chain completes normally, is executed with this chain result as the argument to the supplied function, if the predicate matches. Then, all further applications of chain methods will have no effect anymore, the resulting chain will always complete with the return value.
If the predicate does not match, returns a new StageChain that completes with the same value as this chain.
- Parameters:
test
- The test to check whether to return.fn
- The function to use to compute the return value of the returned StageChain.- Returns:
- The new StageChain
-
returnIfAsync
public StageChain<T,R> returnIfAsync(Predicate<? super T> test, Function<? super T,? extends R> fn, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new returned StageChain that, when this chain completes normally, is executed with this chain result as the argument to the supplied function, if the predicate matches. The test and the supplied test and function are executed by a task running in the given executor. Then, all further applications of chain methods will have no effect anymore, the resulting chain will always complete with the return value.
If the predicate does not match, returns a new StageChain that completes with the same value as this chain.
- Parameters:
test
- The test to check whether to return.fn
- The function to use to compute the return value of the returned StageChain.executor
- The executor to use for asynchronous execution- Returns:
- The new StageChain
-
returnIfCompose
public StageChain<T,R> returnIfCompose(Predicate<? super T> test, Function<? super T,? extends StageChain<R,R>> fn)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new returned StageChain that, when this chain completes normally, is executed with this chain result as the argument to the supplied function, if the predicate matches. Then, all further applications of chain methods will have no effect anymore, the resulting chain will always complete with the return value of the supplied chain.
If the predicate does not match, returns a new StageChain that completes with the same value as this chain.
- Parameters:
test
- The test to check whether to return.fn
- The function to use to compute the return value of the returned StageChain.- Returns:
- The new StageChain
-
returnIfComposeAsync
public StageChain<T,R> returnIfComposeAsync(Predicate<? super T> test, Function<? super T,? extends StageChain<R,R>> fn, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new returned StageChain that, when this chain completes normally, is executed with this chain result as the argument to the supplied function, if the predicate matches. The test and the supplied test and function are executed by a task running in the given executor. Then, all further applications of chain methods will have no effect anymore, the resulting chain will always complete with the return value of the supplied chain.
If the predicate does not match, returns a new StageChain that completes with the same value as this chain.
- Parameters:
test
- The test to check whether to return.fn
- The function to use to compute the return value of the returned StageChain.executor
- The executor to use for asynchronous execution- Returns:
- The new StageChain
-
returnNullIf
public StageChain<T,R> returnNullIf(Predicate<? super T> test)
Same asreturnIf(Predicate, Function)
, but always returnsnull
. When this chain has returned, does nothing. Otherwise, returns a new returned stage chain with a return value ofnull
.- Parameters:
test
- The test to check whether to return.- Returns:
- The new StageChain.
-
returnNullIf
public StageChain<T,R> returnNullIf(Predicate<? super T> test, Consumer<? super T> action)
Same asreturnIf(Predicate, Function)
, but always returnsnull
. When this chain has returned, does nothing. Otherwise, returns a new returned stage chain that completes once the given action completes, and has a return value ofnull
. The- Parameters:
test
- The test to check whether to return.action
- The action to apply if the test is successful.- Returns:
- The new StageChain.
-
returnNullIfAsync
public StageChain<T,R> returnNullIfAsync(Predicate<? super T> test, Consumer<? super T> action, Executor executor)
Same asreturnIf(Predicate, Function)
, but always returnsnull
. When this chain has returned, does nothing. Otherwise, returns a new returned stage chain that completes once the given action completes, and has a return value ofnull
. The- Parameters:
test
- The test to check whether to return.action
- The action to apply if the test is successful.executor
- The executor to use for asynchronous execution- Returns:
- The new StageChain.
-
returnNullIfAsync
public StageChain<T,R> returnNullIfAsync(Predicate<? super T> test, Executor executor)
Same asreturnIf(Predicate, Function)
, but always returnsnull
. When this chain has returned, does nothing. Otherwise, returns a new returned stage chain with a return value ofnull
. The- Parameters:
test
- The test to check whether to return.executor
- The executor to use for asynchronous execution- Returns:
- The new StageChain.
-
returnNullIfCompose
public <U> StageChain<T,R> returnNullIfCompose(Predicate<? super T> test, Function<? super T,? extends StageChain<U,U>> fn)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new returned StageChain that, when this chain completes normally, is executed with this chain result as the argument to the supplied function, if the predicate matches. Then, all further applications of chain methods will have no effect anymore, the resulting chain will always complete with the return value set to
null
.If the predicate does not match, returns a new StageChain that completes with the same value as this chain.
- Parameters:
test
- The test to check whether to return.fn
- The function to use to compute the return value of the returned StageChain.- Returns:
- The new StageChain
-
returnNullIfComposeAsync
public <U> StageChain<T,R> returnNullIfComposeAsync(Predicate<? super T> test, Function<? super T,? extends StageChain<U,U>> fn, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new returned StageChain that, when this chain completes normally, is executed with this chain result as the argument to the supplied function, if the predicate matches. The test and the supplied test and function are executed by a task running in the given executor. Then, all further applications of chain methods will have no effect anymore, the resulting chain will always complete with the return value set to
null
.If the predicate does not match, returns a new StageChain that completes with the same value as this chain.
- Parameters:
test
- The test to check whether to return.fn
- The function to use to compute the return value of the returned StageChain.executor
- The executor to use for asynchronous execution- Returns:
- The new StageChain
-
thenAccept
public StageChain<Void,R> thenAccept(Consumer<? super T> action)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new StageChain that, when this chain completes normally, is executed with this chain's result as the argument to the supplied action. See the
CompletionStage
documentation for rules covering exceptional completion.- Parameters:
action
- The action to perform before completing the returned StageChain- Returns:
- The new StageChain.
-
thenAcceptAsync
public StageChain<Void,R> thenAcceptAsync(Consumer<? super T> action, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new StageChain that, when this chain completes normally, is executed using the supplied Executor with this chain's result as the argument to the supplied action. See the
CompletionStage
documentation for rules covering exceptional completion.- Parameters:
action
- The action to perform before completing the returned StageChainexecutor
- The executor to use for asynchronous execution- Returns:
- The new StageChain.
-
thenApply
public <U> StageChain<U,R> thenApply(Function<? super T,? extends U> fn)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new StageChain that, when this chain completes normally, is executed with this chain result as the argument to the supplied function.
This method is analogous to
Optional.map
andStream.map
.See the
CompletionStage
documentation for rules covering exceptional completion.- Type Parameters:
U
- The function's return type- Parameters:
fn
- The function to use to compute the value of the returned StageChain- Returns:
- The new StageChain
-
thenApplyAsync
public <U> StageChain<U,R> thenApplyAsync(Function<? super T,? extends U> fn, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new StageChain that, when this chain completes normally, is executed with this chain result as the argument to the supplied function.
This method is analogous to
Optional.map
andStream.map
.See the
CompletionStage
documentation for rules covering exceptional completion.- Type Parameters:
U
- The function's return type- Parameters:
fn
- The function to use to compute the value of the returned StageChainexecutor
- The executor to use for asynchronous execution- Returns:
- The new StageChain
-
thenCompose
public <U> StageChain<U,R> thenCompose(Function<? super T,? extends StageChain<U,R>> fn)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new StageChain that is completed with the same value as the StageChain returned by the given function.
When this chain completes normally, the given function is invoked with this chain result as the argument, returning another StageChain. When that chain completes normally, the StageChain returned by this method is completed with the same value. When that chain returns, this chain also returns with the same value and no further chains are evaluated.
To ensure progress, the supplied function must arrange eventual completion of its result.
This method is analogous to
Optional.flatMap
andStream.flatMap
.See the
CompletionStage
documentation for rules covering exceptional completion.- Type Parameters:
U
- The type of the returned StageChain's result- Parameters:
fn
- The function to use to compute another StageChain- Returns:
- The new StageChain
-
thenComposeAsync
public <U> StageChain<U,R> thenComposeAsync(Function<? super T,? extends StageChain<U,R>> fn, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new StageChain that is completed asynchronously, by a task running in the given executor, with the same value as the StageChain returned by the given function.
When this chain completes normally, the given function is invoked with this chain result as the argument, returning another StageChain. When that chain completes normally, the StageChain returned by this method is completed with the same value. When that chain returns, this chain also returns with the same value and no further chains are evaluated.
To ensure progress, the supplied function must arrange eventual completion of its result.
This method is analogous to
Optional.flatMap
andStream.flatMap
.See the
CompletionStage
documentation for rules covering exceptional completion.- Type Parameters:
U
- The type of the returned StageChain's result- Parameters:
fn
- The function to use to compute another StageChainexecutor
- The executor to use for asynchronous execution- Returns:
- The new StageChain
-
thenComposeStage
public <U> StageChain<U,R> thenComposeStage(Function<? super T,? extends CompletionStage<U>> fn)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new StageChain that is completed with the same value as the StageChain returned by the given function.
When this chain completes normally, the given function is invoked with this chain result as the argument, returning another StageChain. When that chain completes normally, the StageChain returned by this method is completed with the same value.
To ensure progress, the supplied function must arrange eventual completion of its result.
This method is analogous to
Optional.flatMap
andStream.flatMap
.See the
CompletionStage
documentation for rules covering exceptional completion.- Type Parameters:
U
- The type of the returned StageChain's result- Parameters:
fn
- The function to use to compute another StageChain- Returns:
- The new StageChain
-
thenComposeStageAsync
public <U> StageChain<U,R> thenComposeStageAsync(Function<? super T,? extends CompletionStage<U>> fn, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new StageChain that is completed with the same value as the StageChain returned by the given function.
When this chain completes normally, the given function is invoked with this chain result as the argument, returning another StageChain. When that chain completes normally, the StageChain returned by this method is completed with the same value.
To ensure progress, the supplied function must arrange eventual completion of its result.
This method is analogous to
Optional.flatMap
andStream.flatMap
.See the
CompletionStage
documentation for rules covering exceptional completion.- Type Parameters:
U
- The type of the returned StageChain's result- Parameters:
fn
- The function to use to compute another StageChainexecutor
- The executor to use for asynchronous execution- Returns:
- The new StageChain
-
thenDiscard
public StageChain<Void,R> thenDiscard()
Same as thenAccept, but simply discards the current result without running any action.When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:
Returns a new StageChain that, when this chain completes normally, completes normally with a value of
null
.- Returns:
- The new StageChain.
-
thenDiscardAsync
public StageChain<Void,R> thenDiscardAsync(Executor executor)
Same as thenAccept, but simply discards the current result without running any action.When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:
Returns a new StageChain that, when this chain completes normally, completes normally with a value of
null
.- Parameters:
executor
- The executor to use for asynchronous execution. As no action is executed, this might only affect the default executor for dependent chains.- Returns:
- The new StageChain.
-
thenHandle
public <U> StageChain<U,R> thenHandle(BiFunction<? super T,Throwable,? extends U> fn)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new StageChain that, when this chain completes either normally or exceptionally, is executed with this chain result and exception as arguments to the supplied function.
When this chain is complete, the given function is invoked with the result (or
null
if none) and the exception (ornull
if none) of this chain as arguments, and the function's result is used to complete the returned chain.- Type Parameters:
U
- The function's return type- Parameters:
fn
- The function to use to compute the value of the returned StageChain- Returns:
- The new StageChain
-
thenHandleAsync
public <U> StageChain<U,R> thenHandleAsync(BiFunction<? super T,Throwable,? extends U> fn, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new StageChain that, when this chain completes either normally or exceptionally, is executed using the supplied executor, with this chain result and exception as arguments to the supplied function.
When this chain is complete, the given function is invoked with the result (or
null
if none) and the exception (ornull
if none) of this chain as arguments, and the function's result is used to complete the returned chain.- Type Parameters:
U
- The function's return type- Parameters:
fn
- The function to use to compute the value of the returned StageChainexecutor
- The executor to use for asynchronous execution- Returns:
- The new StageChain
-
whenCompleteAccept
public StageChain<T,R> whenCompleteAccept(BiConsumer<? super T,Throwable> action)
-
whenCompleteAcceptAsync
public StageChain<T,R> whenCompleteAcceptAsync(BiConsumer<? super T,Throwable> action, Executor executor)
-
whenCompleteCompose
public StageChain<T,R> whenCompleteCompose(BiFunction<? super T,Throwable,? extends StageChain<?,R>> action)
-
whenCompleteComposeAsync
public StageChain<T,R> whenCompleteComposeAsync(BiFunction<? super T,Throwable,? extends StageChain<?,R>> action, Executor executor)
-
whenSuccessfulAccept
public StageChain<T,R> whenSuccessfulAccept(Consumer<? super T> action)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new StageChain with the same result or exception as this chain, that executes the given action when this stage completes.
When this chain is complete, the given action is invoked with the result of this chain. The returned chain is completed when the action completes.
- Parameters:
action
- The action to perform before completing the returned StageChain- Returns:
- The new StageChain.
-
whenSuccessfulAcceptAsync
public StageChain<T,R> whenSuccessfulAcceptAsync(Consumer<? super T> action, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new StageChain with the same result or exception as this chain, that executes the given action when this stage completes.
When this chain is complete, the given action is invoked with the result of this chain. The returned chain is completed when the action completes.
- Parameters:
action
- The action to perform before completing the returned StageChainexecutor
- The executor to use for asynchronous execution- Returns:
- The new StageChain.
-
whenSuccessfulCompose
public StageChain<T,R> whenSuccessfulCompose(Function<? super T,? extends StageChain<?,R>> action)
-
whenSuccessfulComposeAsync
public StageChain<T,R> whenSuccessfulComposeAsync(Function<? super T,? extends StageChain<?,R>> action, Executor executor)
-
whenSuccessfulComposeStage
public StageChain<T,R> whenSuccessfulComposeStage(Function<? super T,? extends CompletionStage<?>> action)
If this chain has already returned: does nothing and returns a StageChain that returns with the same return value. Otherwise:Returns a new StageChain with the same result or exception as this chain, that executes the given action when this stage completes.
When this chain is complete, the given action is invoked with the result of this chain. The returned chain is completed when stage returned by the action completes.
- Parameters:
action
- The action to perform before completing the returned StageChain- Returns:
- The new StageChain.
-
whenSuccessfulComposeStageAsync
public StageChain<T,R> whenSuccessfulComposeStageAsync(Function<? super T,? extends CompletionStage<?>> action, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new StageChain with the same result or exception as this chain, that executes the given action when this stage completes.
When this chain is complete, the given action is invoked with the result of this chain. The returned chain is completed when stage returned by the action completes.
- Parameters:
action
- The action to perform before completing the returned StageChainexecutor
- The executor to use for asynchronous execution- Returns:
- The new StageChain.
-
withDefaultExecutor
public StageChain<T,R> withDefaultExecutor(Executor defaultAsyncExecutor)
- Parameters:
defaultAsyncExecutor
- Default executor to use.- Returns:
- A chain with the same value as this chain, but with the given default executor.
-
withResource
public <A extends AutoCloseable,U> StageChain<U,R> withResource(IResourceOpenFunction<? super T,? extends A> resource, BiFunction<? super T,? super A,? extends U> combiner)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new chain that is completed when a resource was derived from the current value and combined with the current value by the given function. The resource, if opened, is always closed upon a call to
next(Function)
. Any errors in the close function are ignored.- Type Parameters:
A
- Type of the resource.U
- The type of the returned StageChain's current value.- Parameters:
resource
- The function that opens the resource.combiner
- The function that combines the resource with the current value.- Returns:
- The new StageChain.
-
withResource
public <A,U> StageChain<U,R> withResource(IResourceOpenFunction<? super T,? extends A> resource, IResourceCloseAction<? super A> close, BiFunction<? super T,? super A,? extends U> combiner)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new chain that is completed when a resource was derived from the current value and combined with the current value by the given function. The resource, if opened, is always closed via the given close function upon a call to
next(Function)
. Any errors in the close function are ignored.- Type Parameters:
A
- Type of the resource.U
- The type of the returned StageChain's current value.- Parameters:
resource
- The function that opens the resource.close
- The function that closes the resource.combiner
- The function that combines the resource with the current value.- Returns:
- The new StageChain.
-
withResourceAsync
public <A extends AutoCloseable,U> StageChain<U,R> withResourceAsync(IResourceOpenFunction<? super T,? extends A> resource, BiFunction<? super T,? super A,? extends U> combiner, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new chain that is completed asynchronously, by a task running in the given executor, when a resource was derived from the current value and combined with the current value by the given function. The resource, if opened, is always closed after the stage returned by a call to
next(Function)
has completed. Any errors in the close function are ignored.- Type Parameters:
A
- Type of the resource.U
- The type of the returned StageChain's current value.- Parameters:
resource
- The function that opens the resource.combiner
- The function that combines the resource with the current value.executor
- The executor to use for asynchronous execution- Returns:
- The new StageChain.
-
withResourceAsync
public <A,U> StageChain<U,R> withResourceAsync(IResourceOpenFunction<? super T,? extends A> open, IResourceCloseAction<? super A> close, BiFunction<? super T,? super A,? extends U> combiner, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new chain that is completed asynchronously, by a task running in the given executor, when a resource was derived from the current value and combined with the current value by the given function. The resource, if opened, is always closed via the given close function after the stage returned by a call to
next(Function)
has completed. Any errors in the close function are ignored.- Type Parameters:
A
- Type of the resource.U
- The type of the returned StageChain's current value.- Parameters:
open
- The function that opens the resource.close
- The function that closes the resource.combiner
- The function that combines the resource with the current value.executor
- The executor to use for asynchronous execution- Returns:
- The new StageChain.
-
withResourceFile
public <U> StageChain<U,R> withResourceFile(IResourceOpenFunction<? super T,File> resource, BiFunction<? super T,File,? extends U> combiner)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new chain that is completed when a file was derived from the current value and combined with the current value by the given function. The file, if provided, is DELETED after the stage returned by a call to
next(Function)
has completed. Any errors during the deletion of the file are ignored.- Type Parameters:
U
- The type of the returned StageChain's current value.- Parameters:
resource
- The function that opens the resource.combiner
- The function that combines the resource with the current value.- Returns:
- The new StageChain.
-
withResourceFileAsync
public <U> StageChain<U,R> withResourceFileAsync(IResourceOpenFunction<? super T,? extends File> resource, BiFunction<? super T,? super File,? extends U> combiner, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new chain that is completed asynchronously, by a task running in the given executor, when a file was derived from the current value and combined with the current value by the given function. The file, if provided, is DELETED after the stage returned by a call to
next(Function)
has completed. Any errors during the deletion of the file are ignored.- Type Parameters:
U
- The type of the returned StageChain's current value.- Parameters:
resource
- The function that opens the resource.combiner
- The function that combines the resource with the current value.executor
- The executor to use for asynchronous execution- Returns:
- The new StageChain.
-
withResourcePath
public <U> StageChain<U,R> withResourcePath(IResourceOpenFunction<? super T,? extends Path> resource, BiFunction<? super T,? super Path,? extends U> combiner)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new chain that is completed when a file was derived from the current value and combined with the current value by the given function. The file, if provided, is DELETED upon a call to
next(Function)
. Any errors during the deletion of the file are ignored.- Type Parameters:
U
- The type of the returned StageChain's current value.- Parameters:
resource
- The function that opens the resource.combiner
- The function that combines the resource with the current value.- Returns:
- The new StageChain.
-
withResourcePathAsync
public <U> StageChain<U,R> withResourcePathAsync(IResourceOpenFunction<? super T,? extends Path> resource, BiFunction<? super T,? super Path,? extends U> combiner, Executor executor)
When this chain has returned already: does nothing and returns a new chain that completes with the same return value. Otherwise:Returns a new chain that is completed asynchronously, by a task running in the given executor, when a file was derived from the current value and combined with the current value by the given function. The file, if provided, is DELETED after the stage returned by a call to
next(Function)
has completed. Any errors during the deletion of the file are ignored.- Type Parameters:
U
- The type of the returned StageChain's current value.- Parameters:
resource
- The function that opens the resource.combiner
- The function that combines the resource with the current value.executor
- The executor to use for asynchronous execution- Returns:
- The new StageChain.
-
finishToState
protected CompletableFuture<de.xima.fc.stage.StageChain.State<R,R>> finishToState(Function<? super T,? extends R> fn)
-
finishToStateAsync
protected CompletableFuture<de.xima.fc.stage.StageChain.State<R,R>> finishToStateAsync(Function<? super T,? extends R> fn, Executor executor)
-
begin
public static <R> StageChain<LocalVariables,R> begin(Executor defaultAsyncExecutor)
Starts a new chain with an empty set ofLocalVariables
.- Type Parameters:
R
- Type of the eventual return value one wishes to obtain after all transformations were applied.- Parameters:
defaultAsyncExecutor
- Default executor to use. When provided all methods are implicitly async (e.g.thenApplyAsync
instead ofthenApply
. Can benull
.- Returns:
- The new StageChain.
-
begin
public static <T,R> StageChain<T,R> begin(T value, Executor defaultAsyncExecutor)
Starts a new chain initialized with the given current value.- Type Parameters:
T
- Type of the current value for the new chain.R
- Type of the eventual return value one wishes to obtain after all transformations were applied.- Parameters:
value
- Current value for the new chain.defaultAsyncExecutor
- Default executor to use. When provided all methods are implicitly async (e.g.thenApplyAsync
instead ofthenApply
. Can benull
.- Returns:
- The new StageChain.
-
expect
public static <R> StageChain<Void,R> expect(Executor defaultAsyncExecutor)
Starts a new chain with the current value set tonull
.- Type Parameters:
R
- Type of the eventual return value one wishes to obtain after all transformations were applied.- Parameters:
defaultAsyncExecutor
- Default executor to use. When provided all methods are implicitly async (e.g.thenApplyAsync
instead ofthenApply
. Can benull
.- Returns:
- The new StageChain.
-
failed
public static <T,R> StageChain<T,R> failed(Throwable error, Executor defaultAsyncExecutor)
Starts a new chain that is completed exceptionally with given exception.- Type Parameters:
T
- Type of the current value for the new chain.R
- Type of the eventual return value one wishes to obtain after all transformations were applied.- Parameters:
error
- Exception with which to complete the new chain exceptionally.defaultAsyncExecutor
- Default executor to use. When provided all methods are implicitly async (e.g.thenApplyAsync
instead ofthenApply
. Can benull
.- Returns:
- The new StageChain.
-
resume
public static <T,R> StageChain<T,R> resume(CompletableFuture<T> stage, Executor defaultAsyncExecutor)
Starts a new chain initialized with the state of the given stage. If the stage completes normally, the returned chain completes normally with that value. If the stage completes exceptionally, the returned chain also completes exceptionally.- Type Parameters:
T
- Type of the current value for the new chain.R
- Type of the eventual return value one wishes to obtain after all transformations were applied.- Parameters:
stage
- Stage from which to start the chain.defaultAsyncExecutor
- Default executor to use. When provided all methods are implicitly async (e.g.thenApplyAsync
instead ofthenApply
. Can benull
.- Returns:
- The new StageChain.
-
-