Understanding Java Functional Interfaces and Stream API Internals

Functional Interface

When you first encounter lambda expressions, the concept of a functional interface is unavoidable; a functional interface is an interface that contains exactly one abstract method, though it may have multiple default or static methods, and can be implicitly converted to a lambda.

@FunctionalInterface
public interface Closeable {
    void close();
}

The java.util.function package provides many such interfaces to support functional programming in Java.

Operations

Below are the main categories of functional interfaces in java.util.function (illustrated with images in the original article).

Stream Pipeline Structure

Stream-related interfaces form an inheritance diagram that shows how operations are composed.

The pipeline consists of a series of stages, each represented by a class that implements either a stateless or stateful operation.

Collection

Class path:

java.util.collection

@Override
default Spliterator<E> spliterator() {
    return Spliterators.spliterator(this, 0);
}
// Common Stream conversions
default Stream<E> stream() {
    return StreamSupport.stream(spliterator(), false);
}
default Stream<E> parallelStream() {
    return StreamSupport.stream(spliterator(), true);
}

AbstractPipeline

Class path:

java.util.stream.AbstractPipeline

// Various internal fields for linking stages, flags, source spliterator, etc.
private final AbstractPipeline sourceStage;
private final AbstractPipeline previousStage;
protected final int sourceOrOpFlags;
private AbstractPipeline nextStage;
private int depth;
private int combinedFlags;
private Spliterator<?> sourceSpliterator;
private Supplier<? extends Spliterator<?>> sourceSupplier;
private boolean linkedOrConsumed;
private boolean sourceAnyStateful;
private Runnable sourceCloseAction;
private boolean parallel;

Head

Class path:

java.util.stream.ReferencePipeline.Head

public void forEach(Consumer<? super E_OUT> action) {
    if (!isParallel()) {
        sourceStageSpliterator().forEachRemaining(action);
    } else {
        super.forEach(action);
    }
}

StatelessOp

Class path:

java.util.stream.ReferencePipeline.StatelessOp

public final boolean opIsStateful() { return false; }

StatefulOp

Class path:

java.util.stream.ReferencePipeline.StatefulOp

public final boolean opIsStateful() { return true; }

TerminalOp

Class path:

java.util.stream.TerminalOp

default StreamShape inputShape() { return StreamShape.REFERENCE; }
default int getOpFlags() { return 0; }
default <P_IN> R evaluateParallel(PipelineHelper<E_IN> helper, Spliterator<P_IN> spliterator) {
    return evaluateSequential(helper, spliterator);
}
<P_IN> R evaluateSequential(PipelineHelper<E_IN> helper, Spliterator<P_IN> spliterator);

ReduceOp

Class path:

java.util.stream.ReduceOps.ReduceOp

public abstract class ReduceOp<T,R,S extends AccumulatingSink<T,R,S>> implements TerminalOp<T,R> {
    // makeSink() is provided by concrete subclasses to create the reducing sink.
}

MatchOp

Class path:

java.util.stream.MatchOps.MatchOp

public final int getOpFlags() { return StreamOpFlag.IS_SHORT_CIRCUIT | StreamOpFlag.NOT_ORDERED; }

FindOp

Class path:

java.util.stream.FindOps.FindOp

public final int getOpFlags() { return StreamOpFlag.IS_SHORT_CIRCUIT | (mustFindFirst ? 0 : StreamOpFlag.NOT_ORDERED); }

ForEachOp

Class path:

java.util.stream.ForEachOps.ForEachOp

static abstract class ForEachOp<T> implements TerminalOp<T,Void>, TerminalSink<T,Void> {
    private final boolean ordered;
    public int getOpFlags() { return ordered ? 0 : StreamOpFlag.NOT_ORDERED; }
    public Void evaluateSequential(PipelineHelper<T> helper, Spliterator<?> spliterator) {
        return helper.wrapAndCopyInto(this, spliterator).get();
    }
    public Void evaluateParallel(PipelineHelper<T> helper, Spliterator<?> spliterator) {
        if (ordered) new ForEachOrderedTask<>(helper, spliterator, this).invoke();
        else new ForEachTask<>(helper, spliterator, helper.wrapSink(this)).invoke();
        return null;
    }
    public Void get() { return null; }
}

Sink

Class path:

java.util.stream.Sink

interface Sink<T> extends Consumer<T> {
    default void begin(long size) {}
    default void end() {}
    default boolean cancellationRequested() { return false; }
    void accept(T t);
}

ChainedReference

Class path:

java.util.stream.Sink.ChainedReference

abstract class ChainedReference<T,E_OUT> implements Sink<T> {
    protected final Sink<? super E_OUT> downstream;
    public ChainedReference(Sink<? super E_OUT> downstream) { this.downstream = Objects.requireNonNull(downstream); }
    public void begin(long size) { downstream.begin(size); }
    public void end() { downstream.end(); }
    public boolean cancellationRequested() { return downstream.cancellationRequested(); }
}

TerminalSink

Various terminal operations provide their own TerminalSink implementations, e.g., reducing sinks, match sinks, find sinks, and the ForEachOp itself.

Collector

A Collector consists of a Supplier for the result container, a BiConsumer to accumulate elements, a BinaryOperator to combine partial results, an optional Function to finish, and a set of characteristics.

Parallel Stream

Parallel streams use the same helper.wrapAndCopyInto(...) mechanism but execute the pipeline inside a ForkJoinTask hierarchy.

ForkJoinTask & AbstractTask

Parallel execution is built on the Fork/Join framework. AbstractTask extends java.util.concurrent.CountedCompleter and recursively splits a Spliterator using trySplit(), creates child tasks with makeChild(), processes leaf tasks with doLeaf(), and combines results in onCompletion().

public void compute() {
    Spliterator<P_IN> rs = spliterator, ls;
    long sizeEstimate = rs.estimateSize();
    long sizeThreshold = getTargetSize(sizeEstimate);
    boolean forkRight = false;
    K task = (K) this;
    while (sizeEstimate > sizeThreshold && (ls = rs.trySplit()) != null) {
        K leftChild = task.makeChild(ls);
        K rightChild = task.makeChild(rs);
        task.setPendingCount(1);
        if (forkRight) {
            forkRight = false;
            rs = ls;
            task = leftChild;
            taskToFork = rightChild;
        } else {
            forkRight = true;
            task = rightChild;
            taskToFork = leftChild;
        }
        taskToFork.fork();
        sizeEstimate = rs.estimateSize();
    }
    task.setLocalResult(task.doLeaf());
    task.tryComplete();
}

Overall Diagram

The article concludes with a high‑level diagram that shows the relationship between source spliterators, pipeline stages, terminal operations, and the Fork/Join task tree that drives parallel execution.