Functional Java & the Streams API — Pipelines Over Data

Lambdas turned behavior into a value. The Streams API builds on that to let you transform sequences declaratively.

• A stream is a pipeline of operations over a source, such as filter, map and reduce chained together. It describes what to compute, and leaves how to iterate up to the library.
• Pipelines are lazy. Nothing runs until a terminal operation pulls the data through, so the work is fused into a single pass, and can stop early.
• Optional turns "maybe absent" from a null waiting to crash into a type you're forced to handle.
• Parallel streams split the work across processor cores. They're fast when the operations are stateless, and wrong when they share mutable state.

This lesson builds on generics and lambdas. Every output below was produced by compiling and running the code.

You'll be able to: write a pipeline that filters, maps, sorts, flattens and collects, and predict its result; choose reduce, a collector or a primitive stream for an aggregate, and name the error you get when a key repeats in toMap; window and scan a stream with a gatherer; trace which elements a lazy pipeline touches, and predict when peek prints nothing; consume an Optional without get(), and predict when orElse evaluates its argument; explain why a parallel stream that writes shared state gives a wrong count, and rewrite it as a reduction.

Table of contents

1. A stream pipeline
2. Sorting, flattening and joining streams
3. reduce, collectors and primitive streams
4. Lazy evaluation
5. Optional
6. Parallel streams and their hazards
7. Mental-model summary
8. Gotcha checklist
9. Check yourself
10. Sources

1. A stream pipeline

Calling collection.stream() starts a pipeline, which has three parts [1]:

• A source supplies the elements: a collection, an array, or a generator.
• Intermediate operations (filter, map) each return a new stream, so you can chain them.
• A terminal operation (collect) ends the pipeline and produces a result.

Output:

[LINUS, GRACE, BJARNE]

Analysis. The pipeline has three steps:

• filter kept the names longer than 3 characters, dropping "Ada".
• map upper-cased each name that was left.
• collect(toList()) gathered them into a List.

The chain reads like a description: keep the long names, upper-case them, collect them. There's no loop, no index and no intermediate variable. Each lambda or method reference supplies the behavior for one step.

Since Java 16, a stream also has toList() as a shorter terminal operation [2]. The two differ in one way that can bite you:

• Stream.toList() returns an unmodifiable list.
• Collectors.toList() makes "no guarantees on the type, mutability, serializability, or thread-safety" of its list [3].

When you need to add to the result, ask for a specific list type by name, using Collectors.toCollection(ArrayList::new):

Output (prints the first line, then a thrown exception):

toCollection(ArrayList::new): [3, 1, 2, 4]
Exception in thread "main" java.lang.UnsupportedOperationException

Intuition. Mechanism. stream() produces a stream object. Each intermediate operation wraps it in another stream that records the operation, but doesn't do anything yet. Only the terminal collect drives elements through the whole chain. The pipeline expresses the what, and the library owns the how (the iteration).

Concrete bite. A stream is single-use, and it isn't a collection. The API says a stream "should be operated on (invoking an intermediate or terminal stream operation) only once" [2]. Use it a second time, and it throws:

Output (prints 2, then a thrown exception):

2
Exception in thread "main" java.lang.IllegalStateException: stream has already been operated upon or closed

The first count() consumed the stream. A stream is a view of a computation, not data you can come back to. For a fresh pipeline, call stream() on the list again.

2. Sorting, flattening and joining streams

Three more intermediate operations reshape a stream, rather than filtering or transforming single elements [2]:

• sorted() puts the elements in natural order, while sorted(comparator) uses the Comparator you pass in.
• flatMap(f) replaces each element with the elements of the stream that f returns, so nested lists become one flat stream.
• Stream.concat(a, b) is a static method that joins two streams: all of a, then all of b.

Comparator.comparing(key) builds a Comparator from a function that extracts a sort key. For example, Comparator.comparing(String::length) orders strings by their length [4].

Output:

[Ada, Bo, Grace, Linus]
[Bo, Ada, Grace, Linus]
[Linus, Grace]
[Grace, Ada, Linus, Bo]

