DEV Community: Alexey Gavrilov

Record Companion: Simple Builder Pattern for Java Records

Alexey Gavrilov — Sat, 16 Aug 2025 16:03:16 +0000

Building on the foundation of clean record validation

Java Records transformed how we handle immutable data in Java, but they left us with one challenge: creating builder patterns for complex object construction. While Records are perfect for simple data holders, real-world applications often need the flexibility of the builder pattern.

In my previous article about Record constructor validation, I explored how to keep validation logic clean and maintainable. Today, I want to introduce Record Companion - a library that brings the same philosophy of simplicity to builder pattern generation.

The Builder Pattern Problem

Let's say you have a User record:

public record User(String name, int age, String email) {}

Creating instances with all parameters is straightforward:

User user = new User("John Doe", 30, "john@example.com");

But what happens when you need:

Optional parameters
Step-by-step construction
Functional updates
Immutable modifications

You'd typically need to write a lot of boilerplate code. Record Companion solves this with a single annotation.

Enter Record Companion

Record Companion follows the same philosophy I outlined in the validation article: the goal isn't to have the most features—it's to have code that's easy to read, maintain, and debug.

Here's how simple it is:

import io.github.recordcompanion.annotations.Builder;

@Builder
public record User(String name, int age, String email) {}

That's it. One annotation, and you get:

// Create new instances
User user = UserBuilder.builder()
    .name("John Doe")
    .age(30)
    .email("john@example.com")
    .build();

// Create from existing record
User updatedUser = UserBuilder.builder(user)
    .age(31)
    .build();

// Functional updates
User modifiedUser = UserBuilder.with(user, updater ->
    updater.name("Jane Doe").email("jane@example.com")
);

What Record Companion Generates

For each @Builder annotated record, you get two components:

1. Builder Class

A concrete implementation with fluent methods:

public final class UserBuilder implements UserUpdater {
    public UserBuilder name(String name) { ...}
    public UserBuilder age(int age) { ...}
    public UserBuilder email(String email) { ...}
    public User build() { ...}

    // Static factory methods
    public static UserBuilder builder() { ...}
    public static UserBuilder builder(User existing) { ...}
    public static User with(User existing, Consumer<UserUpdater> updater) { ...}
}

2. Updater Interface

For flexible composition and functional updates:

public interface UserUpdater {
    UserUpdater name(String name);
    UserUpdater age(int age);
    UserUpdater email(String email);
}

Advanced Features (Still Simple)

Generic Types

Record Companion handles complex generics naturally:

@Builder
public record Container<T, U extends Number>(
    String name,
    List<T> items,
    Map<String, U> values
) {}

// Usage with proper type inference
Container<String, Integer> container =
    ContainerBuilder.<String, Integer>builder()
        .name("My Container")
        .items(List.of("item1", "item2"))
        .values(Map.of("count", 42))
        .build();

Annotation Copying

For framework integration (like Bean Validation):

@Builder(copyAnnotations = true)
public record ValidatedUser(
    @NotNull @Size(min = 1, max = 100) String name,
    @Min(0) @Max(150) int age,
    @Email String email
) {}

// Generated methods preserve annotations:
// @NotNull @Size(min = 1, max = 100)
// public ValidatedUserBuilder name(String name) { ... }

Bean Validation Integration

Record Companion provides seamless integration with Bean Validation annotations through automatic ValidCheck code generation.

Automatic Validation Code Generation

When you combine @Builder and @ValidCheck with Bean Validation annotations, Record Companion automatically generates validation code:

@Builder
@ValidCheck
public record UserProfile(
    @NotNull @Size(min = 3, max = 20) String username,
    @Min(0) @Max(100) int score,
    @NotEmpty Map<String, String> metadata,
    @Pattern(regexp = "[A-Z]{3}[0-9]{3}") String code
) {
    public UserProfile {
        // Automatic validation using generated check class
        UserProfileCheck.validate(username, score, metadata, code);
    }
}

