What Is the Stream API in Java?

The Stream API gives Java a way to express data transformations — filtering, mapping, aggregating — as a pipeline of operations rather than as a sequence of loops and temporary collections. It arrived alongside lambdas and the functional interfaces, and it is the biggest single change to how everyday Java code is written.

The problem it solves is not performance. It is that the imperative style scatters the intent of a computation across several statements and an ever-growing set of mutable variables. A stream version states what you want: take these elements, keep the ones that match, transform them, collect the result. The intermediate steps are named, so a reader can follow the shape of the computation without tracing variable mutations.

Three properties define a stream. It is not a data structure — it does not hold the elements, it computes them. It is lazy — the work happens only when a terminal operation is called, and elements are pulled through the pipeline one at a time. And it is single-use — once it has been consumed, the pipeline is spent.

The API has three families of methods. Intermediate operations such as filter, map, sorted and distinct return a new stream and do no work themselves. Terminal operations such as forEach, count, collect and anyMatch trigger the pipeline and produce a result or a side effect. And short-circuiting operations such as findFirst and limit stop the pipeline early once the answer is known, which is what makes streams efficient for large or infinite sources.

Streams come from four main places. A collection through its stream method — names.stream(). An array through Arrays.stream or Stream.of. A range or range of values through IntStream.range and IntStream.rangeClosed, which are primitive streams for the numeric cases. And a stream of characters from a String, or a file's lines through Files.lines.

import java.util.List;
import java.util.stream.Stream;

public class Main {
    public static void main(String[] args) {
        // From a collection.
        List<String> names = List.of("Ada", "Grace", "Alan");
        long longerThanThree = names.stream()
                .filter(n -> n.length() > 3)
                .count();
        System.out.println("names longer than 3 : " + longerThanThree);

        // From an array.
        String[] languages = {"Java", "Python", "Rust"};
        System.out.println("array stream        : " + Stream.of(languages).count());

        // From a range.
        System.out.println("sum 1 to 10         : " + java.util.stream.IntStream.rangeClosed(1, 10).sum());

        // Collect back into a list.
        List<String> upper = names.stream().map(String::toUpperCase).collect(java.util.stream.Collectors.toList());
        System.out.println("uppercased          : " + upper);
    }
}

The output shows the three creation styles. The collection pipeline filters the names and counts the survivors. The array stream reports three elements. The range sums to 55, and the final pipeline collects the uppercase names into a new immutable list without changing the original.

Two practical notes. A stream from a collection is a view of it, so it reflects changes made to the collection before the terminal operation runs. And Stream.of with a single array argument is ambiguous — Stream.of(intArray) is a stream of ints, but Stream.of(someIntArray) with varargs can produce a stream of int arrays, which is a classic source of confusion. Use Arrays.stream when you mean one array.

Because a stream is bound to a single traversal of its source. Once a terminal operation has run, the pipeline has been consumed and its internal state has moved past the end. Calling another terminal operation on the same stream throws IllegalStateException with a message saying the stream has already been operated upon or closed.

The design reason is that a stream is not a collection. It is a description of a computation over a source, and the computation can legitimately involve state — a mutable counter in a reduce, an open resource in a stream of IO lines. Allowing the same pipeline to be run twice would mean either supporting that state or silently resetting it, and both are surprising. A collection can be iterated many times because it holds the data; a stream cannot, because it produces the data as it goes.

There is also a performance angle. The intermediate operations are fused into a single pipeline, and the elements are pulled through it one at a time so that a short-circuiting operation can stop early.

What to do instead, in the order you should reach for them. Call supplier again to get a fresh stream from the same source — names.stream() produces a new one each time. Use names.stream().collect(Collectors.toList()) to materialise the result into a collection and then work with the collection. Or, if you genuinely need to reuse the same computation, extract it into a method that returns a fresh stream each time it is called.

One trap worth naming. Assigning a stream to a variable and then trying to use it in two places is a common mistake, and the compiler will not catch it — the failure appears at run time, often far from the line that consumed the stream the first time.