Package de.xima.fc.stage

Class XStageChainUtils

  • public final class XStageChainUtils
extends Object
    Utility methods for StageChains.
    Since:
    8.0.0
    Author:
    XIMA MEDIA GmbH

    • Method Detail

      • allOf

        public static <T,​R,​U> StageChain<List<R>,​U> allOf​(IStageChainFactory rsf,
                                                                    Function<? super T,​? extends R> fn,
                                                                    Iterable<? extends StageChain<? extends T,​R>> stages)
        Similar to CompletableFuture.allOf(), but grants immediate access to the individual values.

        Combines a list of stages into a single stage with the values from all stages. The returned stage is completed when all given stages are completed. The list contains all values in the order as the given stages. When a stage is null, the resulting list will contain a null value. When any stage completes exceptionally, the returned stage also completes exceptionally.

        Type Parameters:
        T - Type of the eventual result of the stages.
        Parameters:
        rsf - Stage factory for creating new stages.
        fn - A function that transforms the intermediate result into the eventual result, for stages that have not returned yet.
        stages - Stages to await.
        Returns:
        A new stage that is completed with the list of all values when all of the given stages have completed.

      • allOf

        @SafeVarargs
public static <T,​R,​U> StageChain<List<R>,​U> allOf​(IStageChainFactory rsf,
                                                                    Function<? super T,​? extends R> fn,
                                                                    StageChain<? extends T,​R>... stages)
        Similar to CompletableFuture.allOf(), but grants immediate access to the individual values.

        Combines a list of stages into a single stage with the values from all stages. The returned stage is completed when all given stages are completed. The list contains all values in the order as the given stages. When a stage is null, the resulting list will contain a null value. When any stage completes exceptionally, the returned stage also completes exceptionally.

        Type Parameters:
        T - Type of the current value of the given stages to await.
        R - Type of the eventual expected result of the given stages to await.
        U - Type of the eventual expected result of the returned stage.
        Parameters:
        rsf - Stage factory for creating new stages.
        fn - A function that transforms the intermediate result into the eventual result, for stages that have not returned yet.
        stages - Stages to await.
        Returns:
        A new stage that is completed with the list of all values when all of the given stages have completed.

      • allOf

        public static <T,​R,​U> StageChain<List<R>,​U> allOf​(IStageChainFactory rsf,
                                                                    Function<? super T,​? extends R> fn,
                                                                    Stream<? extends StageChain<? extends T,​R>> stages)
        Similar to CompletableFuture.allOf(), but grants immediate access to the individual values.

        Combines a list of stages into a single stage with the values from all stages. The returned stage is completed when all given stages are completed. The list contains all values in the order as the given stages. When a stage is null, the resulting list will contain a null value. When any stage completes exceptionally, the returned stage also completes exceptionally.

        Type Parameters:
        T - Type of the eventual result of the stages.
        Parameters:
        rsf - Stage factory for creating new stages.
        fn - A function that transforms the intermediate result into the eventual result, for stages that have not returned yet.
        stages - Stages to await.
        Returns:
        A new stage that is completed with the list of all values when all of the given stages have completed.

      • allOf

        public static <T,​R,​U> StageChain<List<R>,​U> allOf​(IStageChainFactory rsf,
                                                                    int chunkSize,
                                                                    Function<? super T,​? extends R> fn,
                                                                    Iterable<? extends Supplier<? extends StageChain<? extends T,​R>>> stageFactories)
        Similar to allOf, but additional partitions the stages into chunks of a given size and processes the chunks in order. This is useful when you need some degree of parallelism, but do not want to start a potentially unlimited number of tasks all at once.

        Calls each given factory to obtain the corresponding stage, and returns a stage that completes with a list of values from all given stages, in the order as given, when all stages complete. In additional, this method ensures that the factories of a chunk are only called when all stages of the previous chunk have completed.

        When a stage is null, the resulting list will contain a null value. When any stage completes exceptionally, the returned stage also completes exceptionally.

        Note: For this method to be useful, each stage factory should only initiate an asynchronous action (such as a network request) when it is called. If the stage is created before hand and then merely returned by the stage factory, a potential unlimited number of network requests might still be active at any given time. 

         // Reads the data of the first 10 users, then the data of the next 10 users, etc.
 // If fetchUserData starts a network request, at most 10 networks request will be active at any given time
 var userData = allOf(10, users.stream().map(user -> () -> fetchUserData(user)));
        Type Parameters:
        T - Type of the eventual result of the stages.
        R - Type of the eventual result of the stages.
        U - Type of the new expected return value of the returned stage.
        Parameters:
        rsf - Stage factory for creating new stages.
        chunkSize - Chunk size, must be positive.
        fn - A function that transforms the intermediate result into the eventual result, for stages that have not returned yet.
        stageFactories - Stages to await.
        Returns:
        A new stage that is completed with the list of all values when all stages obtained from the given factories have completed.

      • allOf

        public static <T,​R,​U> StageChain<List<R>,​U> allOf​(IStageChainFactory rsf,
                                                                    int chunkSize,
                                                                    Function<? super T,​? extends R> fn,
                                                                    Stream<? extends Supplier<? extends StageChain<? extends T,​R>>> stageFactories)
        Similar to allOf, but additional partitions the stages into chunks of a given size and processes the chunks in order. This is useful when you need some degree of parallelism, but do not want to start a potentially unlimited number of tasks all at once.

        Calls each given factory to obtain the corresponding stage, and returns a stage that completes with a list of values from all given stages, in the order as given, when all stages complete. In additional, this method ensures that the factories of a chunk are only called when all stages of the previous chunk have completed.

        When a stage is null, the resulting list will contain a null value. When any stage completes exceptionally, the returned stage also completes exceptionally.

        Note: For this method to be useful, each stage factory should only initiate an asynchronous action (such as a network request) when it is called. If the stage is created before hand and then merely returned by the stage factory, a potential unlimited number of network requests might still be active at any given time. 

         // Reads the data of the first 10 users, then the data of the next 10 users, etc.
 // If fetchUserData starts a network request, at most 10 networks request will be active at any given time
 var userData = allOf(10, users.stream().map(user -> () -> fetchUserData(user)));
        Type Parameters:
        T - Type of the eventual result of the stages.
        R - Type of the eventual result of the stages.
        U - Type of the new expected return value of the returned stage.
        Parameters:
        rsf - Stage factory for creating new stages.
        chunkSize - Chunk size, must be positive.
        fn - A function that transforms the intermediate result into the eventual result, for stages that have not returned yet.
        stageFactories - Stages to await.
        Returns:
        A new stage that is completed with the list of all values when all stages obtained from the given factories have completed.

      • allOf

        @SafeVarargs
