DEV Community: Dinuka Karunarathna

Java Records Deserve a Mapper Built for Them

Dinuka Karunarathna — Sun, 24 May 2026 01:33:30 +0000

Java Records have been stable since Java 16, and with Java 25 now the LTS baseline, they're showing up everywhere - DTOs, value objects, domain models. Immutable by design, concise, and semantically clear.

But here's the gap nobody talks about: every object mapper in the Java ecosystem was built before Records existed. They were designed around JavaBeans - mutable objects with getters, setters, and no-arg constructors. Records have none of that. So what happens? These libraries bolt on partial Record support as an afterthought, and the seams show.

To be clear: MapStruct and Spring Boot both support Records well when field names match exactly between source and target. The limitation appears in asymmetric mappings - for example, when firstName and lastName on an entity need to map to a single fullName component on a Record DTO. In that case, MapStruct cannot resolve the canonical constructor parameter and silently maps it as null at runtime. Immuto was built specifically to handle these cases using the canonical constructor as the primary contract, turning that silent runtime failure into a compile-time error.

I built Immuto to fill that gap.

The problem with retrofitted Record support

A Record's identity is its canonical constructor:

public record PersonDTO(Long id, String fullName, String email) {}

That constructor is the only way to create a PersonDTO. There are no setters. There is no builder unless you write one yourself. The component accessors are read-only.

Existing mappers were not designed with this in mind. To work with Records, they either:

Generate setter calls that don't exist (and fail at runtime)
Require you to write a mutable builder as a workaround
Fall back to reflection on private fields - bypassing the canonical constructor entirely

These are runtime failures. You don't know something is wrong until you run the code.

What Immuto does differently

Immuto is an annotation processor - it runs during mvn compile, the same way Lombok and the APT-based approach work. It generates plain .java source files that call your record's canonical constructor directly. No reflection. No setters. No runtime surprises.

@RecordMapper
public interface PersonMapper {

    @Mapping(target = "fullName",
             expression = "java(source.firstName() + \" \" + source.lastName())")
    PersonDTO toDto(PersonEntity source);

    @InheritInverseConfiguration(name = "toDto")
    PersonEntity toEntity(PersonDTO source);
}

After mvn compile, Immuto writes PersonMapperImpl.java into target/generated-sources. It looks exactly like code you'd write by hand:

@Generated("io.github.karunarathnad.immuto.processor.RecordMapperProcessor")
public final class PersonMapperImpl implements PersonMapper, ImmutoMapper {

    @Override
    public PersonDTO toDto(PersonEntity source) {
        if (source == null) return null;
        return new PersonDTO(
            source.id(),
            source.firstName() + " " + source.lastName(),
            source.email()
        );
    }
}

Canonical constructor. Always. That's the contract Immuto enforces.

Compile-time validation

If a record component can't be mapped, the build fails - not at runtime, not in a test, but during compilation.

Unmapped component → build error
Type mismatch with no registered converter → build error
@RecordMapper on a class instead of an interface → build error

This is the behaviour Records deserve. They were designed to be explicit and safe; your mapper should be too.

Key features

Nested records - mapped recursively by matching component names. Use @Mapping(expression=...) for asymmetric nesting.

Bidirectional mapping via @InheritInverseConfiguration - define toDto, get toEntity for free.

@NullSafe - wraps the result in Optional.ofNullable(...) at the call site:

@NullSafe
Optional<AddressDTO> toAddressDto(AddressEntity entity);

Sealed class support - Immuto understands sealed hierarchies, something no existing mapper handles.

Lifecycle hooks - @BeforeMapping and @AfterMapping methods are inlined into the generated code. No AOP, no proxy.

Custom type converters:

@Named("isoDate")
public class IsoDateConverter implements TypeConverter<LocalDate, String> {
    @Override
    public String convert(LocalDate source, MappingContext ctx) {
        return source == null ? null : source.toString();
    }
}

Fluent runtime API - for tests or dynamic environments where APT isn't available:

FluentMapper<PersonEntity, PersonDTO> mapper = FluentMapper
    .from(PersonEntity.class)
    .to(PersonDTO.class)
    .override("fullName", p -> p.firstName() + " " + p.lastName())
    .build();

Note: FluentMapper does use reflection - it's the explicit opt-in escape hatch, not the default path.

Getting started

<dependency>
    <groupId>io.github.karunarathnad</groupId>
    <artifactId>immuto-annotations</artifactId>
    <version>1.1.0</version>
</dependency>

<dependency>
    <groupId>io.github.karunarathnad</groupId>
    <artifactId>immuto-core</artifactId>
    <version>1.1.0</version>
