Encapsulation & Immutability

Description

Encapsulation means an object owns its data and is the only one allowed to change it, so the rules about that data can't be broken from outside. Immutability is its strongest form: an object that never changes after it's built. Together they're what make objects trustworthy - safe to pass around, to share between threads and to use as map keys. This skill covers both, in Java and Python.

Here's what goes wrong without them:

class BankAccount {
    public double balance;
    public List<String> history = new ArrayList<>();
}

account.balance = -5000;          // nothing stops this
account.history.clear();          // or this

class BankAccount:
    def __init__(self):
        self.balance = 0.0
        self.history = []


account.balance = -5000          # nothing stops this
account.history.clear()          # or this

With public fields, every piece of code in the system can break the account's rules. When a balance goes negative, you have to search the whole codebase to find out who did it.

We'll go from simple to more technical:

1. The idea: invariants, and methods that protect them.
2. Immutability: what makes a class immutable in each language.
3. How to apply it, step by step.
4. Where you'll see it - and the leaks that quietly undo it.

The idea

Encapsulation means an object owns its data and only lets the outside world change it through methods that keep its invariants - the rules that must always be true (a balance never below the overdraft limit, a date range whose start is before its end).

final class BankAccount {
    private long balanceCents;
    private final List<String> history = new ArrayList<>();

    void deposit(long cents) {
        if (cents <= 0) throw new IllegalArgumentException("deposit must be positive");
        balanceCents += cents;
        history.add("deposit " + cents);
    }

    void withdraw(long cents) {
        if (cents <= 0) throw new IllegalArgumentException("withdrawal must be positive");
        if (cents > balanceCents) throw new IllegalStateException("insufficient funds");
        balanceCents -= cents;
        history.add("withdraw " + cents);
    }

    long balance() { return balanceCents; }
    List<String> history() { return List.copyOf(history); }   // a copy, not the real list
}

class BankAccount:
    def __init__(self):
        self._balance_cents = 0              # "_": internal by convention - Python has no private
        self._history = []

    def deposit(self, cents: int) -> None:
        if cents <= 0:
            raise ValueError("deposit must be positive")
        self._balance_cents += cents
        self._history.append(f"deposit {cents}")

    def withdraw(self, cents: int) -> None:
        if cents <= 0:
            raise ValueError("withdrawal must be positive")
        if cents > self._balance_cents:
            raise RuntimeError("insufficient funds")
        self._balance_cents -= cents
        self._history.append(f"withdraw {cents}")

    @property
    def balance(self) -> int:                # read-only: `account.balance = 5` raises AttributeError
        return self._balance_cents

    def history(self) -> tuple[str, ...]:
        return tuple(self._history)          # a snapshot, not the real list

Every change to the balance goes through one place, so the rules can't be bypassed.

Immutability

The strongest form of encapsulation is an object that never changes after construction. To make a class immutable:

1. Make the class final (so no subclass can add mutable state).
2. Make every field private final.
3. Don't provide setters; "changing" it returns a new object.
4. Defensively copy mutable inputs and outputs (lists, arrays, dates).

Python has no final or private, so immutability is assembled from other parts: a frozen dataclass (or __slots__ plus read-only properties), tuples and frozenset in place of lists and sets, and the same defensive copies. A frozen dataclass that holds a list is still mutable through that list.

record Money(long cents, String currency) {
    Money {
        if (currency == null || currency.isBlank()) throw new IllegalArgumentException("currency required");
    }
    Money plus(Money other) {
        if (!currency.equals(other.currency)) throw new IllegalArgumentException("currency mismatch");
        return new Money(cents + other.cents, currency);   // new object; this one never changes
    }
}

from dataclasses import dataclass


@dataclass(frozen=True)
class Money:
    cents: int
    currency: str

    def __post_init__(self):
        if not self.currency or self.currency.isspace():
            raise ValueError("currency required")

    def plus(self, other: "Money") -> "Money":
        if self.currency != other.currency:
            raise ValueError("currency mismatch")
        return Money(self.cents + other.cents, self.currency)   # new object; this one never changes

Java records give you the final fields, constructor, accessors, equals and hashCode for free. Python's @dataclass(frozen=True) does the same - __init__, __eq__, __hash__ and a readable repr - and assigning to a field raises FrozenInstanceError.

How to apply it, step by step

1. Start every field as private (and final if it never needs to change).
2. Replace setters with meaningful operations: deposit(), rename(), markShipped().
3. Validate in the constructor and in every operation, so an invalid object can never exist.
4. Never hand out a reference to a mutable internal collection - return a copy or an unmodifiable view.
5. For small "value" types (money, dates, coordinates), make them immutable.

Where you'll see it

• String, Integer, LocalDate, BigDecimal - all immutable, which is why they're safe to share and to use as map keys. (Python: str, int, tuple, frozenset, datetime.date, Decimal.)
• List.of(...), Map.of(...) and List.copyOf(...) create unmodifiable collections.
• Domain-driven design calls immutable, value-compared types value objects.

Which tool for which job?

Common mistakes

Check yourself

Try to answer before opening each one - recalling beats re-reading.

1. A getter returns this.items (an ArrayList). What can a caller do that you didn't intend?

2. What four things make a Java class immutable?

3. Why are immutable objects safe to use as HashMap keys?

Key takeaways

• Encapsulation = the object protects its own invariants; nobody else can break them.
• Replace setters with meaningful, validating operations.
• Never leak or store references to mutable internals - copy them.
• Immutable value objects (final, private final, no setters, records) are safe to share and to hash.