Stream API

A Stream is a pipeline over a sequence of elements, not a container that stores them. It has a source (a collection or an array), intermediate operations such as filter and map, and one terminal operation such as collect. Unlike a loop it declares what to compute rather than how to iterate, and it never mutates its source — it produces new results.

An intermediate operation like filter or map returns another Stream, so it merely adds a stage to the pipeline. A terminal operation like collect or count returns a non-stream result and is what actually runs the pipeline. Nothing at all is computed until that terminal call arrives — the intermediate stages are lazy by design.

It is a compile-time error, not runtime. map(authService::findClient) wraps the already-Optional result, producing Optional<Optional<Client>>. So in the next map, client is an Optional<Client>, not a Client, and passing it to createResponse(Client) fails to type-check. Fix it by using flatMap for findClient: flatMap unwraps one level, yielding Optional<Client> so the next map receives a real Client.

parallelStream splits the source and runs stages on the common ForkJoinPool (sized to the cores), then combines partial results. It speeds up CPU-bound work on large, splittable sources but hurts small or I/O-bound ones. It silently breaks correctness when reduce uses a non-identity seed or a non-associative accumulator, or when a lambda mutates shared state — each thread re-applies the seed and ordering is lost.

The Stream API processes a sequence of elements declaratively as a pipeline: a source, intermediate operations like filter and map, and a terminal operation like collect. Intermediate operations are lazy — they build the pipeline without iterating; only a terminal operation triggers execution, streaming each element through. A stream can also run in parallel across threads.

groupingBy(classifier) applies the classifier to each element and collects elements into a Map<K, List<T>> keyed by its result. The two-arg groupingBy(classifier, downstream) feeds each bucket into a second collector instead of listing the elements, so groupingBy(Order::status, counting()) yields a Map<Status, Long> of counts in one stream pass: orders.stream().collect(groupingBy(Order::status, counting())).

reduce is an immutable fold: it applies a BinaryOperator to an identity and the running value, producing a new value each step. collect is a mutable reduction: a supplier creates a container, an accumulator folds each element into it, and a combiner merges two containers. Use reduce for a value like a sum or max; use collect when the result is a container, because folding a String per element allocates O(n) garbage.

Collector.of(supplier, accumulator, combiner, finisher) builds one. The supplier makes a fresh mutable container per worker, the accumulator folds one element into it, the combiner merges two containers — that is what makes it parallel-safe — and the finisher turns the container into the result. For topN the container is a min-heap: push each element, drop the smallest once it holds more than n, and sort the survivors in the finisher. Memory stays O(n).

Laziness pulls elements one at a time, so a short-circuiting terminal — findFirst, anyMatch, allMatch — stops pulling the moment the answer is settled: filter(p).findFirst() over a million elements tests p only until the first match. That is also what makes an infinite Stream.iterate usable behind limit. The catch is order: on a parallel ordered stream findFirst owes you the encounter-order-first match, unlike findAny.

A stream is not a container: it holds a source spliterator plus the pipeline stages and traverses that source exactly once. The pipeline carries a linked-or-consumed flag that the terminal operation sets, so any later operation throws IllegalStateException. Nothing was buffered to replay — the spliterator cannot be rewound. To traverse twice, rebuild the stream from the source or keep a Supplier<Stream<T>>.

The two-argument toMap(keyMapper, valueMapper) has no rule for two elements landing on the same key, so the second Sales employee makes it throw. Use the three-argument overload and give it a merge function — toMap(Employee::department, Employee::salary, Integer::sum) — which folds colliding values instead of failing. groupingBy(Employee::department, summingInt(...)) is the equivalent.

A Gatherer (final in Java 24, JEP 485) is a user-written intermediate operation — the Collector counterpart for the middle of a pipeline, plugged in with stream.gather(g). Built from an initializer, an integrator, an optional combiner and a finisher, it can carry state across elements, emit zero, one or many outputs per input, and short-circuit the upstream. A Collector reduces only once, at the terminal step.