How a stream pipeline executes

For this lesson, we'll focus on what happens between orders.stream().filter(...).map(...).toList() and the result: laziness, vertical traversal, operation fusion, the ReferencePipeline stage chain, the Sink chain built at terminal time, stateful barriers, short-circuiting and stream flags. Interviewers ask this because it exposes whether you learned streams as syntax or as a pull-based execution model.

01Picture it first: an assembly line that pulls

Picture three workstations connected by rollers: quality check, label printing and packing. A worker at the packing station asks for the next box. That request pulls one box through quality check, then label printing, then packing.

That is the stream model for stateless sequential pipelines. The terminal operation pulls; the source does not push a completed list through each stage.

Fig. 1

A terminal operation pulls each order vertically through filter and map stages, one element at a time, rather than running one full horizontal pass per operation

Notice the direction. We often read the code left to right, but execution is demand driven from the terminal operation. That distinction explains most stream surprises.

02Laziness under the hood: nothing runs until terminal

import java.util.List;

final class LazyPipelineDemo {
    public static void main(String[] args) {
        var pipeline = List.of("paid", "failed", "paid").stream()
                .peek(s -> System.out.println("peek " + s))
                .filter("paid"::equals);

        System.out.println("pipeline built");
        long count = pipeline.count();
        System.out.println("count " + count);
    }
}

The output is:

pipeline built
peek paid
peek failed
peek paid
count 2

peek did not run when the pipeline variable was assigned. It ran only when count() started traversing the source. This is why peek is a debugging tool, not a reliable place for business side effects.

The next example shows vertical processing and fusion. Java does not normally filter the whole list into a temporary list and then map the whole temporary list.

import java.util.List;

final class VerticalExecutionDemo {
    public static void main(String[] args) {
        List.of("ann", "bob", "carla").stream()
                .filter(name -> {
                    System.out.println("filter " + name);
                    return name.length() > 3;
                })
                .map(name -> {
                    System.out.println("map " + name);
                    return name.toUpperCase();
                })
                .forEach(name -> System.out.println("forEach " + name));
    }
}

The output is:

filter ann
filter bob
filter carla
map carla
forEach CARLA

ann and bob never reach map. carla passes filter, then immediately goes to map, then immediately to forEach. That is operation fusion: the stateless stages are combined into one traversal.

03The internal model: pipeline stages and sinks

The public API hides the classes, but the shape is not mysterious. A reference stream starts with a ReferencePipeline.Head. Each intermediate operation appends another AbstractPipeline stage. Stateless operations such as filter, map and peek create ReferencePipeline.StatelessOp; stateful operations such as sorted and distinct create ReferencePipeline.StatefulOp.

At terminal time, the JDK builds a chain of Sink objects. A sink is like a tiny receiver with begin, accept, cancellationRequested and end. The terminal operation owns the last sink, and each intermediate stage wraps the downstream sink by calling wrapSink.

Fig. 2

A ReferencePipeline stage chain is assembled left to right, then terminal evaluation builds a Sink chain backwards so source elements flow through filter, map and the terminal sink

Here is the important interaction. The stage chain is built as you call methods. The sink chain is built when the terminal operation evaluates. Then the source Spliterator feeds elements into the outermost sink, which calls the next sink, and so on.

For a pipeline like:

orders.stream()
        .filter(Order::paid)
        .map(Order::id)
        .toList();

The simplified mental model is:

source spliterator
  -> filter sink: if paid, downstream.accept(order)
  -> map sink: downstream.accept(order.id())
  -> terminal sink: add id to result list