Java Sealed Classes and Exhaustive Pattern Matching in Practice

Java Sealed Classes, officially released in Java 17, are changing the way developers design type hierarchies. Combined with the ongoing evolution of Pattern Matching, a safer and more expressive Java programming paradigm is taking shape. Starting from the language design motivation and incorporating perspectives from community discussions, this article analyzes how sealed classes and exhaustiveness checking work together, and how to use them effectively in real code.

Why Sealed Classes Are Needed

In traditional Java, an interface or abstract class can be implemented or extended by any number of classes, unless limited constraints are imposed through access control such as package-private. This openness brings flexibility, but it also makes it impossible to know "how many possibilities this type actually has." When you write a switch to handle different types, the compiler cannot confirm whether you have covered all cases and can only rely on a default branch as a fallback.

Sealed classes explicitly declare the permitted subtypes through a permits clause, turning the inheritance relationship from "open" to "controlled." The direct benefit is that the compiler knows the complete set of subtypes and can therefore determine whether branches are exhaustive. For library authors, this means the API can be safely extended without worrying about breaking users' switches; for users, a missing branch becomes a compile error instead of a bug exposed only at runtime.

According to discussions on Hacker News, many developers believe the most valuable scenario for sealed classes is domain modeling—using a closed set of variants to express business states, rather than simulating them with enums plus fields.

Package-private and module system constraints: Traditional Java restricts inheritance through package-private access (that is, no access modifier), allowing only classes in the same package to inherit. But this depends on developers respecting package boundaries and completely fails across packages. After the introduction of the module system (JPMS), package visibility can be controlled through exports, indirectly restricting inheritance, but it still cannot precisely specify permitted subtypes. The permits clause of sealed classes provides an explicit, compile-time-enforced whitelist mechanism, and subclasses must be in the same module (or the same package, if modules are not used). This is more precise than package-private and more direct than the module system.

How Exhaustive Pattern Matching Works

Pattern matching allows switch to directly destructure and discriminate on types. Combined with sealed classes, the compiler can verify whether all permitted subclasses are handled. If a subtype is missing, a compile-time error occurs; this is called exhaustiveness checking.

The value of this check is that it turns "forgetting to handle a new branch" from a runtime exception into a compile-time error. When a library author adds a new permitted subtype, all code that relies on exhaustive switch fails at compile time, forcing callers to explicitly handle the new case. This contrasts sharply with the silent behavior of traditional default branches—the latter often causes new types to be quietly lumped into default logic, producing hard-to-detect defects.

It is worth noting that exhaustiveness applies only to sealed hierarchies. For ordinary open interfaces, the compiler still requires a default branch, and the analysis capability of pattern matching is limited.

Implementation mechanism of exhaustiveness checking: The compiler obtains the complete set of direct subtypes from the permits list of the sealed class and recursively analyzes them together with the sealedness of the subtypes. If a subtype is also sealed, it continues to expand; if a subtype is final or non-sealed (but already listed in permits), it is treated as a leaf node. For a non-sealed subclass of a sealed interface, the compiler treats it as an open type and therefore requires a default branch. This analysis is completed at compile time and does not rely on runtime reflection, so it introduces no performance overhead.

Design Trade-offs and Common Misconceptions

The choice regarding the default branch is one of the focal points of community discussion. Adding default disables exhaustiveness checking, so new subtypes no longer trigger compile errors. Therefore, when using sealed classes, avoid writing default unless fallback logic is truly needed. This point has been repeatedly emphasized in discussions across multiple technical communities.

Another misconception is treating sealed classes as a replacement for enums. Subtypes of sealed classes can carry their own different states and methods, offering stronger expressiveness; but if it is merely a fixed set of constants, enums remain the lighter-weight choice. The choice between the two depends on whether polymorphic behavior and differentiated data are needed.

In addition, the permits list of a sealed class must work with subclass declarations, and subclasses must be in the same module (or the same package, depending on the module system configuration). This imposes certain constraints on project structure and needs to be evaluated when migrating legacy code.

Semantic versioning and breaking changes: In library design, adding a permitted subtype changes the closed set of the sealed hierarchy and causes all client code that relies on exhaustive switch to fail compilation. Under semantic versioning conventions, this is an incompatible API change and should bump the major version. If backward compatibility is desired, library authors can design the sealed class to be extensible (for example, by providing a non-sealed subclass), but this sacrifices the advantages of exhaustiveness checking. Therefore, the use of sealed classes requires a trade-off between API stability and safety.

Practical Application Recommendations

Using sealed interfaces in domain models to express state machines or result types is a relatively mature practice. For example, modeling operation results as three closed variants—success, failure, and in progress—and handling them with an exhaustive switch is both clear and safe.

In library design, sealed classes can serve as a contract: clearly telling users that the set of types is closed, so they can confidently write exhaustive branches. This requires documenting that adding subtypes is a breaking change and follows semantic versioning conventions.

On the tooling side, mainstream IDEs already support prompts for generating missing branches in sealed hierarchies, forming a double safeguard together with the compiler's exhaustiveness check.

Conclusion

The combination of sealed classes and exhaustive pattern matching turns the closedness of a type hierarchy into a compile-time safety net. Its core value is not syntactic sugar, but making "handling all cases" a constraint that can be verified by machines. Using them appropriately, avoiding unnecessary default branches, and distinguishing their applicable boundaries from enums are the keys to successful adoption.

One-line Summary

Combining sealed classes with exhaustive pattern matching turns type closedness into a compile-time safety net.

Paragraph Summary

Java sealed classes explicitly declare permitted subtypes through the permits clause, enabling the compiler to know the complete set of types. Combined with the exhaustiveness checking of pattern matching, missing switch branches are promoted from runtime errors to compile-time errors, thereby improving code safety. The article analyzes the design motivation of sealed classes and the working principles of exhaustiveness checking, and discusses practical points such as avoiding unnecessary default branches, distinguishing applicable boundaries from enums, and being aware of the breaking nature of adding subtypes. Sealed classes are particularly suitable for domain modeling and library design, but their constraints on project structure need to be evaluated.