{"title":"Immutable Classes","description":"","content":"An immutable class is one whose instances can never change after construction. Once you build the object, the state is frozen for life. This lesson covers the full recipe for writing immutable classes in Java, the traps that break immutability even when the code looks correct, and when this property is worth the overhead. Encapsulation as a concept was introduced in the first lesson of this section, and the access modifiers used here (`private`, `final`) were covered in the data-hiding lesson, so we won't re-derive either.\n\n---\n\n# What \"Immutable\" Really Means\n\nA `Money` object that holds `49.99 USD` should be that exact value from the moment it's created until it's garbage-collected. No method should be able to change the amount. No method should be able to change the currency. Reassigning the variable to a new `Money` value is fine, but the original object stays untouched.\n\n\n```java\nMoney price = new Money(49.99, \"USD\");\nMoney discounted = price.minus(new Money(5.00, \"USD\"));\n\n// price still reads 49.99 USD\n// discounted reads 44.99 USD\n// neither object was mutated; the second is a brand-new instance\n```\n\n\nThat last line is the giveaway. With a mutable class, `price.subtract(5.00)` would reach inside the existing object and modify the field. With an immutable class, there is no such method. Operations that \"change\" the value return a new object instead, leaving the original alone.\n\nThe JDK is full of classes built this way. `String` is the canonical one. So are the wrapper types (`Integer`, `Long`, `Double`), the modern date-time types (`LocalDate`, `LocalDateTime`, `Instant`), and `BigDecimal`. Every method that looks like it modifies one of these actually returns a new instance.\n\n\n```java\npublic class StringIsImmutable {\n public static void main(String[] args) {\n String code = \"save10\";\n String upper = code.toUpperCase();\n\n System.out.println(\"code: \" + code);\n System.out.println(\"upper: \" + upper);\n }\n}\n```\n\n\nThe call `code.toUpperCase()` looks like it should change `code`. It doesn't. `String` returns a new `String` containing the upper-cased characters and leaves the original alone. If you discarded the return value, the operation would effectively do nothing visible. This is the signature behavior of an immutable type.\n\n\n```mermaid\nflowchart LR\n Var1[\"String code\"]:::cyan\n Obj1[\"'save10'
(immutable)\"]:::orange\n Var2[\"String upper\"]:::cyan\n Obj2[\"'SAVE10'
(immutable)\"]:::orange\n\n Var1 -->|points to| Obj1\n Var2 -->|points to| Obj2\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n```\n\n\nTwo variables, two distinct objects, no mutation. The original characters were never touched.\n\n---\n\n# The Immutability Recipe\n\nMaking a class immutable is a recipe, not a single keyword. Miss any step and the property breaks. The full list:\n\n1. Mark the class `final` so no subclass can add mutability.\n2. Make every instance field `private final`.\n3. Don't expose any setters or any other methods that change state.\n4. If the constructor accepts a mutable input (an array, a `Date`, a `List`, another mutable object), make a defensive copy and store the copy, not the original reference.\n5. If a getter would return a reference to a mutable field, return a defensive copy or an unmodifiable view, not the field itself.\n6. Initialize every field in the constructor. After the constructor returns, the object is fully built and frozen.\n\nThe first three steps are mechanical. The fourth and fifth are where most bugs hide, because the compiler can't help with them. Each is covered below.\n\n### Step 1: `final` Class\n\nA subclass can do anything its parent can do plus more. If `Money` is not `final`, someone can write `class MutableMoney extends Money` and add a setter that touches a `protected` field, or simply override methods to behave inconsistently. Marking the class `final` slams that door:\n\n\n```java\npublic final class Money {\n // ...\n}\n```\n\n\nIf your design needs an inheritance hierarchy, there's a softer alternative: make every public constructor private and force construction through a static factory method. That prevents external subclasses while keeping the door open for trusted subclasses within the same package. For a first pass, `final` is simpler and clearer.\n\n### Step 2: All Fields `private final`\n\n\n```java\npublic final class Money {\n private final double amount;\n private final String currency;\n // ...\n}\n```\n\n\n`private` keeps the fields invisible from outside. `final` makes them assign-once: the only place they can be written is in the constructor (or in an initializer that runs before the constructor finishes). Once the constructor returns, the field reference cannot be reseated.\n\n`final` on a reference field locks the reference, not the object the reference points to. This is why steps 4 and 5 exist. A `private final List items` field guarantees the variable always points at the same list, but it does nothing to stop someone from calling `list.add(...)` on that list. Immutability of the field and immutability of the object the field refers to are two different problems.\n\n### Step 3: No Setters, No Other Mutators\n\nThe class exposes getters (read-only access) and methods that return new instances. It exposes nothing that writes to state. This is the easy step to enforce because it's just discipline: don't write the method.\n\nA common temptation is to add a \"convenience\" setter \"just for tests.\" Don't. Tests can construct new objects. Mutating an immutable object is the bug this recipe prevents.\n\n### Step 4: Defensive Copies in the Constructor\n\nThe constructor accepts inputs from callers. If any input is mutable, storing the original reference means the caller still holds a path to mutate the field after construction.\n\n\n```java\nimport java.util.Date;\n\npublic final class OrderConfirmation {\n private final String orderId;\n private final Date placedAt;\n\n // WRONG: stores the caller's Date reference\n public OrderConfirmation(String orderId, Date placedAt) {\n this.orderId = orderId;\n this.placedAt = placedAt;\n }\n}\n```\n\n\nThe problem with that constructor:\n\n\n```java\nDate when = new Date();\nOrderConfirmation order = new OrderConfirmation(\"ORD-1001\", when);\nwhen.setTime(0L); // mutates the Date inside the OrderConfirmation\n```\n\n\nThe caller still owns the `Date` they passed in. They can change it from the outside, and the change shows up inside the `OrderConfirmation` instance. Fix this by copying on the way in:\n\n\n```java\nimport java.util.Date;\n\npublic final class OrderConfirmation {\n private final String orderId;\n private final Date placedAt;\n\n public OrderConfirmation(String orderId, Date placedAt) {\n this.orderId = orderId;\n this.placedAt = new Date(placedAt.getTime()); // defensive copy\n }\n}\n```\n\n\nNow `OrderConfirmation` holds its own private `Date`. Anything the caller does to their `Date` is irrelevant.\n\n`String` doesn't need this treatment because `String` is itself immutable. There's no way for the caller to mutate it later, so storing the original reference is safe. Defensive copying is only required for mutable inputs.\n\n### Step 5: Defensive Copies (or Unmodifiable Views) in Getters\n\nThis is the mirror image of step 4. If a getter returns a reference to a mutable internal field, the caller can mutate the field through that reference:\n\n\n```java\nimport java.util.Date;\n\npublic final class OrderConfirmation {\n private final String orderId;\n private final Date placedAt;\n\n public OrderConfirmation(String orderId, Date placedAt) {\n this.orderId = orderId;\n this.placedAt = new Date(placedAt.getTime());\n }\n\n public String getOrderId() {\n return orderId;\n }\n\n // WRONG: hands the caller a reference to our internal Date\n public Date getPlacedAt() {\n return placedAt;\n }\n}\n```\n\n\nAnd the exploit:\n\n\n```java\nOrderConfirmation order = new OrderConfirmation(\"ORD-1001\", new Date());\norder.getPlacedAt().setTime(0L); // mutates our internal Date\n```\n\n\nFix the getter the same way you fixed the constructor:\n\n\n```java\npublic Date getPlacedAt() {\n return new Date(placedAt.getTime()); // defensive copy\n}\n```\n\n\nFor collections, a second option avoids allocating a full copy: return an unmodifiable view.\n\n\n```java\nimport java.util.ArrayList;\nimport java.util.Collections;\nimport java.util.List;\n\npublic final class ShoppingCart {\n private final List items;\n\n public ShoppingCart(List items) {\n this.items = new ArrayList<>(items); // defensive copy on the way in\n }\n\n public List getItems() {\n return Collections.unmodifiableList(items); // unmodifiable view on the way out\n }\n}\n```\n\n\n`Collections.unmodifiableList(...)` wraps the list in a read-only facade. Any attempt to call `add`, `remove`, or `clear` on the returned list throws `UnsupportedOperationException`. The view doesn't copy the underlying data, so it's cheap. It also stays in sync with the underlying list, which is the desired behavior here because the underlying list itself never changes.\n\nDefensive copies allocate. For small fields (a `Date`, a short array) the cost is negligible. For large collections returned from a frequently called getter, an unmodifiable view is much cheaper than copying on every call.\n\n### Step 6: Initialize Everything in the Constructor\n\n`final` fields must be assigned exactly once before the constructor returns. There's no two-phase construction: no `init()` method that fills in fields later, no \"set this field after the fact.\" Everything an instance needs is supplied at construction time.\n\nThis is mostly a consequence of step 2. `private final` fields can't be reassigned later, so they have to be set during construction. The reason it's called out separately is that deferring initialization (\"I'll just leave this null and set it later\") immediately breaks the recipe.\n\n---\n\n# Putting the Recipe Together: A `Money` Class\n\nA complete immutable `Money` class that follows every step. Currency is a `String` (immutable, no defensive copy needed). Amount is a `double` (a primitive, no copying possible or needed).\n\n\n```java\npublic final class Money {\n private final double amount;\n private final String currency;\n\n public Money(double amount, String currency) {\n if (amount < 0) {\n throw new IllegalArgumentException(\"amount cannot be negative\");\n }\n if (currency == null || currency.length() != 3) {\n throw new IllegalArgumentException(\"currency must be a 3-letter code\");\n }\n this.amount = amount;\n this.currency = currency;\n }\n\n public double getAmount() {\n return amount;\n }\n\n public String getCurrency() {\n return currency;\n }\n\n public Money plus(Money other) {\n if (!this.currency.equals(other.currency)) {\n throw new IllegalArgumentException(\"currency mismatch\");\n }\n return new Money(this.amount + other.amount, this.currency);\n }\n\n public Money minus(Money other) {\n if (!this.currency.equals(other.currency)) {\n throw new IllegalArgumentException(\"currency mismatch\");\n }\n return new Money(this.amount - other.amount, this.currency);\n }\n\n @Override\n public String toString() {\n return amount + \" \" + currency;\n }\n}\n\npublic class MoneyDemo {\n public static void main(String[] args) {\n Money price = new Money(49.99, \"USD\");\n Money couponValue = new Money(5.00, \"USD\");\n Money finalPrice = price.minus(couponValue);\n\n System.out.println(\"price: \" + price);\n System.out.println(\"coupon: \" + couponValue);\n System.out.println(\"finalPrice: \" + finalPrice);\n }\n}\n```\n\n\nThree objects, three values, nothing mutated. `price.minus(couponValue)` reads `price.amount` and `couponValue.amount`, adds them with reversed sign, and constructs a new `Money` to return. The original `Money` objects are unaffected by the call.\n\nThe constructor also validates inputs. Immutable objects are a good place to centralize validation because it only needs to happen once, at construction. After that, the object is guaranteed to be in a valid state forever. Mutable objects have to re-validate on every setter call.\n\n---\n\n# A \"Looks Immutable but Isn't\" Anti-Example\n\nA `ShippingAddress` class that looks correct: the class is `final`, every field is `private final`, and there are no setters. It's still mutable.\n\n\n```java\nimport java.util.Date;\n\npublic final class ShippingAddress {\n private final String street;\n private final String city;\n private final Date lastVerifiedAt;\n\n public ShippingAddress(String street, String city, Date lastVerifiedAt) {\n this.street = street;\n this.city = city;\n this.lastVerifiedAt = lastVerifiedAt; // stores the caller's reference\n }\n\n public String getStreet() {\n return street;\n }\n\n public String getCity() {\n return city;\n }\n\n public Date getLastVerifiedAt() {\n return lastVerifiedAt; // hands out the same reference\n }\n}\n\npublic class BrokenImmutabilityDemo {\n public static void main(String[] args) {\n Date verified = new Date();\n ShippingAddress address = new ShippingAddress(\"221B Baker St\", \"London\", verified);\n\n System.out.println(\"Before: \" + address.getLastVerifiedAt());\n\n verified.setTime(0L); // caller mutates the Date they kept a reference to\n System.out.println(\"After: \" + address.getLastVerifiedAt());\n\n address.getLastVerifiedAt().setTime(1_000_000L); // mutate through the getter\n System.out.println(\"Later: \" + address.getLastVerifiedAt());\n }\n}\n```\n\n\n**Output (dates will differ; the values change between lines):**\n\n\n```shell\nBefore: Wed May 13 12:00:00 UTC 2026\nAfter: Thu Jan 01 00:00:00 UTC 1970\nLater: Thu Jan 01 00:16:40 UTC 1970\n```\n\n\nThe `ShippingAddress` is \"immutable\" by the textbook checklist, and yet its `lastVerifiedAt` field can be made to take any value at any time, both by the original caller and by anyone who can call the getter. The class fails the definition of immutability: state changed after construction.\n\nSteps 4 and 5 fix this:\n\n\n```java\nimport java.util.Date;\n\npublic final class ShippingAddress {\n private final String street;\n private final String city;\n private final Date lastVerifiedAt;\n\n public ShippingAddress(String street, String city, Date lastVerifiedAt) {\n this.street = street;\n this.city = city;\n this.lastVerifiedAt = new Date(lastVerifiedAt.getTime()); // defensive copy in\n }\n\n public String getStreet() {\n return street;\n }\n\n public String getCity() {\n return city;\n }\n\n public Date getLastVerifiedAt() {\n return new Date(lastVerifiedAt.getTime()); // defensive copy out\n }\n}\n```\n\n\nThe same demo run against the fixed class produces identical output for all three `println` calls, because the caller's mutations now touch unrelated `Date` objects.\n\n`String` and `int` and `double` didn't need any of this protection. They're already immutable or primitive. The only field that needed defending was the mutable `Date`. The pattern: defensive copies aren't blanket policy, they're specific to fields whose types are mutable.\n\nModern code can sidestep this entire problem by using `java.time.LocalDateTime` or `java.time.Instant` instead of `java.util.Date`. The `java.time` types from Java 8 are themselves immutable, so storing them directly is safe. The older `Date` example is useful here because it forces a discussion of defensive copies.\n\n---\n\n# The \"With-er\" Pattern\n\nIf a `Money` instance is immutable, how do you \"change\" the amount? You don't. Construct a new `Money` with the desired value, based on the existing one. The convention for these methods is a name starting with `with`:\n\n\n```java\npublic final class Money {\n private final double amount;\n private final String currency;\n\n public Money(double amount, String currency) {\n this.amount = amount;\n this.currency = currency;\n }\n\n public Money withAmount(double newAmount) {\n return new Money(newAmount, this.currency);\n }\n\n public Money withCurrency(String newCurrency) {\n return new Money(this.amount, newCurrency);\n }\n\n public double getAmount() { return amount; }\n public String getCurrency() { return currency; }\n\n @Override\n public String toString() { return amount + \" \" + currency; }\n}\n\npublic class WithDemo {\n public static void main(String[] args) {\n Money usPrice = new Money(49.99, \"USD\");\n Money discounted = usPrice.withAmount(39.99);\n Money euPrice = discounted.withCurrency(\"EUR\");\n\n System.out.println(\"original: \" + usPrice);\n System.out.println(\"discounted: \" + discounted);\n System.out.println(\"euPrice: \" + euPrice);\n }\n}\n```\n\n\nEach `withX` method returns a new instance that copies all the other fields and changes only the one named in the method. The original instance never moves. These calls chain because each returns a `Money`.\n\nThe JDK uses this pattern throughout `java.time`. `LocalDate.now().withYear(2030).withMonth(1)` returns a date with those fields replaced and everything else preserved. The naming is the convention: `withX` returns a copy where X is set to the new value.\n\nEvery `withX` call allocates a new object. For small value types like `Money` this is fine. For large objects (a class with twenty fields, several of which are themselves big collections), a chain of five `withX` calls allocates five intermediate instances. The Builder pattern is the usual escape hatch for that case.\n\n---\n\n# Why Bother? The Benefits\n\nFollowing this recipe isn't free. There's allocation pressure (every modification creates a new object), the API gets more verbose (no more `setX(...)`), and the defensive-copy steps are easy to forget. The benefits:\n\n### Thread Safety\n\nA mutable object shared across threads needs synchronization. Two threads writing to the same field can produce inconsistent state; one thread reading while another writes can see torn values. Immutable objects sidestep the whole problem: there's nothing to write, so there's nothing to synchronize.\n\nAny number of threads can read the same `Money` instance concurrently with zero locks, zero `volatile`, zero `AtomicReference`. The compiler and the JVM guarantee that fields published as `final` are visible to other threads after the constructor finishes. This is why `String`, `Integer`, and the `java.time` types are safe to share globally without any concurrency machinery.\n\n### Safe to Share Without Defensive Copies (Externally)\n\nThe flip side of the constructor's defensive copy: inside an immutable class, references to fields can be handed out freely as long as the field types are also immutable. There's no way for a caller to mutate a `String`, so `return name` is safe. There's no way to mutate an `Integer`, so `return quantity` is safe. Defensive copying is only at the boundary with mutable types.\n\nOutside the class, if a method receives an immutable object as an argument, no copy is needed. It can be stored directly. The caller can't change it.\n\n### Usable as `HashMap` Keys\n\nA `HashMap` key's `hashCode` must stay constant for as long as the key is in the map. If a key mutates, its hash changes, and the map can no longer find it.\n\n\n```java\nimport java.util.HashMap;\nimport java.util.Map;\n\npublic class MutableKeyTrouble {\n public static void main(String[] args) {\n StringBuilder key = new StringBuilder(\"SAVE10\");\n Map coupons = new HashMap<>();\n coupons.put(key, 0.10);\n\n System.out.println(\"Before mutation: \" + coupons.get(key));\n\n key.append(\"X\"); // mutate the key\n\n System.out.println(\"After mutation: \" + coupons.get(key));\n }\n}\n```\n\n\nThe second `get` fails because the key's `hashCode` changed after it was placed in the map. The bucket the map looks in is wrong. Immutable keys avoid this entirely. `String` works perfectly as a `HashMap` key because no method on it can change the hash. Any immutable class you write earns the same guarantee.\n\n### Easier to Reason About\n\nThis benefit doesn't show up in a benchmark or a Stack Overflow answer. With a mutable object, determining its current value requires tracing every method call that touched it. With an immutable object, the value at construction is the value forever. The whole class of bugs where state changes unexpectedly disappears.\n\nThis is why immutability is the default in functional languages and increasingly common in modern Java code (records, the `java.time` API, the `Stream` operations).\n\n\n```mermaid\nflowchart LR\n Benefits[\"Why Immutable?\"]:::cyan\n Thread[\"Thread Safety
(no sync needed)\"]:::green\n Share[\"Safe to share
(no defensive copies
between callers)\"]:::orange\n Key[\"Safe as HashMap key
(stable hashCode)\"]:::teal\n Reason[\"Easier to reason about
(value never changes)\"]:::yellow\n\n Benefits --> Thread\n Benefits --> Share\n Benefits --> Key\n Benefits --> Reason\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef yellow fill:#ffd43b,stroke:#000,color:#000\n```\n\n\n---\n\n# The Costs\n\nThe recipe has real costs worth weighing.\n\n### Allocation Pressure\n\nEvery \"change\" creates a new object. For a `Money` class with two fields, that's cheap: two field copies and a constructor call. For an `Order` class with twenty fields, each `withX` call copies nineteen fields you didn't change. Chained calls compound: `order.withStatus(SHIPPED).withTrackingNumber(\"TRK1\").withShippedAt(now)` produces three intermediate `Order` objects, two of which are immediately discarded.\n\nThe garbage collector handles short-lived allocations well, so this isn't usually a problem. But it can become one in a hot loop. If profiling shows millions of intermediate immutable objects per second, the Builder pattern accumulates changes in a mutable builder and produces a single immutable result at the end.\n\n### Verbosity\n\nThe API can feel chatty. Instead of `coupon.setDiscount(0.15)`, the call becomes `coupon = coupon.withDiscount(0.15)`. The assignment is mandatory; forgetting it discards the result. Code that uses many `withX` calls in sequence reads less naturally than the equivalent mutable code, especially for readers used to imperative style.\n\nRecords (Java 16+) ease some of the verbosity by generating constructors, getters, `equals`, `hashCode`, and `toString` automatically. They are covered at the end of this lesson.\n\n### Not Everything Wants to Be Immutable\n\nA `ShoppingCart` whose items change as the user clicks \"Add\" and \"Remove\" all day is, by its nature, mutable. Expressing it as immutable means rebuilding the whole cart on every click, which is fine in principle but heavy in practice. Some domain objects have an identity that persists through state changes, and those are bad candidates for immutability.\n\n---\n\n# When to Choose Immutability\n\nThe strongest cases:\n\n- **Value objects.** Things defined entirely by their values, with no separate identity. `Money`, `OrderId`, `EmailAddress`, `Coordinate`, `Color`, `Range`. Two `Money(49.99, \"USD\")` instances are equal because they represent the same value; nobody cares which object it is.\n- **DTOs and API payloads.** Objects passed across boundaries (between layers, services, threads). Making them immutable means callers can't accidentally mutate something the producer relied on.\n- **Configuration.** A `RetryPolicy` with a maximum attempt count and a delay. You set it up once at startup, then read it from many places. Mutating it later is almost always a bug.\n- **Anything shared across threads.** The thread-safety benefit is the strongest argument for immutability.\n- **Map keys and `Set` elements.** Anything that needs a stable `hashCode` for the duration of its time in a collection.\n\n### When Not To\n\n- **Large objects with frequent partial updates.** A 30-field domain entity that the user modifies one field at a time through a UI. Each edit allocating a new instance is technically fine, but a builder approach may fit better.\n- **Objects whose identity matters more than their value.** A `User` row from the database has a permanent identity (the primary key), and the same user can change their email or address. Modeling this as immutable means creating a new `User` instance on every edit, which is not always natural.\n- **Performance-critical hot paths with profiled allocation pressure.** Don't preemptively avoid immutability for performance. Measure first. Most of the time, the JIT and GC handle short-lived allocations fine.\n\nThe default for new value-shaped types should be immutable. Mutability is the special case that needs justification.\n\n---\n\n# A `Coupon` Class: One More Worked Example\n\nAnother complete immutable class. A `Coupon` has a code, a discount percentage, and an expiry date. The expiry date is a mutable `Date`, so defensive copying applies again.\n\n\n```java\nimport java.util.Date;\n\npublic final class Coupon {\n private final String code;\n private final double percentOff;\n private final Date expiresAt;\n\n public Coupon(String code, double percentOff, Date expiresAt) {\n if (code == null || code.isEmpty()) {\n throw new IllegalArgumentException(\"code is required\");\n }\n if (percentOff < 0 || percentOff > 100) {\n throw new IllegalArgumentException(\"percentOff must be between 0 and 100\");\n }\n this.code = code;\n this.percentOff = percentOff;\n this.expiresAt = new Date(expiresAt.getTime()); // defensive copy in\n }\n\n public String getCode() {\n return code;\n }\n\n public double getPercentOff() {\n return percentOff;\n }\n\n public Date getExpiresAt() {\n return new Date(expiresAt.getTime()); // defensive copy out\n }\n\n public boolean isExpired(Date now) {\n return now.after(expiresAt);\n }\n\n public double applyTo(double price) {\n return price * (1 - percentOff / 100);\n }\n\n public Coupon withPercentOff(double newPercentOff) {\n return new Coupon(this.code, newPercentOff, this.expiresAt);\n }\n\n @Override\n public String toString() {\n return code + \" (\" + percentOff + \"% off, expires \" + expiresAt + \")\";\n }\n}\n\npublic class CouponDemo {\n public static void main(String[] args) {\n Date expiry = new Date(System.currentTimeMillis() + 1_000_000_000L);\n Coupon save10 = new Coupon(\"SAVE10\", 10.0, expiry);\n\n System.out.println(\"Original: \" + save10);\n System.out.println(\"$49.99 with coupon: $\" + save10.applyTo(49.99));\n\n Coupon save15 = save10.withPercentOff(15.0);\n System.out.println(\"Upgraded: \" + save15);\n\n expiry.setTime(0L); // try to mutate the caller's Date\n save10.getExpiresAt().setTime(0L); // try to mutate through the getter\n System.out.println(\"Still: \" + save10);\n }\n}\n```\n\n\n**Output (expiry timestamps will differ):**\n\n\n```shell\nOriginal: SAVE10 (10.0% off, expires Sun May 24 ...)\n$49.99 with coupon: $44.991\nUpgraded: SAVE10 (15.0% off, expires Sun May 24 ...)\nStill: SAVE10 (10.0% off, expires Sun May 24 ...)\n```\n\n\nThe last two lines are the proof. The caller mutated their own `Date` and the `Date` returned from the getter, and the `Coupon`'s internal state was untouched both times. Every step of the recipe contributes: `final` class, `private final` fields, no setters, defensive copy in, defensive copy out, `withPercentOff` returning a new instance, all initialization done in the constructor.\n\n---\n\n# A Quick Look at Records\n\nMost of the boilerplate in `Money` and `Coupon` is mechanical: same fields, same constructor that assigns them, same getters, same `toString`. Java 16 introduced records to remove the ceremony:\n\n\n```java\npublic record Price(double amount, String currency) {}\n```\n\n\nThat single line provides a `final` class with two `private final` fields, a canonical constructor, accessors `amount()` and `currency()`, sensible `equals` and `hashCode` based on the field values, and a useful `toString`. For simple value objects with only immutable field types, records are a good fit: less code, fewer ways to break the recipe by accident. They have their own rules: a custom constructor can be added for validation, methods can be added, instance fields beyond the record components are not allowed. Writing the long form remains useful when defensive copies for mutable field types are needed (records don't generate those).","pageType":"java"}

Immutable Classes

Get Premium