Java Streams API: map, filter, collect, groupingBy & Gatherers

Q: What's the difference between map and flatMap?

map transforms each element into exactly one element. flatMap transforms each element into a stream of zero or more elements, and flattens them into a single stream, for example turning a list of orders into a stream of all their line items.

Q: What's the difference between toList() and collect(Collectors.toList())?

Stream.toList() (Java 16+) returns an unmodifiable list and is more concise. Collectors.toList() returns a mutable list in practice (ArrayList, though not guaranteed by the spec). Use toList() unless you need to mutate the result.

Java Streams API

The Streams API, introduced in Java 8, brought functional-style collection processing to Java. Instead of writing loops with mutable accumulators, you describe a pipeline: take a source, filter it, transform it, and collect the result, and the stream implementation executes it. Pipelines are lazy (nothing runs until a terminal operation), composable, and can often be parallelized with one method call.

Streams shine for data transformations like grouping orders by customer, summing totals, extracting unique tags, or building lookup maps. They're not always better than loops: side effects, complex control flow, and checked exceptions often read more clearly imperatively. Knowing both, and choosing per case, is the mark of idiomatic modern Java.

TL;DR

A stream pipeline = source → zero or more intermediate operations → one terminal operation.
Intermediate operations (filter, map, flatMap, sorted, distinct, limit) are lazy; terminal ones (collect, forEach, reduce, toList) trigger execution.
Collectors do the heavy lifting: toList, toMap, groupingBy, partitioningBy, joining, counting, summingX, teeing.
Use primitive streams (IntStream, mapToLong) to avoid boxing for numeric work.
Streams are single-use; don't mutate shared state inside them.
Parallel streams help only for large, CPU-bound, independent work; gatherers (Java 24) add custom intermediate operations.

Quick Example

Core Concepts

Creating Streams

Intermediate Operations (Lazy)

Nothing executes until a terminal operation runs. Then elements flow through the pipeline one at a time (except for stateful operations like sorted), and short-circuiting operations (limit, findFirst, anyMatch) can stop early, even on infinite streams.

Terminal Operations

collect, toList() (Java 16+, returns an unmodifiable list), forEach, reduce, count, min/max, findFirst/findAny, anyMatch/allMatch/noneMatch, and toArray. Operations that might not find a value return Optional.

Collectors

Downstream collectors make groupingBy a mini query language: groupingBy(Order::country, counting()), or groupingBy(Order::customerId, mapping(Order::id, toList())). It's similar to SQL GROUP BY.

Optional

Optional<T> models "maybe a value" from operations like findFirst. Use map, filter, orElse, orElseGet, orElseThrow, and ifPresentOrElse. Avoid get() without checking, and don't use Optional for fields or parameters. It's designed for return types.

Primitive Streams

IntStream, LongStream, and DoubleStream avoid boxing overhead, and add sum(), average(), summaryStatistics(), and range(). Convert with mapToInt, and box back with boxed().

Parallel Streams

.parallel() or parallelStream() splits work across the common ForkJoinPool. It helps only when:

The data set is large, and per-element work is CPU-bound.
Operations are stateless, independent, and associative.
The source splits well (arrays and ArrayLists do; LinkedLists and I/O-backed streams don't).

For I/O-bound work, parallel streams are the wrong tool. Use virtual threads or async I/O instead. See virtual threads.

Stream Gatherers

Java 24 finalized Stream Gatherers (Stream.gather), which enable custom intermediate operations: sliding windows (Gatherers.windowSliding(3)), fixed windows, running scans (Gatherers.scan), and concurrent mapping (Gatherers.mapConcurrent). They fill long-standing gaps that previously required awkward collectors or loops.

Best Practices

Keep Lambdas Side-Effect Free

Stream operations should compute values, not mutate external state. Accumulate with collectors rather than adding to an outside list inside forEach. Side effects break under parallel execution, and obscure intent.

Prefer Method References and Small Named Functions

map(Order::total) and filter(this::isEligible) read better than long inline lambdas. Extract complex predicates into named methods.

Use Loops When They're Clearer

Early returns, multiple accumulators, checked exceptions, and complex branching often read better as for loops. Streams aren't automatically faster. Choose for clarity.

Handle Duplicate Keys in toMap

Collectors.toMap throws IllegalStateException on duplicate keys. Provide a merge function ((a, b) -> a), or use groupingBy when duplicates are expected.

Common Mistakes

Reusing a Stream

Create a new stream from the source each time.

Mutating Shared State

Forgetting to Close I/O-Backed Streams

Files.lines(path) holds a file handle open until the stream is closed. Use try-with-resources.

FAQ

Are Java streams faster than for loops?

Not inherently. Sequential streams have small overhead compared to well-written loops, and the JIT often optimizes both similarly. Streams win on expressiveness for transformations and aggregations, and parallel streams can speed up large CPU-bound workloads. Choose based on clarity, and measure when performance matters.

What's the difference between map and flatMap?

map transforms each element into exactly one element. flatMap transforms each element into a stream of zero or more elements, and flattens them into a single stream, for example turning a list of orders into a stream of all their line items.

What's the difference between toList() and collect(Collectors.toList())?

Stream.toList() (Java 16+) returns an unmodifiable list and is more concise. Collectors.toList() returns a mutable list in practice (ArrayList, though not guaranteed by the spec). Use toList() unless you need to mutate the result.

When should I use parallel streams?

Only for large data sets with CPU-intensive, independent per-element work, on sources that split efficiently, after measuring a benefit. Avoid them for I/O, small collections, operations with shared mutable state, and code running inside servers where the common ForkJoinPool is shared.