Optional: a value that might be missing

A library catalog has a method that finds a book by its id. Ask it for book 7 when there is no book 7, and what should it hand back? For a long time the usual answer in Java was null, and the usual result was a NullPointerException a few lines later. This lesson is about Optional, a small class from the Java library that puts “there may be no result” into a method's return type, where the compiler can see it, and about the methods that make the missing case quick to handle.

When a method finds nothing#

Here is a small library catalog. findById walks the list of books and returns the one whose id matches. When no book matches, the loop ends without returning, and the method returns null, the value that means “no object”. Run it and read the error.

The first lookup prints Dune. The second stops the program on line 8 with a NullPointerException and this message:

Cannot invoke "Book.title()" because the return value of "Library.findById(int)" is null

Read it from the end. findById(7) returned null, and the program then asked that null for its title(). There was no book to ask, so Java stopped. Reading errors and debugging takes messages like this one apart piece by piece.

A search that finds nothing has still done its job. The problem is that the line Book findById(int id) gives no hint that it can happen. The return type says Book, so anyone who calls the method without reading its body expects a book. The compiler cannot warn them either, because to the compiler null is an acceptable value for any Book variable. Every caller has to remember to check for null, every time, and one forgotten check is a crash, often far from the method that returned the null.

Methods that work something out run into the same question. What is the longest word in a list? For an empty list there is no answer. Returning "" would claim there was a word with no letters in it, and returning null sets the same trap as findById.

Optional puts “maybe nothing” in the type#

Optional<T>, from the package java.util, is an object that holds either one value of type T or nothing at all. An Optional with a value inside is present; one with nothing inside is empty. Picture a small box with room for one thing. You always get the box, so you can always look inside it safely, and the label on the outside warns you that it may be empty.

Here is findById again, now returning an Optional<Book>. Two lines changed: it returns Optional.of(book) when it finds a match, and Optional.empty() when the loop ends without one.

It prints Optional[Book[id=2, title=Dune]] and then Optional.empty. Printing an Optional shows its value in square brackets, or Optional.empty when there is none. The method never returns null now. Every caller gets an Optional object back, and an empty one answers questions like any other object.

The compiler now reminds you

Try the line that crashed before, library.findById(7).title(), against the new method. It does not compile:

The compiler looked for a method title() on the type that findById returns, Optional<Book>, and found none. title() belongs to Book, and the book is inside the box. To reach it you call one of the methods on this page, and almost all of them make you decide, right there, what happens when the box is empty. The crash from the last section has become a compile error, which you see before the program ever runs.

Key idea

An Optional return type tells every caller, in the type itself, that there may be no result. The compiler makes them open the box before they can use the value, and that is the moment to decide what happens when it is empty.

Making an Optional: of, empty and ofNullable

Optional has no public constructor. You make one with one of three static methods:

• Optional.of(value) wraps a value that is not null.
• Optional.empty() gives an empty Optional.
• Optional.ofNullable(value) wraps a value that might be null. It gives an empty Optional for null and a present one for anything else.

ofNullable is the bridge from older methods that answer with null, such as a map's get. Here the map loans records who has borrowed which book.

The first two lines print Optional[Dune] Optional.empty and Optional[Grace] Optional.empty. Nobody has borrowed book 1, so loans.get(1) returned null, and ofNullable turned that null into an empty Optional. Line 19 passes the same null to Optional.of, which refuses it straight away: the program stops with a java.lang.NullPointerException that has no message.

Writing a method that may find nothing

A method like this has the same shape every time: return Optional.of(...) at the point where you find the answer, and Optional.empty() at the end, once the search has failed. Here is one to put back together.

Getting the value out#

An Optional is only useful once you take the value out, and the methods for that differ in what they do when there is no value. The plainest way asks first.

Asking first: isPresent, isEmpty and get

isPresent() returns true when there is a value, and isEmpty(), added in Java 11, returns true when there is not. get() returns the value, and throws a NoSuchElementException when there is none.

It prints Found Dune and false true, and then line 15 stops the program with java.util.NoSuchElementException: No value present. Calling get() on an empty Optional crashes just as surely as calling title() on null.