public static <T,​R,​U> StageChain<List<R>,​U> allOf​(IStageChainFactory rsf,
                                                                    int chunkSize,
                                                                    Function<? super T,​? extends R> fn,
                                                                    Supplier<? extends StageChain<? extends T,​R>>... stageFactories)
        Similar to allOf, but additional partitions the stages into chunks of a given size and processes the chunks in order. This is useful when you need some degree of parallelism, but do not want to start a potentially unlimited number of tasks all at once.

        Calls each given factory to obtain the corresponding stage, and returns a stage that completes with a list of values from all given stages, in the order as given, when all stages complete. In additional, this method ensures that the factories of a chunk are only called when all stages of the previous chunk have completed.

        When a stage is null, the resulting list will contain a null value. When any stage completes exceptionally, the returned stage also completes exceptionally.

        Note: For this method to be useful, each stage factory should only initiate an asynchronous action (such as a network request) when it is called. If the stage is created before hand and then merely returned by the stage factory, a potential unlimited number of network requests might still be active at any given time. 

         // Reads the data of the first 10 users, then the data of the next 10 users, etc.
 // If fetchUserData starts a network request, at most 10 networks request will be active at any given time
 var userData = allOf(10, users.stream().map(user -> () -> fetchUserData(user)));
        Type Parameters:
        T - Type of the intermediate result of the stages.
        R - Type of the eventual result of the stages.
        U - Type of the new expected return value of the returned stage.
        Parameters:
        rsf - Stage factory for creating new stages.
        chunkSize - Chunk size, must be positive.
        fn - A function that transforms the intermediate result into the eventual result, for stages that have not returned yet.
        stageFactories - Stages to await.
        Returns:
        A new stage that is completed with the list of all values when all stages obtained from the given factories have completed.

      • allOf

        public static <T,​U> StageChain<List<T>,​U> allOf​(IStageChainFactory rsf,
                                                            int chunkSize,
                                                            Iterable<? extends Supplier<? extends StageChain<? extends T,​T>>> stageFactories)
        Waits for all stages to complete normally, then returns a list with the result of each stage, in that order. If any stages completes exceptionally, the returned stage also completes exceptionally.

        In addition, this method also ensures that at most chunkSize stages are started in parallel. Further stages are started only once the previous stages have completed.

        Note: For this method to be useful, each stage factory should only initiate an asynchronous action (such as a network request) when it is called. If the stage is created before hand and then merely returned by the stage factory, a potential unlimited number of network requests might still be active at any given time.

        Type Parameters:
        T - Type of the intermediate and return value.
        U - Type of the new expected return value of the returned stage.
        Parameters:
        rsf - Stage factory for creating new stages.
        chunkSize - Maximum number of pending stages.
        stageFactories - A list of supplier function that, when called, initiate and return a stage.
        Returns:
        A new stage that completes when all given stages have completed.

      • allOf

        public static <T,​U> StageChain<List<T>,​U> allOf​(IStageChainFactory rsf,
                                                            int chunkSize,
                                                            Stream<? extends Supplier<? extends StageChain<? extends T,​T>>> stageFactories)
        Waits for all stages to complete normally, then returns a list with the result of each stage, in that order. If any stages completes exceptionally, the returned stage also completes exceptionally.

        In addition, this method also ensures that at most chunkSize stages are started in parallel. Further stages are started only once the previous stages have completed.

        Note: For this method to be useful, each stage factory should only initiate an asynchronous action (such as a network request) when it is called. If the stage is created before hand and then merely returned by the stage factory, a potential unlimited number of network requests might still be active at any given time.

        Type Parameters:
        T - Type of the intermediate and return value.
        U - Type of the new expected return value of the returned stage.
        Parameters:
        rsf - Stage factory for creating new stages.
        chunkSize - Maximum number of pending stages.
        stageFactories - A list of supplier function that, when called, initiate and return a stage.
        Returns:
        A new stage that completes when all given stages have completed.

      • allOf

        @SafeVarargs
