Null and Optional

You call user.getAddress().getCity().toUpperCase() and the program crashes with a NullPointerException. Which of the three calls returned null? The message may tell you, and the code does not. Nothing in the type of getAddress() warned that the result might be missing.

This is the most common runtime error in Java, and it comes from a design choice: any reference variable can be null, and the compiler does not track where. Tony Hoare, who introduced null references into a language in 1965, later called it his "billion-dollar mistake". This article explains why null is a problem, what to do about it in general, and how Optional helps in one specific, useful role.

• Why null is ambiguous and hard to reason about.
• General habits that reduce null problems with or without Optional.
• What Optional is, and what it is designed for.
• The operations that make Optional useful: map, flatMap, filter and the or... family.
• The common misuses, and when not to use it.

null is a reference that points to nothing. Calling a method on it throws NullPointerException (NPE). The deeper problem is meaning. When a method returns null, does that mean "not found", "not applicable", "an error occurred", "not yet loaded", or "the programmer forgot to set it"? Different callers read it differently, so every caller must remember to check, and one missing check is a crash.

// File: Main.javapublic class Main {    static class Address {        private final String city;        Address(String city) {            this.city = city;        }        String city() {            return city;        }    }    static class User {        private final String name;        private final Address address;      // may be null        User(String name, Address address) {            this.name = name;            this.address = address;        }        Address address() {            return address;        }    }    static String cityOf(User user) {        return user.address().city().toUpperCase();    }    static String cityOfSafely(User user) {          // the defensive version: a pyramid of checks        if (user != null) {            Address address = user.address();            if (address != null) {                String city = address.city();                if (city != null) {                    return city.toUpperCase();                }            }        }        return "UNKNOWN";    }    public static void main(String[] args) {        User asha = new User("Asha", new Address("Pune"));        User ravi = new User("Ravi", null);        System.out.println(cityOf(asha));        System.out.println(cityOfSafely(ravi));        System.out.println(cityOf(ravi));    }}

PUNEUNKNOWNException in thread "main" java.lang.NullPointerException: Cannot invoke "Main$Address.city()" because the return value of "Main$User.address()" is null

The first call works. The defensive version works but is a pyramid of checks that obscures the actual logic. The last call crashes. Since Java 14, the NPE message says exactly what was null (here, the result of the address() call). Helpful, but it still happens at runtime, in production, after the fact.

Before reaching for a new class, apply the basics:

1. Do not return null for collections. Return an empty list, set or map. Callers can then loop without a check.
2. Fail fast on required arguments. Objects.requireNonNull(value, "value must not be null") at the top of a method or constructor turns a distant crash into an immediate, explained one.
3. Initialise fields. A field that is never null (an empty list, an empty string, a default) removes a whole class of checks.
4. Make "absence" a deliberate part of the design. Decide for each value whether it can legitimately be missing, and document and model that.
5. Prefer values that cannot be null (records with validated constructors, enums, sealed types).
6. Do not use null to signal errors. Throw an exception, or return a result type (article 10).

A third-party approach is to annotate parameters and returns with @Nullable or @NonNull and let tools check them. Those annotations are not part of the standard library, and they are used by many frameworks, including Spring, but they are conventions and not a language feature.

Optional<T> (Java 8) is a container that either holds one non-null value or is empty. The Javadoc describes it as a container object which may or may not contain a non-null value, and gives its purpose precisely: it is primarily intended for use as a method return type where there is a clear need to represent "no result", and where using null is likely to cause errors. A variable of type Optional should never itself be null.

Return type Optional<User> tells every caller, in the signature, "this may find nothing". The compiler cannot force you to handle the empty case, but the API makes it hard to forget.

The aim is to avoid unwrapping manually. These methods let you describe what to do with the value, whether or not it is there.

// File: Main.javaimport java.util.List;import java.util.NoSuchElementException;import java.util.Optional;public class Main {    record Address(String city) {}    record User(String name, Address address, String email) {        Optional<Address> findAddress() {            return Optional.ofNullable(address);        }        Optional<String> findEmail() {            return Optional.ofNullable(email);        }    }    static Optional<User> findUser(List<User> users, String name) {        return users.stream().filter(u -> u.name().equals(name)).findFirst();    }    public static void main(String[] args) {        List<User> users = List.of(                new User("Asha", new Address("Pune"), "asha@example.com"),                new User("Ravi", null, null));        // map: transform the value if present; flatMap: when the function itself returns an Optional        String city = findUser(users, "Asha")                .flatMap(User::findAddress)                .map(Address::city)                .map(String::toUpperCase)                .orElse("UNKNOWN");        String missing = findUser(users, "Ravi")                .flatMap(User::findAddress)                .map(Address::city)                .orElse("UNKNOWN");        String nobody = findUser(users, "Zed")                .flatMap(User::findAddress)                .map(Address::city)                .orElse("UNKNOWN");        System.out.println(city + " " + missing + " " + nobody);        // filter: keep the value only if it satisfies a condition        System.out.println(findUser(users, "Asha").flatMap(User::findEmail).filter(e -> e.endsWith("@example.com")).isPresent());        // ifPresent / ifPresentOrElse: perform an action        findUser(users, "Ravi").flatMap(User::findEmail).ifPresentOrElse(                e -> System.out.println("email: " + e),                () -> System.out.println("no email on file"));        // orElseThrow: absence is an error here        try {            findUser(users, "Zed").orElseThrow(() -> new IllegalArgumentException("no such user: Zed"));        } catch (IllegalArgumentException e) {            System.out.println(e.getMessage());        }        try {            findUser(users, "Zed").orElseThrow();            // no-argument form: NoSuchElementException        } catch (NoSuchElementException e) {            System.out.println("NoSuchElementException: " + e.getMessage());        }        // or: an alternative Optional; stream: zero or one element in a stream        System.out.println(findUser(users, "Zed").or(() -> findUser(users, "Ravi")).map(User::name).orElse("?"));        System.out.println(users.stream().map(User::findEmail).flatMap(Optional::stream).toList());    }}

