The Stream API

SQL-like pipelines over data: filter, map, sort, reduce, and collect — sequentially or in parallel

1. The Big Idea

A stream is a conduit for data — a sequence of objects flowing from a source. Key facts:

• A stream never stores data; it moves data, optionally transforming it along the way.
• A stream operation does not modify the source. Sorting a stream produces a new sorted stream; the source's order is unchanged.
• This "stream" is unrelated to the I/O streams covered earlier — here it always means a java.util.stream object.

2. Why This Topic Matters

• Replaces verbose loops with declarative, composable operations ("what", not "how").
• Chains of intermediate operations read like a query: source.stream().filter(...).map(...).sorted().collect(...).
• Switching to parallel execution is often a one-word change (parallelStream() or .parallel()).
• Streams and collections convert back and forth, so you can operate through a stream and repackage as a collection.

3. Stream Interfaces

3.1 Terminal vs. intermediate operations

Examples: intermediate — filter, map, sorted, parallel, unordered; terminal — forEach, min, max, count, reduce, collect, toArray, iterator, toList.

3.2 Stateless vs. stateful

A stateless operation processes each element independently (filter() with a stateless predicate). A stateful operation may depend on other elements (sorted() — an element's position depends on the rest). This distinction matters for parallel streams, where a stateful operation may need more than one pass.

4. How to Obtain a Stream

5. A Simple Stream Example

Reading the code

• min(Comparator) / max(Comparator) return an Optional<T> — it either holds a value or is empty. Check with isPresent(), read with get() (or orElseThrow() on JDK 10+). Here a method reference Integer::compare supplies the comparator.
• min(), max(), forEach() are terminal — each consumes its stream, so a fresh myList.stream() is needed for the next operation.
• sorted() and filter() are intermediate — each returns a new stream, so they chain. forEach(Consumer) runs an action per element (the lambda implements Consumer.accept()).
• filter(Predicate) keeps elements for which the predicate's test() returns true; filtering a filtered stream again is fine.

6. Reduction Operations

min(), max(), and count() are special-case reductions — they reduce a stream to one value. The general form is reduce() (always terminal):

• accumulator combines two values into one. In reduce() its first argument holds the running result, its second is the next element.
• identityVal is a value that leaves any element unchanged under the operation: 0 for addition, 1 for multiplication. The one-argument form returns an Optional; the two-argument form returns a plain T.

7. Parallel Streams

Request parallel processing with Collection.parallelStream(), or call parallel() on a sequential stream (defined by BaseStream). Switch back with sequential(). Parallelism happens only if the environment supports it.

Every operation on a parallel stream should be stateless, non-interfering, and associative so that the parallel result equals the sequential result.

7.1 The three-argument reduce() (accumulator + combiner)

combiner merges two partial results produced by the accumulator. When accumulator and combiner do the same thing you can often use the simpler two-argument form, but sometimes they must differ:

The buggy version happens to work for a sequential stream (no partial results to combine); it fails for a parallel one.

8. Mapping

map() applies a function to each element, yielding a new stream (intermediate; the mapping function must be stateless and non-interfering):

8.1 Mapping to primitive streams

For "one element → many elements" mappings there are flatMap(), flatMapToInt(), … (and, since JDK 16, mapMulti() variants).

9. Collecting

collect() turns a stream into a container (a mutable reduction). Terminal operation. Simplest form uses a ready-made Collector from Collectors:

9.1 The three-argument collect()

• target (Supplier) creates the result container.
• accumulator adds one element to the container; combiner merges two partial containers. Both must be stateless, non-interfering, and associative.

10. Iterators and Streams

A stream is not storage, but you can still iterate it. iterator() and spliterator() are terminal operations.

10.1 Iterator

10.2 Spliterator (JDK 8)

Better than Iterator for parallel processing. Three methods matter here:

Manual splitting rarely helps in simple code; it matters for large parallel data sets — but usually a predefined Stream method on a parallel stream is better than handling Spliterator yourself.

11. Visual Mental Model

12. Important Comparisons

13. Common Beginner Mistakes

14. Best Practices

• Build a pipeline: chain intermediate operations, end with exactly one terminal operation.
• Keep lambdas stateless and non-interfering; make reduction/collect functions associative.
• Prefer map() for transformation, then a simple two-argument reduce() — often avoids needing a combiner.
• Use primitive streams (mapToInt, …) when working with numbers to avoid boxing.
• Use collect(Collectors.toList()/toSet()) for the common cases; Stream.toList() when an unmodifiable list is fine.
• Go parallel only for large data and only when every operation is stateless/associative; consider unordered().
• Handle Optional results explicitly.
• Close streams over external resources (files) with try-with-resources; collection streams need no closing.

15. "Remember" Points

16. Interview / Revision Questions

• Define "stream". How does it differ from a collection and from an I/O stream?
• Contrast intermediate and terminal operations. What does "lazy" mean here?
• Why can't you reuse a stream after calling min()?
• What is Optional, and how do you read a value from it safely?
• Give the three forms of reduce(). What is the identity value for addition and for multiplication?
• What three properties must a reduction accumulator have, and why does associativity matter for parallel streams?
• How do you obtain a parallel stream? How do you switch back to sequential?
• When must the accumulator and combiner in a 3-argument reduce() differ? Give an example.
• What does map() do, and what interface does its argument implement? Name the primitive-mapping variants.
• What is a "mutable reduction"? Show two ways to collect a stream into a list.
• What does Stream.toList() (JDK 16) return that collect(Collectors.toList()) historically did not?
• Compare Iterator and Spliterator. What do tryAdvance(), forEachRemaining(), and trySplit() do?

17. Practice Exercises

• Pipeline: From a List<Integer> print the sorted odd values greater than 10 using stream().sorted().filter(...).filter(...).forEach(...).
• Reduction: Compute the sum (identity 0) and product (identity 1) of a list two ways — the Optional form and the identity form.
• Even product: Use a block-lambda accumulator in reduce(1, ...) to multiply only the even elements.
• Parallel + combiner: Compute the product of the square roots of a List<Double> with parallelStream().reduce(1.0, accumulator, combiner); then show the accumulator-only version gives the wrong answer in parallel but the right one sequentially.
• Mapping: Map a List<NamePhoneEmail> to a stream of NamePhone; then pipeline filter + map to keep only one person.
• Primitive stream: Map a List<Double> to an IntStream of ceilings and print them.
• Collecting: Collect a mapped stream into a List and a Set with Collectors; then into a LinkedList and a HashSet using the 3-argument collect() (lambdas, then method references).
• Spliterator: Iterate a stream with tryAdvance(), then with forEachRemaining(), then split it with trySplit() and print each partition.

18. Quick Memory Map

19. Complete Chapter Revision

1. A stream is a sequence of objects flowing from a source; it stores nothing and never modifies the source.
2. Interfaces: BaseStream → Stream<T> for references, plus IntStream/LongStream/DoubleStream for primitives.
3. Intermediate operations return a new stream and are lazy; terminal operations produce a result and consume the stream (which then can't be reused). Operations are stateless or stateful (sorted() is stateful).
4. Obtain streams via Collection.stream()/parallelStream() or Arrays.stream().
5. The simple example demonstrates min/max (returning Optional, read via isPresent()/get()), sorted(), filter(), and forEach(), including pipelined filters.
6. Reductions collapse a stream to one value. reduce() has three forms; identity is 0 for sum, 1 for product; the accumulator must be stateless, non-interfering, associative.
7. Parallel streams (parallelStream() / parallel()) require those guarantees; the 3-argument reduce() adds a combiner for merging partial results, which must sometimes differ from the accumulator. Consider unordered() and forEachOrdered().
8. map() transforms each element to a new stream; mapToInt/Long/Double() produce primitive streams; flatMap() handles one-to-many.
9. collect() performs a mutable reduction into a container — via a Collector (Collectors.toList()/toSet()) or the 3-argument (supplier, accumulator, combiner) form; Stream.toList() gives an unmodifiable list.
10. Streams can be iterated with Iterator or, for parallel work, Spliterator (tryAdvance(), forEachRemaining(), trySplit()).

20. Final Takeaway