The Streams API

Optional with Streams

15 min Lesson 9 of 13

Optional with Streams

Two stream terminal operations — findFirst() and findAny() — do not return a single concrete value. They return an Optional<T>. Understanding why, and knowing how to handle that Optional safely, is the focus of this lesson.

Why search operations return Optional

A stream may be empty. If you ask "find me the first element" and the stream has no elements, there is no meaningful value to return. In older Java you would return null and every caller would have to remember to null-check. Optional<T> makes the possible absence explicit in the type system — the compiler forces you to deal with it.

Optional is a container. It holds either one value (present) or nothing (empty). It is not a collection — it holds at most one element. Think of it as a typed alternative to null.

findFirst() — deterministic search

findFirst() returns the first element of the stream that survives any preceding filter operations, wrapped in an Optional. "First" means the first element in encounter order — the order of the underlying source (a List, for example).

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

List<String> names = List.of("Alice", "Bob", "Charlie", "Anna");

Optional<String> first = names.stream()
    .filter(name -> name.startsWith("A"))
    .findFirst();

System.out.println(first); // Optional[Alice]

The stream finds "Alice" first and stops — it does not scan the rest of the list. Streams are lazy: terminal operations only pull as many elements as they need.

findAny() — parallel-friendly search

findAny() returns any element that satisfies the preceding filters. On a sequential stream it usually returns the first element, but the JVM makes no guarantee. On a parallel stream it returns whichever matching element a thread happens to find first, which is faster because threads do not have to agree on order.

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

List<Integer> numbers = List.of(1, 3, 5, 8, 10, 12);

Optional<Integer> anyEven = numbers.parallelStream()
    .filter(n -> n % 2 == 0)
    .findAny();

// could print Optional[8], Optional[10], or Optional[12] — non-deterministic
System.out.println(anyEven);

Rule of thumb: use findFirst() when you need a predictable, reproducible result (tests, ordered processing). Use findAny() when you only need a match and are using a parallel stream for speed.

Handling the Optional result

Both methods give you an Optional<T>. There are several ways to unwrap it safely.

isPresent() / get()

The most explicit — but verbose — approach:

Optional<String> result = names.stream()
    .filter(n -> n.startsWith("Z"))
    .findFirst();

if (result.isPresent()) {
    System.out.println("Found: " + result.get());
} else {
    System.out.println("Not found");
}

Never call get() without first checking isPresent() (or using one of the safer alternatives below). If the Optional is empty, get() throws NoSuchElementException — the exact runtime crash Optional was designed to prevent.

orElse() — provide a default

Returns the value if present, or a fallback you supply:

String found = names.stream()
    .filter(n -> n.startsWith("Z"))
    .findFirst()
    .orElse("Unknown");

System.out.println(found); // Unknown

orElseGet() — lazy default via supplier

Like orElse(), but the fallback is only computed when it is actually needed. Prefer this when the fallback is expensive (a database call, object construction, etc.):

String found = names.stream()
    .filter(n -> n.startsWith("A"))
    .findFirst()
    .orElseGet(() -> "default-from-db");

System.out.println(found); // Alice  (lambda never runs)

orElseThrow() — fail loudly

Throws an exception if the Optional is empty. Use this when an absent value is a genuine programming error:

String admin = names.stream()
    .filter(n -> n.equals("Admin"))
    .findFirst()
    .orElseThrow(() -> new IllegalStateException("Admin user must exist in the list"));

ifPresent() — run a side-effect only when a value exists

Executes a consumer when the Optional has a value; does nothing when it is empty:

names.stream()
    .filter(n -> n.startsWith("B"))
    .findFirst()
    .ifPresent(n -> System.out.println("Processing: " + n)); // Processing: Bob

Chaining Optional transformations

Optional itself has map() and filter() methods, so you can transform the value inside without ever unwrapping it early:

List<String> emails = List.of("alice@example.com", "bob@example.com");

Optional<String> domain = emails.stream()
    .filter(e -> e.startsWith("alice"))
    .findFirst()
    .map(e -> e.substring(e.indexOf('@') + 1)); // transforms the value inside Optional

domain.ifPresent(d -> System.out.println("Domain: " + d)); // Domain: example.com

Quick reference

findFirst() — first match in encounter order; use for sequential, deterministic needs.
findAny() — any match; prefer on parallel streams for performance.
orElse(T) — constant default value.
orElseGet(Supplier) — lazy default, evaluated only if empty.
orElseThrow(Supplier) — throw when absence is an error.
ifPresent(Consumer) — side-effect when present.
map(Function) — transform the value while staying inside Optional.

Mastering these patterns means your code clearly communicates intent: absent values are handled explicitly, NPEs are avoided by design, and parallel searches become trivial to express.