Java Reference ยท Streams and Functional
The Stream API
Overview of java.util.stream: sources, intermediate and terminal operations, laziness, the single-use rule and how primitive streams fit in.
A stream is a sequence of elements that you process with a pipeline of operations. It is not a data structure: it stores nothing, it just describes a computation over a source such as a collection, an array, a range of numbers or a generator. Streams live in java.util.stream and were added in Java 8.
Every pipeline has three parts: a source (list.stream(), Stream.of(...), IntStream.range(...)), zero or more intermediate operations that return another stream (filter, map, sorted, limit), and exactly one terminal operation that produces a result or a side effect (toList, count, collect, forEach). Nothing runs until the terminal operation is called.
List<String> result = names.stream() // source .filter(n -> n.length() > 3) // intermediate .map(String::toUpperCase) // intermediate .toList(); // terminal
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Syntax
public interface Stream<T> extends BaseStream<T, Stream<T>>
| Kind | Typical members |
|---|---|
| Sources | Collection.stream(), Arrays.stream(a), Stream.of(...), Stream.iterate(...), Stream.generate(...), IntStream.range(...), String.lines(), Files.lines(path) |
| Intermediate (lazy) | filter, map, flatMap, mapMulti, distinct, sorted, peek, limit, skip, takeWhile, dropWhile, boxed, mapToInt, gather (Java 24) |
| Terminal | forEach, toList, toArray, collect, reduce, count, min, max, anyMatch, allMatch, noneMatch, findFirst, findAny |
| Primitive variants | IntStream, LongStream, DoubleStream with sum, average, summaryStatistics |
Usage notes
- A stream can be consumed once. Reusing it throws
IllegalStateException("stream has already been operated upon or closed"). Keep aSupplier<Stream<T>>or rebuild it from the source. - Laziness: elements move through the whole pipeline one at a time, not stage by stage. Short-circuiting operations such as
limit,findFirstandanyMatchcan stop early, even on infinite streams. - The source is not modified. A stream pipeline should not change its own source while running; the result is undefined.
- Keep lambdas pure. Behavioral parameters should be stateless and free of side effects, especially for parallel streams.
- Ordering: streams from lists, arrays and ranges are ordered;
sorted,distinctandlimitrespect it, andunordered()relaxes it for parallel speed. - Streams that hold resources (
Files.lines,Files.walk) must be closed; use try-with-resources. - Not always better than a loop. See streams versus loops.
Related
Collection.stream(),Stream.of(),filter(),map(),collect(),IntStream- Lessons: Streams, Advanced streams