Optional in stream pipelines

For this lesson, we'll focus on the stream angle: terminal operations that return Optional, converting Stream<Optional<T>> to Stream<T>, lookup methods that return Optional, primitive optionals, null elements, lazy fallbacks and collectors such as maxBy. We will not re-teach Optional basics, factories or general anti-patterns from the ground up. If you want the full API tour first, read A guide to Java Optional and come back here.

01Picture it first: a security line with empty envelopes

Picture a security line where every traveler hands over an envelope. Some envelopes contain a boarding pass, and some are empty because the lookup failed. A stream pipeline can either carry the envelopes all the way down the line, or open each envelope and let only real boarding passes continue.

That is the main move. Flatten the optional at the point where the stream needs values, not ten steps later after every operation has learned to deal with emptiness.

Fig. 1

A stream of Optional envelopes flows through flatMap Optional stream so present customers continue and empty envelopes disappear before email extraction

Notice the two different shapes. Before flattening, each element is Optional<Customer>. After flattening, each element is Customer, so the rest of the pipeline is ordinary stream code.

02Optional-returning terminals under the hood

The stream terminals that return Optional all share one reason: the stream might be empty. There may be no first element, no maximum, no minimum and no pair of values to reduce.

import java.util.Comparator;
import java.util.List;
import java.util.Optional;

record Order(String id, int totalCents) { }

public class OptionalTerminalsDemo {
    public static void main(String[] args) {
        List<Order> orders = List.of(
                new Order("o-1", 1200),
                new Order("o-2", 2900),
                new Order("o-3", 700)
        );
        List<Order> none = List.of();

        Optional<Order> first = orders.stream().findFirst();
        Optional<Order> biggest = orders.stream()
                .max(Comparator.comparingInt(Order::totalCents));
        Optional<Integer> sum = orders.stream()
                .map(Order::totalCents)
                .reduce(Integer::sum);
        Optional<Order> emptyMax = none.stream()
                .max(Comparator.comparingInt(Order::totalCents));

        System.out.println(first.map(Order::id).orElse("none"));
        System.out.println(biggest.map(Order::id).orElse("none"));
        System.out.println(sum.orElse(0));
        System.out.println(emptyMax.isEmpty());
    }
}

o-1
o-2
4800
true

Notice four things:

• findFirst() and findAny() return Optional<T> because an empty stream has no element to return.
• min(comparator) and max(comparator) return Optional<T> because they need at least one candidate.
• reduce(BinaryOperator<T>) returns Optional<T> because without an identity value, an empty stream has no starting answer.
• reduce(identity, accumulator) does not return Optional, because the identity is the answer for an empty stream.

findFirst respects encounter order. findAny is allowed to return any matching element, which gives parallel streams more freedom. We cover that properly in findFirst vs findAny and short-circuiting, but the Optional part is the same: maybe one result, maybe empty.

Primitive streams follow the same contract without boxing. IntStream.max() returns OptionalInt, LongStream.min() returns OptionalLong, and DoubleStream.average() returns OptionalDouble.

import java.util.IntSummaryStatistics;
import java.util.List;
import java.util.OptionalDouble;
import java.util.OptionalInt;

record LineItem(String sku, int quantity) { }

public class PrimitiveOptionalDemo {
    public static void main(String[] args) {
        List<LineItem> items = List.of(
                new LineItem("book", 2),
                new LineItem("pen", 5)
        );
        List<LineItem> emptyCart = List.of();

        OptionalInt maxQty = items.stream().mapToInt(LineItem::quantity).max();
        OptionalDouble averageEmpty = emptyCart.stream().mapToInt(LineItem::quantity).average();
        IntSummaryStatistics stats = items.stream().mapToInt(LineItem::quantity).summaryStatistics();

        System.out.println(maxQty.orElse(0));
        System.out.println(averageEmpty.isEmpty());
        System.out.println(stats.getSum());
    }
}