Comprehensive Bean Validation Support

Record Companion maps Bean Validation annotations directly to ValidCheck API calls:

@NotNull → .notNull(value, fieldName)
@NotEmpty → .notNullOrEmpty(value, fieldName)
@Size(min, max) → .hasLength(value, min, max, fieldName)
@Pattern(regexp) → .matches(value, pattern, fieldName)
@Min + @Max (combined) → .inRange(value, min, max, fieldName)

Generated Validation Classes

For each record with @ValidCheck, you get three convenient validation methods:

// BatchValidator for manual control
UserProfileCheck.check(username, score, metadata, code)

// Validator for immediate validation with chaining
UserProfileCheck.require(username, score, metadata, code)

// Convenience method - validates and throws on failure
UserProfileCheck.validate(username, score, metadata, code)

Generated Validation Chain Example

Here's what the generated validation looks like:

return validator
    .notNull(username, "username")
    .hasLength(username, 3, 20, "username")
    .inRange(score, 0, 100, "score")
    .notNullOrEmpty(metadata, "metadata")
    .matches(code, "[A-Z]{3}[0-9]{3}", "code");

Builder Pattern with Automatic Validation

When you use the builder pattern, validation happens automatically:

// Builder pattern with automatic validation
UserProfile profile = UserProfileBuilder.builder()
    .username("john_doe")
    .score(85)
    .metadata(Map.of("role", "admin"))
    .code("ABC123")
    .build(); // Validation happens automatically

// Functional updates with validation
UserProfile updated = UserProfileBuilder.with(profile, updater ->
    updater.score(95)
); // Re-validates with new values

Getting Started

Add Record Companion to your project:

Maven:

<!-- Record Companion Processor -->
<dependency>
    <groupId>io.github.ag-libs.record-companion</groupId>
    <artifactId>record-companion-processor</artifactId>
    <version>0.1.4</version>
    <scope>provided</scope>
</dependency>

<!-- ValidCheck library (required only for @ValidCheck integration) -->
<dependency>
    <groupId>io.github.ag-libs.validcheck</groupId>
    <artifactId>validcheck</artifactId>
    <version>0.9.4</version>
</dependency>

<!-- Bean Validation API (required only for @ValidCheck integration) -->
<dependency>
    <groupId>javax.validation</groupId>
    <artifactId>validation-api</artifactId>
    <version>2.0.1.Final</version>
    <scope>provided</scope>
</dependency>

Gradle:

// Record Companion Processor
annotationProcessor 'io.github.ag-libs.record-companion:record-companion-builder:0.1.4'
compileOnly 'io.github.ag-libs.record-companion:record-companion-builder:0.1.1'

// ValidCheck library (required only for @ValidCheck integration)
implementation 'io.github.ag-libs.validcheck:validcheck:0.9.4'

// Bean Validation API (required only for @ValidCheck integration)
compileOnly 'javax.validation:validation-api:2.0.1.Final'

That's it. No configuration files, no complex setup.

Requirements

Java 17+ (for record support)
Maven 3.6+ or Gradle 6.0+
Any IDE (no special plugins required)

Alternatives

If you're looking for more features, record-builder is a popular and well-established alternative. It offers more advanced features like "wither" methods and interface-based record generation.

Record Companion focuses on simplicity and ease of use, making it perfect if you just want straightforward builder patterns without the extra bells and whistles.

Conclusion

Java Records gave us immutable data structures. ValidCheck gave us clean validation. Record Companion completes the picture with simple, powerful builder patterns and seamless Bean Validation integration.

The combination of these three - Records + ValidCheck + Record Companion - creates a development experience that's both powerful and maintainable. You get immutability, declarative validation through standard Bean Validation annotations, and flexible construction without drowning in boilerplate.

The automatic Bean Validation mapping means you can use industry-standard validation annotations while still benefiting from ValidCheck's clean API and Record Companion's builder pattern generation.

Try Record Companion in your next project. Your future self (and your teammates) will thank you for choosing simplicity with power.