public static <T,​U> StageChain<List<T>,​U> allOf​(IStageChainFactory rsf,
                                                            int chunkSize,
                                                            Supplier<? extends StageChain<? extends T,​T>>... stageFactories)
        Waits for all stages to complete normally, then returns a list with the result of each stage, in that order. If any stages completes exceptionally, the returned stage also completes exceptionally.

        In addition, this method also ensures that at most chunkSize stages are started in parallel. Further stages are started only once the previous stages have completed.

        Note: For this method to be useful, each stage factory should only initiate an asynchronous action (such as a network request) when it is called. If the stage is created before hand and then merely returned by the stage factory, a potential unlimited number of network requests might still be active at any given time.

        Type Parameters:
        T - Type of the intermediate and return value.
        U - Type of the new expected return value of the returned stage.
        Parameters:
        rsf - Stage factory for creating new stages.
        chunkSize - Maximum number of pending stages.
        stageFactories - A list of supplier function that, when called, initiate and return a stage.
        Returns:
        A new stage that completes when all given stages have completed.

      • allOf

        public static <T,​U> StageChain<List<T>,​U> allOf​(IStageChainFactory rsf,
                                                            Iterable<? extends StageChain<? extends T,​T>> stages)
        Waits for all stages to complete normally, then returns a list with the result of each stage, in that order. If any stages completes exceptionally, the returned stage also completes exceptionally.
        Type Parameters:
        T - Type of the intermediate and return value.
        U - Type of the new expected return value of the returned stage.
        Parameters:
        rsf - Stage factory for creating new stages.
        stages - A list of stages to await.
        Returns:
        A new stage that completes when all given stages have completed.

      • allOf

        @SafeVarargs
public static <T,​U> StageChain<List<T>,​U> allOf​(IStageChainFactory rsf,
                                                            StageChain<? extends T,​T>... stages)
        Waits for all stages to complete normally, then returns a list with the result of each stage, in that order. If any stages completes exceptionally, the returned stage also completes exceptionally.
        Type Parameters:
        T - Type of the intermediate and return value.
        U - Type of the new expected return value of the returned stage.
        Parameters:
        rsf - Stage factory for creating new stages.
        stages - A list of stages to await.
        Returns:
        A new stage that completes when all given stages have completed.

      • allOf

        public static <T,​U> StageChain<List<T>,​U> allOf​(IStageChainFactory rsf,
                                                            Stream<? extends StageChain<? extends T,​T>> stages)
        Waits for all stages to complete normally, then returns a list with the result of each stage, in that order. If any stages completes exceptionally, the returned stage also completes exceptionally.
        Type Parameters:
        T - Type of the intermediate and return value.
        U - Type of the new expected return value of the returned stage.
        Parameters:
        rsf - Stage factory for creating new stages.
        stages - A list of stages to await.
        Returns:
        A new stage that completes when all given stages have completed.