Skip to content
Tutorials Center
My learning

Topics

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.

Java
List<String> result = names.stream()      // source
    .filter(n -> n.length() > 3)          // intermediate
    .map(String::toUpperCase)             // intermediate
    .toList();                            // terminal

Try it

Java A first pipeline

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.

Java Lazy and single-use

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

Java
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 a Supplier<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, findFirst and anyMatch can 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, distinct and limit respect it, and unordered() 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.