Resources:

What's your experience with builder patterns in Java? Have you tried Record Companion's Bean Validation features? Share your thoughts in the comments below!

Java Records Constructor Validation: Beyond the Boilerplate

Alexey Gavrilov — Sun, 03 Aug 2025 21:50:26 +0000

Java Records, finalized in Java 16, provide a concise way to create immutable data carriers. But what happens when your clean Record needs to validate its data? Suddenly, that elegant one-liner becomes a validation challenge.

Let me show you three approaches to Record validation I've encountered in production code, and why I ended up building a new solution.

The Problem: Real-World Records Need Validation

Consider this simple user registration scenario:

public record User(String name, String email, int age) {}

Clean, right? But in production, you need validation:

Name: 2-50 characters, not null or empty
Email: valid format, not null
Age: 0-120, reasonable range

Suddenly, your elegant Record isn't so simple anymore.

Approach 1: Manual Validation (The Verbose Way)

The most straightforward approach is manual validation in the compact constructor:

public record User(String name, String email, int age) {
    public User {
        if (name == null || name.trim().isEmpty()) {
            throw new IllegalArgumentException("Name cannot be null or empty");
        }
        if (name.length() < 2 || name.length() > 50) {
            throw new IllegalArgumentException("Name must be between 2 and 50 characters");
        }
        if (email == null || email.trim().isEmpty()) {
            throw new IllegalArgumentException("Email cannot be null or empty");
        }
        if (!email.matches("^[A-Za-z0-9+_.-]+@(.+)$")) {
            throw new IllegalArgumentException("Invalid email format");
        }
        if (age < 0 || age > 120) {
            throw new IllegalArgumentException("Age must be between 0 and 120");
        }
    }
}

Problems:

15+ lines of boilerplate for simple validation
Repetitive null/empty checks
Hard to read the actual business rules
Error messages are inconsistent
Stops at first error (no way to collect all validation issues)

Approach 2: Bean Validation Annotations (The Framework Way)

Let's try Jakarta Bean Validation (formerly JSR 303):

public record User(
    @NotBlank @Size(min = 2, max = 50) String name,
    @NotBlank @Email String email,
    @Min(0) @Max(120) int age
) {
    public User {
        ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
        Validator validator = factory.getValidator();
        Set<ConstraintViolation<User>> violations = validator.validate(this);
        if (!violations.isEmpty()) {
            throw new ConstraintViolationException(violations);
        }
    }
}

Wait, there's a problem! This code looks clean but doesn't actually work. In the compact constructor, when you call validator.validate(this), the Record instance hasn't been fully constructed yet—the fields are not initialized with the parameter values. The validator sees default values (null, 0) instead of your actual parameters.

To make Bean Validation work properly, you'd need to move validation outside the constructor:

public record User(
    @NotBlank @Size(min = 2, max = 50) String name,
    @NotBlank @Email String email,
    @Min(0) @Max(120) int age
) {
    // No validation in constructor!
    public static User createValidated(String name, String email, int age) {
        // Create instance first
        User user = new User(name, email, age);
        // Then validate it
        ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
        Validator validator = factory.getValidator();
        Set<ConstraintViolation<User>> violations = validator.validate(user);
        if (!violations.isEmpty()) {
            throw new ConstraintViolationException(violations);
        }
        return user;
    }
}

But now you have a fundamental problem: you can still create invalid User records directly with new User("", "invalid", -5) and bypass validation entirely. The constructor is public and unvalidated!

Problems:

Complex setup for simple validation
Heavy dependencies (2+ MB of JARs)
Doesn't work with simple validate(this) approach
Either move validation outside constructor (breaks immutability guarantee) or complex workarounds
Reflection-based (performance overhead)
Overkill for basic parameter checking

Advanced Bean Validation Solution

There is a way to make Bean Validation work properly with Records, but it requires significant complexity. Gunnar Morling's approach uses ByteBuddy for compile-time byte code enhancement:

