DEV Community: Dinuka Karunarathna

MapStruct vs Immuto: Where the Records Gap Actually Is

Dinuka Karunarathna — Sun, 05 Jul 2026 11:15:10 +0000

A follow-up to Java Records deserve a mapper

My earlier post introduced Immuto and made the general case for a mapper designed around Records from day one. This one is narrower and more specific: it walks through exactly where MapStruct, which is the mapper most Java teams already use, runs into friction with Records, with real annotations and real generated code on both sides.

MapStruct is excellent. It’s been the go-to compile-time mapper for a decade, and it has supported Records since 1.4.0 by generating direct calls to the canonical constructor. That part works well. To be fair to it upfront: if your Record fields line up cleanly with your entity fields, MapStruct handles that today with no builder and no factory. The gaps below are specific and narrower than “MapStruct can’t do Records,” since they show up in particular corners: asymmetric mappings, defaults, null handling, and sealed hierarchies.

1.Asymmetric mappings and the reverse direction

Where MapStruct’s constructor-based mapping gets genuinely difficult is asymmetric mappings, meaning cases where a target constructor parameter is built from more than one source field via an expression, and you also want the reverse mapping generated automatically.

// MapStruct: forward direction is fine here
@Mapping(target = "fullName",
    expression = "java(source.firstName() + \" \" + source.lastName())")
PersonDTO toDto(PersonEntity source);

@InheritInverseConfiguration(name = "toDto")
PersonEntity toEntity(PersonDTO source);
// ↑ MapStruct can't invert "firstName() + \" \" + lastName()" back into
//   two separate constructor parameters. It silently passes null for
//   whichever parameter it can't resolve. No compile error, no warning,
//   just a broken PersonEntity at runtime.

Immuto detects the unresolvable parameter at compile time instead of injecting null:

@RecordMapper
public interface PersonMapper {
    @Mapping(target = "fullName", source = "firstName")
    PersonDTO toDto(PersonEntity source);

    @InheritInverseConfiguration(name = "toDto")
    PersonEntity toEntity(PersonDTO source);
    // ↑ if a component genuinely can't be resolved, the build fails
    //   with a named-component error instead of a silent null
}

This is the real, verifiable gap, meaning not “MapStruct can’t map Records,” but rather “MapStruct can’t always invert an asymmetric mapping, and when it can’t, it fails silently instead of at compile time.”

2.Unmapped target components: warning vs. build error

MapStruct’s default unmappedTargetPolicy is WARN. The build succeeds, the field is mapped to null, and the only trace is a compiler warning that's easy to lose in CI output.

// DTO has a 'version' field; entity does not.
// Compiles fine under MapStruct's default WARN policy, so version is null at runtime.
@Mapper
public interface ReportMapper {
    ReportDTO toDto(ReportEntity source);
}

MapStruct can be configured to fail the build (@Mapper(unmappedTargetPolicy = ReportingPolicy.ERROR)), so this isn't a capability gap, it's a default-behavior gap. Immuto just ships with the strict option as the default:

// Immuto: same scenario, build fails until you decide explicitly.
// error: [Immuto] Target component 'version' has no matching source component.
//        Use @Mapping(target="version", ignore=true) to suppress this error.
@RecordMapper
public interface ReportMapper {
    @Mapping(target = "version", ignore = true)  // must be explicit
    ReportDTO toDto(ReportEntity source);
}

(Immuto exposes the same opt-out in reverse: @RecordMapper(warnOnUnmappedTargetComponents = true) downgrades it to a warning. The difference is which behavior you get without configuring anything.)

3.Optional-returning mappings

MapStruct has real, native Optional support: it can wrap and unwrap Optional properties, and a NullValuePropertyMappingStrategy can turn a null source property into Optional.empty() on the target automatically. That part isn't a gap.

The gap is narrower: when the whole source object passed into a mapping method is null and the method’s return type is Optional, MapStruct doesn't generate the null guard for you, so you still write it at the call site:

// MapStruct: property-level Optional handling is automatic, but the
// method-level null check on the *source object* is manual:
Optional<AddressDTO> toDto(AddressEntity source);

// at the call site:
return source == null ? Optional.empty() : Optional.of(mapper.toDto(source));

Immuto’s @NullSafe moves that specific guard into the mapper declaration:

@NullSafe
Optional<AddressDTO> toDto(AddressEntity source);

// generated:
// if (source == null) return Optional.empty();
// return Optional.of(new AddressDTO(...));

4.@AfterMapping on a Record target is observation-only

Both libraries support @BeforeMapping and @AfterMapping. MapStruct's @AfterMapping was designed with JavaBeans in mind, where the hook receives a @MappingTarget object it can still mutate via setters. For a Record target, that design doesn't transfer cleanly: the hook fires after the canonical constructor has already produced an immutable object, so there are no setters left to call. MapStruct doesn't warn you about this, so the annotation just quietly becomes observation-only.

Immuto makes that explicit rather than implicit:

@RecordMapper
public interface PaymentMapper {
    PaymentDTO toDto(PaymentEntity source);

    @BeforeMapping
    default void validate(PaymentEntity source) {
        Objects.requireNonNull(source.amount(), "amount must not be null");
    }
    @AfterMapping
    default void audit(PaymentEntity source, PaymentDTO target) {
        AuditLog.record(target);  // target is already built and immutable
    }
}
// generated
@Override
public PaymentDTO toDto(PaymentEntity source) {
    if (source == null) return null;
    validate(source);
    PaymentDTO __result = new PaymentDTO(source.id(), source.amount(), source.currency());
    audit(source, __result);
    return __result;
}

5.Sealed interface hierarchies

MapStruct can map a sealed interface to a sealed interface, but every subtype pair needs an explicit @SubclassMapping on the parent-mapping method, even though the full set of permitted subtypes is already known at compile time from the permits clause. (As of MapStruct 1.6, a sealed source no longer needs subclassExhaustiveStrategy to prove exhaustiveness, but the per-pair annotations are still required.)

// MapStruct: one @SubclassMapping per subtype pair, every time.
@Mapper
public interface ShapeMapper {
    @SubclassMapping(source = CircleEntity.class, target = CircleDTO.class)
    @SubclassMapping(source = SquareEntity.class, target = SquareDTO.class)
    ShapeDTO toDto(ShapeEntity source);
}

Immuto reads the sealed interface’s permits list directly: declare one method per subtype, no subclass-mapping annotation required.

@RecordMapper
public interface ShapeMapper {
    ShapeDTO toDto(CircleEntity source);
    ShapeDTO toDto(SquareEntity source);
    // dispatch is generated from the sealed interface's permitted subtypes
}

(If you’re implementing this, it’s worth deciding up front what happens when a new subtype is added later and no matching method exists, since failing the build there is what keeps this feature consistent with the “explicit over silent” theme running through the rest of this piece.)

6.Error messages that name the component

This one is more UX than capability, but it’s part of the same philosophy: Immuto’s compiler errors are written around the Record’s component model, and each one names the exact component and the fix:

error: [Immuto] Target component 'fullName' has no matching source component.
       Use @Mapping(target="fullName", ignore=true) to suppress this error.
       PersonDTO toDto(PersonEntity source);
                 ^
error: [Immuto] Cannot auto-convert component 'createdAt': no TypeConverter
       registered for java.time.Instant → java.lang.String.
       Register a TypeConverter or add @Mapping(expression="java(...)").
       PersonDTO toDto(PersonEntity source);

At a glance

Straightforward Record mapping (matching fields) MapStruct: Native, constructor-based, works well Immuto: Native, constructor-based
Asymmetric / expression-based reverse mappings MapStruct: Can silently pass null for unresolvable parameters Immuto: Compile-time error on unresolvable parameters
Unmapped target components MapStruct: WARN by default (configurable to ERROR) Immuto: Build error by default (configurable to warn)
Optional-returning methods MapStruct: Property-level Optional handling is automatic; method-level source-null guard is manual Immuto: @NullSafe generates the source-null guard automatically
@AfterMapping on a Record target MapStruct: Supported, but silently observation-only (no setters exist) Immuto: Explicit observation hook, documented as such
Sealed interface mapping MapStruct: Supported via explicit @SubclassMapping per subtype pair Immuto: Declared via per-subtype methods, dispatch inferred from permits

Getting started

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

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

Links

GitHub: Immuto
Maven Central: Maven Artifact
Earlier post: Java Records deserve a mapper

Feedback, issues, and contributions are very welcome

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));