Package de.xima.fc.stage

Class 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 a CompletableFuture 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) or opened resources closed when the chain completes). This can be very useful when you need to do complex processing with StageChains. In combination with LocalVariables, 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 Detail

      • __rawFinishToStage

        public CompletableFuture<R> __rawFinishToStage​(Function<? super T,​? extends R> fn)
        Similar to next(Function). Can be used to access the underlying CompletableFuture 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 to nextAsync(Function, Executor). Can be used to access the underlying CompletableFuture 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 exceptionally
        executor - 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 exceptionally
        executor - 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 via withResource(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 via withResource(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 a TimeoutException 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 a TimeoutException 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 as returnIf(Predicate, Function), but always returns null. When this chain has returned, does nothing. Otherwise, returns a new returned stage chain with a return value of null.
        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 as returnIf(Predicate, Function), but always returns null. 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 of null. 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 as returnIf(Predicate, Function), but always returns null. 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 of null. 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 as returnIf(Predicate, Function), but always returns null. When this chain has returned, does nothing. Otherwise, returns a new returned stage chain with a return value of null. 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 StageChain
        executor - 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 and Stream.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 and Stream.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
        executor - 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 and Stream.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 and Stream.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
        executor - 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 and Stream.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 and Stream.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
        executor - 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 (or null 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 (or null 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
        executor - The executor to use for asynchronous execution
        Returns:
        The new StageChain

      • 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 StageChain
        executor - The executor to use for asynchronous execution
        Returns:
        The new StageChain.

      • 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 StageChain
        executor - 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)

      • begin

        public static <R> StageChain<LocalVariables,​R> begin​(Executor defaultAsyncExecutor)
        Starts a new chain with an empty set of LocalVariables.
        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 of thenApply. Can be null.
        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 of thenApply. Can be null.
        Returns:
        The new StageChain.

      • expect

        public static <R> StageChain<Void,​R> expect​(Executor defaultAsyncExecutor)
        Starts a new chain with the current value set to null.
        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 of thenApply. Can be null.
        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 of thenApply. Can be null.
        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 of thenApply. Can be null.
        Returns:
        The new StageChain.