Analysis. Three sorts, and one untouched source:

• sorted() used String's natural order.
• sorted(Comparator.comparing(String::length)) ordered by length. Grace and Linus both have 5 letters, and they kept their original order, because this sort is stable for an ordered stream [2].
• limit(2) kept the first two elements of the reverse-sorted stream.
• The last line printed names itself, unchanged. A stream reads its source, but never reorders it.

flatMap is how a stream takes nested data apart. map produces exactly one output element per input element, so a stream of lists stays a stream of lists. flatMap, on the other hand, produces zero or more per input:

Output:

map:     [[1, 2], [3], []]
flatMap: [1, 2, 3]
concat:  [a, b, c]

Intuition. Mechanism. flatMap(List::stream) turned each inner list into a stream, and poured all those streams into one. The empty list contributed zero elements, so it simply vanished. Stream.of(…) makes a stream from the values you list, and concat ran one stream after the other.

Concrete bite. The map line is the non-example: it printed [[1, 2], [3], []], still three lists. Asking map to flatten does nothing, because map never changes the number of elements.

3. reduce, collectors and primitive streams

Terminal operations turn a stream into a result. reduce folds the elements into a single value using a combining function. Collectors gather them into structures: a List, a joined String, a grouping Map.

Output:

15
1, 2, 3, 4, 5
odd=[1, 3, 5]
even=[2, 4]

Analysis. Three terminals over the same five numbers:

• reduce(0, Integer::sum) folded 1..5 into 15. It started at 0, and combined each element using sum.
• Collectors.joining(", ") produced "1, 2, 3, 4, 5".
• Collectors.groupingBy(...) built a Map from each element's group key ("odd"/"even") to the list of elements in that group. It's the stream form of the counting and grouping idioms, packed into one expression.

Intuition. Mechanism. reduce(identity, accumulator) applies the accumulator over and over, starting from the identity. The API requires that "the identity value must be an identity for the accumulator function" [2]: 0 for a sum, "" for concatenation. A Collector, meanwhile, is a recipe for gathering elements into a container. groupingBy, toList, joining, counting and partitioningBy cover most needs [3].

Concrete bite. Seed a sum with 1 — the identity for multiplication — and every result is off by one:

Output:

15
16

The seed is part of the computation — the same lesson as the accumulator-seed trap.

Partitioning is grouping by a yes/no test. partitioningBy(test) always returns a map with exactly two keys, false and true. You can pass a second collector, such as counting(), to apply inside each group:

Output:

{false=[1, 2], true=[3, 4, 5]}
{false=2, true=3}

Non-example: toMap with a repeated key. Collectors.toMap(keyFn, valueFn) builds one entry per element. When two elements produce the same key, it throws [3]:

Output (a thrown exception):

Exception in thread "main" java.lang.IllegalStateException: Duplicate key A (attempted merging values Ada and Al)

"Ada" and "Al" both map to 'A'. When a key can repeat, use groupingBy instead, or pass toMap a third argument that merges the two values.

Primitive streams. A Stream<Integer> holds boxed Integer objects. IntStream, LongStream and DoubleStream hold primitive values instead, and add arithmetic terminals such as sum() and average() [5]. mapToInt turns a stream of objects into an IntStream:

Output:

13
OptionalDouble[4.333333333333333]
OptionalDouble.empty
0.0

The sum() of no elements is 0, but an average of no elements has no value at all. That's why average() returns an OptionalDouble, the primitive cousin of the Optional you'll meet in §5.

Gatherers: intermediate operations of your own. A collector lets you write your own terminal step. Since JDK 24, a gatherer does the same for an intermediate step [8]. You pass one to Stream.gather, and the class Gatherers already has the common ones, "such as windowing functions, folding functions" [10]:

Output:

[[1, 2, 3], [4, 5, 6], [7]]
[[1, 2], [2, 3], [3, 4]]
[1, 3, 6, 10]

