Stream gatherers

suggest change

Java 24 made stream gatherers final (JEP 485, previewed in Java 22 and 23). A gatherer is a custom intermediate operation. You plug it into a pipeline with Stream.gather(...), the same way a Collector is a custom terminal operation that you plug in with collect(...).

Before gatherers, if map, filter, flatMap, takeWhile and friends couldn't express what you needed, you had to end the stream, do the work in a loop and start a new stream. Fixed-size batches, sliding windows, running totals, "distinct by key" and "stop after the first match, but include it" are all awkward with the built-in operations. A gatherer can do all of them, because it can:

This article covers:

The examples are single files you run with java Example.java. Output is from JDK 25. Gatherers need Java 24 or newer, with no --enable-preview flag.

Stream basics are in Streams. Related articles: Flatten Streams with flatMap, Reduction with Streams and Collect Elements of a Stream into a Collection.

Windows: windowFixed and windowSliding

Gatherers.windowFixed(n) groups elements into lists of n. The last list can be shorter. Gatherers.windowSliding(n) emits every run of n consecutive elements:

import java.util.List;
import java.util.stream.Gatherers;
import java.util.stream.Stream;

public class Windows {
    public static void main(String[] args) {
        List<List<Integer>> fixed = Stream.of(1, 2, 3, 4, 5, 6, 7)
                .gather(Gatherers.windowFixed(3))
                .toList();
        System.out.println("fixed:   " + fixed);

        List<List<Integer>> sliding = Stream.of(1, 2, 3, 4, 5)
                .gather(Gatherers.windowSliding(3))
                .toList();
        System.out.println("sliding: " + sliding);

        // fewer elements than the window size: one short window
        System.out.println("short:   " + Stream.of(1, 2).gather(Gatherers.windowSliding(3)).toList());

        // moving average of daily temperatures
        List<Double> temps = List.of(20.0, 22.0, 21.0, 25.0, 27.0, 26.0);
        List<Double> avg = temps.stream()
                .gather(Gatherers.windowSliding(3))
                .map(w -> w.stream().mapToDouble(Double::doubleValue).average().orElseThrow())
                .toList();
        System.out.println("average: " + avg);

        // pairs of consecutive elements: differences
        List<Integer> readings = List.of(100, 104, 103, 110, 120);
        List<Integer> deltas = readings.stream()
                .gather(Gatherers.windowSliding(2))
                .map(p -> p.get(1) - p.get(0))
                .toList();
        System.out.println("deltas:  " + deltas);

        try {
            Stream.of(1).gather(Gatherers.windowFixed(0)).toList();
        } catch (IllegalArgumentException e) {
            System.out.println("error:   " + e.getMessage());
        }
    }
}
fixed:   [[1, 2, 3], [4, 5, 6], [7]]
sliding: [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
short:   [[1, 2]]
average: [21.0, 22.666666666666668, 24.333333333333332, 26.0]
deltas:  [4, -1, 7, 10]
error:   'windowSize' must be greater than zero

Before Java 24 you would write batching with index arithmetic on a List:

import java.util.List;
import java.util.stream.IntStream;
import java.util.stream.Gatherers;

public class BeforeGatherers {
    public static void main(String[] args) {
        List<Integer> data = List.of(1, 2, 3, 4, 5, 6, 7);
        int size = 3;

        // before Java 24: index arithmetic, only works on a List you already have
        List<List<Integer>> old = IntStream.range(0, (data.size() + size - 1) / size)
                .mapToObj(i -> data.subList(i * size, Math.min((i + 1) * size, data.size())))
                .toList();
        System.out.println(old);

        // Java 24+: works on any stream, including infinite ones
        System.out.println(data.stream().gather(Gatherers.windowFixed(size)).toList());
    }
}
[[1, 2, 3], [4, 5, 6], [7]]
[[1, 2, 3], [4, 5, 6], [7]]

The subList version needs all the data in a random-access list up front. The gatherer works on any stream: lines from a file, an infinite Stream.iterate, or the output of earlier stream stages.

Running state: scan and fold

Gatherers.scan(initial, f) emits the accumulated value after every element, so you get a running total. Gatherers.fold(initial, f) emits only the final value, as a one-element stream:

import java.util.List;
import java.util.Optional;
import java.util.stream.Gatherers;
import java.util.stream.Stream;

public class FoldScan {
    public static void main(String[] args) {
        // scan: running total, one output per input
        List<Integer> running = Stream.of(5, 3, -2, 10)
                .gather(Gatherers.scan(() -> 0, Integer::sum))
                .toList();
        System.out.println("scan:  " + running);

        // fold: only the final value, as a one-element stream
        Optional<String> joined = Stream.of(1, 2, 3)
                .gather(Gatherers.fold(() -> "", (acc, n) -> acc + n))
                .findFirst();
        System.out.println("fold:  " + joined.orElseThrow());

        // the seed and the elements may have different types
        Stream.of("apple", "kiwi", "banana")
                .gather(Gatherers.scan(() -> 0, (len, s) -> len + s.length()))
                .forEach(n -> System.out.print(n + " "));
        System.out.println();

        // fold on an empty stream still emits the seed
        System.out.println("empty: " + Stream.<Integer>empty()
                .gather(Gatherers.fold(() -> 0, Integer::sum)).toList());

        // balance never going below zero: scan then check
        boolean overdrawn = Stream.of(100, -30, -80, 50)
                .gather(Gatherers.scan(() -> 0, Integer::sum))
                .anyMatch(balance -> balance < 0);
        System.out.println("overdrawn: " + overdrawn);
    }
}
scan:  [5, 8, 6, 16]
fold:  123
5 9 15 
empty: [0]
overdrawn: true

Use fold when you want a reduction but then keep going with more stream operations. If the reduction is the last step, reduce or a Collector is usually clearer.

Concurrent mapping: mapConcurrent

Gatherers.mapConcurrent(maxConcurrency, mapper) runs the mapper on virtual threads, with at most maxConcurrency calls in flight at once. Results come out in the original order. It's meant for blocking I/O such as HTTP calls or database queries, and it gives you bounded thread-per-task concurrency in one line:

import java.util.List;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.stream.Gatherers;
import java.util.stream.IntStream;

public class MapConcurrent {
    static final AtomicInteger inFlight = new AtomicInteger();
    static final AtomicInteger maxInFlight = new AtomicInteger();

    // pretend this is an HTTP call that takes 200 ms
    static String fetch(int id) {
        int now = inFlight.incrementAndGet();
        maxInFlight.accumulateAndGet(now, Math::max);
        try {
            Thread.sleep(200 - id * 10); // later ids finish sooner
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new RuntimeException(e);
        } finally {
            inFlight.decrementAndGet();
        }
        return "user-" + id + (Thread.currentThread().isVirtual() ? " (virtual)" : "");
    }

    public static void main(String[] args) {
        long start = System.nanoTime();
        List<String> users = IntStream.rangeClosed(1, 10).boxed()
                .gather(Gatherers.mapConcurrent(4, MapConcurrent::fetch))
                .toList();
        long ms = (System.nanoTime() - start) / 1_000_000;

        users.forEach(System.out::println);
        System.out.println("max in flight: " + maxInFlight.get());
        System.out.println("took about " + (ms / 100 * 100) + " ms (sequential: ~1450 ms)");
    }
}
user-1 (virtual)
user-2 (virtual)
user-3 (virtual)
user-4 (virtual)
user-5 (virtual)
user-6 (virtual)
user-7 (virtual)
user-8 (virtual)
user-9 (virtual)
user-10 (virtual)
max in flight: 4
took about 400 ms (sequential: ~1450 ms)

The later ids sleep less, so they finish first, but the output is still in input order. Ten calls of 100-190 ms each would take about 1450 ms one after another. With 4 at a time it takes about 400 ms.

Here's what happens when a call fails, and when the stream stops early:

import java.util.List;
import java.util.Set;
import java.util.TreeSet;
import java.util.concurrent.ConcurrentSkipListSet;
import java.util.stream.Gatherers;
import java.util.stream.IntStream;

public class MapConcurrentErrors {
    public static void main(String[] args) {
        Set<String> events = new ConcurrentSkipListSet<>();
        long start = System.nanoTime();
        try {
            IntStream.rangeClosed(1, 6).boxed()
                    .gather(Gatherers.mapConcurrent(3, id -> {
                        if (id == 2) {
                            throw new IllegalStateException("user " + id + " not found");
                        }
                        try {
                            Thread.sleep(id == 1 ? 100 : 5000);
                        } catch (InterruptedException e) {
                            events.add("task " + id + " interrupted");
                            return "cancelled";
                        }
                        return "user-" + id;
                    }))
                    .toList();
        } catch (RuntimeException e) {
            System.out.println(e.getClass().getSimpleName() + ": " + e.getMessage());
        }
        System.out.println("failed after ~" + (System.nanoTime() - start) / 100_000_000 * 100 + " ms");
        try { Thread.sleep(100); } catch (InterruptedException e) { }
        events.forEach(System.out::println);

        // short-circuiting: stops starting new tasks once limit() is satisfied
        Set<Integer> started = new ConcurrentSkipListSet<>();
        List<Integer> first = IntStream.rangeClosed(1, 1000).boxed()
                .gather(Gatherers.mapConcurrent(4, id -> {
                    started.add(id);
                    return id * id;
                }))
                .limit(2)
                .toList();
        System.out.println(first + ", started " + started.size() + " of 1000 tasks");
    }
}
IllegalStateException: user 2 not found
failed after ~100 ms
task 3 interrupted
[1, 4], started 2 of 1000 tasks

mapConcurrent works on a sequential stream; it doesn't need .parallel().

Writing your own gatherer

A Gatherer<T, A, R> takes elements of type T, keeps state of type A and emits elements of type R. It's defined by up to four functions:

Function Type Purpose
initializer Supplier<A> create the private state
integrator Gatherer.Integrator<A, T, R> handle one element: update state, push outputs, return false to stop
combiner BinaryOperator<A> merge two states when running in parallel
finisher BiConsumer<A, Gatherer.Downstream<? super R>> after the last element: push any remaining outputs

Only the integrator is required. The Downstream object is how you emit: downstream.push(r) sends r to the next stage and returns false if the downstream doesn't want any more elements (for example, because limit is satisfied).

You rarely implement the interface directly. Use the factory methods instead:

A stateless gatherer

The simplest gatherer has no state and decides what to push for each element. Here is mapNotNull, which maps and drops null results:

import java.util.List;
import java.util.function.Function;
import java.util.stream.Gatherer;
import java.util.stream.Stream;

public class Stateless {
    // like map(), but drops elements for which the mapper returns null
    static <T, R> Gatherer<T, ?, R> mapNotNull(Function<? super T, ? extends R> mapper) {
        return Gatherer.of(Gatherer.Integrator.ofGreedy((state, element, downstream) -> {
            R result = mapper.apply(element);
            if (result != null) {
                return downstream.push(result);
            }
            return true;
        }));
    }

    static Integer parseOrNull(String s) {
        try {
            return Integer.parseInt(s.strip());
        } catch (NumberFormatException e) {
            return null;
        }
    }

    public static void main(String[] args) {
        List<Integer> numbers = Stream.of("1", " 22", "x", "", "333", "4.5")
                .gather(mapNotNull(Stateless::parseOrNull))
                .toList();
        System.out.println(numbers);
    }
}
[1, 22, 333]

Integrator.ofGreedy(...) marks an integrator that never starts a short-circuit itself: it consumes all its input and only passes along the false from push. That lets the stream choose a more efficient evaluation. Use Integrator.of(...) when your integrator can decide to stop on its own.

The state parameter is unused here. Without an initializer the state type is Void.

State: distinctBy and dropRepeats

The initializer creates the state, and the integrator receives it with every element:

import java.util.HashSet;
import java.util.List;
import java.util.Objects;
import java.util.Set;
import java.util.function.Function;
import java.util.stream.Gatherer;
import java.util.stream.Stream;

public class DistinctBy {
    // keep the first element for each key
    static <T, K> Gatherer<T, ?, T> distinctBy(Function<? super T, ? extends K> key) {
        return Gatherer.ofSequential(
                () -> new HashSet<K>(),                      // initializer: fresh state per evaluation
                Gatherer.Integrator.ofGreedy((seen, element, downstream) -> {
                    if (seen.add(key.apply(element))) {
                        return downstream.push(element);
                    }
                    return true;
                }));
    }

    // drop elements equal to the previous one (like Unix uniq)
    static <T> Gatherer<T, ?, T> dropRepeats() {
        class Last { T value; boolean hasValue; }
        return Gatherer.ofSequential(
                Last::new,
                Gatherer.Integrator.ofGreedy((last, element, downstream) -> {
                    if (last.hasValue && Objects.equals(last.value, element)) {
                        return true;
                    }
                    last.value = element;
                    last.hasValue = true;
                    return downstream.push(element);
                }));
    }

    record Person(String name, String city) {}

    public static void main(String[] args) {
        List<Person> people = List.of(
                new Person("Ann", "Oslo"), new Person("Bob", "Rome"),
                new Person("Cid", "Oslo"), new Person("Dan", "Lima"),
                new Person("Eve", "Rome"));
        people.stream()
                .gather(distinctBy(Person::city))
                .forEach(System.out::println);

        System.out.println(Stream.of(1, 1, 2, 2, 2, 3, 1, 1).gather(dropRepeats()).toList());

        // the gatherer object is reusable: each stream gets its own state
        var byLength = distinctBy(String::length);
        System.out.println(Stream.of("a", "bb", "c", "dd").gather(byLength).toList());
        System.out.println(Stream.of("x", "yy", "zzz").gather(byLength).toList());
    }
}
Person[name=Ann, city=Oslo]
Person[name=Bob, city=Rome]
Person[name=Dan, city=Lima]
[1, 2, 3, 1]
[a, bb]
[x, yy, zzz]

A finisher: batching by size

The finisher runs after the last element. That's where a buffering gatherer flushes what it still holds:

import java.util.ArrayList;
import java.util.List;
import java.util.stream.Gatherer;
import java.util.stream.Stream;

public class Batching {
    // group strings into batches whose total length stays within maxChars
    static Gatherer<String, ?, List<String>> batchByLength(int maxChars) {
        class Batch {
            List<String> items = new ArrayList<>();
            int chars;
        }
        return Gatherer.ofSequential(
                Batch::new,
                Gatherer.Integrator.ofGreedy((batch, s, downstream) -> {
                    if (!batch.items.isEmpty() && batch.chars + s.length() > maxChars) {
                        boolean more = downstream.push(List.copyOf(batch.items));
                        batch.items.clear();
                        batch.chars = 0;
                        if (!more) {
                            return false;                // downstream is done (e.g. limit)
                        }
                    }
                    batch.items.add(s);
                    batch.chars += s.length();
                    return true;
                }),
                (batch, downstream) -> {             // finisher: flush the last batch
                    if (!batch.items.isEmpty() && !downstream.isRejecting()) {
                        downstream.push(List.copyOf(batch.items));
                    }
                });
    }

    public static void main(String[] args) {
        Stream.of("alpha", "beta", "gamma", "delta", "epsilon", "zeta", "eta")
                .gather(batchByLength(10))
                .forEach(System.out::println);

        System.out.println(Stream.of("alpha", "beta", "gamma", "delta", "epsilon")
                .gather(batchByLength(10))
                .limit(1)
                .toList());
    }
}
[alpha, beta]
[gamma, delta]
[epsilon]
[zeta, eta]
[[alpha, beta]]

Without the finisher, [zeta, eta] would be lost. windowFixed works the same way internally, but here the batch boundary depends on the content, which windowFixed can't express.

When a push returns false, return false from the integrator too, so the upstream stops sending elements. In the finisher, check downstream.isRejecting() before pushing. In the limit(1) run above, the integrator stopped after the first batch and the finisher pushed nothing.

Short-circuiting: takeUntil

An integrator returns true to ask for more elements and false to stop. takeWhile drops the element that ends the run. This gatherer keeps it:

import java.util.List;
import java.util.function.Predicate;
import java.util.stream.Gatherer;
import java.util.stream.Stream;

public class ShortCircuit {
    // like takeWhile(), but also emits the first element that fails the test
    static <T> Gatherer<T, ?, T> takeUntil(Predicate<? super T> stop) {
        return Gatherer.ofSequential(
                Gatherer.Integrator.of((state, element, downstream) -> {
                    boolean more = downstream.push(element);
                    return more && !stop.test(element);   // false = "send me nothing more"
                }));
    }

    public static void main(String[] args) {
        List<String> lines = List.of("HEADER", "a=1", "b=2", "END", "garbage", "more garbage");

        System.out.println(lines.stream().takeWhile(l -> !l.equals("END")).toList());
        System.out.println(lines.stream().gather(takeUntil(l -> l.equals("END"))).toList());

        // works on an infinite stream because it stops pulling
        System.out.println(Stream.iterate(1, n -> n * 3)
                .peek(n -> System.out.print("[" + n + "] "))
                .gather(takeUntil(n -> n > 100))
                .toList());
    }
}
[HEADER, a=1, b=2]
[HEADER, a=1, b=2, END]
[1] [3] [9] [27] [81] [243] [1, 3, 9, 27, 81, 243]

The integrator pushes the element first, then returns false once it has seen the stop element, or when push returned false. Because it stops pulling, it works on an infinite Stream.iterate: the peek output shows that nothing after 243 was generated.

This integrator is created with Integrator.of, not ofGreedy, because it decides to stop on its own.

Composing gatherers with andThen

a.andThen(b) creates a gatherer that runs a and feeds its output into b. That lets you build a reusable operation out of smaller ones and give it a name:

import java.util.Objects;
import java.util.function.Function;
import java.util.stream.Gatherer;
import java.util.stream.Gatherers;
import java.util.stream.Stream;

public class Compose {
    static <T> Gatherer<T, ?, T> dropRepeats() {
        class Last { T value; boolean hasValue; }
        return Gatherer.ofSequential(
                Last::new,
                Gatherer.Integrator.ofGreedy((last, element, downstream) -> {
                    if (last.hasValue && Objects.equals(last.value, element)) {
                        return true;
                    }
                    last.value = element;
                    last.hasValue = true;
                    return downstream.push(element);
                }));
    }

    static <T, R> Gatherer<T, ?, R> map(Function<? super T, ? extends R> f) {
        return Gatherer.of((_, element, downstream) -> downstream.push(f.apply(element)));
    }

    public static void main(String[] args) {
        // which state transitions happened? dedupe, then look at consecutive pairs
        Gatherer<String, ?, String> transitions = Compose.<String>dropRepeats()
                .andThen(Gatherers.windowSliding(2))
                .andThen(map(pair -> pair.get(0) + " -> " + pair.get(1)));

        Stream.of("idle", "idle", "running", "running", "paused", "running", "idle")
                .gather(transitions)
                .forEach(System.out::println);

        // chained gather() calls mean the same thing
        System.out.println(Stream.of(1, 1, 2, 3, 3)
                .gather(dropRepeats())
                .gather(Gatherers.windowSliding(2))
                .toList());
    }
}
idle -> running
running -> paused
paused -> running
running -> idle
[[1, 2], [2, 3]]

stream.gather(a).gather(b) is equivalent to stream.gather(a.andThen(b)), so pick whichever reads better. Use andThen when you want to store or return the combined operation as a single value.

The map helper shows how short a stateless gatherer can be. _ (an unnamed variable, final in Java 22) marks the unused state parameter.

Parallel gatherers

A gatherer created with Gatherer.of(...) can run in parallel when the stream is parallel. The stream splits the input into chunks, runs the initializer and integrator on each chunk, merges the states with the combiner and calls the finisher once at the end.

Here topK keeps a bounded min-heap per chunk and merges heaps in the combiner:

import java.util.Comparator;
import java.util.List;
import java.util.PriorityQueue;
import java.util.stream.Gatherer;
import java.util.stream.IntStream;

public class Parallel {
    // the k largest elements, largest first; works in parallel
    static <T extends Comparable<? super T>> Gatherer<T, ?, T> topK(int k) {
        return Gatherer.of(
                () -> new PriorityQueue<T>(),                         // min-heap per chunk
                Gatherer.Integrator.ofGreedy((heap, element, downstream) -> {
                    heap.offer(element);
                    if (heap.size() > k) {
                        heap.poll();                                  // drop the smallest
                    }
                    return true;
                }),
                (left, right) -> {                                    // combiner: merge two chunks
                    for (T t : right) {
                        left.offer(t);
                        if (left.size() > k) {
                            left.poll();
                        }
                    }
                    return left;
                },
                (heap, downstream) -> heap.stream()                   // finisher
                        .sorted(Comparator.reverseOrder())
                        .forEach(downstream::push));
    }

    public static void main(String[] args) {
        List<Integer> parallel = IntStream.range(0, 1_000_000).boxed()
                .parallel()
                .map(n -> (int) ((n * 7919L) % 1_000_003))
                .gather(topK(5))
                .toList();
        List<Integer> sequential = IntStream.range(0, 1_000_000).boxed()
                .map(n -> (int) ((n * 7919L) % 1_000_003))
                .gather(topK(5))
                .toList();
        System.out.println(parallel);
        System.out.println(parallel.equals(sequential));
    }
}
[1000002, 1000001, 1000000, 999999, 999998]
true

Some rules for parallel gatherers:

topK emits only from its finisher, much like a collector. Writing it as a gatherer means the pipeline can continue afterwards with map, filter or another gather.

mapMulti: simple one-to-many mapping

Java 16 added Stream.mapMulti, a lighter alternative to flatMap when each element turns into a few (or zero) elements. Instead of returning a stream, the lambda calls sink.accept(...) once for each output:

import java.util.List;
import java.util.stream.Stream;

public class MapMulti {
    record Order(String id, List<String> items) {}

    public static void main(String[] args) {
        List<Order> orders = List.of(
                new Order("A1", List.of("pen", "ink")),
                new Order("B2", List.of()),
                new Order("C3", List.of("paper")));

        // zero or more outputs per input, without building a Stream for each
        List<String> lines = orders.stream()
                .<String>mapMulti((order, sink) -> {
                    for (String item : order.items()) {
                        sink.accept(order.id() + ":" + item);
                    }
                })
                .toList();
        System.out.println(lines);

        // filter and cast in one step
        List<Object> mixed = List.of(1, "two", 3.0, 4, "five");
        List<Integer> ints = mixed.stream()
                .<Integer>mapMulti((o, sink) -> {
                    if (o instanceof Integer i) {
                        sink.accept(i);
                    }
                })
                .toList();
        System.out.println(ints);

        // same thing with flatMap allocates a stream per element
        System.out.println(orders.stream()
                .flatMap(o -> o.items().stream().map(i -> o.id() + ":" + i))
                .toList());
    }
}
[A1:pen, A1:ink, C3:paper]
[1, 4]
[A1:pen, A1:ink, C3:paper]

mapMulti has no state and can't stop the stream. If you need either, write a gatherer.

When to use what

If the logic reads more naturally as a for loop with a couple of variables, a loop is still a good choice.

Summary

Feedback about page:

Feedback:
Optional: your email if you want me to get back to you:



Table Of Contents