Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Streams and Functional

Java Optional.map() and flatMap()

Reference for Java Optional.map(), flatMap(), filter() and stream(): transform a value without unwrapping it, and learn when to use flatMap instead of map.

Optional.map() applies a function to the value inside an Optional and wraps the result in a new Optional. If the Optional is empty, the function is never called and the result is empty too. That lets you build a chain of steps without a single if (x != null) check.

flatMap() is the same idea for functions that already return an Optional. Using map there would give you an Optional<Optional<T>>; flatMap flattens it into a single level. filter() keeps the value only when a condition holds.

Java
Optional<Integer> length = Optional.of("hello").map(String::length);

Try it

Java Chaining map, filter and flatMap

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java map results, null and streams

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
public <U> Optional<U> map(Function<? super T, ? extends U> mapper)
public <U> Optional<U> flatMap(Function<? super T, ? extends Optional<? extends U>> mapper)
public Optional<T> filter(Predicate<? super T> predicate)
public Stream<T> stream()
Parameter Description
mapper Function applied to the value if present. For flatMap it must return an Optional (not null).
predicate Test for filter; the value is kept when it returns true.

Returns: map returns an Optional of the result, or empty if this Optional was empty or the function returned null. flatMap returns the Optional the function produced. filter returns this Optional or the empty one. stream() returns a stream with zero or one element (Java 9).

Throws: NullPointerException if the function or predicate is null, or if the function passed to flatMap returns null.

Usage notes

  • null becomes empty in map. This is what makes user.map(User::address).map(Address::city) safe, but it also hides which step failed.
  • map versus flatMap. If your method reference returns Optional<X>, use flatMap; if it returns plain X, use map.
  • No side effects in mappers. The mapper only runs when a value is present; do not rely on it for logging or counting.
  • Use ifPresent for actions. map is for producing a new value; to just do something with the value, see optional-ifpresent.
  • Not the same as Stream.map. An Optional holds at most one value, so there is no laziness or iteration.
  • Flattening streams. Optional::stream inside flatMap is the idiomatic way to drop empty Optionals from a stream (Java 9+).
  • Do not overuse chains. A long chain of map calls is fine; nested lambdas inside flatMap quickly become harder to read than a plain if.