Uses for Optional in Java

1. Introduction

In this tutorial, we’ll look at the purpose of the Optional class in Java and some of the advantages of using it when building our applications.

2. The Purpose of Optional<T> in Java

Optional is a class that represents either presence or absence of something. Technically, an Optional is a wrapper class for a generic type T, where the Optional instance is empty if T is null. Otherwise, it’s full.

As per the Java 11 documentation, the purpose of Optional is to provide a return type that can represent the absence of value in scenarios where returning null might cause unexpected errors, like the infamous NullPointerException.

2.1. Useful Methods

The Optional class provides useful methods to help us work with that API. The important ones for this article are the of(), orElse(), and empty() methods:

• of(T value) returns an instance of an Optional with a value inside
• orElse(T other) returns the value inside an Optional, otherwise returns other
• Finally, empty() returns an empty instance of Optional

We’ll see these methods in action to build both the code that returns the Optional and the code that uses it.

3. Advantages of Optional

We’ve looked at the purpose of Optional and some of its methods. But, how can we benefit from that class in our programs? In this section, we’ll see a few ways to use it that helps us to create clear and robust APIs.

3.1. Optional vs. null

Before the creation of the Optional class, the way we had to represent the absence of value was by using null. The language doesn’t obligate us to treat the null case properly. In other words, null checks are sometimes necessary, but not mandatory. Thus, creating methods that return null proved to be a way to produce unexpected runtime errors like NullPointerExceptions.

On the other hand, an instance of Optional should always be treated properly at compile time to get the value inside of it. This obligation to handle an Optional at compile time results in fewer unexpected NullPointerExceptions.

Let’s try an example simulating a database of Users:

public class User {

    public User(String id, String name) {
        this.id = id;
        this.name = name;
    }

    private String id;

    private String name;

    public String getName() {
        return name;
    }

    public String getId() {
        return id;
    }
}

Let’s also define the repository class that returns a User if found. Otherwise, it returns null:

public class UserRepositoryWithNull {

    private final List<User> dbUsers = Arrays.asList(new User("1", "John"), new User("2", "Maria"), new User("3", "Daniel"));

    public User findById(String id) {

        for (User u : dbUsers) {
            if (u.getId().equals(id)) {
                return u;
            }
        }

        return null;
    }
}

Now, we’ll write a unit test that shows how the code breaks with a NullPointerException if we don’t address null using null checks:

@Test
public void givenNonExistentUserId_whenSearchForUser_andNoNullCheck_thenThrowException() {

    UserRepositoryWithNull userRepositoryWithNull = new UserRepositoryWithNull();
    String nonExistentUserId = "4";

    assertThrows(NullPointerException.class, () -> {
        System.out.println("User name: " + userRepositoryWithNull.findById(nonExistentUserId)
          .getName());
    });
}

Java allows us to use the getName() method from the object returned by findById() without a null check. In that case, we can only discover the problem at runtime.

To avoid that, we can create another repository where if we find a User, then we return a full Optional. Otherwise, we return an empty one. Let’s see this in practice:

public class UserRepositoryWithOptional {

    private final List<User> dbUsers = Arrays.asList(new User("1", "John"), new User("2", "Maria"), new User("3", "Daniel"));

    public Optional<User> findById(String id) {

        for (User u : dbUsers) {
            if (u.getId().equals(id)) {
                return Optional.of(u);
            }
        }

        return Optional.empty();
    }
}

Now, when we rewrite our unit test, we see how we must treat the Optional first to get its value when we don’t find any User:

@Test
public void givenNonExistentUserId_whenSearchForUser_thenOptionalShouldBeTreatedProperly() {

    UserRepositoryWithOptional userRepositoryWithOptional = new UserRepositoryWithOptional();
    String nonExistentUserId = "4";

    String userName = userRepositoryWithOptional.findById(nonExistentUserId)
      .orElse(new User("0", "admin"))
      .getName();

    assertEquals("admin", userName);
}

In the case above, we didn’t find any User, so we can return a default user using the orElse() method. To get its value, it is mandatory to treat the Optional properly at compile time. With that, we can mitigate unexpected errors at runtime.

Two other options we can use instead of providing a default with the orElse() method are to throw an exception using orElseThrow() or use orElseGet() to call a Supplier function.

3.2. Design Clear Intention APIs

As we discussed previously, null was widely used to represent nothing. However, the meaning of null is only clear to the person who created the API. Other developers that glance at that API may find different meanings for null.

Probably the name “Optional” is the main reason that Optional is a useful tool when building our APIs. Optional in the return of a method provides a clear intention of what we should expect from that method: it returns something or nothing. No documentation is needed to explain the return type of that method. The code explains itself.

Using the repository that returns null, we may find in the worst way that null represents that a User was not found in the database. Or maybe it could represent other things, like an error in connecting to the database, or the object not being initialized yet. It’s hard to know.

On the other hand, using the repository that returns an Optional instance makes it clear by looking just at the method signature that we may or may not find a user in the database.

An important practice for designing clear APIs is to never return a null Optional. Methods should always return a valid instance of Optional, using the static methods.

3.3. Declarative Programming

Another good reason to use the Optional class is the ability to use a chain of fluent methods. It provides a “pseudo-stream” similar to the stream() from collections, but with only one value. That means we can call methods like map(), and filter() on the value in it. That helps to create more declarative programs, instead of imperative ones.

Let’s say the requirement is to change the case of User‘s name to uppercase if the name starts with the letter ‘M’.

First, let’s look at the imperative way, using the repository that doesn’t return an Optional:

@Test
public void givenExistentUserId_whenFoundUserWithNameStartingWithMInRepositoryUsingNull_thenNameShouldBeUpperCased() {

    UserRepositoryWithNull userRepositoryWithNull = new UserRepositoryWithNull();

    User user = userRepositoryWithNull.findById("2");
    String upperCasedName = "";

    if (user != null) {
        if (user.getName().startsWith("M")) {
            upperCasedName = user.getName().toUpperCase();
        }
    }

    assertEquals("MARIA", upperCasedName);
}

Now, let’s take a look at the declarative way, using the Optional version of the repository:

@Test
public void givenExistentUserId_whenFoundUserWithNameStartingWithMInRepositoryUsingOptional_thenNameShouldBeUpperCased() {

    UserRepositoryWithOptional userRepositoryWithOptional = new UserRepositoryWithOptional();

    String upperCasedName = userRepositoryWithOptional.findById("2")
      .filter(u -> u.getName().startsWith("M"))
      .map(u -> u.getName().toUpperCase())
      .orElse("");

    assertEquals("MARIA", upperCasedName);
}

The imperative way needs two nested if statements to check if the object is not null and filter the user name. If the User is not found, the uppercase string remains empty.

In the declarative way, we use lambda expressions to filter the name and map the uppercase function to the User found. If the User is not found, we return an empty string using orElse().

It’s still a matter of preference which one we use. Both of them achieve the same result. The imperative way needs a bit more digging to understand what the code means. If we add more logic in the first or second if statement, for example, it might create some confusion about what the intention of that code is. In this type of scenario, declarative programming makes it clear what is the intent of the code: to return the uppercased name, otherwise, return an empty string.

4. Conclusion

In this article, we looked at the purpose of the Optional class and how to use it efficiently to design clear and robust APIs.