So asking first only moves the old null check: if (found.isPresent()) instead of if (book != null). It works, and you will see it in real code. The methods in the rest of this section are shorter, and they have no get() that you could call without the check.

A stand-in value: orElse

orElse(other) returns the value if there is one, and other if there is not. It suits a missing value that has a sensible stand-in. The library has a second lookup, borrowerOf, which tells you who has a book. Most books are on the shelf, so it returns an Optional<String>: the borrower's name, or empty.

It prints Book 2 is with Grace and Book 1 is with nobody. Notice that who is a plain String. orElse takes the value out of the box, so the rest of the code never sees an Optional.

A stand-in made only when needed: orElseGet

Sometimes the stand-in costs something to make: reading a file, asking a server, or searching old records. In the next program that work is checkPaperRecords(), which prints a line so that you can see when it runs. Decide what the program prints before you run it.

It is the second one. On line 8, checkPaperRecords() runs even though book 2 has a borrower. Java works out every argument of a method before the method starts, so it calls checkPaperRecords() to get the argument for orElse, and only then does orElse look in the box, find Grace and throw "unknown" away. orElse receives a finished value, so it has no way to skip making it.

orElseGet takes a Supplier instead. Supplier<T>, from java.util.function, is a functional interface whose one method, get(), takes nothing and returns a T. A lambda that takes nothing starts with empty parentheses: () -> checkPaperRecords(). orElseGet calls the lambda only when the box is empty, which is why the records are checked for book 1 on line 10 and not for book 2 on line 9.

Key idea

orElse always works out its argument, even when the value is there. When the stand-in takes real work to make, use orElseGet with a lambda, which runs only for an empty Optional.

No value is a mistake: orElseThrow

Sometimes a missing value means something has gone wrong. An id that came from your own list of books should always be found. orElseThrow(), added in Java 10, returns the value or throws a NoSuchElementException with the message No value present. It does exactly what get() does, but its name tells the reader that it can throw, and the documentation of get() names orElseThrow() as the method to prefer.

To throw an exception of your own, with a message that helps, pass orElseThrow a lambda that makes the exception. The lambda runs only when the box is empty. From here on, findById is a stream pipeline, because findFirst() already returns the Optional the method needs.

It prints Reading Dune, and then Caught: No value present from the catch block. The last lookup throws the exception that the lambda made, and the program stops with java.lang.IllegalArgumentException: No book has id 7. That message names the missing id, at the place where the lookup failed, which is much easier to trace than a NullPointerException several methods later.

Working inside the box: map, filter and flatMap#

Often what you need is something made from the value, such as the title of the book in the box. map(function) makes it without opening the box. If there is a value, map passes it to the function and puts the result in a new Optional. If the box is empty, map never calls the function and hands back an empty Optional.

It prints Optional[Dune] Optional.empty, and then NO SUCH BOOK. Step through lines 12 to 14 and watch the narration: findById(7) returns an empty Optional, and the lambda inside map never runs. The chain reads like a sentence, with no if for the empty case: find book 7, turn it into its title in capitals, or else use NO SUCH BOOK.

filter: keep the value only if it passes a test

filter(test) keeps the value when the test returns true for it, and gives back an empty Optional when the test returns false. An empty Optional has nothing to test, so it stays empty.

One case catches people out. A shopper types three spaces into the box for a discount code. Predict what the program prints.

It prints true, true and false. trim() turns " " into "", the empty string, and map puts that in a new box. A box that holds the empty string is present, because the empty string is still a value. Only filter, whose test fails for "", gives back an empty Optional. Printed, trimmed would show Optional[] and real would show Optional.empty.

Watch one value travel down a chain

The lab runs a greetingmethod for three users. It looks up the user's nickname, trims the spaces off it, drops it if nothing is left, and builds a greeting, with "Hello, guest" as the stand-in. Pick a user and press Next step to run one step at a time. Watch which lambdas run, and where an empty box makes the later steps skip theirs.

Here is the same method in a program. Step through it and follow the narration: for cleo, none of the three lambdas runs.

It prints Hello, Ada and then Hello, guesttwice. Ben and Cleo get the same greeting for different reasons: Ben's box was emptied by filter, while Cleo's was empty from the start.

