Immutability in Java: Principles and Practice

Introduction

What is an immutable object

Why immutability matters

• Safe sharing: an immutable object can be passed to any method, stored in any collection and returned from any getter, with no risk that someone else changes it behind your back.
• Thread safety for free: immutable objects need no locks. Any number of threads can read them at the same time, because there are no writes to coordinate.
• Reliable map keys and set elements: a hash code that can never change means an object can never get "lost" inside a HashMap or HashSet.
• Easier reasoning: once an object is valid after construction, it stays valid. You check its rules once, in the constructor, rather than after every change.
• Caching and reuse: values can be cached and shared freely, as the JDK does for small Integer values and string literals.

Example - three immutability lessons in code

//ImmutabilityExample.java
import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Set;

public class ImmutabilityExample {

  // ---------- 1. A mutable object used as a set element ----------
  static class MutableEmployee {
    private String name;

    MutableEmployee(String name) { this.name = name; }
    void setName(String name) { this.name = name; }

    @Override
    public boolean equals(Object o) {
      return o instanceof MutableEmployee m && m.name.equals(name);
    }

    @Override
    public int hashCode() { return name.hashCode(); }
  }

  // ---------- 2. A record is only as immutable as its fields ----------
  record ShallowTeam(String name, List<String> members) {}

  record Team(String name, List<String> members) {
    Team {
      members = List.copyOf(members);   // defensive, unmodifiable copy
    }
  }

  // ---------- 3. "Changing" an immutable value returns a new one ----------
  record Employee(String name, double salary) {
    Employee withSalary(double newSalary) { return new Employee(name, newSalary); }
  }

  public static void main(String[] args) {
    Set<MutableEmployee> onPayroll = new HashSet<>();
    MutableEmployee tom = new MutableEmployee("Tom Jones");
    onPayroll.add(tom);
    tom.setName("Thomas Jones");                   // changes its hash code
    System.out.println("1. contains(tom) after rename : " + onPayroll.contains(tom));
    System.out.println("   size of the set            : " + onPayroll.size());

    List<String> names = new ArrayList<>(List.of("Tom Jones", "Harry Major"));
    ShallowTeam shallow = new ShallowTeam("Payroll", names);
    Team team = new Team("Payroll", names);
    names.add("Intruder");                         // the caller changes its own list
    System.out.println("2. shallow record members     : " + shallow.members());
    System.out.println("   defensive-copy members     : " + team.members());
    try {
      team.members().add("Intruder");
    } catch (UnsupportedOperationException e) {
      System.out.println("   team.members().add(...)    : UnsupportedOperationException");
    }

    Employee nancy = new Employee("Nancy Smith", 5200);
    Employee raised = nancy.withSalary(5600);
    System.out.println("3. original : " + nancy);
    System.out.println("   raised   : " + raised);
  }
}

1. contains(tom) after rename : false
   size of the set            : 1
2. shallow record members     : [Tom Jones, Harry Major, Intruder]
   defensive-copy members     : [Tom Jones, Harry Major]
   team.members().add(...)    : UnsupportedOperationException
3. original : Employee[name=Nancy Smith, salary=5200.0]
   raised   : Employee[name=Nancy Smith, salary=5600.0]

Explanation of the code

• Lesson 1: HashSet files each element under its hash code when it is added. Renaming tom changed his hash code, so the set now looks in the wrong place and reports that he is not there - although the set still has one element. The object is in the set but cannot be found or removed. The equals and hashCode contractClick to read: equals and hashCode contract assumes the fields they use do not change while the object is in a collection.
• Lesson 2: record fields are final, but final only stops the reference from changing. ShallowTeam stores the caller's own ArrayList, so when the caller added "Intruder" to its list, the team changed too.
• Team fixes this in its compact constructor with List.copyOf(), which makes an unmodifiable copy. Later changes to the caller's list do not reach it, and the list it hands out cannot be modified.
• Lesson 3: withSalary() returns a new Employee, and nancy is unchanged. Code that still holds the original sees the original - which is exactly what you want for an audit trail, an undo history, or a report that is being generated while salaries are updated.

Rules for writing an immutable class

1. Do not provide methods that modify state - no setters, and no other methods that change fields.
2. Make sure the class cannot be extended - declare it final, or make its constructors private and use static factory methods, so a subclass cannot add mutable state or override behaviour.
3. Make all fields final - the compiler then checks that each is assigned exactly once.
4. Make all fields private - so no one can reach a mutable field directly.
5. Ensure exclusive access to mutable components - if a field refers to a mutable object, such as a list, an array or a Date, make a defensive copy when it comes in through the constructor, and never return the original from a getter.

Records make it easier, not automatic

List<String> source = new ArrayList<>(List.of("Tom Jones"));

List<String> view = Collections.unmodifiableList(source); // a read-only VIEW of source
List<String> copy = List.copyOf(source);                  // an independent unmodifiable copy
List<String> literal = List.of("Tom Jones");              // unmodifiable from the start

source.add("Harry Major");
// view    -> [Tom Jones, Harry Major]   the view shows the change
// copy    -> [Tom Jones]
// literal -> [Tom Jones]

The costs, and when to stay mutable

• More objects: every change allocates a new object. For most business objects this is cheap - the JVM is very good at short-lived objects - but in a tight loop building a large string or collection, use a mutable builder such as StringBuilder, then produce the immutable result at the end.
• Many fields: an immutable object with ten fields needs a long constructor. The Builder patternClick to read: Builder pattern or a set of with methods keeps creation readable.
• Frameworks: some frameworks, such as JPA, expect entity classes with a no-argument constructor and settable fields. Keep entities mutable, and use immutable objects for values inside them and for the data you pass between layers.
• Objects that model change: something that really is a changing thing - a shopping cart being filled, a game board - can be mutable, as long as the mutation is kept inside one object that guards its own rules.

Summary