</dependency>

<dependency>
    <groupId>io.github.karunarathnad</groupId>
    <artifactId>immuto-processor</artifactId>
    <version>1.1.0</version>
    <scope>provided</scope>
</dependency>

Add the processor path to the compiler plugin:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <annotationProcessorPaths>
            <path>
                <groupId>io.github.karunarathnad</groupId>
                <artifactId>immuto-processor</artifactId>
                <version>1.1.0</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

Then annotate an interface, run mvn compile, and use it:

PersonMapper mapper = Immuto.getMapper(PersonMapper.class);
PersonDTO dto = mapper.toDto(entity);

Why now

Records have been production-ready since Java 16, fully available through both the Java 17 and Java 21 LTS cycles. Java 25 is now the current LTS (released September 2025), with Java 21 as the previous LTS. As more codebases have adopted Records across these LTS versions, the need for tooling that treats them as first-class citizens - not an edge case - has grown with it.

Immuto is on Maven Central, Apache 2.0 licensed, and under active development.

Stop Writing Webhook Boilerplate in Spring Boot

Dinuka Karunarathna — Sun, 17 May 2026 00:52:13 +0000

If you've ever needed to send outgoing webhooks from a Spring Boot application, you know the drill. You wire up an HTTP client, implement HMAC signing, add retry logic, bolt on a circuit breaker, set up an async thread pool, and somehow fit audit logging in too, before you've even written a single line of business logic.

I got tired of doing this repeatedly across projects, so I built
spring-webhook-sender - a Spring Boot 3.x starter that handles all of it for you.

What it does

Drop in one dependency and inject WebhookClient. That's it. Under the hood it handles:

HMAC-SHA256 signing - every request gets an X-Webhook-Signature: sha256=<hmac> header automatically
Retry with exponential backoff - 5xx and network errors are retried; 4xx are not
HTTP 429 Retry-After support - respects the server's retry window
Per-endpoint circuit breaker - powered by Resilience4j; a broken endpoint only trips its own circuit
Non-blocking async dispatch - sendAsync() returns a CompletableFuture, your thread is never blocked
Audit logging - SLF4J by default, pluggable to a database via a single bean

Installation

<dependency>
    <groupId>io.github.karunarathnad</groupId>
    <artifactId>spring-webhook-sender</artifactId>
    <version>2.0.1</version>
</dependency>

Requires Java 17+ and Spring Boot 3.2+. No extra configuration needed — Spring Boot auto-configuration wires everything up.

Usage

@Service
public class OrderService {

    @Autowired
    private WebhookClient webhookClient;

    private static final WebhookEndpoint PAYMENT_ENDPOINT = WebhookEndpoint.builder()
            .id("payment-service")
            .targetUrl("https://payments.example.com/webhooks")
            .secret(System.getenv("PAYMENT_WEBHOOK_SECRET"))
            .build();

    public void onOrderCreated(Order order) {
        WebhookEvent event = WebhookEvent.builder()
                .eventType("order.created")
                .payload(order)
                .build();

        webhookClient.sendAsync(event, PAYMENT_ENDPOINT)
                .thenAccept(result -> log.info("delivered={} attempts={}", 
                    result.success(), result.totalAttempts()));
    }
}

The JSON payload sent to the endpoint looks like this:

{
  "eventId": "a3f1c2d4-...",
  "eventType": "order.created",
  "occurredAt": "2026-05-10T08:30:00Z",
  "payload": { "orderId": "ORD-001", "amount": 99.99 }
}

Configuration

All settings have sensible defaults. Override only what you need in application.yml:

webhook:
  retry:
    max-attempts: 3
    initial-interval: 1s
    multiplier: 2.0
    max-interval: 30s
  circuit-breaker:
    failure-rate-threshold: 50
    minimum-number-of-calls: 10
  async:
    core-pool-size: 4
    max-pool-size: 16

Extending

Need to persist delivery records to a database? Register one bean:

@Bean
public AuditLogger webhookAuditLogger(WebhookAuditRepository repo) {
    return record -> repo.save(toEntity(record));
}

Need a custom signing strategy? Override SignatureStrategy. Need snake_case JSON? Override webhookObjectMapper. The library gets out of your way when you need it to.

Verifying on the receiving side

Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(UTF_8), "HmacSHA256"));
String expected = "sha256=" + HexFormat.of().formatHex(mac.doFinal(rawBody.getBytes(UTF_8)));
String received = request.getHeader("X-Webhook-Signature");

// constant-time comparison to prevent timing attacks
boolean valid = MessageDigest.isEqual(expected.getBytes(UTF_8), received.getBytes(UTF_8));