Immutable value boundaries: protect the edges

Trace shallow read-only fields and choose defensive-copy or immutable-view policies for nested mutable state. Relationships and copying · Object-oriented programming.

You hand a courier a list of delivery tags to attach to a parcel. Later you add one more tag to your own list, and the parcel's tags change too, though nobody touched the parcel. Marking a field read-only is not enough to stop that. What matters is who still holds an arrow into the list behind the field.

A fixed field can still reach a growing list

Start with a Parcel that holds a tracking code and a list of tags. Java records and Python's @dataclass(frozen=True) fix the field itself: after construction the field cannot be pointed at another list. They say nothing about the list it already points at, which is a separate object with its own add or append.

The Python run below confirms both halves. Assigning a new list is refused, but appending to the old one works, and the caller's own variable sees the item too because it holds an arrow into the same list.

from dataclasses import dataclass, FrozenInstanceError

@dataclass(frozen=True)
class Parcel:
    code: str
    tags: list

tags = ["new"]
parcel = Parcel("P-17", tags)
parcel.tags.append("fragile")
print(parcel.tags, tags)   # ['new', 'fragile'] ['new', 'fragile']
try:
    parcel.tags = []
except FrozenInstanceError as e:
    print(type(e).__name__)  # FrozenInstanceError

record Parcel(String code, java.util.List<String> tags) {}

var input = new java.util.ArrayList<>(java.util.List.of("new"));
var parcel = new Parcel("P-17", input);
parcel.tags().add("fragile");
System.out.println(parcel.tags() + " " + input); // [new, fragile] [new, fragile]

Copy on the way in

The construction boundary is where the value decides whether to keep the caller's list or make its own. A record's generated constructor keeps the caller's list as it is. So when the caller adds an item afterward, the parcel changes with no method call on the parcel at all. That breaks encapsulation, and it can also change what the parcel equals or hashes to once it is a map key.

The fix is one line in the constructor: store a copy. In Java, List.copyOf builds a separate unmodifiable snapshot of the list. In Python, tuple(tags) builds a separate tuple, and a tuple has no append at all.

In both programs the caller's later item never reaches the safe parcel; the Java run also prints the unsafe Parcel for contrast. The copy covers the list the parcel owns. The scene also keeps a Meter the whole service counts into; that one is shared on purpose, so it is deliberately not copied.

record Parcel(String code, java.util.List<String> tags) {}
record SafeParcel(String code, java.util.List<String> tags) {
    SafeParcel { tags = java.util.List.copyOf(tags); }
}

var a = new java.util.ArrayList<>(java.util.List.of("new"));
var kept = new Parcel("P-17", a);
a.add("caller-only");
System.out.println(kept.tags()); // [new, caller-only]

var b = new java.util.ArrayList<>(java.util.List.of("new"));
var safe = new SafeParcel("P-17", b);
b.add("caller-only");
System.out.println(safe.tags() + " " + b); // [new] [new, caller-only]

from dataclasses import dataclass

@dataclass(frozen=True)
class SafeParcel:
    code: str
    tags: tuple

    @classmethod
    def from_tags(cls, code, tags):
        return cls(code, tuple(tags))

given = ["new"]
safe = SafeParcel.from_tags("P-17", given)
given.append("caller-only")
print(safe.tags, given)   # ('new',) ['new', 'caller-only']

A copy of the list is shallow about what the list holds. Strings cannot be edited in place, so sharing them is harmless. If the items were editable objects, every one would still be shared with the caller, and the copy would need to go one level deeper.

Choose what leaves the box

Construction is half the boundary. An accessor that returns the stored list reopens the same hole in the other direction: any caller can write into private state. A box has three honest things it can return.

A snapshot is a separate unmodifiable list, so later changes by the owner never reach it. A view is an unmodifiable wrapper that reads through to the owner's list: callers cannot write, but they see every later change. Returning the field itself lets callers write into private state and see every later change. "Snapshot" and "View" are role names for these two kinds of list, not Java class names.

The output below shows each choice after the owner adds late and a leaked reference adds injected.

import java.util.*;

final class ParcelBox {
    private final List<String> tags = new ArrayList<>(List.of("new"));
    List<String> snapshot() { return List.copyOf(tags); }
    List<String> view() { return Collections.unmodifiableList(tags); }
    List<String> field() { return tags; }
    void add(String tag) { tags.add(tag); }
}

var box = new ParcelBox();
var snap = box.snapshot();
var view = box.view();
box.add("late");
box.field().add("injected");
System.out.println(snap); // [new]
System.out.println(view); // [new, late, injected]
try {
    view.add("x"); // the view refuses every write
} catch (UnsupportedOperationException e) {
    System.out.println("refused"); // refused
}

class ParcelBox:
    def __init__(self):
        self._tags = ["new"]

    def snapshot(self):
        return tuple(self._tags)   # separate; later edits never reach it

    def field(self):
        return self._tags          # the box's own list

box = ParcelBox()
snap = box.snapshot()
box.field().append("late")
print(snap, box.field())   # ('new',) ['new', 'late']

Python's standard library has no read-only live view of a list, so a Python box chooses between a snapshot and the field itself.

Choose the boundary from what callers must not do

Ask what callers are forbidden to do, then pick the cheapest boundary that enforces it. If callers must not change the value, copy on the way in and return a snapshot or a view. If callers need to watch the owner's later changes, return a view. If the item is a shared resource such as a counter, a connection or a cache that the whole service uses, keep one shared copy and let the lifecycle owner manage it; duplicating it would make two meters that disagree. Do not freeze everything by habit, and do not copy a resource whose identity is the point.

Take a pricing table loaded once at startup and read by every request handler. The loader copies the rows in, so the file reader's buffer cannot rewrite them later. The table hands handlers a view or an immutable list, so one buggy handler cannot change the prices the next request sees. The database connection pool beside it is never copied: it is a shared resource, and handlers borrow it. Each choice costs a line of code at the boundary, and each one is made where the data crosses it.

Recap

• Final fields, records and frozen dataclasses fix which list a field points at, not what the list holds.
• Copy a mutable input in the constructor when the value must own stable state, and keep deliberately shared resources shared.
• Return a snapshot when callers should not see later changes, a view when they should, and never the field when they must not write.

Continue to shallow and deep copy when the required boundary is a mutable object graph. Practise encapsulated state in Linked List Fundamentals, where a link API must control which nodes callers can reach.