Module java.base

Class Gatherers

java.lang.Object
java.util.stream.Gatherers

public final class Gatherers extends Object
Implementations of Gatherer that implement various useful intermediate operations, such as windowing functions, folding functions, transforming elements concurrently, etc.
  • Method Summary

    Modifier and Type
    Method
    Description
    static <T, R> Gatherer<T,?,R>
    fold(Supplier<R> initial, BiFunction<? super R,? super T,? extends R> folder)
    An operation which performs an ordered, reduction-like, transformation for scenarios where no combiner-function can be implemented, or for reductions which are intrinsically order-dependent.
    static <T, R> Gatherer<T,?,R>
    mapConcurrent(int maxConcurrency, Function<? super T,? extends R> mapper)
    An operation which executes operations concurrently with a fixed window of max concurrency, using VirtualThreads.
    static <TR> Gatherer<TR,?,TR>
    peek(Consumer<? super TR> effect)
    Runs an effect for each element which passes through this gatherer, in the order in which they are processed -- which in the case of parallel evaluation can be out-of-sequence compared to the sequential encounter order of the stream.
    static <TR> Gatherer<TR,?,TR>
    peekOrdered(Consumer<? super TR> effect)
    Runs an effect for each element which passes through this gatherer, in the order in which they appear in the stream.
    static <T, R> Gatherer<T,?,R>
    scan(Supplier<R> initial, BiFunction<? super R,? super T,? extends R> scanner)
    Performs a prefix scan -- an incremental accumulation, using the provided functions.
    static <TR> Gatherer<TR,?,List<TR>>
    windowFixed(int windowSize)
    Gathers elements into fixed-size windows.
    static <TR> Gatherer<TR,?,List<TR>>
    windowSliding(int windowSize)
    Gathers elements into sliding windows, sliding out the most previous element and sliding in the next element for each subsequent window.

    Methods declared in class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Method Details

    • windowFixed

      public static <TR> Gatherer<TR,?,List<TR>> windowFixed(int windowSize)
      Gathers elements into fixed-size windows. The last window may contain fewer elements than the supplied window size.

      Example:

      // will contain: [[1, 2, 3], [4, 5, 6], [7, 8]]
      List<List<Integer>> windows =
          Stream.of(1,2,3,4,5,6,7,8).gather(Gatherers.windowFixed(3)).toList();
      
      Type Parameters:
      TR - the type of elements the returned gatherer consumes and the contents of the windows it produces
      Parameters:
      windowSize - the size of the windows
      Returns:
      a new gatherer which groups elements into fixed-size windows
      Throws:
      IllegalArgumentException - when groupSize is less than 1
    • windowSliding

      public static <TR> Gatherer<TR,?,List<TR>> windowSliding(int windowSize)
      Gathers elements into sliding windows, sliding out the most previous element and sliding in the next element for each subsequent window. If the stream is empty then no window will be produced. If the size of the stream is smaller than the window size then only one window will be emitted, containing all elements.

      Example:

      // will contain: [[1, 2], [2, 3], [3, 4], [4, 5], [5, 6], [6, 7], [7, 8]]
      List<List<Integer>> windows =
          Stream.of(1,2,3,4,5,6,7,8).gather(Gatherers.windowSliding(2)).toList();
      
      Type Parameters:
      TR - the type of elements the returned gatherer consumes and the contents of the windows it produces
      Parameters:
      windowSize - the size of the windows
      Returns:
      a new gatherer which groups elements into sliding windows
      Throws:
      IllegalArgumentException - when windowSize is less than 1
    • fold

      public static <T, R> Gatherer<T,?,R> fold(Supplier<R> initial, BiFunction<? super R,? super T,? extends R> folder)
      An operation which performs an ordered, reduction-like, transformation for scenarios where no combiner-function can be implemented, or for reductions which are intrinsically order-dependent.

      This operation always emits a single resulting element.

      Example:

      // will contain: Optional[123456789]
      Optional<String> numberString =
          Stream.of(1,2,3,4,5,6,7,8,9)
                .gather(
                    Gatherers.fold(() -> "", (string, number) -> string + number)
                 )
                .findFirst();
      
      Type Parameters:
      T - the type of elements the returned gatherer consumes
      R - the type of elements the returned gatherer produces
      Parameters:
      initial - the identity value for the fold operation
      folder - the folding function
      Returns:
      a new Gatherer
      Throws:
      NullPointerException - if any of the parameters are null
      See Also:
    • peekOrdered

      public static <TR> Gatherer<TR,?,TR> peekOrdered(Consumer<? super TR> effect)
      Runs an effect for each element which passes through this gatherer, in the order in which they appear in the stream.

      This operation produces the same elements it consumes, and preserves ordering.

      Type Parameters:
      TR - the type of elements the returned gatherer consumes and produces
      Parameters:
      effect - the effect to execute with the current element
      Returns:
      a new gatherer which executes an effect, in order, for each element which passes through it
      Throws:
      NullPointerException - if the provided effect is null
      See Also:
    • peek

      public static <TR> Gatherer<TR,?,TR> peek(Consumer<? super TR> effect)
      Runs an effect for each element which passes through this gatherer, in the order in which they are processed -- which in the case of parallel evaluation can be out-of-sequence compared to the sequential encounter order of the stream.
      Type Parameters:
      TR - the type of elements the returned gatherer consumes and produces
      Parameters:
      effect - the effect to execute with the current element
      Returns:
      a new gatherer which executes an effect for each element which passes through it
      See Also:
    • scan

      public static <T, R> Gatherer<T,?,R> scan(Supplier<R> initial, BiFunction<? super R,? super T,? extends R> scanner)
      Performs a prefix scan -- an incremental accumulation, using the provided functions.
      Type Parameters:
      T - the type of element which this gatherer consumes
      R - the type of element which this gatherer produces
      Parameters:
      initial - the supplier of the initial value for the scanner
      scanner - the function to apply for each element
      Returns:
      a new Gatherer which performs a prefix scan
      Throws:
      NullPointerException - if any of the parameters are null
    • mapConcurrent

      public static <T, R> Gatherer<T,?,R> mapConcurrent(int maxConcurrency, Function<? super T,? extends R> mapper)
      An operation which executes operations concurrently with a fixed window of max concurrency, using VirtualThreads. This operation preserves the ordering of the stream.

      In progress tasks will be attempted to be cancelled, on a best-effort basis, in situations where the downstream no longer wants to receive any more elements.

      Type Parameters:
      T - the type of input
      R - the type of output
      Parameters:
      maxConcurrency - the maximum concurrency desired
      mapper - a function to be executed concurrently
      Returns:
      a new Gatherer
      Throws:
      IllegalArgumentException - if maxConcurrency is less than 1
      NullPointerException - if mapper is null