Analysis. windowFixed(3) grouped the elements into lists of three, and the last window held what was left. windowSliding(2) made overlapping pairs. scan emitted a running total. None of these fit map or filter, because each output depends on earlier elements, so each step needs state.

That's what you write when you build your own gatherer. This one drops an element that repeats the one just before it:

Output:

[a, b, a, c]
[x, y]

Analysis. ofSequential took two parts [9]. Last::new creates fresh state for each pipeline. The lambda, the integrator, runs once per element: it gets the state, the element, and the downstream (the next step). Its boolean result says whether it wants more elements. push returns false once the downstream wants no more, so after limit(2) was full, the integrator returned false, and the stream stopped pulling elements.

4. Lazy evaluation

Intermediate operations are lazy: they process nothing until a terminal operation runs [1]. Once it does, elements flow through one at a time. That lets the pipeline short-circuit — stop as soon as the answer is known.

Output:

peek 1
peek 2
found: 2

Analysis. peek prints each element as it flows by, and the output stops at peek 2. The pipeline never even looked at 3, 4 or 5. findFirst needed only the first even number, so once filter let 2 through, the whole pipeline stopped. A loop that first built a filtered list would have visited all five.

Intuition. Mechanism. The terminal operation pulls elements through the pipeline one at a time, from top to bottom:

1. peek(1), then filter rejects 1.
2. peek(2), then filter accepts 2, and findFirst is satisfied and halts.

Stateless steps such as filter and map remember nothing between elements. A short-circuiting terminal (findFirst, anyMatch) or intermediate operation (limit) stops early.

Concrete bite. The peek output is the proof: only 1 and 2 were processed. This is also why a stream can have an infinite source. Stream.iterate(1, n -> n * 2) generates 1, 2, 4, 8, … forever, yet a short-circuiting step still lets it finish:

Output:

1024
[1, 2, 4, 8, 16]

Non-example: a stateful step breaks the one-at-a-time flow. sorted is stateful: it can't pass on the smallest element until it has seen them all [1]. Put it before findFirst, and every element gets pulled:

Output:

peek 5
peek 3
peek 4
peek 1
peek 2
found: 2

All five elements were peeked, because sorted needed every one of them before filter could see any.

Non-example: peek as logic. Laziness also means that a side effect inside a pipeline might never run:

Output:

no terminal operation, so no peek lines
count = 3

• The first pipeline had no terminal operation, so nothing ran at all.
• The second one did have a terminal operation, count(), and still printed no peek line. The list knows its own size, and the API lets count() skip the pipeline "if it is capable of computing the count directly from the stream source" [2].

The API says peek "exists mainly to support debugging" [2]. Never put work there that has to happen.

5. Optional

A stream query that might find nothing returns an Optional<T>: a container that either holds a value or is empty. It turns "absent" into a type, so you have to handle the missing case, instead of risking a NullPointerException.

Output:

true
Linus
none

Analysis. The first query found "Linus", so found was present, and orElse returned the value. The second query matched nothing, so missing was empty, and orElse("none") supplied the fallback. The type Optional<String> made the possibility of absence visible right in the signature. You can't use a missing value by accident, the way you can with null.

Intuition. Mechanism. Optional wraps the idea of "a value, or nothing" [6]:

• orElse and orElseGet supply a default.
• map transforms the value only if one is present, and filter keeps it only if it passes a test.
• ifPresent runs an action only if a value is present.

None of them ever exposes a raw null.

Concrete bite. Calling get() on an empty Optional defeats the whole purpose, and throws:

Output (a thrown exception):

Exception in thread "main" java.util.NoSuchElementException: No value present

empty.get() is the Optional version of dereferencing null: it asserts that a value is present when it isn't. Instead of a bare get(), use orElse, orElseThrow(...) with a meaningful exception, or ifPresent.

Edge: orElse always evaluates its argument. orElse(x) is an ordinary method call, so Java computes x before making the call — even when the Optional already has a value. orElseGet(supplier), by contrast, calls the supplier only when the Optional is empty [6]:

Output:

orElse:
  fallback() ran
Linus
orElseGet:
Linus
5
0

