Immutable objects

Written Explanation

What immutable means

An object is immutable when its state cannot change after construction. The Java tutorial on concurrency gives a short recipe for building one. In our own words and order:

1. No setters. Provide no method that changes a field, or an object a field refers to. A method that would "change" the value returns a new object instead.
2. All fields private and final. private keeps outsiders away from them; final means a field can be assigned exactly once, in the constructor, and never again.
3. The class cannot be subclassed. Declare the class final so that nobody creates a subclass that adds changing behavior. (The tutorial mentions a private constructor with factory methods as a more flexible alternative.)
4. Protect mutable references. If a field refers to a mutable object, never share that reference: copy it when it comes in, and return a copy when it goes out.

Each ingredient plugs one hole. Items 1 and 2 stop direct changes, item 3 stops changes by inheritance, and item 4 stops changes through a shared reference. We will see item 4 fail, then work.

The final keyword on fields

A final field is assigned once. The compiler enforces it:

final class Point {
    private final int x;
    private final int y;

    Point(int x, int y) { this.x = x; this.y = y; }

    void broken() {
        x = 5;   // attempt to change a final field
    }
}

Main.java:10: error: cannot assign a value to final variable x
        x = 5;
        ^
1 error

That is a compile-time guarantee, the same kind you got from private in lesson 1.

Methods that "change" return a new object

If a Point cannot move, how do you get a moved point? You build another one:

Point moveRight(int dx) { return new Point(x + dx, y); }

The original Point is untouched. Strings work exactly like that: "abc".toUpperCase() leaves "abc" as it was. Creating small new objects is cheap in Java, and the safety is worth it for small value types like money or coordinates.

Why final is not enough: the mutable field trap

final fixes the reference, not the thing referred to. A final array field always points to the same array, but the contents of that array can change.

Look at a Team class that looks immutable but is not:

class Team {
    private final String[] members;

    Team(String[] members) {
        this.members = members;          // keeps the caller's array
    }

    String[] members() {
        return members;                  // hands out the live array
    }
}

There are two leaks:

String[] names = {"Ana", "Omar"};
Team t = new Team(names);
names[0] = "HACKED";            // leak 1: the caller still holds the same array
t.members()[1] = "ALSO HACKED"; // leak 2: the getter handed out the same array
System.out.println(t);

[HACKED, ALSO HACKED]

(System.out.println(t) printed the array contents because Team defines a toString method that formats the array. The mechanism is taught in the module on the Object class; ignore it for now.)

Both lines change the "private" state from outside. Private and final did not help, because the same array object is shared between the caller and the team.

Defensive copies

The cure is a defensive copy: never store, or hand out, a reference to something the outside can still change.

this.members = members.clone();   // copy in: the caller's array is now independent
return members.clone();           // copy out: the caller gets their own copy

For arrays, clone() creates a new array of the same size with the same elements. The Java Language Specification says an array's clone is public and returns the array's own type, and that it makes a shallow copy: the new array holds the same element references. This matters for what you copy:

• An array of immutable elements, such as String[] or int[], is safe after one clone(). Nobody can change the elements themselves.
• An array of mutable objects needs each element copied too, or the elements stay shared.

The same ideas hold for collections like List, which a later module teaches. Preview only: List.copyOf(list) makes an unmodifiable copy for you, and the API says that later changes to the original list do not affect the copy. Do not try it yet unless you have met List.

Benefits and costs

Benefits.

• Safe to share. Pass an immutable object anywhere; no one can change it under you.
• Easy to reason about. The value you see at construction is the value forever.
• Invariants checked once. If the constructor validates, the object stays valid.

Cost. Every "change" creates a new object. For small values this is cheap. For a large structure that changes thousands of times a second, immutability may not fit. A mutable class with strong encapsulation (like your Account) is also perfectly valid: things that have an identity and a life, such as an account or an order, usually change, whereas pure values, such as an amount or a date, usually do not.

Value or entity?

A helpful question: is this thing defined by what it is or by which one it is? Ten dollars is ten dollars; any ten-dollar note is as good as another, so Money should be an immutable value. Sara's account is this particular account whose balance changes over time, so Account is a changeable entity. Value types are the natural candidates for immutability.