{"title":"Sealed Classes","description":"","content":"A regular class hierarchy in Java is open. Any class anywhere can extend `Order`, any class can implement `PaymentMethod`, and your code has no way to say \"actually, there are only three kinds of these and that's the whole list.\" Sealed classes and sealed interfaces, added in Java 17, close that door. They let you declare a parent type along with the exact set of direct subtypes the compiler will accept, which gives you a closed family of related types you can reason about, document, and switch over completely.\n\nThis lesson covers the `sealed` and `permits` keywords, the three modifiers a permitted subtype must pick from (`final`, `sealed`, `non-sealed`), the location rule that puts the parent and its subtypes in the same package, and the way sealed interfaces combine with records to model a small fixed set of cases. We'll finish with a worked example of an order status modeled as a sealed interface.\n\n---\n\n# The Problem: Hierarchies Are Open by Default\n\nConsider modeling the different kinds of orders an online store handles. A physical order ships through the warehouse, a digital order delivers a download link, and a gift order delivers to a different address than the buyer's. A first cut might look like this.\n\n\n```java\npublic class OpenHierarchy {\n public static void main(String[] args) {\n Order order = new PhysicalOrder(1001, \"Wireless Mouse\");\n describe(order);\n }\n\n public static void describe(Order order) {\n if (order instanceof PhysicalOrder p) {\n System.out.println(\"Physical order \" + p.orderId + \" for \" + p.productName);\n } else if (order instanceof DigitalOrder d) {\n System.out.println(\"Digital order \" + d.orderId + \" download: \" + d.downloadUrl);\n } else if (order instanceof GiftOrder g) {\n System.out.println(\"Gift order \" + g.orderId + \" to \" + g.recipientName);\n } else {\n System.out.println(\"Unknown order type\");\n }\n }\n}\n\nclass Order {\n int orderId;\n Order(int orderId) { this.orderId = orderId; }\n}\n\nclass PhysicalOrder extends Order {\n String productName;\n PhysicalOrder(int orderId, String productName) {\n super(orderId);\n this.productName = productName;\n }\n}\n\nclass DigitalOrder extends Order {\n String downloadUrl;\n DigitalOrder(int orderId, String downloadUrl) {\n super(orderId);\n this.downloadUrl = downloadUrl;\n }\n}\n\nclass GiftOrder extends Order {\n String recipientName;\n GiftOrder(int orderId, String recipientName) {\n super(orderId);\n this.recipientName = recipientName;\n }\n}\n```\n\n\nThe code works, but the `describe` method has an `else` branch for \"Unknown order type\" that exists because the compiler can't prove the list of subtypes is complete. Tomorrow, anyone with access to `Order` can write `class SubscriptionOrder extends Order { ... }` in a different file, and `describe` will route that new type through the `else` branch.\n\nThat open extension is the right default for some designs. For an `Order` type that's part of a public framework where third parties should add their own kinds, you want this. For domain types in your own codebase, you usually don't. You want a fixed list of cases, and you want the compiler to fail your build the moment someone tries to add a fourth one without updating `describe`.\n\n`sealed` is the keyword that gives you that closed list.\n\n---\n\n# The `sealed` and `permits` Keywords\n\nA sealed class declares the exact set of classes that are allowed to extend it. The `permits` clause spells out the list.\n\n\n```java\npublic class SealedHierarchy {\n public static void main(String[] args) {\n Order order = new PhysicalOrder(1001, \"Wireless Mouse\");\n System.out.println(\"Order id: \" + order.orderId);\n }\n}\n\nsealed class Order permits PhysicalOrder, DigitalOrder, GiftOrder {\n int orderId;\n Order(int orderId) { this.orderId = orderId; }\n}\n\nfinal class PhysicalOrder extends Order {\n String productName;\n PhysicalOrder(int orderId, String productName) {\n super(orderId);\n this.productName = productName;\n }\n}\n\nfinal class DigitalOrder extends Order {\n String downloadUrl;\n DigitalOrder(int orderId, String downloadUrl) {\n super(orderId);\n this.downloadUrl = downloadUrl;\n }\n}\n\nfinal class GiftOrder extends Order {\n String recipientName;\n GiftOrder(int orderId, String recipientName) {\n super(orderId);\n this.recipientName = recipientName;\n }\n}\n```\n\n\nTwo new things here. The parent class is `sealed`, and it lists its permitted subtypes after `permits`. Each subtype is `final`, which means the chain stops there. Any attempt to add a fourth subtype outside the `permits` list, anywhere in the codebase, becomes a compile error.\n\nThe compiler now has full knowledge: there are exactly three direct subtypes of `Order`. That knowledge unlocks two things. First, anywhere you switch over an `Order`, the compiler can warn you if you missed a case (and in newer Java versions, refuse to compile pattern-matching switches that aren't exhaustive). Second, anyone reading the code can see the complete family of types in one line, instead of grepping the whole project.\n\nThe hierarchy as a diagram:\n\n\n```mermaid\nflowchart TD\n Order[\"sealed class Order
permits PhysicalOrder,
DigitalOrder, GiftOrder\"]:::cyan\n Order --> Physical[\"final class
PhysicalOrder\"]:::green\n Order --> Digital[\"final class
DigitalOrder\"]:::green\n Order --> Gift[\"final class
GiftOrder\"]:::green\n\n Blocked[\"class SubscriptionOrder
extends Order
(rejected by compiler)\"]:::red\n Order -.->|not permitted| Blocked\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef red fill:#ff8787,stroke:#000,color:#000\n```\n\n\nThe dashed line shows what `sealed` blocks. Any class not in the `permits` list can't extend `Order`, even if it's in the same package, even if it's `public`, even if it's `final` itself.\n\n---\n\n# Every Permitted Subtype Picks One of Three Modifiers\n\nA permitted subtype must declare itself as exactly one of `final`, `sealed`, or `non-sealed`. The compiler enforces this. The three modifiers control what happens to extension below that subtype.\n\n\n| Modifier | Meaning | When to use |\n| --- | --- | --- |\n| `final` | The chain stops. No further subclasses allowed. | Most common. You're done modeling at this level. |\n| `sealed` | Keep restricting. This subtype itself has a `permits` list. | When a category splits into a closed set of further cases. |\n| `non-sealed` | Re-open the hierarchy from this point. Any class can extend this subtype. | When a category really is open to extension by other code. |\n\n\nThe diagram below uses all three.\n\n\n```mermaid\nflowchart TD\n Order[\"sealed class Order\"]:::cyan\n Order --> Physical[\"final class
PhysicalOrder\"]:::green\n Order --> Digital[\"sealed class
DigitalOrder\"]:::orange\n Order --> Gift[\"non-sealed class
GiftOrder\"]:::red\n\n Digital --> Streaming[\"final class
StreamingOrder\"]:::green\n Digital --> Download[\"final class
DownloadOrder\"]:::green\n\n Gift --> AnyExt[\"any class
can extend\"]:::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 red fill:#ff8787,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\n`PhysicalOrder` is final. There is no `PartialPhysicalOrder` or `ExpressPhysicalOrder`. `DigitalOrder` is itself sealed and splits further into `StreamingOrder` and `DownloadOrder`. `GiftOrder` is non-sealed, which means we deliberately allow other code (perhaps a separate gifting module) to extend it.\n\nThe matching code:\n\n\n```java\npublic class ThreeModifiers {\n public static void main(String[] args) {\n Order order = new StreamingOrder(2001, \"https://stream.example.com/movie-42\");\n System.out.println(\"Order class: \" + order.getClass().getSimpleName());\n }\n}\n\nsealed class Order permits PhysicalOrder, DigitalOrder, GiftOrder {\n int orderId;\n Order(int orderId) { this.orderId = orderId; }\n}\n\nfinal class PhysicalOrder extends Order {\n PhysicalOrder(int orderId) { super(orderId); }\n}\n\nsealed class DigitalOrder extends Order permits StreamingOrder, DownloadOrder {\n String url;\n DigitalOrder(int orderId, String url) {\n super(orderId);\n this.url = url;\n }\n}\n\nfinal class StreamingOrder extends DigitalOrder {\n StreamingOrder(int orderId, String url) { super(orderId, url); }\n}\n\nfinal class DownloadOrder extends DigitalOrder {\n DownloadOrder(int orderId, String url) { super(orderId, url); }\n}\n\nnon-sealed class GiftOrder extends Order {\n String recipientName;\n GiftOrder(int orderId, String recipientName) {\n super(orderId);\n this.recipientName = recipientName;\n }\n}\n```\n\n\nRead top to bottom: `Order` is sealed and permits three subtypes. Each subtype picks one of the three modifiers. Below `DigitalOrder`, the chain narrows further with its own permits list. Below `GiftOrder`, the chain reopens.\n\nThe reason the compiler forces every permitted subtype to pick one of the three is that \"sealed\" has to mean something at every layer. If a permitted subtype left this unspecified, the closed list at the top would leak through a half-open subtype in the middle, and the guarantees of the seal would vanish.\n\n**What's wrong with this code?**\n\n\n```java\nsealed class PriceAdjustment permits Discount, Surcharge {}\n\nclass Discount extends PriceAdjustment {}\nclass Surcharge extends PriceAdjustment {}\n```\n\n\n**Fix:**\n\n\n```java\nsealed class PriceAdjustment permits Discount, Surcharge {}\n\nfinal class Discount extends PriceAdjustment {}\nfinal class Surcharge extends PriceAdjustment {}\n```\n\n\nBoth `Discount` and `Surcharge` are listed in `PriceAdjustment`'s permits clause, but neither is marked `final`, `sealed`, or `non-sealed`. The compiler reports an error like `sealed, non-sealed or final modifiers expected`. Picking `final` says these are the leaves of the hierarchy.\n\n---\n\n# Sealed Interfaces\n\nSealed interfaces work the same way as sealed classes, and in practice they are more common. An interface has no constructor or fields to worry about, and many sealed hierarchies model a fixed set of cases that share behavior rather than implementation. A payment method is a classic example.\n\n\n```java\npublic class SealedInterfaceExample {\n public static void main(String[] args) {\n PaymentMethod payment = new CreditCard(\"4111-1111-1111-1111\", \"12/29\");\n System.out.println(\"Paying with: \" + describe(payment));\n }\n\n public static String describe(PaymentMethod method) {\n if (method instanceof CreditCard c) {\n return \"credit card ending \" + c.cardNumber().substring(c.cardNumber().length() - 4);\n }\n if (method instanceof PayPal p) {\n return \"PayPal account \" + p.email();\n }\n if (method instanceof GiftCard g) {\n return \"gift card with $\" + g.balance() + \" left\";\n }\n throw new IllegalStateException(\"Unhandled payment method: \" + method);\n }\n}\n\nsealed interface PaymentMethod permits CreditCard, PayPal, GiftCard {}\n\nrecord CreditCard(String cardNumber, String expiry) implements PaymentMethod {}\nrecord PayPal(String email) implements PaymentMethod {}\nrecord GiftCard(String code, double balance) implements PaymentMethod {}\n```\n\n\nThe interface `PaymentMethod` is sealed. The three implementations are records, which are implicitly `final`. The implementations satisfy the \"every permitted subtype must be `final`, `sealed`, or `non-sealed`\" rule automatically.\n\nCombining sealed interfaces with records like this is a popular pattern. The interface names the abstract category. Each record names one concrete variant and carries the data specific to it. You get a small, closed family of value types you can pass around and inspect by type.\n\nThis shape, a closed parent type plus a fixed set of variant types, is what functional languages call an **algebraic data type** (ADT). Java doesn't use that term in the spec, but the combination of `sealed` and records is functionally the same thing. The phrase shows up often in articles about modern Java; it means \"a sealed interface with a finite, known set of cases.\"\n\n---\n\n# The Location Rule: Same Package or Same Module\n\nA sealed parent and its permitted subtypes must live close to each other. The exact rule depends on whether your code uses Java modules:\n\n- **In a regular (unnamed) module**, sealed parents and their permitted subtypes must be in the same **package**.\n- **In a named module**, they may be in different packages, but they must be in the same **module**.\n\nThis is a structural rule the compiler enforces. It exists because sealing only makes sense if you can see all the cases at once. If a subtype lived in a faraway package or a separate module, the sealed parent couldn't reliably know about it, and the closed-list guarantee would weaken.\n\nFor most code, the practical version is: keep the parent and the permitted subtypes in the same `.java` source file or in sibling files in the same package directory.\n\n**What's wrong with this code?**\n\n\n```java\n// File: com/store/orders/Order.java\npackage com.store.orders;\n\npublic sealed class Order permits PhysicalOrder {\n int orderId;\n public Order(int orderId) { this.orderId = orderId; }\n}\n```\n\n\n\n```java\n// File: com/store/physical/PhysicalOrder.java\npackage com.store.physical;\n\nimport com.store.orders.Order;\n\npublic final class PhysicalOrder extends Order {\n public PhysicalOrder(int orderId) { super(orderId); }\n}\n```\n\n\n**Fix:**\n\nMove `PhysicalOrder` into the `com.store.orders` package so it sits next to `Order`. The compiler error reads `class is not allowed to extend sealed class: different package`. If you need the subtype in a different package, your project must use Java modules and both packages must be in the same module.\n\nKeep sealed types and their subtypes in the same package.\n\n---\n\n# Exhaustive Switch Over a Sealed Type\n\nThe most useful payoff of a sealed type is that the compiler now knows the complete list of cases. Combine that with a switch over the sealed type, and you can write code that handles every case once and is guaranteed to keep handling every case even as the hierarchy changes.\n\nThe switch syntax stays light here. The minimum needed to see what sealing buys you:\n\n\n```java\npublic class SwitchOverSealed {\n public static void main(String[] args) {\n PaymentMethod payment = new GiftCard(\"WELCOME10\", 25.0);\n System.out.println(describe(payment));\n }\n\n public static String describe(PaymentMethod method) {\n return switch (method) {\n case CreditCard c -> \"Credit card ending \" + last4(c.cardNumber());\n case PayPal p -> \"PayPal account \" + p.email();\n case GiftCard g -> \"Gift card with $\" + g.balance() + \" remaining\";\n };\n }\n\n private static String last4(String cardNumber) {\n return cardNumber.substring(cardNumber.length() - 4);\n }\n}\n\nsealed interface PaymentMethod permits CreditCard, PayPal, GiftCard {}\nrecord CreditCard(String cardNumber, String expiry) implements PaymentMethod {}\nrecord PayPal(String email) implements PaymentMethod {}\nrecord GiftCard(String code, double balance) implements PaymentMethod {}\n```\n\n\nThere's no `default` branch. The switch handles each permitted subtype exactly once, and the compiler accepts that as exhaustive because the sealed declaration tells it the list is complete. If someone later adds `record ApplePay(String deviceId) implements PaymentMethod` and updates the `permits` clause, this switch stops compiling until they handle the new case.\n\nCompare to the same code with an open (non-sealed) parent. There, you'd need a `default` branch or an explicit fallback, because the compiler can't prove you've covered every case. Adding a new subtype somewhere far away would fall through to `default` with no warning, and nothing would alert you that the new variant needs special handling.\n\nPattern matching in a switch with many cases compiles to fast jump-table dispatch in modern JVMs, similar in cost to a chain of `instanceof` checks. Exhaustiveness is a compile-time property; it doesn't slow down the running program.\n\nThe key fact: switch over a sealed type can be exhaustive, and the compiler will enforce it.\n\n---\n\n# Putting It Together: An Order Status Type\n\nA worked example. Model order status as a sealed interface, give each status a record implementation that carries the data specific to it, and write a function that describes any status in a single switch.\n\nThe states are: `Placed` (carries a timestamp), `Shipped` (carries a tracking number), `Delivered` (carries a delivery date), and `Cancelled` (carries a reason).\n\n\n```java\npublic class OrderStatusDemo {\n public static void main(String[] args) {\n OrderStatus[] history = {\n new Placed(\"2025-05-13T09:15\"),\n new Shipped(\"TRACK-91022\"),\n new Delivered(\"2025-05-15\"),\n new Cancelled(\"Customer changed mind\")\n };\n\n for (OrderStatus status : history) {\n System.out.println(describe(status));\n }\n }\n\n public static String describe(OrderStatus status) {\n return switch (status) {\n case Placed p -> \"Order placed at \" + p.placedAt();\n case Shipped s -> \"Order shipped, tracking \" + s.trackingNumber();\n case Delivered d -> \"Order delivered on \" + d.deliveredOn();\n case Cancelled c -> \"Order cancelled: \" + c.reason();\n };\n }\n}\n\nsealed interface OrderStatus permits Placed, Shipped, Delivered, Cancelled {}\n\nrecord Placed(String placedAt) implements OrderStatus {}\nrecord Shipped(String trackingNumber) implements OrderStatus {}\nrecord Delivered(String deliveredOn) implements OrderStatus {}\nrecord Cancelled(String reason) implements OrderStatus {}\n```\n\n\nFour cases, four records, one sealed interface, one exhaustive switch. The whole hierarchy fits in fewer than fifteen lines of declarations. If the business later adds a fifth status (say, `Returned`), there's exactly one place to update the `permits` clause and one place where the compiler will refuse to build the project until `describe` handles the new case.\n\nWhy not use an `enum`? Enums also give you a fixed set of values, but each enum constant carries the same fields. With a sealed interface plus records, each variant can carry different data: `Shipped` has a tracking number, `Delivered` has a date, `Cancelled` has a reason, and `Placed` has a timestamp. Enums force every constant to share one field layout, which doesn't fit when the variants have different shapes.\n\nUse enums when every case is interchangeable in structure (`Day.MONDAY`, `Day.TUESDAY`). Use a sealed interface with records when each case carries its own data and you still want a closed list.\n\n---\n\n# Common Mistakes\n\nA few errors come up often when working with sealed types. Knowing the message and the fix saves time.\n\n**Mistake 1: Forgetting to mark a permitted subtype.**\n\n\n```java\nsealed class Notification permits EmailNotification, SmsNotification {}\n\nclass EmailNotification extends Notification {}\nclass SmsNotification extends Notification {}\n```\n\n\nThe compiler complains: `sealed, non-sealed or final modifiers expected`. Pick one for each subtype.\n\n**Fix:**\n\n\n```java\nsealed class Notification permits EmailNotification, SmsNotification {}\n\nfinal class EmailNotification extends Notification {}\nfinal class SmsNotification extends Notification {}\n```\n\n\n**Mistake 2: Extending a sealed type without being in the permits list.**\n\n\n```java\nsealed class ShippingMethod permits StandardShipping, ExpressShipping {}\n\nfinal class StandardShipping extends ShippingMethod {}\nfinal class ExpressShipping extends ShippingMethod {}\n\nfinal class OvernightShipping extends ShippingMethod {} // compile error\n```\n\n\nThe error reads `class is not allowed to extend sealed class`. The fix is to add `OvernightShipping` to the `permits` clause, or to not extend `ShippingMethod` at all.\n\n**Fix:**\n\n\n```java\nsealed class ShippingMethod permits StandardShipping, ExpressShipping, OvernightShipping {}\n\nfinal class StandardShipping extends ShippingMethod {}\nfinal class ExpressShipping extends ShippingMethod {}\nfinal class OvernightShipping extends ShippingMethod {}\n```\n\n\nIf new subtypes get added to the `permits` list from far-flung parts of the codebase, the sealed type may be the wrong tool. Sealed types fit closed domains where the set of cases is known and small. Truly open extension points belong in regular (or `non-sealed`) classes.\n\n**Mistake 3: Permitted subtype in a different package.**\n\n\n```java\n// File: com/store/orders/Notification.java\npackage com.store.orders;\npublic sealed class Notification permits EmailNotification {}\n\n// File: com/store/email/EmailNotification.java\npackage com.store.email;\nimport com.store.orders.Notification;\npublic final class EmailNotification extends Notification {}\n```\n\n\nThe error reads `class is not allowed to extend sealed class: different package`. Move the subtype into the parent's package, or move both into a Java module if a cross-package layout is required.\n\n**Fix:**\n\n\n```java\n// File: com/store/orders/Notification.java\npackage com.store.orders;\npublic sealed class Notification permits EmailNotification {}\n\n// File: com/store/orders/EmailNotification.java\npackage com.store.orders;\npublic final class EmailNotification extends Notification {}\n```\n\n\n**Mistake 4: Treating sealed as a synonym for final.**\n\n\n```java\npublic sealed class Coupon {\n public Coupon(String code) {}\n}\n```\n\n\nThe compiler complains because a sealed class with no `permits` clause and no permitted subtypes in the same file is meaningless. The fix is either to list permitted subtypes or to mark the class as `final` if no extension is allowed.\n\n**Fix (no extension wanted):**\n\n\n```java\npublic final class Coupon {\n public Coupon(String code) {}\n}\n```\n\n\n**Fix (closed set of extensions):**\n\n\n```java\npublic sealed class Coupon permits PercentCoupon, FixedCoupon {\n String code;\n public Coupon(String code) { this.code = code; }\n}\n\npublic final class PercentCoupon extends Coupon {\n double percent;\n public PercentCoupon(String code, double percent) {\n super(code);\n this.percent = percent;\n }\n}\n\npublic final class FixedCoupon extends Coupon {\n double amount;\n public FixedCoupon(String code, double amount) {\n super(code);\n this.amount = amount;\n }\n}\n```\n\n\n`final` and `sealed` are related but different. `final` allows no extension. `sealed` allows extension by a fixed list.\n\n---\n\n# Sealed Classes vs Enums vs Regular Classes\n\nCompare the three options for modeling a small family of related cases:\n\n\n| Feature | Regular class hierarchy | `enum` | Sealed interface + records |\n| --- | --- | --- | --- |\n| Closed list of cases | No | Yes | Yes |\n| Each case can carry different data | Yes | No, all constants share fields | Yes |\n| Exhaustive switch support | No (needs default) | Yes | Yes |\n| Easy to add new case | Yes (no other code changes) | Yes (other code may break) | Yes (other code may break, intentionally) |\n| Use when | The set of subtypes is open | Constants with identical shape | Variants with different data and a closed set |\n\n\nThe \"other code may break, intentionally\" entry is the point. With an enum or sealed type, adding a new case makes the compiler flag every exhaustive switch that doesn't handle it. That's a feature. It's how the type system helps you keep all the call sites in sync.\n\nA regular class hierarchy keeps switches \"working\" when you add a new subtype, but only by falling through to a `default` branch that probably does the wrong thing for the new case. Silent fallthrough is the failure mode sealed types are designed to prevent.","pageType":"java"}

Sealed Classes

Get Premium