1. Introduction
Java records, introduced in Java 16, offer a concise way to model immutable data. They automatically generate constructors, accessors, equals(), hashCode(), and toString() methods, reducing boilerplate and improving readability.
Despite these benefits, records come with notable limitations. For example, all fields must be declared in the record header, setter methods aren’t allowed, and extensibility is restricted due to their implicit final nature. These constraints make records less than ideal when we need flexible object creation, especially in scenarios involving optional parameters or modifications to existing instances.
To address these limitations, the RecordBuilder library offers a simple yet effective solution. It enhances records with a builder pattern, bridging the gap between the elegance of immutability and the practicality of flexible construction.
2. Getting Started
To begin using RecordBuilder, we first need to add the annotation processor to our build setup. For Maven users, this looks like:
<dependency>
<groupId>io.soabase.record-builder</groupId>
<artifactId>record-builder-core</artifactId>
<version>47</version>
</dependency>
After setup, we’ll annotate our record with @RecordBuilder, and optionally implement the With interface it generates, to enable inline builders and fluent withX() methods.
3. Why Use RecordBuilder?
At first glance, records in their pure form are powerful – they give us concise, immutable data structures with minimal syntax:
public record Person(String name, int age) {}
However, their all-args constructors and lack of setters make them rigid when we need flexibility. In domains where we construct data with optional or varying values, this can quickly become limiting. We could write our own builder to solve this, but doing so reintroduces the very boilerplate that records are meant to eliminate.
RecordBuilder bridges this gap elegantly. With a single annotation, we gain a fluent, safe, and readable way to build and modify record instances. It offers support for staged builders, withX() methods, customization hooks, and more – all while respecting immutability. For example, let’s suppose we annotate our record like this:
@RecordBuilder
public record Person(String name, int age) implements PersonBuilder.With {}
From this, RecordBuilder generates an entire suite of builder methods, withX() accessors, and even static factory helpers, all adhering to the best practices of immutability.
4. Using the Generated Builder
Let’s walk through some practical ways the builder improves our workflow, using the RecordBuilderDemo class.
First, we construct the initial record in the standard way:
Person p1 = new Person("foo", 123);
assertEquals("foo", p1.name());
assertEquals(123, p1.age());
Next, we update individual fields via generated withName() or withAge() methods:
Person p2 = p1.withName("bar");
assertEquals("bar", p2.name());
assertEquals(123, p2.age());
Person p3 = p2.withAge(456);
assertEquals("bar", p3.name());
assertEquals(456, p3.age());
Here, we preserve the immutability and modify only the intended field with each transformation. Even so, RecordBuilder offers more. We can build an entirely new instance based on a previous one with a fluent builder syntax:
Person p4 = p3.with()
.age(101)
.name("baz")
.build();
assertEquals("baz", p4.name());
assertEquals(101, p4.age());
This style improves clarity when multiple fields need to change. It avoids constructor chaining and makes the intent of each transformation explicit. As we’ll see next, the builder also supports inline consumer-based updates for even more expressive modification logic.
5. Advanced Features
One of the highlights of RecordBuilder is the support for inline, consumer-based modifications. Here’s how we can modify a record with a lambda:
Person p5 = p4.with(p -> p.age(200).name("whatever"));
assertEquals("whatever", p5.name());
assertEquals(200, p5.age());
In addition, we can apply conditional logic in the builder context:
Person p6 = p5.with(p -> {
if (p.age() > 13) {
p.name("Teen " + p.name());
} else {
p.name("whatever");
}
});
assertEquals("Teen whatever", p6.name());
assertEquals(200, p6.age());
For more control, we can also use the static builder factory, especially helpful when operating outside the record instance:
Person p7 = PersonBuilder.from(p6)
.with(p -> p.age(300).name("Manual Copy"));
assertEquals("Manual Copy", p7.name());
assertEquals(300, p7.age());
Alternatively, we can directly apply updates to individual fields:
Person p8 = PersonBuilder.from(p6)
.withName("boop");
assertEquals("boop", p8.name());
assertEquals(200, p8.age());
This static form is particularly useful when working with detached builders, external data transformations, or in test utilities. As a result, it provides a clean separation between construction logic and business logic, making the builder pattern a versatile tool across service layers.
6. Customization and Options
With RecordBuilder, we go beyond basic builder generation by offering customization features that let us adapt the builder to our domain-specific needs. This way, we support staged builders for compile-time enforcement of required fields, ensuring that essential values are always set before construction. This helps us to prevent subtle runtime bugs and to improve the safety of our object creation logic.
We can also integrate RecordBuilder with testing frameworks or dependency injection tools, making it an excellent choice for setting up fixtures or injecting partially constructed objects. The ability to align builder logic with application architecture – without losing the benefits of immutability – makes RecordBuilder both flexible and production-ready.
7. Comparison: RecordBuilder vs Manual Builder
It’s entirely possible to write our own builder for a record, especially if it has just a few fields. However, as records grow and evolve, manual builders quickly become a maintenance headache. Each change to the record requires updates across the builder: new fields, constructor logic, withX() methods, and build() logic, all need to be manually adjusted.
RecordBuilder removes that burden through annotation processing. It generates the builder at compile time and keeps it perfectly in sync with the record’s structure. Any modification to the record header – adding, removing, or reordering field – is automatically handled. This eliminates a common source of bugs and improves long-term maintainability.
Additionally, RecordBuilder brings in useful patterns like consumer-based updates and static cloning methods that would require significant effort to implement manually. In terms of developer efficiency, correctness, and consistency, RecordBuilder provides more value than a hand-rolled builder ever could.
8. Conclusion
The RecordBuilder library makes working with Java records easier and more practical. It generates fluent, immutable-friendly builders that remove the need for manual constructors or update methods.
Its real strength is balance: flexible updates without losing immutability, and expressive code without boilerplate. Whether we’re building DTOs, API responses, or config objects, it fits naturally into our workflow. With almost no setup, RecordBuilder becomes a powerful tool for clean, scalable Java development.
The complete source code for this article can be found over on GitHub.