PUNE UNKNOWN UNKNOWNtrueno email on fileno such user: ZedNoSuchElementException: No value presentRavi[asha@example.com]

Compare this with the pyramid of null checks. The chain flatMap(...).map(...).map(...).orElse("UNKNOWN") describes the happy path once, and the empty case flows through to the end without any if. The important distinction between the two transforming methods:

• map(f) applies f to the value and wraps the result. If f returns null, you get an empty Optional.
• flatMap(f) is for functions that already return an Optional. It avoids ending up with an Optional<Optional<T>>.

The terminal operations, from safest to least safe:

This difference is a classic interview question and a real source of bugs. orElse(x) takes a value, so the expression for x is always evaluated, even when the Optional has a value. orElseGet(supplier) takes a function and only calls it when needed.

// File: Main.javaimport java.util.Optional;public class Main {    static int expensiveCalls = 0;    static String loadDefault() {        expensiveCalls++;        return "default";    }    public static void main(String[] args) {        Optional<String> present = Optional.of("value");        String a = present.orElse(loadDefault());              // loadDefault() runs even though not needed        System.out.println(a + " calls=" + expensiveCalls);        String b = present.orElseGet(() -> loadDefault());     // not called: the value is present        System.out.println(b + " calls=" + expensiveCalls);        String c = Optional.<String>empty().orElseGet(() -> loadDefault());        System.out.println(c + " calls=" + expensiveCalls);    }}

value calls=1value calls=1default calls=2

Use orElse for a cheap constant (orElse("UNKNOWN")) and orElseGet whenever computing the fallback costs something or has a side effect (a database call, a log entry, creating an object).

You have already seen Optional from stream terminal operations: findFirst, findAny, min and max return one. Optional::stream (Java 9) turns an Optional into a stream of zero or one elements, which lets flatMap(Optional::stream) skip the empty ones, as in the last line of the example. Numeric streams have their own OptionalInt, OptionalLong and OptionalDouble, such as the result of average().

Optional is often overused, which creates noise without benefit. Avoid these:

Here is a short before and after:

// File: Main.javaimport java.util.List;import java.util.Optional;public class Main {    record Product(String name, Double discount) {}    // Misuse: isPresent + get, and the fallback is computed eagerly    static double finalPriceBad(Product p, double price) {        Optional<Double> discount = Optional.ofNullable(p.discount());        if (discount.isPresent()) {            return price - discount.get();        }        return price;    }    // Better: describe the transformation    static double finalPrice(Product p, double price) {        return Optional.ofNullable(p.discount()).map(d -> price - d).orElse(price);    }    // Collections: never null, never Optional    static List<String> tagsFor(String productName) {        return productName.equals("pen") ? List.of("stationery", "office") : List.of();    }    public static void main(String[] args) {        Product pen = new Product("pen", 2.0);        Product book = new Product("book", null);        System.out.println(finalPriceBad(pen, 10) + " " + finalPriceBad(book, 10));        System.out.println(finalPrice(pen, 10) + " " + finalPrice(book, 10));        for (String tag : tagsFor("unknown product")) {      // safe: an empty list simply loops zero times            System.out.println(tag);        }        System.out.println(tagsFor("pen"));    }}

8.0 10.08.0 10.0[stationery, office]

It is tempting to conclude that null is banned and Optional is the fix for everything. The Javadoc says otherwise: it is for return values with a clear need to represent "no result". A balanced approach:

• Return values that may be absent: Optional<T>. This is the main use (a lookup by id, a search, a first match).
• Fields and parameters: allow null internally where you must, validate with Objects.requireNonNull where you must not, and keep the nullability out of your public API where you can.
• Collections and arrays: empty, never null.
• Alternatives that fit better: a default value, an exception for "must exist", a sealed result type (a record Found and a record NotFound, as in article 9) when the reason for absence matters.
• Boundaries: values arriving from a database, JSON or a library can be null. Convert them at the boundary (Optional.ofNullable, or a default) so that the interior of your code deals with clean values.

In the Job Application Tracker project, repository methods such as findById return Optional<JobApplication>, and the service turns an empty result into a NotFound exception in one place (article 33).

• Using Optional for fields or parameters.
• Calling get() without a check.
• Writing isPresent() then get() where map or ifPresent is clearer.
• Using orElse with an expensive or side-effecting call.
• Returning null from a method whose type is Optional.
• Using Optional.of with a value that can be null.
• Wrapping collections in Optional.
• Treating Optional as a substitute for validation.

String zip = Optional.ofNullable(user)        .map(User::getAddress)        .map(Address::getZipCode)        .map(String::trim)        .orElse("none");

• Next: How the JVM Runs Your Code: Memory, GC and JIT begins the JVM and concurrency module.
• For Optional in repositories: Building a REST API with Spring Boot.
• For the interview version: Interview Concepts, Part 1.