One of the most interesting features that Java 8 introduced to the language was the Optional class. The main issue this class is intended to tackle is the infamous NullPointerException that every Java programmer knows only too well.

Essentially, this is a wrapper class that contains an optional value, meaning it can either contain an object or it can simply be empty.

Optional comes along with a strong move towards functional programming in Java and is meant to help in that paradigm, but definitely also outside of that.

Let’s start with a simple use-case. Before Java 8, any number of operations involving accessing an object’s methods or properties could result in a NullPointerException:

String isocode = user.getAddress().getCountry().getIsocode().toUpperCase();

If we wanted to make sure we won’t hit the exception in this short example, we would need to do explicit checks for every value before accessing it:

if (user != null) {
    Address address = user.getAddress();
    if (address != null) {
        Country country = address.getCountry();
        if (country != null) {
            String isocode = country.getIsocode();
            if (isocode != null) {
                isocode = isocode.toUpperCase();
            }
        }
    }
}

As you can see, this can easily become cumbersome and hard to maintain.

To ease this process, let’s take a look at how we can use the Optional class instead, from creating and verifying an instance, to using the different methods it provides and combining it with other methods that return the same type, the latter being where the true power of Optional lies.

Creating Optional Instances

To reiterate, an object of this type can contain a value or be empty. You can create an empty Optional by using the method with the same name:

@Test(expected = NoSuchElementException.class)
public void whenCreateEmptyOptional_thenNull() {
    Optional<User> emptyOpt = Optional.empty();
    emptyOpt.get();
}

Not surprisingly, attempting to access the value of the emptyOpt variable results in a NoSuchElementException.

To create an Optional object that can contain a value – you can use the of() and ofNullable() methods. The difference between the two is that the of() method will throw a NullPointerException if you pass it a null value as an argument:

@Test(expected = NullPointerException.class)
public void whenCreateOfEmptyOptional_thenNullPointerException() {
    Optional<User> opt = Optional.of(user);
}

As you can see, we’re not completely rid of the NullPointerException. For this reason, you should only use of() when you are sure the object is not null.

If the object can be both null or not-null, then you should instead choose the ofNullable() method:

Optional<User> opt = Optional.ofNullable(user);

Accessing the Value of Optional Objects

One way to retrieve the actual object inside the Optional instance is to use the get() method:

@Test
public void whenCreateOfNullableOptional_thenOk() {
    String name = "John";
    Optional<String> opt = Optional.ofNullable(name);

    assertEquals("John", opt.get());
}

However, as you saw before, this method throws an exception in case the value is null. To avoid this exception, you can choose to first verify if a value is present or not:

@Test
public void whenCheckIfPresent_thenOk() {
    User user = new User("john@gmail.com", "1234");
    Optional<User> opt = Optional.ofNullable(user);
    assertTrue(opt.isPresent());

    assertEquals(user.getEmail(), opt.get().getEmail());
}

Another option for checking the presence of a value is the ifPresent() method. In addition to performing the check, this method also takes a Consumer argument and executes the lambda expression if the object is not empty:

opt.ifPresent( u -> assertEquals(user.getEmail(), u.getEmail()));

In this example, the assertion is only executed if the user object is not null.

Next, let’s look at ways in which alternatives for empty values can be provided.

Returning Default Values

The Optional class provides APIs for returning the value of the object or a default value if the object is empty.

The first method you can use for this purpose is orElse(), which works in a very straight-forward way: it returns the value if it’s present, or the argument it receives if not:

@Test
public void whenEmptyValue_thenReturnDefault() {
    User user = null;
    User user2 = new User("anna@gmail.com", "1234");
    User result = Optional.ofNullable(user).orElse(user2);

    assertEquals(user2.getEmail(), result.getEmail());
}

Here, the user object was null, so user2 was returned as a default instead.

If the initial value of the object is not null, then the default value is ignored:

@Test
public void whenValueNotNull_thenIgnoreDefault() {
    User user = new User("john@gmail.com","1234");
    User user2 = new User("anna@gmail.com", "1234");
    User result = Optional.ofNullable(user).orElse(user2);

    assertEquals("john@gmail.com", result.getEmail());
}

The second API in the same category is orElseGet() – which behaves in a slightly different manner. In this case, the method returns the value if one is present, and if not it executes the Supplier functional interface that it receives as an argument, and returns the result of that execution:

User result = Optional.ofNullable(user).orElseGet( () -> user2);

Difference Between orElse() and orElseGet()

At first glance, it might seem as if the two methods have the same effect. However, this is not exactly the case. Let’s create some examples that highlight the similarities as well as the differences in behavior between the two.

First, let’s see how they behave when an object is empty:

@Test
public void givenEmptyValue_whenCompare_thenOk() {
    User user = null
    logger.debug("Using orElse");
    User result = Optional.ofNullable(user).orElse(createNewUser());
    logger.debug("Using orElseGet");
    User result2 = Optional.ofNullable(user).orElseGet(() -> createNewUser());
}

private User createNewUser() {
    logger.debug("Creating New User");
    return new User("extra@gmail.com", "1234");
}

In the code above, both methods call the createNewUser() method which logs a message and returns a User object.

The output of this code is:

Using orElse
Creating New User
Using orElseGet
Creating New User

Therefore, when the object is empty and the default object is returned instead, there is no difference in behavior.

Next, let’s take a look at a similar example in which the Optional is not empty:

@Test
public void givenPresentValue_whenCompare_thenOk() {
    User user = new User("john@gmail.com", "1234");
    logger.info("Using orElse");
    User result = Optional.ofNullable(user).orElse(createNewUser());
    logger.info("Using orElseGet");
    User result2 = Optional.ofNullable(user).orElseGet(() -> createNewUser());
}

The output this time is:

Using orElse
Creating New User
Using orElseGet

Here, both Optional objects contain a non-null value which the methods will return. However, the orElse() method will still create the default User object. By contrast, the orElseGet() method will no longer create a User object.

This difference can have a significant effect on performance if the operation executed involves more intensive calls, such as a web service call or a database query.

Returning an Exception

Next to the orElse() and orElseGet() methods, Optional also defines an orElseThrow() API – which, instead of returning an alternate value, throws an exception instead if the object is empty:

@Test(expected = IllegalArgumentException.class)
public void whenThrowException_thenOk() {
    User result = Optional.ofNullable(user)
      .orElseThrow( () -> new IllegalArgumentException());
}

Here, if the user value is null, an IllegalArgumentException is thrown.

This allows us to have a lot more flexible semantics and decide the exception that gets thrown instead of always seeing a NullPointerException.

Now that we have a good understanding of how we can leverage Optional by itself, let’s have a look at additional methods that can be used to apply transformations and filtering to Optional values.

Transforming Values

Optional values can be transformed in a number of ways; let’s start with map() and flatMap() methods.

First, let’s see an example that uses the map() API:

@Test
public void whenMap_thenOk() {
    User user = new User("anna@gmail.com", "1234");
    String email = Optional.ofNullable(user)
      .map(u -> u.getEmail()).orElse("default@gmail.com");

    assertEquals(email, user.getEmail());
}

map() applies the Function argument to the value, then returns the result wrapped in an Optional. This makes it possible to apply and chain further operations on the response – such orElse() here.

By comparison, flatMap() also takes a Function argument that is applied to an Optional value, and then returns the result directly.

To see this in action, let’s add a method that returns an Optional to the User class:

public class User {    
    private String position;

    public Optional<String> getPosition() {
        return Optional.ofNullable(position);
    }

    //...
}

Since the getter method returns an Optional of String value, you can use as the argument for flatMap(), where this is called for an Optional User object. The return will be the unwrapped String value:

@Test
public void whenFlatMap_thenOk() {
    User user = new User("anna@gmail.com", "1234");
    user.setPosition("Developer");
    String position = Optional.ofNullable(user)
      .flatMap(u -> u.getPosition()).orElse("default");

    assertEquals(position, user.getPosition().get());
}

Filtering Values

Alongside transforming the values, the Optional class also offers the possibility to “filter” them based on a condition.

The filter() method takes a Predicate as an argument and returns the value as it is if the test evaluates to true. Otherwise, if the test is false, the returned value is an empty Optional.

Let’s see an example of accepting or rejecting a User based on a very basic email verification:

@Test
public void whenFilter_thenOk() {
    User user = new User("anna@gmail.com", "1234");
    Optional<User> result = Optional.ofNullable(user)
      .filter(u -> u.getEmail() != null && u.getEmail().contains("@"));

    assertTrue(result.isPresent());
}

The result object will contain a non-null value as a result of it passing the filter test.