Write a custom ByteBuddy plugin
Configure Maven build-time enhancement
Implement validation interceptors
Set up proper constructor parameter validation

While this works, it adds substantial complexity to your build process and requires deep knowledge of byte code manipulation. For most teams, this level of complexity isn't justified for basic parameter validation.

Approach 3: Lightweight Fluent Validation (The Pragmatic Way)

After wrestling with both approaches in different projects, I wanted something that was:

Explicit and readable
Zero dependencies
Fast (no reflection)
Designed for constructor validation
Capable of collecting all errors or failing fast

This led me to create ValidCheck:

public record User(String name, String email, int age) {
    public User {
        ValidCheck.require()
            .notNullOrEmpty(name, "name")
            .hasLength(name, 2, 50, "name")
            .matches(email, "(?i)^[\\w._%+-]+@[\\w.-]+\\.[A-Z]{2,}$", "email")
            .inRange(age, 0, 120, "age");
    }
}

Usage:

// Valid user - no exceptions
User user = new User("John", "john@example.com", 25);

// Invalid user - clear error message
User invalid = new User("", "invalid", -5);
// Throws: ValidationException: 'name' must not be empty

For collecting all validation errors:

public record CreateUserRequest(String name, String email, Integer age, String phone) {
    public CreateUserRequest {
        ValidCheck.check()
            .notNull(name, "name")
            .hasLength(name, 1, 100, "name")
            .matches(email, "(?i)^[\\w._%+-]+@[\\w.-]+\\.[A-Z]{2,}$", "email")
            .inRange(age, 0, 120, "age")
            .when(phone != null,
                v -> v.matches(phone, "\\d{10}", "phone", "must be 10 digits"))
            .validate(); // Throws with all errors if any validation failed
    }
}

Real-World Example: API DTOs

Here's how ValidCheck looks with a realistic API request object:

public record CreateOrderRequest(
    String customerId,
    List<OrderItem> items,
    String shippingAddress,
    PaymentMethod paymentMethod
) {
    public CreateOrderRequest {
        ValidCheck.require()
            .notNullOrEmpty(customerId, "customerId")
            .matches(customerId, "[A-Z0-9]{8}", "customerId")
            .notNullOrEmpty(items, "items")
            .hasLength(shippingAddress, 10, 200, "shippingAddress")
            .notNull(paymentMethod, "paymentMethod");
    }
}

The validation reads like documentation of your business rules.

IDE-First Design

ValidCheck's API excels at IDE integration, making validation code practically write itself through intelligent autocomplete. As you type ValidCheck.require()., your IDE suggests only relevant validation methods - starting with notNull(), then flowing naturally to type-specific options like hasLength() for strings or inRange() for numbers. After selecting a method, the first parameter is always the value you want to validate, so you naturally type the variable name you're checking - no mental mapping required.

This guided discovery means you rarely need to memorize method names or check documentation. The method chaining reads like natural language, making complex validation both discoverable and maintainable while eliminating the cognitive overhead of remembering syntax.

Conclusion

Java Records provide a clean way to create immutable data carriers, but validation can quickly turn elegant code into verbose boilerplate.

Choose manual validation when you have simple rules and want maximum control.

Choose Bean Validation when you're already invested in the Jakarta ecosystem or need complex validation features.

Consider a lightweight alternative like ValidCheck when you want explicit, readable validation without the framework overhead.

The goal isn't to have the most features—it's to have code that's easy to read, maintain, and debug when things go wrong.

What's your experience with Record validation? Have you found other approaches that work well? I'd love to hear about them in the comments.

About ValidCheck: It's a zero-dependency Java validation library designed specifically for constructor and method parameter validation. You can find it on GitHub or add it to your Maven project:

    <dependency>
      <groupId>io.github.ag-libs.validcheck</groupId>
      <artifactId>validcheck</artifactId>
      <version>0.9.7</version>
    </dependency>

This blog post was written with AI assistance for editing and structure.