This chapter is from the book
This chapter is from the book
This chapter is from the book
16.6 The Optional Class
When a method returns a null value, it is not always clear whether the null value represents a valid value or the absence of a value. Methods that can return null values invariably force their callers to check the returned value explicitly in order to avoid a NullPointerException before using the returned value. For example, method chaining, which we have seen for composing stream pipelines, becomes cumbersome if each method call must be checked to see whether it returns a null value before calling the next method, resulting in a cascade of conditional statements.
The concept of an Optional object allows the absence of a value to be handled in a systematic way, making the code robust by enforcing that a consumer of an Optional must also deal with the case when the value is absent. Taking full advantage of Optional wrappers requires using them the right way, primarily to handle situations where the value returned by a method is absent.
The generic class Optional<T> provides a wrapper that represents either the presence or absence of a non-null value of type T. In other words, the wrapper either contains a non-null value of type T or no value at all.
Example 16.8 illustrates using objects of the Optional<T> class.
Declaring and Returning an Optional
Example 16.8 illustrates declaring and returning an Optional. A book is represented by the Book class that has an optional blurb of type String; that is, a book may or may not have a blurb. The Optional<T> class is parameterized with the type String in the declaration, and so is the return type of the method that returns the optional blurb.
class Book {
private Optional<String> optBlurb;
public Optional<String> getOptBlurb() { return optBlurb; }
//...
}
Creating an Optional
The Optional<T> class models the absence of a value by a special singleton returned by the Optional.empty() method. In contrast to the null value, this singleton is a viable Optional object on which methods of the Optional class can be invoked without a NullPointerException being thrown.
The static Optional.of() factory method creates an Optional that encapsulates the non-null argument specified in the method call, as in the first declaration below. However, if the argument is a null value, a NullPointerException is thrown at runtime, as in the second declaration.
Optional<String> blurb0 = Optional.of("Java Programmers tell all!");
Optional<String> xblurb = Optional.of(null); // NullPointerException
The static Optional.ofNullable() factory method also creates an Optional that encapsulates the non-null argument specified in the method call, as in the first declaration below. However, if the argument is a null value, the method returns an empty Optional, as in the second declaration—which is effectively the same as the third declaration below.
Optional<String> blurb1 = Optional.ofNullable("Program like a Java Pro!");
Optional<String> noBlurb2 = Optional.ofNullable(null); // Optional.empty()
Optional<String> noBlurb3 = Optional.empty();
The blurbs above are used to initialize two Book objects (book0, book1) in Example 16.8. These Book objects with optional blurbs will be used to illustrate how to use Optional objects.
Example 16.8 Using Optionals
// File: OptionalUsage.java
import java.util.Optional;
// A book can have an optional blurb.
class Book {
private String bookName;
private Optional<String> optBlurb;
public String getBookName() { return bookName; }
public Optional<String> getOptBlurb() { return optBlurb; }
public Book(String bookName, Optional<String> optBlurb) {
this.bookName = bookName;
this.optBlurb = optBlurb;
}
}
// A course can have an optional book.
class Course {
private Optional<Book> optBook;
public Optional<Book> getOptBook() { return optBook; }
public Course(Optional<Book> optBook) { this.optBook = optBook; }
}
public class OptionalUsage {
public static void main(String[] args) {
// Creating an Optional:
Optional<String> blurb0 = Optional.of("Java Programmers tell all!");
//Optional<String> xblurb = Optional.of(null); // NullPointerException
Optional<String> blurb1 = Optional.ofNullable("Program like a Java Pro!");
Optional<String> noBlurb2 = Optional.ofNullable(null); // Optional.empty()
Optional<String> noBlurb3 = Optional.empty();
// Create some books:
Book book0 = new Book("Embarrassing Exceptions", blurb0);
Book book1 = new Book("Dancing Lambdas", noBlurb2); // No blurb.
// Querying an Optional:
if (book0.getOptBlurb().isPresent()) {
System.out.println(book0.getOptBlurb().get());//Java Programmers tell all!
}
book0.getOptBlurb()
.ifPresent(System.out::println); //Java Programmers tell all!
// System.out.println(book1.getOptBlurb().get()); // NoSuchElementException
String blurb = book0.getOptBlurb()
.orElse("No blurb"); // "Java Programmers tell all!"
System.out.println(blurb);
blurb = book1.getOptBlurb().orElse("No blurb"); // "No blurb"
System.out.println(blurb);
blurb = book1.getOptBlurb().orElseGet(() -> "No blurb"); // "No blurb"
System.out.println(blurb);
//blurb = book1.getOptBlurb() // RuntimeException
// .orElseThrow(() -> new RuntimeException("No blurb"));
}
}
Output from the program:
Java Programmers tell all! Java Programmers tell all! Java Programmers tell all! No blurb No blurb
Querying an Optional
The presence of a value in an Optional can be determined by the isPresent() method, and the value can be obtained by calling the get() method—which is not much better than checking explicitly for the null value, but as we shall see, other methods in the Optional class alleviate this drudgery. The get() method throws a NoSuchElementException if there is no value in the Optional.
if (book0.getOptBlurb().isPresent()) {
System.out.println(book0.getOptBlurb().get()); // Java Programmers tell all!
}
System.out.println(book1.getOptBlurb().get()); // NoSuchElementException
The idiom of determining the presence of a value and then handling the value is combined by the ifPresent() method that accepts a Consumer to handle the value if one is present. The ifPresent() method does nothing if there is no value present in the Optional.
Often, a default value should be supplied when an Optional does not contain a value. The orElse() method returns the value in the Optional if one is present; otherwise, it returns the value given by the argument specified in the method call.
The orElse() method in the statement below returns the blurb in the book referenced by the reference book0, as this book has a blurb.
String blurb = book0.getOptBlurb()
.orElse("No blurb"); // "Java Programmers tell all!"
The book referenced by the reference book1 has no blurb. Therefore, the orElse() method invoked on the optional blurb returns the argument in the method.
blurb = book1.getOptBlurb().orElse("No blurb"); // "No blurb"
For an Optional with a value, the orElseGet() method returns the value in the Optional. The orElseGet() method in the statement below returns the object supplied by the Supplier specified as an argument, since the book has no blurb.
blurb = book1.getOptBlurb().orElseGet(() -> "No blurb"); // "No blurb"
For an Optional with a value, the orElseThrow() method also returns the value in the Optional. The orElseThrow() method in the statement below throws the exception created by the Supplier specified as an argument, since the book has no blurb.
blurb = book1.getOptBlurb() // RuntimeException
.orElseThrow(() -> new RuntimeException("No blurb"));
Numeric Optional Classes
An instance of the generic Optional<T> class can only encapsulate an object. To deal with optional numeric values, the java.util package also defines the following non-generic classes that can encapsulate primitive numeric values: OptionalInt, OptionalLong, and OptionalDouble. For example, an OptionalInt object encapsulates an int value.
The numeric optional classes provide methods analogous to the static factory methods of the Optional class to create a numeric optional from a numeric value and methods to query a numeric optional. The filter(), map(), and flatMap() methods are not defined for the numeric optional classes.
The following methods are defined in the OptionalInt, OptionalLong, and Optional-Double classes in the java.util package. In the methods below, NumType is Int, Long, or Double, and the corresponding numtype is int, long, or double.
Example 16.9 illustrates using numeric optional values. A recipe has an optional number of calories that are modeled using an OptionalInt that can encapsulate an int value. Declaring, creating, and querying OptionalInt objects is analogous to that for Optional objects.
Example 16.9 Using Numerical Optionals
// File: NumericOptionalUsage.java
import java.util.OptionalInt;
class Recipe {
private String recipeName;
private OptionalInt calories; // Optional number of calories.
public String getRecipeName() { return recipeName; }
public OptionalInt getCalories() { return calories; }
public Recipe(String recipeName, OptionalInt calories) {
this.recipeName = recipeName;
this.calories = calories;
}
}
public final class NumericOptionalUsage {
public static void main(String[] args) {
// Creating an OptionalInt:
OptionalInt optNOC0 = OptionalInt.of(3500);
OptionalInt optNOC1 = OptionalInt.empty();
// Creating recipes with optional number of calories:
Recipe recipe0 = new Recipe("Mahi-mahi", optNOC0);
Recipe recipe1 = new Recipe("Loco moco", optNOC1);
// Querying an Optional:
// System.out.println(recipe1.getCalories()
// .getAsInt()); // NoSuchElementException
System.out.println((recipe1.getCalories().isPresent()
? recipe1.getCalories().getAsInt()
: "Unknown calories.")); // Unknown calories.
recipe0.getCalories().ifPresent(s -> System.out.println(s + " calories."));
System.out.println(recipe0.getCalories().orElse(0) + " calories.");
System.out.println(recipe1.getCalories().orElseGet(() -> 0) + " calories.");
// int noc = recipe1.getCalories() // RuntimeException
// .orElseThrow(() -> new RuntimeException("Unknown calories."));
}
}
Output from the program:
Unknown calories. 3500 calories. 3500 calories. 0 calories.