{"title":"Record Classes","description":"","content":"In Java, simple data carriers like an `OrderItem` or a shipping `Address` end up filling whole files with private fields, a constructor, getters, `equals`, `hashCode`, and `toString`. None of that code is interesting, but you still have to write it, read it during reviews, and keep it in sync whenever a field is added. Records, introduced in Java 16, give you all of that boilerplate from a single line of declaration. This lesson covers what a record is, what the compiler generates for you, how to add validation through compact constructors, and where records fit relative to regular classes.\n\n---\n\n# The Problem: Data Classes Are Mostly Boilerplate\n\nA typical \"data class\" in an e-commerce app is something like an `OrderItem`: a product name, a price, and a quantity, bundled together. Written by hand, it looks like this.\n\n\n```java\nimport java.util.Objects;\n\npublic final class OrderItem {\n private final String productName;\n private final double price;\n private final int quantity;\n\n public OrderItem(String productName, double price, int quantity) {\n this.productName = productName;\n this.price = price;\n this.quantity = quantity;\n }\n\n public String productName() {\n return productName;\n }\n\n public double price() {\n return price;\n }\n\n public int quantity() {\n return quantity;\n }\n\n @Override\n public boolean equals(Object o) {\n if (this == o) return true;\n if (!(o instanceof OrderItem)) return false;\n OrderItem other = (OrderItem) o;\n return Double.compare(price, other.price) == 0\n && quantity == other.quantity\n && Objects.equals(productName, other.productName);\n }\n\n @Override\n public int hashCode() {\n return Objects.hash(productName, price, quantity);\n }\n\n @Override\n public String toString() {\n return \"OrderItem[productName=\" + productName\n + \", price=\" + price\n + \", quantity=\" + quantity + \"]\";\n }\n}\n```\n\n\nForty lines of code, and the class doesn't actually *do* anything yet. Every field shows up four times: once as the field, once as a constructor parameter, once as an accessor, and once in each of `equals`, `hashCode`, and `toString`. Add a fourth field like `sku` and you touch six places. Forget one and the bugs are subtle: two `OrderItem` values that should be equal aren't, or a `HashSet` lookup misses because `hashCode` doesn't include the new field.\n\nRecords collapse the whole thing into one line.\n\n\n```java\npublic record OrderItem(String productName, double price, int quantity) {}\n```\n\n\nThat single declaration gives you everything the long version had. Same final fields, same accessors, same `equals`, `hashCode`, and `toString`. We'll spend the rest of the lesson unpacking what's hiding inside that one line.\n\n---\n\n# Anatomy of a Record\n\nThe smallest possible record, with the parts labeled:\n\n\n```java\npublic record OrderItem(String productName, double price, int quantity) {}\n```\n\n\n\n| Part | Value | Meaning |\n| --- | --- | --- |\n| Keyword | `record` | Tells the compiler this is a record, not a class |\n| Name | `OrderItem` | The type name, same as any class |\n| Header (components) | `(String productName, double price, int quantity)` | The data the record holds |\n| Body | `{}` | Extra members (often empty) |\n\n\nThe list in parentheses is called the **header**, and each entry is a **record component**. Each component contributes one field, one accessor, and one constructor parameter to the generated class. The body, the part inside `{ }`, can stay empty for pure data carriers, or hold extra methods, static fields, and compact constructors.\n\nThe same record being used like any other type:\n\n\n```java\npublic class RecordIntro {\n public record OrderItem(String productName, double price, int quantity) {}\n\n public static void main(String[] args) {\n OrderItem item = new OrderItem(\"Wireless Mouse\", 29.99, 2);\n System.out.println(item.productName());\n System.out.println(item.price());\n System.out.println(item.quantity());\n System.out.println(item);\n }\n}\n```\n\n\nA few details. The accessor is `productName()`, not `getProductName()`. The `toString` is the bracketed form `OrderItem[...]`, not the `OrderItem@1a2b3c` you'd get from a regular class. Both come from the compiler, not from anything you wrote.\n\n---\n\n# What the Compiler Generates\n\nWhen you write `public record OrderItem(String productName, double price, int quantity) {}`, the compiler quietly produces something equivalent to the 40-line class above. The pieces matter because they show up in stack traces, debuggers, and IDE navigation.\n\n\n```mermaid\nflowchart LR\n Source[\"public record
OrderItem(
String productName,
double price,
int quantity) {}\"]:::cyan --> Gen[Compiler]:::orange\n Gen --> Fields[\"3 private final fields\"]:::green\n Gen --> Ctor[\"Canonical constructor
matching the header\"]:::green\n Gen --> Acc[\"3 accessors:
productName(),
price(), quantity()\"]:::green\n Gen --> Eq[\"equals + hashCode
over all components\"]:::teal\n Gen --> Ts[\"toString prints
OrderItem[name=..., ...]\"]:::teal\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nLet's walk through each one.\n\n**Private final fields.** For every component, the compiler adds a `private final` field with the same name and type. So `OrderItem` ends up with `private final String productName`, `private final double price`, and `private final int quantity`. Because the fields are `final`, they can only be assigned once, in the constructor. There are no setters, ever.\n\n**Canonical constructor.** The compiler generates a constructor whose parameter list matches the header exactly. Calling `new OrderItem(\"Mouse\", 29.99, 2)` assigns each argument to the matching field in order. This is called the **canonical constructor** because its signature mirrors the record's declaration. You can also write it explicitly when you need to.\n\n**Accessor methods.** For each component, the compiler adds a public method with the same name as the component (no `get` prefix) that returns the field's value. So `productName()` returns the `productName` field, `price()` returns `price`, and so on. This is one of the biggest visible differences from classic JavaBeans-style data classes, which use `getProductName()`. The record convention is shorter and matches modern Java patterns like pattern matching for `instanceof`.\n\n**`equals`.** Two records are equal if they are the same class and every component is equal. For primitive components, that means `==`. For reference components, it means `Objects.equals(a, b)`, which handles nulls. Two `OrderItem` values with the same name, price, and quantity will be `equal` even though they're different objects in memory.\n\n**`hashCode`.** The hash is built from every component, consistent with `equals`. If two records are `equal`, they have the same `hashCode`. This is what makes records work correctly as keys in `HashMap` and as elements in `HashSet`.\n\n**`toString`.** The generated `toString` follows the format `ClassName[component1=value1, component2=value2, ...]`. It uses each component's own `toString` for the values, so nested records print readably without any extra work.\n\nA quick demonstration of `equals`, `hashCode`, and `toString` in action:\n\n\n```java\nimport java.util.HashSet;\nimport java.util.Set;\n\npublic class RecordGeneratedMethods {\n public record OrderItem(String productName, double price, int quantity) {}\n\n public static void main(String[] args) {\n OrderItem a = new OrderItem(\"Wireless Mouse\", 29.99, 2);\n OrderItem b = new OrderItem(\"Wireless Mouse\", 29.99, 2);\n OrderItem c = new OrderItem(\"Wireless Mouse\", 29.99, 3);\n\n System.out.println(\"a.equals(b): \" + a.equals(b));\n System.out.println(\"a.equals(c): \" + a.equals(c));\n System.out.println(\"a.hashCode() == b.hashCode(): \" + (a.hashCode() == b.hashCode()));\n\n Set seen = new HashSet<>();\n seen.add(a);\n System.out.println(\"seen contains b? \" + seen.contains(b));\n System.out.println(\"toString: \" + a);\n }\n}\n```\n\n\nThe `HashSet` recognizes `b` as already present even though `a` and `b` are different objects. That's `equals` and `hashCode` doing their job, with zero code written by hand.\n\n---\n\n# Records Are Implicitly Final\n\nA record is implicitly `final`. You cannot extend it with another class, and you cannot mark it `abstract`. Likewise, a record cannot extend another class. Every record silently extends `java.lang.Record`, which is the common supertype the JVM uses to recognize records.\n\n\n```java\npublic class RecordFinality {\n public record Coupon(String code, double percentOff) {}\n\n // The following lines would NOT compile if uncommented:\n // public class BigCoupon extends Coupon { } // error: cannot inherit from final Coupon\n // public record SuperCoupon(...) extends SomeClass { } // error: records cannot extend classes\n\n public static void main(String[] args) {\n Coupon c = new Coupon(\"WELCOME10\", 10.0);\n System.out.println(c);\n System.out.println(\"Is a java.lang.Record? \" + (c instanceof java.lang.Record));\n }\n}\n```\n\n\nThe reasoning is straightforward: records exist to be predictable data carriers. If a subclass could add hidden state or override `equals`, the guarantees that make records useful would evaporate. Two `Coupon` values that look identical from outside might be unequal because some subclass changed the meaning. By forbidding inheritance, the language keeps the contract simple: what you see in the header is everything the record holds.\n\nThis also explains the missing class-level extension. A record's behavior is fixed by its components, and there's no useful way to merge that with whatever a parent class might bring along.\n\n---\n\n# Records Can Implement Interfaces\n\nWhat records *can* do is implement interfaces. That's enough for most uses, because the typical reason to want inheritance with a data class is to give it a shared behavior contract, and an interface covers exactly that.\n\n\n```java\npublic class RecordImplementsInterface {\n public interface ShippingOption {\n double cost();\n int estimatedDays();\n }\n\n public record StandardShipping(double cost, int estimatedDays) implements ShippingOption {}\n\n public record ExpressShipping(double cost, int estimatedDays) implements ShippingOption {}\n\n public static void describe(ShippingOption option) {\n System.out.println(\"Cost: $\" + option.cost() + \", arrives in \" + option.estimatedDays() + \" days\");\n }\n\n public static void main(String[] args) {\n describe(new StandardShipping(4.99, 5));\n describe(new ExpressShipping(14.99, 2));\n }\n}\n```\n\n\nThe components `cost` and `estimatedDays` automatically satisfy the interface methods `cost()` and `estimatedDays()`. Because record accessors share the names of the components, the interface's abstract methods are implemented automatically as long as the names line up. If the interface had defined `getCost()` instead, you'd need an extra method in the record body to bridge the gap.\n\nThis pattern shows up a lot. The interface declares the shape of the operation, and several records implement it with their own combination of fields.\n\n---\n\n# Compact Constructors: Validation Without Repetition\n\nThe canonical constructor is fine when you trust the inputs, but in real code you usually want to validate or normalize values before they land in the fields. A `quantity` of `-3` or a `price` of `Double.NaN` shouldn't be allowed. You could write a full constructor and copy each assignment, but records offer something tidier: the **compact constructor**.\n\nA compact constructor uses the record's name with no parameter list. Inside, you can read and reassign the component parameters (which already exist as local variables matching the header), and the compiler adds the field assignments for you when the body finishes.\n\n\n```java\npublic class CompactConstructor {\n public record OrderItem(String productName, double price, int quantity) {\n public OrderItem {\n if (productName == null || productName.isBlank()) {\n throw new IllegalArgumentException(\"productName cannot be blank\");\n }\n if (price < 0) {\n throw new IllegalArgumentException(\"price cannot be negative\");\n }\n if (quantity < 1) {\n throw new IllegalArgumentException(\"quantity must be at least 1\");\n }\n }\n }\n\n public static void main(String[] args) {\n OrderItem ok = new OrderItem(\"Wireless Mouse\", 29.99, 2);\n System.out.println(\"Created: \" + ok);\n\n try {\n new OrderItem(\"Wireless Mouse\", 29.99, 0);\n } catch (IllegalArgumentException e) {\n System.out.println(\"Caught: \" + e.getMessage());\n }\n }\n}\n```\n\n\nThe compact constructor is `public OrderItem { ... }`, with no `(...)` after the name. Inside the braces, `productName`, `price`, and `quantity` are the incoming parameters. Once the block finishes without throwing, the compiler assigns them to the matching fields. You never write `this.productName = productName`.\n\nCompact constructors are also a good place for normalization. Trim a string, round a double, copy a mutable list. The reassignments stick because the compiler picks up the values from the local variables after your block runs.\n\n\n```java\npublic class NormalizingCompact {\n public record Address(String street, String city, String zip) {\n public Address {\n street = street.trim();\n city = city.trim();\n zip = zip.trim();\n }\n }\n\n public static void main(String[] args) {\n Address a = new Address(\" 221B Baker St \", \" London \", \" NW1 6XE \");\n System.out.println(a);\n }\n}\n```\n\n\nThe compact constructor normalizes the input, and the fields end up trimmed.\n\nThrowing from a compact constructor happens during `new`, before any reference to the record escapes. There's no half-built record to worry about, which is the same guarantee a normal class constructor gives. Validation here is as safe as it is convenient.\n\n---\n\n# Beyond the Header: Extra Members in the Body\n\nThe header captures the state of a record, but the body can hold more. The two most useful additions are extra methods and static helpers.\n\n### Adding Methods\n\nAny method that derives a value from the components is a natural fit. Keep the record immutable, return a new value, and you get a clean way to express derived properties.\n\n\n```java\npublic class RecordWithMethods {\n public record OrderItem(String productName, double price, int quantity) {\n public double subtotal() {\n return price * quantity;\n }\n\n public boolean isFreeItem() {\n return price == 0.0;\n }\n }\n\n public static void main(String[] args) {\n OrderItem item = new OrderItem(\"Wireless Mouse\", 29.99, 3);\n System.out.println(\"Subtotal: $\" + item.subtotal());\n System.out.println(\"Free? \" + item.isFreeItem());\n\n OrderItem sample = new OrderItem(\"Free Sample\", 0.0, 1);\n System.out.println(\"Free? \" + sample.isFreeItem());\n }\n}\n```\n\n\n`subtotal()` and `isFreeItem()` are regular instance methods. They read the components through the accessors (or directly by field name, both work inside the record) and return derived values. Nothing new state-wise; just convenience on top of the data the record already holds.\n\n### Static Factories and Static Fields\n\nRecords can hold `static` fields and `static` methods just like regular classes. A common pattern is a static factory for the most common shape of the record.\n\n\n```java\npublic class RecordWithStatics {\n public record Coupon(String code, double percentOff) {\n public static final Coupon NO_DISCOUNT = new Coupon(\"NONE\", 0.0);\n\n public static Coupon welcome() {\n return new Coupon(\"WELCOME10\", 10.0);\n }\n\n public static Coupon flatPercent(double percentOff) {\n return new Coupon(\"FLAT\" + (int) percentOff, percentOff);\n }\n }\n\n public static void main(String[] args) {\n System.out.println(Coupon.NO_DISCOUNT);\n System.out.println(Coupon.welcome());\n System.out.println(Coupon.flatPercent(25));\n }\n}\n```\n\n\nA useful constraint: a record cannot declare its own *instance* fields outside the header. All instance state lives in the components. `static` fields, which belong to the class itself rather than to any specific record, are allowed because they don't break the contract that \"the components are the data\". This is what keeps records honest as data carriers.\n\n---\n\n# \"Modifying\" a Record: With-Style Helpers\n\nBecause records are immutable, there are no setters. To produce a record with one field changed, you build a new one and copy the other fields over. It feels a bit verbose at the call site, so a common pattern is to add a small \"with\" method inside the record body for the field you change most often.\n\n\n```java\npublic class RecordWithHelper {\n public record OrderItem(String productName, double price, int quantity) {\n public OrderItem withQuantity(int newQuantity) {\n return new OrderItem(productName, price, newQuantity);\n }\n }\n\n public static void main(String[] args) {\n OrderItem original = new OrderItem(\"Wireless Mouse\", 29.99, 1);\n OrderItem moreUnits = original.withQuantity(3);\n\n System.out.println(\"Original: \" + original);\n System.out.println(\"Updated: \" + moreUnits);\n }\n}\n```\n\n\n`original` is untouched because it can't be touched. `moreUnits` is a brand new `OrderItem` that happens to share the product name and price with the original. The `withQuantity` helper isn't anything the compiler generates for you, but it's a small, readable pattern that pays for itself when callers frequently tweak one field.\n\nFor deeper changes across many fields, consider a builder or simply pass everything into the canonical constructor.\n\nEach call to `withQuantity` allocates a new `OrderItem`. For records used in tight inner loops, prefer to compute the final shape once rather than chaining a series of `with...` calls.\n\n---\n\n# Records as Map Keys and Set Elements\n\nBecause records get correct `equals` and `hashCode` from the compiler, they work as map keys and set elements without any extra effort. This is one of the bigger day-to-day wins.\n\n\n```java\nimport java.util.HashMap;\nimport java.util.Map;\n\npublic class RecordsAsKeys {\n public record Address(String street, String city, String zip) {}\n\n public static void main(String[] args) {\n Map nameByAddress = new HashMap<>();\n nameByAddress.put(new Address(\"221B Baker St\", \"London\", \"NW1 6XE\"), \"Holmes\");\n nameByAddress.put(new Address(\"742 Evergreen Terrace\", \"Springfield\", \"00000\"), \"Simpson\");\n\n Address lookup = new Address(\"221B Baker St\", \"London\", \"NW1 6XE\");\n System.out.println(\"Lookup result: \" + nameByAddress.get(lookup));\n }\n}\n```\n\n\nThe lookup `Address` is a different object from the one used to insert, but `equals` says they're equal and `hashCode` matches, so `HashMap` finds the entry. With a hand-written class, you'd have to remember to override `equals` and `hashCode` correctly. Forget either one and the map silently misbehaves.\n\nWhen a record is used as a map key, the map calls `hashCode` on every lookup. For records with many components or large strings, that hash is recomputed each time. If the same key is used heavily, the cost is usually fine; if not, consider whether a smaller key would serve.\n\n---\n\n# Common Mistakes\n\nA few traps come up when first using records.\n\n**What's wrong with this code?**\n\n\n```java\npublic record OrderItem(String productName, double price, int quantity) {\n public void setQuantity(int newQuantity) {\n this.quantity = newQuantity;\n }\n}\n```\n\n\n**Fix:**\n\nRecords are immutable. The component fields are `final` and there is no setter pattern. To produce an `OrderItem` with a different quantity, build a new one (or add a `withQuantity` helper that returns a fresh record).\n\n\n```java\npublic record OrderItem(String productName, double price, int quantity) {\n public OrderItem withQuantity(int newQuantity) {\n return new OrderItem(productName, price, newQuantity);\n }\n}\n```\n\n\n**What's wrong with this code?**\n\n\n```java\npublic record DiscountedItem(String productName, double price, int quantity, double discount)\n extends OrderItem {\n}\n```\n\n\n**Fix:**\n\nRecords cannot extend a class. They are implicitly `final` and silently extend `java.lang.Record`. If you want to share behavior, define an interface and have both records implement it.\n\n\n```java\npublic interface PricedItem {\n double price();\n int quantity();\n}\n\npublic record OrderItem(String productName, double price, int quantity) implements PricedItem {}\npublic record DiscountedItem(String productName, double price, int quantity, double discount) implements PricedItem {}\n```\n\n\n**What's wrong with this code?**\n\n\n```java\npublic record Cart(String customerName) {\n private int itemCount; // extra instance field, not declared in the header\n}\n```\n\n\n**Fix:**\n\nA record's instance state must be exactly the components in the header. The compiler rejects extra instance fields. If you actually need that state, make it a regular class. If it's a derived value, compute it from the components instead.\n\n\n```java\npublic record Cart(String customerName, int itemCount) {}\n```\n\n\n**What's wrong with this code?**\n\n\n```java\npublic record OrderItem(String productName, double price, int quantity) {\n public OrderItem(String productName, double price, int quantity) {\n // missing field assignments\n }\n}\n```\n\n\n**Fix:**\n\nThe explicit canonical constructor must assign every field. If you don't want to write the assignments, use a compact constructor instead. Compact constructors look like `public OrderItem { ... }` with no parameter list, and the compiler adds the assignments for you.\n\n\n```java\npublic record OrderItem(String productName, double price, int quantity) {\n public OrderItem {\n if (quantity < 1) throw new IllegalArgumentException(\"quantity must be at least 1\");\n }\n}\n```\n\n\n---\n\n# Records vs Regular Classes: When to Pick Which\n\nRecords suit types that are transparent, immutable carriers of values. They don't suit types with identity beyond their fields, types whose state should change over time, or types that need to participate in a class hierarchy.\n\n\n| Need | Records | Regular Class |\n| --- | --- | --- |\n| Immutable data carrier (DTO, query result, key) | Best fit | Works but verbose |\n| Mutable state (counters, caches, accumulators) | Not possible | Use a class |\n| Inheritance from another class | Not possible | Use a class |\n| Implements an interface | Supported | Supported |\n| Hidden state, lazy initialization | Not possible | Use a class |\n| Use as a `HashMap` key | Free `equals`, `hashCode` | Must override both |\n| Validation on construction | Compact constructor | Manual in constructor |\n\n\nA useful rule of thumb: if you'd be tempted to mark every field `final` and override `equals` and `hashCode` based on every field, you want a record. If not, a class is the better fit.\n\nA side-by-side comparison of the same concept written both ways:\n\n\n```mermaid\nflowchart LR\n Hand[Hand-written
data class
~40 lines]:::red --> Same[Same behavior]:::orange\n Rec[Record
1 line]:::green --> Same\n Same --> Result[Equal fields
same equals,
hashCode,
toString]:::cyan\n\n classDef red fill:#ff8787,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n```\n\n\nThe line count isn't the only win. The bigger win is that a record's contract is locked: every reader sees the components and knows exactly what the type holds. A hand-written class can drift, adding fields that aren't in `equals` or accessors that hide more than they expose. Records keep everyone honest.\n\n---\n\n# A Larger Example: A Cart of Records\n\nTo pull the pieces together, a small e-commerce scenario built entirely from records. The cart calculates a subtotal, applies a coupon, and prints a summary, with each domain concept as its own immutable record.\n\n\n```java\nimport java.util.List;\n\npublic class CartExample {\n public record OrderItem(String productName, double price, int quantity) {\n public OrderItem {\n if (price < 0) throw new IllegalArgumentException(\"price cannot be negative\");\n if (quantity < 1) throw new IllegalArgumentException(\"quantity must be at least 1\");\n }\n\n public double subtotal() {\n return price * quantity;\n }\n }\n\n public record Coupon(String code, double percentOff) {\n public static final Coupon NONE = new Coupon(\"NONE\", 0.0);\n\n public double applyTo(double amount) {\n return amount * (1 - percentOff / 100);\n }\n }\n\n public record PriceQuote(double subtotal, double discount, double total) {}\n\n public static PriceQuote quote(List items, Coupon coupon) {\n double subtotal = 0;\n for (OrderItem item : items) {\n subtotal += item.subtotal();\n }\n double total = coupon.applyTo(subtotal);\n double discount = subtotal - total;\n return new PriceQuote(subtotal, discount, total);\n }\n\n public static void main(String[] args) {\n List cart = List.of(\n new OrderItem(\"Wireless Mouse\", 29.99, 2),\n new OrderItem(\"USB Cable\", 9.99, 3),\n new OrderItem(\"Headphones\", 49.99, 1)\n );\n\n PriceQuote quote = quote(cart, new Coupon(\"WELCOME10\", 10.0));\n System.out.println(quote);\n System.out.println(\"You saved: $\" + quote.discount());\n }\n}\n```\n\n\nA few details about this example. `OrderItem` carries validation in a compact constructor and exposes a derived `subtotal()`. `Coupon` exposes an `applyTo` method and a static `NONE` constant. `PriceQuote` is a pure data carrier with no extra behavior at all. Three records, three different shapes, and not a single setter, getter, `equals`, or `hashCode` written by hand.\n\nCompare this to the same example written with traditional classes and the difference is striking. The records version reads top-to-bottom like a description of the domain. The class version would devote most of its space to plumbing.","pageType":"java"}

Record Classes

Get Premium