fallback() ran for orElse, even though its result was thrown away. So use orElseGet when the default is costly to compute. The last two lines show map on a present value (5) and on an empty one (the fallback 0).

6. Parallel streams and their hazards

A thread is one independent path of execution through a program. A program can run several threads at once, and on a machine with several processor cores, they genuinely run side by side. The concurrency lessons cover threads in depth.

parallelStream() (or .parallel()) splits a stream's work across several threads [1]. It can speed up stateless operations on large data. But it's a trap when the pipeline touches shared mutable state, because the threads race each other.

Output:

500000500000

Analysis. The parallel sum over one million numbers gave the correct 500000500000, on every run. sum is a proper reduction: each thread sums its own chunk, and the chunks combine associatively, with no shared state. This is the safe way to parallelize: a stateless pipeline that ends in a reduction or a collector.

Intuition. Mechanism. A parallel stream splits the source into chunks, processes them on a pool of threads, and then combines the partial results. That's correct as long as the operations are stateless and the combination is associative [1]. sum, map, filter and collect all qualify.

Concrete bite. Touch shared mutable state, and the threads corrupt it. This is called a data race, and it produces no error — only wrong answers.

First, a word on why the example below counts in an int[]. A lambda may use a local variable only if it's effectively final [7], so the obvious total += n doesn't compile:

Compiler error:

Main.java:6: error: local variables referenced from a lambda expression must be final or effectively final
        List.of(1, 2, 3).stream().forEach(n -> total += n);
                                               ^
1 error

Here, the compiler is protecting you. An array slot isn't a local variable, though, so counter[0]++ slips past the rule — and the race below is the result:

Output (illustrative — the value changes every run and is almost never 1000000; three runs on JDK 25 printed 124149, 123649, 102111):

124149

Many threads ran counter[0]++ at the same time, and each ++ is really three steps: read, add one, write.

• Two threads read the same value, both write value + 1, and one update is lost.
• The count is wrong, and different on every run.
• There's no exception, only silent corruption.

The fix is to let the stream do the counting itself, as a reduction. Same scenario, same million elements:

Output:

1000000
500000

7. Mental-model summary

8. Gotcha checklist

✅ Check yourself

One check per objective. Answer before you open anything.

[4, 16]
10
11
false
none

📚 Sources

1. java.util.stream package summary, Java SE 25 API ("Stream operations and pipelines", "Parallelism", "Associativity") — https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/stream/package-summary.html
2. java.util.stream.Stream, Java SE 25 API (toList() since 16; sorted; reduce; peek "exists mainly to support debugging"; count() may skip the pipeline) — https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/stream/Stream.html
3. java.util.stream.Collectors, Java SE 25 API (toList() "no guarantees on the type, mutability …"; toMap and IllegalStateException on duplicate keys) — https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/stream/Collectors.html
4. java.util.Comparator.comparing(Function), Java SE 25 API — https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/Comparator.html#comparing(java.util.function.Function)
5. java.util.stream.IntStream, Java SE 25 API (sum(), average() returning OptionalDouble) — https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/stream/IntStream.html
6. java.util.Optional, Java SE 25 API (the API note on return types; orElseGet) — https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/Optional.html
7. The Java Language Specification, Java SE 25, §15.27.2 "Lambda Body" (a local variable used but not declared in a lambda body must be final or effectively final) — https://docs.oracle.com/javase/specs/jls/se25/html/jls-15.html#jls-15.27.2
8. JEP 485: Stream Gatherers (JDK 24) — https://openjdk.org/jeps/485
9. java.util.stream.Gatherer, Java SE 25 API ("An intermediate operation that transforms a stream of input elements into a stream of output elements"; ofSequential; Downstream.push) — https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/stream/Gatherer.html
10. java.util.stream.Gatherers, Java SE 25 API ("such as windowing functions, folding functions"; since 24) — https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/stream/Gatherers.html

Your Turn

Before you move on, check your understanding with the coach — explain the idea, apply it, weigh the trade-offs, then defend your reasoning.