Java has long been known for its verbosity, especially when defining simple data carriers. Prior to Java 14, creating a basic data class involved writing a considerable amount of boilerplate code: constructors, getters, equals(), hashCode(), and toString(). This all changed with the introduction of records, a feature aimed at simplifying the declaration of immutable data classes.
In this article, we’ll explore what Java record classes are, why they matter, best practices, and real-world scenarios where they shine. Examples and sources are included throughout for clarity.
What Are Records in Java?
Introduced as a preview feature in Java 14 and made stable in Java 16, a record is a special kind of class in Java meant to hold immutable data. Here’s the syntax:
public record Person(String name, int age) {}
This single line replaces 50+ lines of boilerplate you’d write for a typical POJO (Plain Old Java Object).
✅ Compiler-Generated Members
When you declare a record, Java automatically provides:
- A constructor
gettersfor each componentequals(),hashCode(), andtoString()finalfields
According to Oracle’s documentation, records are a concise way to model data-as-data.
Best Practices for Using Java Records
1. Use Records for Immutable Data Models
Records are inherently immutable. Once created, their fields cannot be modified. This makes them ideal for:
- DTOs (Data Transfer Objects)
- Event payloads
- API responses
- Database row mappings (read-only)
public record Order(String id, String productId, int quantity) {}
Tip: Prefer records over traditional classes when mutability is not required.
2. Avoid Business Logic Inside Records
Records are meant to model data, not behavior. While you can add methods, it’s best to avoid complex logic.
public record Product(String id, double price) {
public double discountedPrice(double discountRate) {
return price * (1 - discountRate);
}
}
✅ Okay: Small utility methods
❌ Avoid: Embedding service logic or stateful behaviors
3. Use Compact Constructors for Validation
You can validate input using a compact constructor:
public record User(String username, String email) {
public User {
if (username == null || username.isBlank()) {
throw new IllegalArgumentException("Username cannot be blank");
}
}
}
Compact constructors are ideal for enforcing invariants while preserving brevity.
4. Avoid Setters and Mutability Hacks
The main benefit of records is immutability. Trying to work around it defeats the purpose. Avoid reflections or bytecode manipulations that attempt to mutate fields.
5. Be Cautious When Using with ORM Frameworks
Most ORM tools like Hibernate rely on no-arg constructors and mutable fields. Since records don’t allow these, using them directly with JPA entities is discouraged.
Alternative: Use records for projections or DTOs, not entity classes.
Example with Spring Data JPA projection:
public interface CustomerView {
String name();
String email();
}
Or using a record for API response:
public record CustomerDto(String name, String email) {}
Source: Spring Documentation on Projections
Real-World Use Cases
1. DTOs in REST APIs
In a Spring Boot app:
@RestController
@RequestMapping("/api/orders")
public class OrderController {
@GetMapping("/{id}")
public OrderDto getOrder(@PathVariable String id) {
return new OrderDto(id, "Widget", 10);
}
public record OrderDto(String id, String productName, int quantity) {}
}
Records reduce boilerplate and make DTOs concise and clear.
2. Pattern Matching in Switch Statements
With Java 21’s preview of pattern matching for switch, records can work seamlessly:
sealed interface Shape permits Circle, Rectangle {}
record Circle(double radius) implements Shape {}
record Rectangle(double width, double height) implements Shape {}
double area(Shape shape) {
return switch (shape) {
case Circle c -> Math.PI * c.radius() * c.radius();
case Rectangle r -> r.width() * r.height();
};
}
Source: JEP 441 – Pattern Matching for switch
3. Kafka Message Payloads
In an event-driven architecture using Kafka:
public record UserRegisteredEvent(String userId, String email, Instant registeredAt) {}
Records ensure message immutability and clarity in serialization.
4. Immutable Configuration Objects
For services needing simple configuration values:
public record AppConfig(String host, int port, boolean sslEnabled) {}
Combine with a configuration parser to load from YAML or JSON.
Records vs. Lombok
Many developers used Project Lombok to avoid boilerplate:
@Data
@AllArgsConstructor
public class Customer {
private final String name;
private final String email;
}
However, Lombok adds compile-time dependencies and complexity. With records, the same can be written as:
public record Customer(String name, String email) {}
🔁 Recommendation: Use records for simple cases; fall back to Lombok if more customization or mutability is needed.
Limitations of Records
- No field mutation (by design)
- No inheritance (records implicitly extend
java.lang.Record) - Cannot be abstract
- Limited to final fields and canonical constructors
References
- Oracle Docs on Records: https://docs.oracle.com/en/java/javase/17/language/records.html
- JEP 395: Records (Standard): https://openjdk.org/jeps/395
- Spring Data Projections: https://docs.spring.io/spring-data/jpa/docs/current/reference/html/#projections
- JEP 441: Pattern Matching for switch: https://openjdk.org/jeps/441
Conclusion
Java record classes are a modern, concise, and powerful way to represent immutable data. They reduce boilerplate and improve code clarity, especially in DTOs, APIs, and event payloads. While not a fit for all use cases—especially those requiring mutability or ORM compatibility—records are a go-to choice for many common scenarios.
Embrace them in your modern Java projects and see your code become cleaner, safer, and more expressive.
