Java Optional as Return Type

1. Introduction

The Optional type was introduced in Java 8.  It provides a clear and explicit way to convey the message that there may not be a value, without using null.

When getting an Optional return type, we’re likely to check if the value is missing, leading to fewer NullPointerExceptions in the applications. However, the Optional type isn’t suitable in all places.

Although we can use it wherever we see fit, in this tutorial, we’ll focus on some best practices of using Optional as a return type.

2. Optional as Return Type

An Optional type can be a return type for most methods except some scenarios discussed later in the tutorial.

Most of the time, returning an Optional is just fine:

public static Optional<User> findUserByName(String name) {
    User user = usersByName.get(name);
    Optional<User> opt = Optional.ofNullable(user);
    return opt;
}

This is handy since we can use the Optional API in the calling method:

public static void changeUserName(String oldFirstName, String newFirstName) {
    findUserByFirstName(oldFirstName).ifPresent(user -> user.setFirstName(newFirstName));
}

It’s also appropriate for a static method or utility method to return an Optional value.  However, there are many situations where we should not return an Optional type.

3. When to Not Return Optional

Because Optional is a wrapper and value-based class, there are some operations that can’t be done against Optional object. Many times, it’s just simply better to return the actual type rather than an Optional type.

Generally speaking, for getters in POJOs, it’s more suitable to return the actual type, not an Optional type. Particularly, it’s important for Entity Beans, Data Models, and DTOs to have traditional getters.

We’ll examine some of the important use cases below.

3.1. Serialization

Let’s imagine we have a simple entity:

public class Sock implements Serializable {
    Integer size;
    Optional<Sock> pair;

    // ... getters and setters
}

This actually won’t work at all. If we were to try and serialize this, we’d get an NotSerializableException:

new ObjectOutputStream(new ByteArrayOutputStream()).writeObject(new Sock());

And really, while serializing Optional may work with other libraries, it certainly adds what may be unnecessary complexity.

Let’s take a look at another application of this same serialization mismatch, this time with JSON.

3.2. JSON

Modern applications convert Java objects to JSON all the time. If a getter returns an Optional type, we’ll most likely see some unexpected data structure in the final JSON.

Let’s say we have a bean with an optional property:

private String firstName;

public Optional<String> getFirstName() {
    return Optional.ofNullable(firstName);
}

public void setFirstName(String firstName) {
    this.firstName = firstName;
}

So, if we use Jackson to serialize an instance of Optional, we’ll get:

{"firstName":{"present":true}}

But, what we’d really want is:

{"firstName":"Baeldung"}

So, Optional is a pain for serialization use cases. Next, let’s look at the cousin to serialization: writing data to a database.

3.3. JPA

In JPA, the getter, setter, and field should have name as well as type agreement. For example, a firstName field of type String should be paired with a getter called getFirstName that also returns a String.

Following this convention makes several things simpler, including the use of reflection by libraries like Hibernate, to give us great Object-Relational mapping support.

Let’s take a look at our same use case of an optional first name in a POJO.

This time, though, it’ll be a JPA entity:

@Entity
public class UserOptionalField implements Serializable {
    @Id
    private long userId;

    private Optional<String> firstName;

    // ... getters and setters
}

And let’s go ahead and try to persist it:

UserOptionalField user = new UserOptionalField();
user.setUserId(1l);
user.setFirstName(Optional.of("Baeldung"));
entityManager.persist(user);

Sadly, we run into an error:

Caused by: javax.persistence.PersistenceException: [PersistenceUnit: com.baeldung.optionalReturnType] Unable to build Hibernate SessionFactory
	at org.hibernate.jpa.boot.internal.EntityManagerFactoryBuilderImpl.persistenceException(EntityManagerFactoryBuilderImpl.java:1015)
	at org.hibernate.jpa.boot.internal.EntityManagerFactoryBuilderImpl.build(EntityManagerFactoryBuilderImpl.java:941)
	at org.hibernate.jpa.HibernatePersistenceProvider.createEntityManagerFactory(HibernatePersistenceProvider.java:56)
	at javax.persistence.Persistence.createEntityManagerFactory(Persistence.java:79)
	at javax.persistence.Persistence.createEntityManagerFactory(Persistence.java:54)
	at com.baeldung.optionalReturnType.PersistOptionalTypeExample.<clinit>(PersistOptionalTypeExample.java:11)
Caused by: org.hibernate.MappingException: Could not determine type for: java.util.Optional, at table: UserOptionalField, for columns: [org.hibernate.mapping.Column(firstName)]

We could try deviating from this standard. For example, we could keep the property as a String, but change the getter:

@Column(nullable = true) 
private String firstName; 

public Optional<String> getFirstName() { 
    return Optional.ofNullable(firstName); 
}

It appears that we could have both ways: have an Optional return type for the getter and a persistable field firstName.

However, now that we are inconsistent with our getter, setter, and field, it’ll be more difficult to leverage JPA defaults and IDE source code tools.

Until JPA has elegant support of Optional type, we should stick to the traditional code. It’s simpler and better:

private String firstName;

// ... traditional getter and setter

Let’s finally take a look at how this affects the front end – check to see if the problem we run into sounds familiar.

3.4. Expression Languages

Preparing a DTO for the front-end presents similar difficulties.

For example, let’s imagine that we are using JSP templating to read our UserOptional DTO’s firstName from the request:

<c:out value="${requestScope.user.firstName}" />

Since it’s an Optional, we’ll not see “Baeldung“. Instead, we’ll see the String representation of the Optional type:

Optional[Baeldung]

And this isn’t a problem just with JSP. Any templating language, be it Velocity, Freemarker, or something else, will need to add support for this. Until then, let’s continue to keep our DTOs simple.

4. Conclusion

In this tutorial, we’ve learned how we can return an Optional object, and how to deal with this kind of return value.

On the other hand, we’ve also learned that there are many scenarios that we would be better off to not use Optional return type for a getter. While we can use Optional type as a hint that there might be no non-null value, we should be careful not to overuse the Optional return type, particularly in a getter of an entity bean or a DTO.

The source code of the examples in this tutorial can be found on GitHub.