Java 21 brought a transformative feature to the language: Record Patterns (JEP 440). After being previewed in Java 19 and 20, this feature is now finalized and fundamentally changes how developers work with structured data. Record patterns enable elegant deconstruction of record values, and when combined with nested patterns, they provide a powerful mechanism for navigating complex data structures without the ceremonial accessor calls that traditionally cluttered Java code.
Understanding Record Patterns
Record patterns extend pattern matching to destructure instances of record classes, enabling more sophisticated data queries. At its core, a record pattern allows you to test whether a value is an instance of a record type and simultaneously extract its components into variables.
record Point(int x, int y) {}
static void printCoordinates(Object obj) {
if (obj instanceof Point(int x, int y)) {
System.out.println("x: " + x + ", y: " + y);
}
}
This example extracts the x and y values from obj directly, automatically calling the Point record’s accessor methods. Compare this to the traditional approach with type patterns:
// Traditional approach
if (obj instanceof Point p) {
System.out.println("x: " + p.x() + ", y: " + p.y());
}
While the difference seems minor in this simple case, the real power emerges with nested records.
The Power of Nested Deconstruction
The real power of deconstructing records is found when a record contains another record. Nested patterns allow you to match against nested record structures in a single, declarative statement.
Let’s examine a practical example with window coordinates:
record Size(int width, int height) {}
record Point(int x, int y) {}
record WindowFrame(Point origin, Size size) {}
Before record patterns, accessing nested components required multiple steps:
// Pre-Java 21 approach
if (obj instanceof WindowFrame wf) {
if (wf.size() != null) {
System.out.println("Height: " + wf.size().height());
}
}
With nested deconstruction, the pattern can be nested, eliminating the need for the null check: if the full pattern matches, all components are guaranteed non-null:
// Java 21 with nested patterns
if (obj instanceof WindowFrame(Point origin, Size(int width, int height))) {
System.out.println("Height: " + height);
}
This code echoes the structure of nested constructors, making the intent clear and removing accidental complexity from navigating objects.
Using var for Type Inference
You can use var in the record pattern’s component list, and the compiler will infer the type of the pattern variables. This makes patterns even more concise:
if (obj instanceof Point(var x, var y)) {
System.out.println(Math.toDegrees(Math.atan2(y, x)));
}
The compiler infers that x and y are of type int based on the Point record definition. Pattern variable names can differ from the record component names, helping make record patterns more flexible and avoiding potential variable name conflicts.
Record Patterns in Switch Expressions
Record patterns work with switch expressions, which now support pattern matching in Java 21. This enables clean, declarative code for handling multiple record types:
sealed interface Shape permits Circle, Rectangle {}
record Circle(double radius) implements Shape {}
record Rectangle(double length, double width) implements Shape {}
static double calculateArea(Shape shape) {
return switch(shape) {
case Circle(double radius) ->
Math.PI * radius * radius;
case Rectangle(double length, double width) ->
length * width;
};
}
Object destructuring extracts the record component values and directly populates them into the pattern variables, removing the need for temporary variables whose only purpose is to provide access to component values.
Deep Nesting: Complex Structures Made Simple
Record patterns can be nested to arbitrary depths. Consider this example from the official JEP:
enum Color { RED, GREEN, BLUE }
record ColoredPoint(Point p, Color c) {}
record ColoredRectangle(ColoredPoint upperLeft, ColoredPoint lowerRight) {}
static void printUpperLeftX(ColoredRectangle r) {
if (r instanceof ColoredRectangle(
ColoredPoint(Point(var x, var y), var color),
var lowerRight)) {
System.out.println("Upper-left x: " + x);
}
}
This example nests record patterns inside other record patterns, allowing direct access to deeply nested components. The pattern matches only if the entire structure is valid and non-null.
Important Constraints
The null value does not match any record pattern. This is a critical safety feature: if any component in a nested pattern is null, the entire pattern fails to match. This built-in null safety eliminates a common source of NullPointerExceptions.
Additionally, the component types in your pattern must match the record’s definition; the compiler will reject incompatible types:
record Point(int x, int y) {}
// Compiler error: pattern type doesn't match component type
if (obj instanceof Point(long x, int y)) { }
Generic Records and Type Inference
The compiler can infer the type arguments for record patterns in all constructs that accept patterns: switch statements, switch expressions, and instanceof expressions:
record Box<T>(T value) {}
static void printBoxContents(Box<String> box) {
// Compiler infers Box<String>(String s)
if (box instanceof Box(var s)) {
System.out.println("Contains: " + s);
}
}
Practical Applications
Record patterns are particularly compelling with nested deconstruction and sealed record hierarchies. Common use cases include:
- Expression trees and AST manipulation: Evaluating or transforming tree structures
- Event processing: Deconstructing event records to access relevant data
- Domain modeling: Working with nested value objects in domain-driven design
- Data transformation: Processing structured data from APIs or databases
Looking Forward
Records and record patterns are an essential element of Java’s emerging data-oriented programming story. Combined with sealed types and switch pattern matching, they enable a more declarative programming style that separates data structure from behavior.
While you need multiple records implementing a common interface for record patterns to be most useful, they represent a significant step toward making Java code more expressive and maintainable. As the ecosystem evolves and libraries adopt these patterns, we’ll likely see new idioms emerge that further leverage this powerful feature.
Conclusion
Record patterns and nested deconstruction in Java 21 eliminate much of the boilerplate traditionally required for working with structured data. By allowing patterns to mirror the structure of your data, they make code more readable and maintainable. Nested patterns elide the accidental complexity of navigating objects so that we can focus on the data expressed by those objects.
For developers working with records, pattern matching, and complex data structures, this feature is not just syntactic sugar—it’s a fundamental improvement in how we express data-oriented logic in Java.
Additional Resources
- JEP 440: Record Patterns – Official specification
- Oracle Java Documentation: Record Patterns – Comprehensive guide
- Inside Java: Record Patterns Tutorial – Practical examples
