Introduction
Java Records, introduced in Java 14 and finalized in Java 16, provide a compact syntax for declaring data carrier classes. With Java 21's Pattern Matching for switch and Record Patterns, we can now deconstruct records in a declarative way, especially powerful when dealing with nested data structures. Nested record patterns allow for elegant, type-safe decomposition of complex object graphs in a single operation.
This guide explores nested record patterns through practical examples, demonstrating how to simplify data processing and validation in modern Java applications.
Basic Record Patterns
1. Simple Record Definitions
// Basic record definitions for a e-commerce domain
public record Address(
String street,
String city,
String state,
String zipCode
) {}
public record Customer(
String id,
String name,
Address address,
String email
) {}
public record LineItem(
String productId,
String productName,
int quantity,
double price
) {}
public record Order(
String orderId,
Customer customer,
List<LineItem> items,
OrderStatus status,
LocalDateTime orderDate
) {}
public enum OrderStatus {
PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED
}
2. Basic Record Pattern Matching
public class BasicRecordPatterns {
// Traditional approach without pattern matching
public static String getCustomerCityTraditional(Customer customer) {
if (customer != null && customer.address() != null) {
return customer.address().city();
}
return "Unknown";
}
// With record patterns (Java 21+)
public static String getCustomerCityModern(Object obj) {
if (obj instanceof Customer(String id, String name, Address street, String city, String state, String zipCode), String email)) {
return city;
}
return "Unknown";
}
// Pattern matching with switch expressions
public static String describeOrderTraditional(Order order) {
if (order.status() == OrderStatus.PENDING) {
return "Order is pending confirmation";
} else if (order.status() == OrderStatus.SHIPPED) {
return "Order has been shipped";
}
return "Order status: " + order.status();
}
public static String describeOrderModern(Object obj) {
return switch (obj) {
case Order(String id, Customer customer, List<LineItem> items, OrderStatus status, LocalDateTime date)
when status == OrderStatus.PENDING -> "Order %s is pending confirmation".formatted(id);
case Order(String id, Customer customer, List<LineItem> items, OrderStatus status, LocalDateTime date)
when status == OrderStatus.SHIPPED -> "Order %s has been shipped to %s".formatted(id, customer.name());
case Order order -> "Order status: " + order.status();
case null -> "No order provided";
default -> "Unknown object: " + obj.getClass().getSimpleName();
};
}
}
Nested Record Patterns
1. Deeply Nested Data Structures
// Complex domain models for nested patterns
public record GeoPoint(double latitude, double longitude) {}
public record Location(String name, GeoPoint coordinates, String type) {}
public record ProductCategory(String id, String name, String description) {}
public record Product(String id, String name, ProductCategory category, double price, Location warehouse) {}
public record PaymentInfo(
String paymentMethod,
String transactionId,
double amount,
LocalDateTime paymentDate,
PaymentStatus status
) {}
public record ShippingDetails(
Address shippingAddress,
String carrier,
String trackingNumber,
LocalDateTime estimatedDelivery
) {}
public record CompleteOrder(
String orderId,
Customer customer,
List<LineItem> items,
PaymentInfo payment,
ShippingDetails shipping,
OrderStatus status
) {}
2. Nested Pattern Deconstruction
public class NestedRecordPatterns {
/**
* Deeply nested pattern matching for order validation
*/
public static ValidationResult validateOrder(Object obj) {
return switch (obj) {
case CompleteOrder(
String orderId,
Customer(String customerId, String customerName, Address custAddress, String email),
List<LineItem> items,
PaymentInfo(String paymentMethod, String transactionId, double amount, LocalDateTime paymentDate, PaymentStatus paymentStatus),
ShippingDetails(Address shippingAddress, String carrier, String trackingNumber, LocalDateTime deliveryDate),
OrderStatus status
) when paymentStatus == PaymentStatus.PAID -> {
yield new ValidationResult(orderId, true, "Order is fully paid and ready for shipping");
}
case CompleteOrder(
String orderId,
Customer customer,
List<LineItem> items,
PaymentInfo paymentMethod, String transactionId, double amount, LocalDateTime paymentDate, PaymentStatus paymentStatus),
ShippingDetails shipping,
OrderStatus status
) when paymentStatus == PaymentStatus.PENDING -> {
yield new ValidationResult(orderId, false, "Order payment is pending");
}
case CompleteOrder order -> {
yield new ValidationResult(order.orderId(), false, "Order validation failed");
}
case null -> new ValidationResult("null", false, "No order provided");
default -> new ValidationResult("unknown", false, "Invalid object type: " + obj.getClass().getSimpleName());
};
}
/**
* Extract shipping information using nested patterns
*/
public static String extractShippingCarrier(Object obj) {
return switch (obj) {
case CompleteOrder(
String orderId,
Customer customer,
List<LineItem> items,
PaymentInfo payment,
ShippingDetails(Address address, String carrier, String tracking, LocalDateTime delivery),
OrderStatus status
) -> carrier;
case null -> "No carrier";
default -> "Unknown";
};
}
/**
* Complex validation with multiple nested conditions
*/
public static boolean isExpressShippingEligible(Object obj) {
return switch (obj) {
case CompleteOrder(
String orderId,
Customer(String custId, String name, Address(String street, String city, String state, String zip), String email),
List<LineItem> items,
PaymentInfo payment,
ShippingDetails shipping,
OrderStatus status
) when items.size() <= 5 &&
!city.equals("Remote") &&
payment.amount() > 50.0 -> true;
default -> false;
};
}
public record ValidationResult(String orderId, boolean isValid, String message) {}
}
Advanced Nested Patterns with Collections
1. Pattern Matching with Lists and Arrays
public class CollectionPatterns {
/**
* Process order items using nested patterns with collections
*/
public static double calculateOrderTotal(Object obj) {
return switch (obj) {
case CompleteOrder(
String orderId,
Customer customer,
List<LineItem> items,
PaymentInfo payment,
ShippingDetails shipping,
OrderStatus status
) -> items.stream()
.mapToDouble(LineItem::price)
.sum();
default -> 0.0;
};
}
/**
* Complex pattern with list decomposition (Java 21+)
* Note: List patterns are a preview feature in Java 21
*/
public static String analyzeOrderItems(Object obj) {
return switch (obj) {
case CompleteOrder(
String orderId,
Customer customer,
List<LineItem> items, // Can't directly pattern match list contents yet
PaymentInfo payment,
ShippingDetails shipping,
OrderStatus status
) when !items.isEmpty() -> {
LineItem firstItem = items.get(0);
yield "First item: %s, Total items: %d".formatted(firstItem.productName(), items.size());
}
case CompleteOrder order when order.items().isEmpty() -> "Empty order";
default -> "Invalid order";
};
}
/**
* Pattern matching with array decomposition (Preview feature)
*/
public static String processCoordinates(Object obj) {
return switch (obj) {
case GeoPoint(double lat, double lon) when lat > 0 && lon > 0 ->
"Northern and Eastern hemisphere: (%f, %f)".formatted(lat, lon);
case GeoPoint(double lat, double lon) when lat < 0 && lon > 0 ->
"Southern and Eastern hemisphere: (%f, %f)".formatted(lat, lon);
case GeoPoint(double lat, double lon) ->
"Coordinates: (%f, %f)".formatted(lat, lon);
default -> "Not a geographic point";
};
}
}
Real-World Use Cases
1. E-Commerce Order Processing
public class OrderProcessor {
/**
* Process different order types using nested patterns
*/
public static ProcessingResult processOrder(Object order) {
return switch (order) {
// Digital order - no shipping needed
case CompleteOrder(
String id,
Customer customer,
List<LineItem> items,
PaymentInfo payment,
ShippingDetails shipping,
OrderStatus status
) when items.stream().allMatch(item -> item.productName().contains("E-Book")) -> {
yield new ProcessingResult(id, "DIGITAL", "Send download links to " + customer.email());
}
// International order - customs documentation needed
case CompleteOrder(
String id,
Customer(String custId, String name, Address(String street, String city, String state, String zip), String email),
List<LineItem> items,
PaymentInfo payment,
ShippingDetails shipping,
OrderStatus status
) when !zip.startsWith("US") -> {
yield new ProcessingResult(id, "INTERNATIONAL", "Generate customs forms for shipping to " + zip);
}
// High-value order - special handling
case CompleteOrder(
String id,
Customer customer,
List<LineItem> items,
PaymentInfo(String method, String txId, double amount, LocalDateTime date, PaymentStatus pStatus),
ShippingDetails shipping,
OrderStatus status
) when amount > 1000.0 -> {
yield new ProcessingResult(id, "HIGH_VALUE", "Requires manager approval and insurance");
}
// Standard domestic order
case CompleteOrder order -> {
yield new ProcessingResult(order.orderId(), "STANDARD", "Process for standard shipping");
}
case null -> new ProcessingResult("null", "ERROR", "No order provided");
default -> new ProcessingResult("unknown", "ERROR", "Invalid order type");
};
}
/**
* Validate customer address using nested patterns
*/
public static AddressValidationResult validateAddress(Object obj) {
return switch (obj) {
case Customer(String id, String name, Address(String street, String city, String state, String zip), String email)
when street != null && !street.isBlank() &&
city != null && !city.isBlank() &&
state != null && state.length() == 2 &&
zip != null && zip.matches("\\d{5}(-\\d{4})?") -> {
yield new AddressValidationResult(true, "Address is valid", zip);
}
case Customer customer -> {
yield new AddressValidationResult(false, "Invalid customer address", "unknown");
}
default -> new AddressValidationResult(false, "Not a customer object", "unknown");
};
}
public record ProcessingResult(String orderId, String orderType, String instructions) {}
public record AddressValidationResult(boolean isValid, String message, String zipCode) {}
}
2. Financial Transaction Analysis
// Financial domain records
public record Account(String accountNumber, String accountType, double balance) {}
public record Transaction(
String transactionId,
Account fromAccount,
Account toAccount,
double amount,
LocalDateTime timestamp,
String description
) {}
public record TransactionAnalysisResult(
String transactionId,
String riskLevel,
String reason,
boolean requiresReview
) {}
public class FinancialAnalyzer {
/**
* Analyze transactions using nested record patterns
*/
public static TransactionAnalysisResult analyzeTransaction(Object obj) {
return switch (obj) {
// High-risk: Large amount from savings account
case Transaction(
String txId,
Account(String fromAccNum, String fromType, double fromBalance),
Account toAccount,
double amount,
LocalDateTime time,
String desc
) when "SAVINGS".equals(fromType) && amount > 10000 -> {
yield new TransactionAnalysisResult(txId, "HIGH",
"Large withdrawal from savings account", true);
}
// Suspicious: Rapid consecutive transactions
case Transaction(
String txId,
Account fromAccount,
Account(String toAccNum, String toType, double toBalance),
double amount,
LocalDateTime time,
String desc
) when amount > 5000 && time.getHour() >= 23 -> {
yield new TransactionAnalysisResult(txId, "MEDIUM",
"Large late-night transaction", true);
}
// Normal transaction
case Transaction transaction -> {
yield new TransactionAnalysisResult(transaction.transactionId(),
"LOW", "Normal transaction", false);
}
default -> new TransactionAnalysisResult("unknown", "UNKNOWN",
"Invalid transaction object", true);
};
}
/**
* Pattern matching for transaction categorization
*/
public static String categorizeTransaction(Object obj) {
return switch (obj) {
case Transaction(
String txId,
Account from,
Account to,
double amount,
LocalDateTime time,
String desc
) when desc != null && desc.toLowerCase().contains("salary") -> "INCOME";
case Transaction(
String txId,
Account from,
Account to,
double amount,
LocalDateTime time,
String desc
) when desc != null && (
desc.toLowerCase().contains("grocery") ||
desc.toLowerCase().contains("supermarket")) -> "GROCERIES";
case Transaction tx when tx.amount() < 0 -> "REFUND";
case Transaction tx -> "OTHER";
default -> "UNKNOWN";
};
}
}
Error Handling and Edge Cases
1. Robust Pattern Matching with Null Safety
public class RobustPatternMatching {
/**
* Safe pattern matching with comprehensive null checks
*/
public static String safeExtractCustomerInfo(Object obj) {
return switch (obj) {
case CompleteOrder(
String orderId,
Customer(String customerId, String name, Address address, String email),
List<LineItem> items,
PaymentInfo payment,
ShippingDetails shipping,
OrderStatus status
) when orderId != null &&
customerId != null &&
name != null &&
email != null -> {
yield "Order: %s, Customer: %s (%s)".formatted(orderId, name, email);
}
case CompleteOrder order when order.customer() == null ->
"Order %s has no customer".formatted(order.orderId());
case CompleteOrder order ->
"Order %s - incomplete customer data".formatted(order.orderId());
case null -> "Null object provided";
default -> "Not a complete order";
};
}
/**
* Handling optional fields with patterns
*/
public static String extractTrackingInfo(Object obj) {
return switch (obj) {
case CompleteOrder(
String orderId,
Customer customer,
List<LineItem> items,
PaymentInfo payment,
ShippingDetails(Address addr, String carrier, String tracking, LocalDateTime delivery),
OrderStatus status
) when tracking != null && !tracking.isBlank() ->
"Tracking: %s via %s".formatted(tracking, carrier);
case CompleteOrder order ->
"No tracking available for order %s".formatted(order.orderId());
default -> "Invalid order object";
};
}
}
Performance Considerations and Best Practices
1. Efficient Pattern Matching
public class PatternMatchingBestPractices {
/**
* Order patterns from most specific to least specific
*/
public static String efficientOrderProcessing(Object obj) {
return switch (obj) {
// Most specific case first
case CompleteOrder(
String id,
Customer cust,
List<LineItem> items,
PaymentInfo(String pm, String txId, double amt, LocalDateTime dt, PaymentStatus.PAID),
ShippingDetails shipping,
OrderStatus.CONFIRMED
) -> "Paid and confirmed order: " + id;
// Then less specific
case CompleteOrder(
String id,
Customer cust,
List<LineItem> items,
PaymentInfo payment,
ShippingDetails shipping,
OrderStatus status
) when status == OrderStatus.CANCELLED -> "Cancelled order: " + id;
// Most general last
case CompleteOrder order -> "Processing order: " + order.orderId();
default -> "Unknown object";
};
}
/**
* Avoid overly complex nested patterns
*/
public static String readablePatternMatching(Object obj) {
// Instead of one massive pattern, break it down
if (obj instanceof CompleteOrder order) {
return processCompleteOrder(order);
}
return "Not a complete order";
}
private static String processCompleteOrder(CompleteOrder order) {
return switch (order) {
case CompleteOrder(String id, Customer cust, List<LineItem> items, PaymentInfo payment, ShippingDetails shipping, OrderStatus status)
when status == OrderStatus.SHIPPED ->
"Shipped order: " + id + " to " + cust.name();
default -> "Processing order: " + order.orderId();
};
}
}
Testing Nested Record Patterns
1. Comprehensive Test Suite
class NestedRecordPatternsTest {
@Test
void testCompleteOrderPatternMatching() {
Address address = new Address("123 Main St", "Springfield", "IL", "62701");
Customer customer = new Customer("cust123", "John Doe", address, "[email protected]");
LineItem item1 = new LineItem("prod1", "Java Book", 1, 49.99);
LineItem item2 = new LineItem("prod2", "Coffee Mug", 2, 15.99);
PaymentInfo payment = new PaymentInfo("CREDIT_CARD", "txn123", 81.97,
LocalDateTime.now(), PaymentStatus.PAID);
ShippingDetails shipping = new ShippingDetails(address, "UPS", "1Z123456",
LocalDateTime.now().plusDays(3));
CompleteOrder order = new CompleteOrder("order123", customer,
List.of(item1, item2), payment, shipping, OrderStatus.CONFIRMED);
ValidationResult result = NestedRecordPatterns.validateOrder(order);
assertTrue(result.isValid());
assertEquals("order123", result.orderId());
}
@Test
void testFinancialTransactionAnalysis() {
Account fromAccount = new Account("acc123", "CHECKING", 5000.0);
Account toAccount = new Account("acc456", "SAVINGS", 10000.0);
Transaction transaction = new Transaction("txn789", fromAccount, toAccount,
15000.0, LocalDateTime.of(2024, 1, 15, 23, 30), "Large transfer");
TransactionAnalysisResult analysis = FinancialAnalyzer.analyzeTransaction(transaction);
assertEquals("HIGH", analysis.riskLevel());
assertTrue(analysis.requiresReview());
}
@Test
void testNullSafetyInPatterns() {
String result = RobustPatternMatching.safeExtractCustomerInfo(null);
assertEquals("Null object provided", result);
CompleteOrder orderWithNullCustomer = new CompleteOrder("order123", null,
List.of(), null, null, OrderStatus.PENDING);
result = RobustPatternMatching.safeExtractCustomerInfo(orderWithNullCustomer);
assertTrue(result.contains("has no customer"));
}
}
Migration Strategy from Traditional Code
1. Before and After Examples
public class MigrationExamples {
// Traditional imperative style
public static String processOrderTraditional(CompleteOrder order) {
if (order == null) {
return "No order provided";
}
if (order.customer() == null) {
return "Order " + order.orderId() + " has no customer";
}
if (order.payment() == null) {
return "Order " + order.orderId() + " has no payment info";
}
if (order.payment().status() == PaymentStatus.PAID) {
return "Processing paid order: " + order.orderId();
}
return "Order " + order.orderId() + " not ready for processing";
}
// Modern pattern matching style
public static String processOrderModern(Object obj) {
return switch (obj) {
case CompleteOrder(
String orderId,
Customer customer,
List<LineItem> items,
PaymentInfo(String pm, String txId, double amt, LocalDateTime dt, PaymentStatus.PAID),
ShippingDetails shipping,
OrderStatus status
) -> "Processing paid order: " + orderId;
case CompleteOrder(String orderId, null, List<LineItem> items, PaymentInfo payment, ShippingDetails shipping, OrderStatus status) ->
"Order " + orderId + " has no customer";
case CompleteOrder order ->
"Order " + order.orderId() + " not ready for processing";
case null -> "No order provided";
default -> "Invalid order object";
};
}
}
Conclusion
Nested record patterns in Java 21+ represent a significant leap forward in writing concise, readable, and maintainable code for complex data structures. Key benefits include:
Code Quality Improvements:
- Elimination of boilerplate for data extraction and validation
- Compile-time safety with exhaustive pattern matching
- Improved readability through declarative data decomposition
- Reduced null-checking through integrated null patterns
Performance Advantages:
- Early termination in pattern matching
- Reduced intermediate variables through direct decomposition
- Optimized bytecode through JVM pattern matching support
Best Practices:
- Order patterns from specific to general for efficiency
- Use guard clauses (
when) for additional conditions - Break complex patterns into smaller, readable chunks
- Leverage exhaustive matching in switch expressions
- Combine with sealed interfaces for maximum type safety
Nested record patterns are particularly powerful in domains like:
- E-commerce systems with complex order hierarchies
- Financial applications with transaction processing
- Data validation pipelines with structured data
- API response handling with nested JSON structures
As Java continues to evolve, nested record patterns combined with other modern features like sealed classes and pattern matching will fundamentally change how we write data-oriented Java code, making it more expressive, safe, and maintainable.