Key idea

Once an Optional is empty, every map and filter after it is skipped. The empty box travels to the end of the chain, where orElse or one of its relatives decides what to do.

flatMap: when the function returns an Optional too

Now ask a question with two lookups in it: who has the book called Dune? First find the book by its title, which may find nothing. Then look up its borrower, which may also find nothing. Both lookups return an Optional. Here is what happens when you join them with map, and then with flatMap.

The first line prints Optional[Optional[Grace]], a box inside a box. The function passed to map already returns an Optional<String>, and map wraps whatever its function returns in another Optional, so the result is an Optional<Optional<String>>. To get Grace out of that you would have to open two boxes.

flatMap is made for this case. It expects a function that returns an Optional, and hands that Optional back as it is, without wrapping it again. The loop prints Dune: Optional[Grace], Emma: Optional.empty and Ulysses: Optional.empty. Emma is in the catalog but nobody has borrowed it; Ulysses is not in the catalog at all. Both come out empty, because flatMap gives back an empty Optional as soon as either lookup finds nothing. When your program has to tell those two cases apart, do the lookups one at a time.

1import java.util.List;
2import java.util.Optional;
3 
4public class Main {
5    public static void main(String[] args) {
6        List<Song> playlist = List.of(
7            new Song("Intro", 95),
8            new Song("Night Drive", 241),
9            new Song("Echo", 187));
10 
11        System.out.println(firstLongerThan(playlist, 90).map(Song::title).orElse("none"));
12        System.out.println(firstLongerThan(playlist, 200).map(Song::title).orElse("none"));
13        System.out.println(firstLongerThan(playlist, 300).map(Song::title).orElse("none"));
14    }
15 
16    static Optional<Song> firstLongerThan(List<Song> songs, int seconds) {
17        // TODO: return the first song longer than seconds, or an empty Optional
18        return Optional.empty();
19    }
20}
21 
22record Song(String title, int seconds) {}

Acting on the value: ifPresent, or and stream#

ifPresent and ifPresentOrElse

Sometimes there is nothing to return, only something to do with the value: print it, add it to a list, send it somewhere. ifPresent(action) runs the action with the value if there is one, and does nothing for an empty Optional. ifPresentOrElse(action, emptyAction), from Java 9, takes a second action for the empty case.

It prints Reserved Dune, then Reserved Beloved and No book has id 9. The lookup of book 7 on lines 10 and 11 prints nothing at all. The second argument of ifPresentOrElse is a Runnable, a functional interface whose one method, run(), takes nothing and returns nothing, so its lambda starts with () as well. You will meet Runnable again in introduction to threads.

or: a second place to look

or(supplier), also from Java 9, keeps an Optional that has a value. For an empty one it calls the supplier, which returns another Optional to use instead. Unlike orElse, it gives you an Optional back, so you can try a third place or carry on with map. Here a town library falls back on the school library's catalog.

It prints 2: Optional[Book[id=2, title=Dune]], 4: Optional[Book[id=4, title=Kindred]] and 9: Optional.empty. Book 2 is in the town library, so the school's catalog is never searched. Book 4 comes from the fallback, and book 9 is in neither.

stream(): zero elements or one

stream(), from Java 9 as well, turns an Optional into a stream with one element, or with none when the Optional is empty. It is handy when you have a stream of Optionals: together with the flatMap from Collectors and stream recipes, it drops the empty ones and keeps the values.

The first two lines print [Book[id=2, title=Dune]] and []. In the pipeline, map turns each id into an Optional<Book>, and flatMap(Optional::stream) replaces each one with its stream of zero books or one. The ids with no book drop out, and the last line is [Book[id=3, title=Beloved], Book[id=1, title=Emma]], in the order the ids were asked for.

Optionals the library hands you#

You will write methods that return an Optional, and you will call even more of them. Every stream operation that may have no answer returns one.

The longest word in a list, the method with no good answer at the start of this lesson, takes one line with max. It compares the elements with a Comparator, here one that compares words by length as in Comparable, Comparator and sorting, and returns the biggest in an Optional.