Stop Returning null! 4 Advanced Optional Patterns

1. Introduction

Returning null from query methods in Java business code is a common source of NullPointerException because callers often forget to perform non‑null checks. Using Optional as a return type makes the possibility of absence explicit, forces callers to handle both presence and absence, and avoids the “null‑check pyramid”. The article recommends using Optional only as a return type, combined with chainable calls and flatMap, while keeping Optional out of method parameters and class fields.

2. Practical examples

2.1 Optional replaces null as a query return value

// ❌ Caller has no idea the method may return null
public User findByEmail(String email) {
    // may return null
    return userRepository.findByEmail(email);
}

// ❌ Caller forgets null check → production crash
User user = userService.findByEmail("[email protected]");
// NullPointerException
sendWelcomeEmail(user.getEmail());

// ✅ Method signature clearly indicates possible absence
public Optional<User> findByEmail(String email) {
    // returns Optional
    return userRepository.findByEmail(email);
}

// ✅ Caller must handle both presence and absence
public void sendWelcomeEmailIfExists(String email) {
    // A: ifPresent – execute only when value exists
    userService.findByEmail(email)
        .ifPresent(user -> emailService.sendWelcome(user.getEmail()));

    // B: orElseThrow – throw a meaningful exception when absent
    User user = userService.findByEmail(email)
        .orElseThrow(() -> new UserNotFoundException("User not found for email: %s".formatted(email)));

    // C: orElse – provide a reasonable default when absent
    User user = userService.findByEmail(email).orElse(User.anonymous());
}

Method signature is honest and clear – callers know the result may be missing. orElseThrow replaces silent NPEs with meaningful exceptions.

Forces callers to decide how to handle missing results.

Spring Data already returns Optional; avoid converting back to null with orElse(null).

2.2 Optional chaining: simplify nested null checks

// ❌ Defensive null‑check pyramid (deeply nested code)
public String getCustomerCity(Long orderId) {
    Order order = orderRepository.findById(orderId);
    if (order != null) {
        Customer customer = order.getCustomer();
        if (customer != null) {
            Address address = customer.getAddress();
            if (address != null) {
                return address.getCity();
            }
        }
    }
    return "Unknown";
}

// ✅ Flat, readable, null‑safe chain
public String getCustomerCity(Long orderId) {
    return orderRepository.findById(orderId)   // Optional<Order>
        .map(Order::getCustomer)               // Optional<Customer>
        .map(Customer::getAddress)             // Optional<Address>
        .map(Address::getCity)                 // Optional<String>
        .orElse("Unknown");                  // any step null returns default
}

// ✅ Same pattern works for deep configuration objects
public int getTimeoutMillis() {
    return Optional.ofNullable(appConfig)
        .map(AppConfig::getHttp)
        .map(HttpConfig::getTimeout)
        .map(TimeoutConfig::getMillis)
        .orElse(3000); // reasonable default
}

Eliminates the null‑check pyramid – logic flows top‑to‑bottom.

Each map() short‑circuits automatically when a step is empty.

Default values are explicit and not hidden in else branches.

Works seamlessly with method references, keeping code concise and expressive.

2.3 Using flatMap for methods that return Optional

// ❌ <code>map()</code> wraps an inner Optional, producing Optional<Optional<T>>
public Optional<String> getPrimaryCity(Long userId) {
    return userRepository.findById(userId)
        // getPrimaryAddress returns Optional<Address>
        .map(user -> user.getPrimaryAddress());
    // Result: Optional<Optional<Address>> – hard to use
}

// ❌ Forced to unpack manually
Optional<Optional<Address>> nested = userRepository.findById(userId)
    .map(User::getPrimaryAddress);
String city = nested.isPresent() && nested.get().isPresent()
    ? nested.get().get().getCity()
    : "Unknown"; // back to cumbersome null checks

// ✅ <code>flatMap</code> flattens Optional<Optional<T>> to Optional<T>
public Optional<String> getPrimaryCity(Long userId) {
    return userRepository.findById(userId)   // Optional<User>
        .flatMap(User::getPrimaryAddress)   // Optional<Address>
        .map(Address::getCity);              // Optional<String>
}

// ✅ Real‑world example: resolve discount
public Optional<BigDecimal> resolveDiscount(Long orderId) {
    return orderRepository.findById(orderId)          // Optional<Order>
        .flatMap(Order::getPromoCode)               // Optional<PromoCode>
        .flatMap(promoCodeService::findDiscount);   // Optional<BigDecimal>
}

// ✅ Caller handles final Optional concisely
BigDecimal discount = resolveDiscount(orderId).orElse(BigDecimal.ZERO);

Avoids the double‑Optional anti‑pattern that confuses reviewers.

Simple rule: use map() for ordinary values, flatMap() when the next step already returns Optional.

No matter how many Optional -returning steps are chained, the code stays flat and readable.

Demonstrates functional composition – a hallmark of seasoned Java code.

2.4 Optional only for service layer – never for method parameters or class fields

// ❌ Using Optional as a method parameter – absolutely prohibited
public void updateUser(Long id, Optional<String> name, Optional<String> email) {
    // Caller must wrap values: updateUser(1L, Optional.of("John"), Optional.empty())
    // Worse than passing null directly
}

// ❌ Using Optional as a class field – breaks Jackson, Hibernate, equals/hashCode
public class User {
    private Optional<String> middleName; // serialization issues
}

// ❌ Calling .get() without a check – throws NoSuchElementException, same fatal as NPE
Optional<User> user = userRepository.findById(id);
String email = user.get().getEmail();

// ✅ Optional should only be a return type – never a parameter or field
@Service
public class UserService {
    // ✅ Return Optional when value may be absent
    public Optional<User> findById(Long id) {
        return userRepository.findById(id);
    }

    // ✅ Optional parameters replaced by @Nullable annotations
    public void updateUser(Long id, @Nullable String name, @Nullable String email) {
        User user = userRepository.findById(id)
            .orElseThrow(() -> new UserNotFoundException(id));
        if (name != null) user.setName(name);
        if (email != null) user.setEmail(email);
        userRepository.save(user);
    }

    // ✅ Java 9+ ifPresentOrElse for branch handling
    public UserResponse resolveUserResponse(Long id) {
        return userRepository.findById(id)
            .map(user -> UserResponse.found(user))
            .orElseGet(() -> UserResponse.notFound(id));
    }
}

// ✅ Class fields use @Nullable, not Optional
public class User {
    @Nullable
    private String middleName; // simple, serialisable, JPA‑compatible
}

Putting Optional on fields breaks Jackson serialization, JPA mapping, and equals/hashCode implementations.

Optional parameters make calling code ugly; @Nullable is cleaner and aligns with Java conventions.

Never call .get() directly – using it signals a non‑standard, unsafe practice.

Restricting Optional to return types makes API intent crystal clear.