Stream gatherers
suggest changeJava 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:
- keep private state between elements
- emit zero, one or many elements for each input
- emit more elements after the input ends
- stop the stream early (short-circuit)
- optionally run in parallel
This article covers:
- the built-in gatherers in
java.util.stream.Gatherers:windowFixed,windowSliding,fold,scanandmapConcurrent - writing your own
Gatherer: integrator, state, finisher, short-circuiting - composing gatherers with
andThen - parallel gatherers with a combiner
Stream.mapMulti(Java 16), a lighter tool for simple one-to-many mapping
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
- Each window is an unmodifiable
List. Callingaddon it throwsUnsupportedOperationException. windowFixednever drops elements. The leftover[7]is emitted when the input ends.windowSlidingemits a single short window if the stream has fewer elements than the window size. Otherwise every window has exactlynelements.windowSliding(2)is the usual way to look at consecutive pairs: deltas, "did the value change", "is the list sorted".
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
- The initial value comes from a
Supplier, so each stream evaluation starts with a fresh one. - The accumulator type can differ from the element type.
(len, s) -> len + s.length()turns strings into runningIntegertotals. foldemits the seed on an empty stream, so you always get exactly one element.- Both are sequential: the function is applied strictly left to right, so it doesn't need to be associative. That's the difference from
reduce, which requires an associative function so it can run in parallel.
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
- If a mapper throws, the exception is rethrown from the stream, and tasks that are still running are interrupted (task 3 here). Because results are delivered in order, a failure surfaces only when its turn comes: task 2 failed at once, but the stream first waited for task 1.
- With a short-circuiting operation like
limitorfindFirstdownstream,mapConcurrentstops starting new tasks. The exact number started depends on timing (anywhere from 2 to 5 in different runs), but it's bounded by the concurrency limit, not by the size of the input. - The concurrency limit doubles as a rate limiter. Don't set it higher than the remote service or connection pool can take.
- It doesn't help CPU-bound work. Use a Parallel Stream for that.
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:
Gatherer.of(integrator)andGatherer.of(initializer, integrator, combiner, finisher)for gatherers that can run in parallelGatherer.ofSequential(integrator),ofSequential(initializer, integrator)andofSequential(initializer, integrator, finisher)for gatherers that always process elements in order
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]
distinctBykeeps aHashSetof keys it has seen. The built-indistinct()can only compare whole elements.dropRepeatsuses a small local class as a mutable state holder. A gatherer's state is private to one evaluation, so a plain mutable object is fine. There's no need for atomics.- The initializer runs once for every stream that uses the gatherer, so one gatherer object can be stored in a variable or a constant and reused. Never capture mutable state directly in the lambdas (for example, a
HashSetcreated outside the initializer). It would be shared between streams. - Both use
ofSequential. They depend on encounter order, so running them on chunks in parallel would give wrong answers.
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:
- The combiner must merge two states into one that is equivalent to processing both chunks in sequence.
- A stateless gatherer from
Gatherer.of(integrator)needs no combiner and runs in parallel as-is. The output keeps encounter order. - A gatherer created with
ofSequentialin a parallel stream doesn't break anything. That stage is evaluated sequentially, while the stages around it can still run in parallel. windowFixed,windowSliding,fold,scanandmapConcurrentare all sequential.
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]
flatMapcreates aStreamobject for every element.mapMultidoesn't, which is cheaper when most elements produce zero or one output.- The result type usually has to be given explicitly (
.<String>mapMulti(...)), because Java can't infer it from the lambda body. mapMultiwithinstanceofis a compact way to filter and cast in one step.- There are primitive versions:
mapMultiToInt,mapMultiToLongandmapMultiToDouble.
mapMulti has no state and can't stop the stream. If you need either, write a gatherer.
When to use what
- One output per element:
map. Zero or more outputs, no state:filter,flatMapormapMulti. - Fixed batches, sliding windows, running totals: the built-in
Gatherers. - Blocking I/O on many elements with a concurrency limit:
Gatherers.mapConcurrent. - Anything that needs state across elements, emits after the input ends, or stops early on a custom condition: a custom
Gatherer. - A single result at the end of the pipeline:
reduceor aCollector. A gatherer that only emits from its finisher makes sense when you want to keep the stream going.
If the logic reads more naturally as a for loop with a couple of variables, a loop is still a good choice.
Summary
stream.gather(gatherer)adds a custom intermediate operation. Final since Java 24 (JEP 485).Gatherers.windowFixed(n)andwindowSliding(n)emit unmodifiable lists of consecutive elements.Gatherers.scanemits a running accumulation.Gatherers.foldemits a single final value and lets the stream continue.Gatherers.mapConcurrent(n, f)runsfon virtual threads with at mostncalls in flight and keeps encounter order.- A custom gatherer has an initializer (state), an integrator (per element), an optional combiner (parallel) and an optional finisher (end of input).
downstream.pushreturnsfalsewhen no more elements are wanted. Integrators returnfalseto short-circuit. UseIntegrator.ofGreedyfor integrators that never stop on their own.- Use
Gatherer.ofSequentialfor order-dependent logic andGatherer.ofwith a combiner for gatherers that can run in parallel. andThencomposes gatherers into one reusable operation.mapMulti(Java 16) is a cheaperflatMapfor simple one-to-many mapping without state.