Lesson 4. null and Where It Comes From

Mission link: A NullPointerException in production tells you where the program noticed, not where the null came from. Closing the distance between those two is a design skill, and it starts with knowing which constructs produce null at all.
Primary source: The Java Language Specification, 4.12.5 Initial Values of Variables
Prerequisites: Lesson 1, Lesson 3

Warm-up

1. ▢ What must be true of a field that hashCode reads, if the object is going to be a map key?

2. ▢ Which fails first when name is null: name.equals("x") or "x".equals(name)?

Know this

null is a reference value that refers to no object. It has its own type, the null type, which has no name and is assignable to every reference type. It is not an object, so it has no methods, and it is not zero, so it is not a number.

Three sources put null into a program:

1. Defaults. Every field and array element of a reference type starts as null, before any constructor body runs.
2. Returns. A method that has nothing to return and no better answer returns null. Map.get on a missing key is the most-called example in the language.
3. Inputs. Callers pass it, deserialisation produces it, and a database column allows it.

What actually throws

A NullPointerException comes from using a null reference, which means one of:

name.length();          // calling a method
config.retries;         // reading or writing a field
array[0];               // indexing, or reading array.length
throw problem;          // throwing it
int n = boxedInteger;   // unboxing, which is a hidden method call
for (String s : list)   // iterating, which calls iterator()

The unboxing case is worth its own look, because nothing in the line mentions a method:

Map<String, Integer> counts = new HashMap<>();
int n = counts.get("missing");      // NullPointerException, not 0

get returned null, and the assignment to int had to call intValue() on it. Use counts.getOrDefault("missing", 0) when zero is the right answer.

Since JDK 15, the message names the expression that was null, which turns most of these from a hunt into a read. That is JEP 358, and it is on by default.

Two things that do not throw: "" + name produces the string "null" when name is null, and System.out.println(name) prints those same four characters. That is how null ends up written to logs and stored in databases as text.

A curiosity worth knowing because it confuses people once: the literal System.out.println(null) does not compile at all, since the compiler cannot choose between the String and char[] overloads. A null-valued variable is unambiguous, which is why the version above is fine.

null and the collections

The rules differ per implementation, and they are not arbitrary:

The immutable factories reject null deliberately, so List.of(a, b) throws immediately if either is null rather than storing a hole for someone to trip on later. Treat that as guidance rather than an inconvenience.

Rejecting instead of checking

Scattering if (x != null) through a codebase treats null as a value with meaning. The alternative is to decide, once, where a null is allowed and to stop it there:

public Order(String id, List<Item> items) {
    this.id = Objects.requireNonNull(id, "id");
    this.items = List.copyOf(items);       // throws on null, and on null elements
}

requireNonNull throws at the boundary, with the parameter name, before the object exists in an invalid state. List.copyOf does the same for a collection and gives you an unmodifiable copy, which also settles lesson 1's question about whether the caller can still mutate it.

Three habits that follow, all of them cheap:

• Never return null for a collection. Return List.of(). Callers can iterate it without a guard, and an empty list means exactly what a caller wants to know.
• Validate at the edge, meaning constructors, public entry points and deserialisation, and trust the interior.
• Say so in the signature's documentation when null is genuinely permitted, because otherwise every reader has to guess.

Stage 3 adds Optional, which is the right tool for "this method may have no answer". It is not a replacement for the three habits above, and using it as a field type or a parameter type is a known mistake this workspace will come back to.

Practice

1. ▢ Which line throws, and what is the exception?

   Map<String, Integer> counts = new HashMap<>();
   Integer a = counts.get("missing");
   int b = counts.get("missing");
   System.out.println(a);
   

2. ▢ For each, say whether it throws, and when.

   List<String> a = new ArrayList<>();  a.add(null);
   List<String> b = List.of("x", null);
   Map<String, String> c = new HashMap<>();  c.put(null, "v");
   Map<String, String> d = Map.of("k", null);
   

3. ▢ A method returns null when it finds no matching users. Rewrite the contract, and say what the caller stops having to write.

   List<User> findByTenant(String tenant);   // returns null when none found
   

4. ▢ Where should this validation go, and which spelling would you use?

   class Report {
       private final String title;
       private final List<Row> rows;
       Report(String title, List<Row> rows) { this.title = title; this.rows = rows; }
   }
   

Report(String title, List<Row> rows) {
    this.title = Objects.requireNonNull(title, "title");
    this.rows = List.copyOf(rows);
}

5. ▢ A log line reads user=null tenant=acme. The field is a String. Name two different things that could have produced that text.

Real-world reps

• [ ] Trigger the unboxing NullPointerException from practice 1 and read the message. Note that it names the expression, which is what makes JDK 15 and later much less painful than what came before.
• [ ] Take one constructor in code you know and add Objects.requireNonNull to each reference parameter. Run the tests. Anything that now fails was passing null and getting away with it.
• [ ] Tomorrow: find a method that returns null for "nothing found". Count the call sites that guard for it, and the ones that do not.

Going further

• JLS 4.12.5, Initial Values of Variables: why a field is null before any code runs
• Objects: requireNonNull, requireNonNullElse, and the null-safe helpers
• List: what of and copyOf guarantee, including their treatment of null
• JEP index: JEP 358 is the helpful NullPointerException messages
• Resources

Not landing? Reread the primary source at the top, since this lesson compresses it and compression is where understanding leaks. Check the glossary for any term that felt slippery.

If the lesson itself is unclear rather than the material, that is a defect: open an issue.