Java Immutability

Java Immutability

Purpose

Make objects that cannot change after construction actually unable to change — and know when not to bother. Two failure modes to prevent: the shallowly immutable object (final fields, mutable contents) that changes under a caller who believed it could not; and dogmatic immutability forced onto hot paths, entity frameworks and accumulators, where it fights the tools without a measurement to justify it.

Workflow

0. Inspect the compatibility and ownership contract. Check compiler release/toolchains, framework/binder versions, equality/hash behavior, null/order requirements and who can mutate each input. Examples use Java 17-compatible features: records and type-pattern instanceof need Java 16+ without preview, copyOf needs Java 10+, and Stream.toList() needs Java 16+. Keep the project baseline; use ordinary classes/private-copy wrappers on older targets.
1. Classify every field or record component. Primitive and known deeply immutable values are safe. Collections, arrays, legacy dates, buffers and custom types require proof of both container and element immutability; “no setters” is not proof.
2. Close the inbound route. Copy in the constructor: List.copyOf, Map.copyOf, Set.copyOf, clone() for arrays. These are shallow copies; mutable elements/keys/values need their own immutable representation or deep-copy policy.
3. Close the outbound route. Accessors can return deeply immutable values directly. Owned mutable representations still need isolation on output: arrays, dates and buffers need defensive access even after an inbound copy. An unmodifiable container does not protect mutable elements.
4. Check publication. Fields final, this not escaping the constructor. Final-field initialization safety protects observed constructed state, but a happens-before publication mechanism is still preferable for reference visibility, lifecycle and later mutable state.
5. Verify with a hostile test. Mutate the constructor container and a nested mutable element after construction; attempt mutation through each accessor; publish across threads using the intended handoff. The documented state must remain unchanged and visible.

Rules

• A record guarantees final component references, not immutable referents. A mutable input must be isolated by copying or a proven ownership transfer; already immutable values can be reused. Check the reachable state, not merely whether the component type is List or Map.
• Never ship a record with an array component and generated equals/hashCode — arrays compare by identity, so two records with equal contents are not equal. Copy in and out and override both, or use a List instead.
• Prefer List.copyOf when its null contract fits. An unmodifiable wrapper around a privately owned copy is also a valid snapshot; a wrapper around aliased mutable backing is a live view requiring a documented concurrency/lifecycle protocol. copyOf remains shallow; never call re-copying “free” without measuring a material path.
• Evolve immutable state with hand-written withX methods that return a new instance. Java has no wither syntax and records have no generated with — do not claim or wait for one.
• Do not assert or deny an allocation cost without a measurement. Escape analysis may eliminate an allocation; it never guarantees it.
• State what immutability includes: object fields only, reachable graph, external resources, and cached/derived state. An immutable wrapper around a mutable entity/client/file is not deeply immutable merely because its reference is final.
• Copying is not an atomic snapshot of concurrently changing input. Require confinement, synchronization or a collection-specific snapshot contract before copying; final fields cannot repair a mixed or raced constructor read. Preserve null acceptance, iteration order and equality when replacing an API, or explicitly identify the contract change.

Deliverable

Name the immutability boundary and remaining aliases, construction/access strategy and any API behavior changed. Report mutation tests and the happens-before argument for the actual handoff; a passing thread test alone does not prove JMM correctness. Keep allocation benefits and framework round-trip safety conditional until measured or exercised.

References

• Records and defensive copies — read when writing or reviewing a record, a constructor/accessor pair, or a wither; includes the worked example and the false positives (builders, cached derived fields).
• Safe publication and the JMM — read when the object crosses threads, when a field cannot be final, or when reviewing lazy caching of a derived value.
• Costs and when not to apply — read before making an existing mutable class immutable, and whenever performance is the argument for or against immutability.