DEV Community: Petr Filaretov

MapStruct: When a Helper Method Maps More Than You Asked For

Petr Filaretov — Tue, 28 Oct 2025 11:54:11 +0000

When using MapStruct, it’s tempting to tuck small helper methods into your mapper and use them via expression. However, if that helper looks like a generic mapping method (for instance, String -> String), MapStruct may discover and apply it to other fields of the same type — even when you didn’t intend to.

Let's look at an example. The full source code is available on GitHub: pfilaretov42/spring-mapstruct-test. Check out the fix-<n> branches for different ways to address the problem.

The Setup

Imagine we have a simple DTO...

class BalrogDto(
    val millenniaOld: Int,
    val trueName: String,
    val battleName: String,
)

...a corresponding model...

class Balrog(
    val millenniaOld: Int,
    val trueName: String,
    val battleName: String,
)

...and a mapper:

@Mapper(componentModel = "spring")
abstract class BalrogMapper {

    @Mapping(target = "trueName", expression = "java(uppercased(dto.getTrueName()))")
    abstract fun toModel(dto: BalrogDto): Balrog

    protected fun uppercased(value: String): String = value.uppercase()
}

Here we only want to customize the trueName field by uppercasing it. The battleName should remain as is.

The Pitfall

However, here is what the mapper implementation looks like:

@Generated(...)
@Component
public class BalrogMapperImpl extends BalrogMapper {

    @Override
    public Balrog toModel(BalrogDto dto) {
        if ( dto == null ) {
            return null;
        }

        int millenniaOld = 0;
        String battleName = null;

        millenniaOld = dto.getMillenniaOld();
        battleName = uppercased( dto.getBattleName() );

        String trueName = uppercased(dto.getTrueName());

        Balrog balrog = new Balrog( millenniaOld, trueName, battleName );

        return balrog;
    }

}

Under the hood, MapStruct scans the mapper for available mapping methods. A protected String -> String method looks like a perfect general-purpose candidate and will be applied to other String-to-String mappings (like battleName). So, battleName will also be mapped using the uppercased method, which is not what we wanted.

Why This Happens

It happens because MapStruct selects mapping methods primarily by signature. If it sees a String -> String method on the mapper, it may use that method to map any String field.

Using that method in an expression does not "scope" it to a single target. It still remains discoverable by MapStruct for other fields of the same type.

How To Avoid The Surprise

Now, let's see how we can keep the intention explicit and avoid accidental global application.

1. Move the helper out of the mapper and call it via `expression`

We can put the logic in a separate utility class that MapStruct does not scan as a source of mapping methods:

object StringUtils {
    @JvmStatic
    fun uppercased(s: String): String = s.uppercase()
}

Remember not to list it in @Mapper(uses = ...); instead, import it in the mapper and call it explicitly in expression:

@Mapper(componentModel = "spring", imports = [StringUtils::class])
abstract class BalrogMapper {

    @Mapping(target = "trueName", expression = "java(StringUtils.uppercased(dto.getTrueName()))")
    abstract fun toModel(dto: BalrogDto): Balrog
}

Because StringUtils is not a mapper and not listed in uses, MapStruct won’t auto-apply it to other String fields. We still get our one-off transformation through the expression.

2. Qualify and isolate mapping methods

If we want to keep a mapping method but apply it only when explicitly referenced, we can annotate the method with the @org.mapstruct.Named annotation and reference it using qualifiedByName on the specific field mapping:

@Mapper(componentModel = "spring")
abstract class BalrogMapper {

    @Mapping(target = "trueName", qualifiedByName = ["uppercased"])
    abstract fun toModel(dto: BalrogDto): Balrog

    @Named("uppercased")
    protected fun uppercased(value: String): String = value.uppercase()
}

3. Make the transformation type-specific

Another approach is to avoid generic method signatures. We can wrap the concept (trueName, in our case) into a domain-specific type (TrueName)...

class Balrog(
    val millenniaOld: Int,
    val trueName: TrueName,
    val battleName: String,
)

class TrueName(val value: String)

...so the mapper’s method signature is no longer String -> String:

@Mapper(componentModel = "spring")
abstract class BalrogMapper {

    abstract fun toModel(dto: BalrogDto): Balrog

    fun toTrueName(raw: String): TrueName = TrueName(raw.uppercase())
}

This way, MapStruct cannot accidentally reuse it for unrelated String fields. This option is heavier and typically only worthwhile if you already embrace rich domain types.

Conclusion

Here are the key takeaways:

A method that looks like a general String -> String mapper inside your @Mapper can be auto-applied to any String field.
Using such a method in an expression does not limit its scope.
Prefer isolating one-off logic in a utility and calling it via expression, or qualify mapping methods with @Named and reference them with qualifiedByName.
Keep your mapper free of unintended generic mapping methods unless you truly want them globally applied.

Dream your code, code your dream.

The Return of the LTS: What Java 25 Brings Beyond 21

Petr Filaretov — Thu, 21 Aug 2025 09:59:40 +0000

Intro

In one of my previous posts, I wrote about features between Java LTS versions 21 and 17. Now, two years later (how!? Two years already!?), a new LTS version is scheduled for release on September 16, 2025 — Java 25. Today, it has moved into the "Final Release Candidate" phase, and the feature set is frozen.

The vast majority of projects skip non-LTS releases and use Java LTS versions only. So, let's take a look at the features that the new LTS version (Java 25) delivers compared to the previous LTS version (Java 21).

I will be using the following abbreviations for the feature states in the tables below:

exp = Experimental
inc[2|3|4|etc] = Incubator [2|3|4|etc]
pre[2|3|4|etc] = Preview [2|3|4|etc]
prod = Production
w/d = Withdrawn

Production-Ready Features in Java 25

Feature	Java 21	Java 22	Java 23	Java 24	Java 25
Scoped Values	JEP 446 (pre)	JEP 464 (pre2)	JEP 481 (pre3)	JEP 487 (pre4)	JEP 506 (prod)
Flexible Constructor Bodies	-	JEP 447 (pre)	JEP 482 (pre2)	JEP 492 (pre3)	JEP 513 (prod)
Unnamed Variables & Patterns	JEP 443 (pre)	JEP 456 (prod)	+	+	+
Stream Gatherers	-	JEP 461 (pre)	JEP 473 (pre2)	JEP 485 (prod)	+
Quantum-Resistant Module-Lattice-Based Key Encapsulation Mechanism	-	-	-	JEP 496 (prod)	+
Quantum-Resistant Module-Lattice-Based Digital Signature Algorithm	-	-	-	JEP 497 (prod)	+
Key Derivation Function API	-	-	-	JEP 478 (pre)	JEP 510 (prod)
Foreign Function & Memory API	JEP 442 (pre3)	JEP 454 (prod)	+	+	+
Compact Source Files and Instance Main Methods	JEP 445 (pre)	JEP 463 (pre2)	JEP 477 (pre3)	JEP 495 (pre4)	JEP 512 (prod)
Markdown Documentation Comments	-	-	JEP 467 (prod)	+	+
Module Import Declarations	-	-	JEP 476 (pre)	JEP 494 (pre2)	JEP 511 (prod)
Ahead-of-Time Class Loading & Linking	-	-	-	JEP 483 (prod)	+
Ahead-of-Time Command-Line Ergonomics	-	-	-	-	JEP 514 (prod)
Ahead-of-Time Method Profiling	-	-	-	-	JEP 515 (prod)
JFR Cooperative Sampling	-	-	-	-	JEP 518 (prod)
JFR Method Timing & Tracing	-	-	-	-	JEP 520 (prod)
Compact Object Headers	-	-	-	JEP 450 (exp)	JEP 519 (prod)
Prepare to Restrict the Use of JNI	-	-	-	JEP 472 (prod)	+
Region Pinning for G1	-	JEP 423 (prod)	+	+	+
Late Barrier Expansion for G1	-	-	-	JEP 475 (prod)	+
Class-File API	-	JEP 457 (pre)	JEP 466 (pre2)	JEP 484 (prod)	+
Permanently Disable the Security Manager	-	-	-	JEP 486 (prod)	+
Launch Multi-File Source-Code Programs	-	JEP 458 (prod)	+	+	+
ZGC: Generational Mode by Default	-	-	JEP 474 (prod)	+	+
ZGC: Remove the Non-Generational Mode	-	-	-	JEP 490 (prod)	+
Generational Shenandoah	-	-	-	JEP 404 (exp)	JEP 521 (prod)
Synchronize Virtual Threads without Pinning	-	-	-	JEP 491 (prod)	+
Linking Run-Time Images without JMODs	-	-	-	JEP 493 (prod)	+
Deprecate the Memory-Access Methods in sun.misc.Unsafe for Removal	-	-	JEP 471 (prod)	+	+
Warn upon Use of Memory-Access Methods in sun.misc.Unsafe	-	-	-	JEP 498 (prod)	+
Remove the Windows 32-bit x86 Port	-	-	-	JEP 479 (prod)	+
Deprecate the 32-bit x86 Port for Removal	-	-	-	JEP 501 (prod)	+
Remove the 32-bit x86 Port	-	-	-	-	JEP 503 (prod)

Preview Features in Java 25

Feature	Java 21	Java 22	Java 23	Java 24	Java 25
Stable Values	-	-	-	-	JEP 502 (pre)
PEM Encodings of Cryptographic Objects	-	-	-	-	JEP 470 (pre)
Structured Concurrency	JEP 453 (pre)	JEP 462 (pre2)	JEP 480 (pre3)	JEP 499 (pre4)	JEP 505 (pre5)
Primitive Types in Patterns, instanceof, and switch	-	-	JEP 455 (pre)	JEP 488 (pre2)	JEP 507 (pre3)

Incubator Features in Java 25

Feature	Java 21	Java 22	Java 23	Java 24	Java 25
Vector API	JEP 448 (inc6)	JEP 460 (inc7)	JEP 469 (inc8)	JEP 489 (inc9)	JEP 508 (inc10)

Experimental Features in Java 25

Feature	Java 21	Java 22	Java 23	Java 24	Java 25
JFR CPU-Time Profiling	-	-	-	-	JEP 509 (exp)

Withdrawn Features Between Java 21 and Java 25

Feature	Java 21	Java 22	Java 23	Java 24	Java 25
String Templates	JEP 430 (pre)	JEP 459 (pre2)	JEP 465 (pre3 - w/d)	-	-

Production-Ready Features with Examples

Now, let's briefly go through some production-ready features and look at code samples.

The full source code is available on GitHub: pfilaretov42/java-features.

Scoped Values

Scoped Values provide a safer alternative to thread-local variables by offering immutable, inheritable values that are only accessible within a defined scope.

Before: The ThreadLocal Approach

Like carrying the One Ring - dangerous if shared carelessly:

class ThreadLocalTest {
    private static final ThreadLocal<String> CURRENT_RING_BEARER = new ThreadLocal<>();

    void dangerousJourney() {
        CURRENT_RING_BEARER.set("Frodo");
        try {
            travelToMordor();
        } finally {
            CURRENT_RING_BEARER.remove();
        }
    }

    void travelToMordor() {
        // Any method in the call chain can access...
        String bearer = CURRENT_RING_BEARER.get();
        System.out.println(bearer + " bears the burden");

        // ...and modify
        CURRENT_RING_BEARER.set("Sam");
        bearer = CURRENT_RING_BEARER.get();
        System.out.println(bearer + " bears the burden");
    }

    public static void main() {
        ThreadLocalTest test = new ThreadLocalTest();
        test.dangerousJourney();
    }
}

After: The ScopedValue Way

Like the Phial of Galadriel - light that's safely contained:

public class ScopedValuesTest {
    private static final ScopedValue<String> CURRENT_RING_BEARER = ScopedValue.newInstance();

    void safeJourney() {
        ScopedValue.where(CURRENT_RING_BEARER, "Frodo")
                .run(this::travelToMordorSafely);
    }

    private void travelToMordorSafely() {
        // Only accessible in this scope, cannot be modified
        String bearer = CURRENT_RING_BEARER.get();
        System.out.println(bearer + " bears the burden safely");

        // Attempting to rebind would result in compilation error:
        //CURRENT_RING_BEARER.set("Sam");
    }

    void noJourney() {
        // Not accessible outside the scope, throws NoSuchElementException (ScopedValue not bound):
        String bearer = CURRENT_RING_BEARER.get();
        System.out.println(bearer + " bears the burden");
    }

    public static void main() {
        ScopedValuesTest test = new ScopedValuesTest();
        test.safeJourney();
        test.noJourney();
    }
}

Flexible Constructor Bodies

Allows more flexible ordering of statements in constructor bodies, including permitting code before explicit constructor invocations (this() or super() calls).

Before: The Rigid Constructor Rules

Like the rigid walls of Orthanc - no flexibility:

class Palantir {
    private final String owner;
    private final boolean isCorrupted;

    public Palantir(String owner) {
        // This would not compile:
        //validateOwner(owner);
        // Call to this() must be the first statement:
        this(validateOwner(owner), false);
    }

    private static String validateOwner(String owner) {
        if (owner == null || owner.isBlank()) {
            throw new IllegalArgumentException("Owner cannot be null or blank");
        }
        System.out.println("A new palantir is given to " + owner);
        return owner;
    }

    private Palantir(String owner, boolean isCorrupted) {
        this.owner = owner;
        this.isCorrupted = isCorrupted;
    }
}

After: The Graceful Constructor Freedom

Now flows like the waters of Bruinen - natural and flexible:

class Palantir {
    private final String owner;
    private final boolean isCorrupted;

    public Palantir(String owner) {
        validateOwner(owner);
        // Now this() call is allowed after other statements:
        this(owner, false);
    }

    private static void validateOwner(String owner) {
        if (owner == null || owner.isBlank()) {
            throw new IllegalArgumentException("Owner cannot be null or blank");
        }
        System.out.println("A new palantir is given to " + owner);
    }

    private Palantir(String owner, boolean isCorrupted) {
        this.owner = owner;
        this.isCorrupted = isCorrupted;
    }
}

Unnamed Variables & Patterns

Allows developers to explicitly mark unused variables/patterns with underscore _ to improve code clarity and maintainability.

Common Use Cases:

Exception parameters
Lambda parameters
Pattern matching variables
Loop variables when only counter is needed

Before: Forced to Name Unused Variables

Like being forced to name every orc in Mordor's army:

try {
    int rings = forgeNewRing();
} catch (RingForgingException e) {  // Never used
    System.out.println("The fires of Mount Doom failed us!");
}

// Pattern matching with unused bindings
if (fighter instanceof Elf(String name, Weapon(String type, int damage))) {  // name and damage unused
    System.out.println("Armed with: " + type);
}

After: Clean Unused Variable Declaration

As elegant as Legolas defying gravity:

try {
    int _ = forgeNewRing();
} catch (RingForgingException _) {  // Clear this is unused
    System.out.println("The fires of Mount Doom failed us!");
}

// Clean pattern matching
if (fighter instanceof Elf(_, Weapon(String type, _))) {
    System.out.println("Armed with: " + type);
}

Stream Gatherers

Introduces custom intermediate stream operations through the new gather(Gatherer) method, allowing more complex stream transformations.

Before: Limited to Built-in Operations

Like trying to forge the One Ring with only basic tools:

List<String> hobbits = List.of("Frodo", "Sam", "Merry", "Pippin");

// To get overlapping pairs, we needed a workarounds
List<String> pairs = IntStream.range(0, hobbits.size() - 1)
        .mapToObj(i -> hobbits.get(i) + " & " + hobbits.get(i + 1))
        .toList();
System.out.println(pairs);
// Output: ["Frodo & Sam", "Sam & Merry", "Merry & Pippin"]

After: Custom Stream Transformations

Now wielding the power of the Elven smiths:

List<String> hobbits = List.of("Frodo", "Sam", "Merry", "Pippin");

Gatherer<String, ?, String> pairing = Gatherer.ofSequential(
        () -> new Object() { String previous; },
        (state, element, downstream) -> {
            if (state.previous != null) {
                downstream.push(state.previous + " & " + element);
            }
            state.previous = element;
            return true;
        }
);

List<String> pairs = hobbits.stream()
        .gather(pairing)
        .toList();
System.out.println(pairs);
// Output: ["Frodo & Sam", "Sam & Merry", "Merry & Pippin"]

Quantum-Resistant Module-Lattice-Based Key Encapsulation Mechanism

Java 24 introduces built-in support for module-lattice-based key encapsulation mechanism (ML-KEM), part of quantum-resistant cryptography.

This feature provides quantum-resistant key encapsulation that is used to secure symmetric keys over insecure communication channels using public key cryptography.

It can be used to withstand the might of quantum computers — future threats to classical RSA and Diffie-Hellman.

With the following session key exchange example...

// Elrond prepares his runes of protection (Receiver creates key pair)
ElrondTheReceiver elrond = new ElrondTheReceiver();

// Gandalf crafts a secret using Elrond’s rune (Sender uses receiver's public key to encapsulate session key)
GandalfTheSender gandalf = new GandalfTheSender(elrond.revealPublicRune());
SecretKey senderSessionKey = gandalf.getSessionKey();

// Elrond deciphers the sealed whisper from Gandalf (Receiver decapsulates to get the same session key)
SecretKey receiverSessionKey = elrond.decapsulateWhisper(gandalf.getSealedWhisper());
boolean secretsMatch = MessageDigest.isEqual(senderSessionKey.getEncoded(), receiverSessionKey.getEncoded());

// Output for verification:
HexFormat hex = HexFormat.of();
System.out.println("Sender session key:   " + hex.formatHex(senderSessionKey.getEncoded()));
System.out.println("Receiver session key: " + hex.formatHex(receiverSessionKey.getEncoded()));
System.out.println("Secrets match: " + secretsMatch);

if (secretsMatch) {
    // Gandalf and Elrond exchange messages using the securely transmitted session key
    // ...
}

..., here is what we have.

Before: RSA Key Transport

Like wielding Gondorian steel — mighty, yet vulnerable to greater powers:

/**
 * Receiver generates key pair and decapsulates session key
 */
class ElrondTheReceiver {
    private final KeyPair keyPair;

    public ElrondTheReceiver() throws GeneralSecurityException {
        KeyPairGenerator generator = KeyPairGenerator.getInstance("RSA");
        generator.initialize(4096);
        keyPair = generator.generateKeyPair();
    }

    public PublicKey revealPublicRune() {
        return keyPair.getPublic();
    }

    public SecretKey decapsulateWhisper(byte[] sealedWhisper) throws GeneralSecurityException {
        Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-256AndMGF1Padding");
        cipher.init(Cipher.DECRYPT_MODE, keyPair.getPrivate());
        byte[] keyBytes = cipher.doFinal(sealedWhisper);

        return new SecretKeySpec(keyBytes, "AES");
    }
}

/**
 * Sender uses receiver's public key to generate session key
 */
class GandalfTheSender {
    private final SecretKey sessionKey; // Sender’s secret session key
    private final byte[] sealedWhisper; // The message with session key encapsulated for Receiver

    public GandalfTheSender(PublicKey receiverPublicKey) throws GeneralSecurityException {
        // Generate session key (AES)
        KeyGenerator generator = KeyGenerator.getInstance("AES");
        generator.init(256);
        sessionKey = generator.generateKey();

        // Encrypt (encapsulate) session key with RSA
        Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-256AndMGF1Padding");
        cipher.init(Cipher.ENCRYPT_MODE, receiverPublicKey);
        sealedWhisper = cipher.doFinal(sessionKey.getEncoded());
    }

    public SecretKey getSessionKey() {
        return sessionKey;
    }

    public byte[] getSealedWhisper() {
        return sealedWhisper;
    }
}

After: Post-Quantum Key Encapsulation

Like the Gates of Moria - impregnable to force:

/**
 * Receiver generates key pair and decapsulates session key
 */
class ElrondTheReceiver {
    private final KeyPair keyPair;

    public ElrondTheReceiver() throws GeneralSecurityException {
        KeyPairGenerator generator = KeyPairGenerator.getInstance("ML-KEM");
        keyPair = generator.generateKeyPair();
    }

    public PublicKey revealPublicRune() {
        return keyPair.getPublic();
    }

    public SecretKey decapsulateWhisper(byte[] sealedWhisper) throws GeneralSecurityException {
        KEM kem = KEM.getInstance("ML-KEM");
        KEM.Decapsulator decapsulator = kem.newDecapsulator(keyPair.getPrivate());
        return decapsulator.decapsulate(sealedWhisper);
    }
}

/**
 * Sender uses receiver's public key to generate session key
 */
class GandalfTheSender {
    private final SecretKey sessionKey; // Sender’s secret session key
    private final byte[] sealedWhisper; // The message with session key encapsulated for Receiver

    public GandalfTheSender(PublicKey receiverPublicKey) throws GeneralSecurityException {
        KEM kem = KEM.getInstance("ML-KEM");
        KEM.Encapsulator encapsulator = kem.newEncapsulator(receiverPublicKey);
        KEM.Encapsulated encapsulated = encapsulator.encapsulate();

        sessionKey = encapsulated.key();
        sealedWhisper = encapsulated.encapsulation();
    }

    public SecretKey getSessionKey() {
        return sessionKey;
    }

    public byte[] getSealedWhisper() {
        return sealedWhisper;
    }
}

Quantum-Resistant Module-Lattice-Based Digital Signature Algorithm

ML-DSA provides post-quantum secure digital signatures based on lattice cryptography, part of Java's new cryptographic suite for the quantum computing era.

With the following message signing example...

// Gandalf prepares his spell (Sender creates a public/private key pair)
GandalfTheSender gandalf = new GandalfTheSender();

// Sender signs a message using the private key
String scroll = gandalf.speakWordsOfPower();
byte[] waxSeal = gandalf.signMessage(scroll);

// Aragorn receives the scroll and the seal
AragornTheReceiver aragorn = new AragornTheReceiver(gandalf.revealPublicRune());

// Verifying the true words of Gandalf (Receiver verifies the message using the sender's public key)
boolean isTrueScroll = aragorn.verifyMessage(scroll, waxSeal);
System.out.println("Is the scroll valid: " + isTrueScroll); // true

// Attempt to fool the ranger with a forged scroll (verification fails for counterfeit message)
String fakeScroll = """
    A new Power is rising. Against it the old allies and policies will not avail us at all. \
    There is no hope left in Elves or dying Númenor.
    """;
isTrueScroll = aragorn.verifyMessage(fakeScroll, waxSeal);
System.out.println("Is the forged scroll valid: " + isTrueScroll); // false

..., here is what we have.

Before: Signing with ECDSA

Like the walls of Isengard against Entish wrath:

/**
 * Sender signs message with private key
 */
class GandalfTheSender {
    private final KeyPair keyPair;

    public GandalfTheSender() throws Exception {
        KeyPairGenerator generator = KeyPairGenerator.getInstance("EC");
        generator.initialize(new ECGenParameterSpec("secp256r1"));
        keyPair = generator.generateKeyPair();
    }

    public PublicKey revealPublicRune() {
        return keyPair.getPublic();
    }

    public byte[] signMessage(String message) throws Exception {
        Signature runeEngraver = Signature.getInstance("SHA256withECDSA");
        runeEngraver.initSign(keyPair.getPrivate());
        runeEngraver.update(message.getBytes());
        return runeEngraver.sign();
    }

    public String speakWordsOfPower() {
        return """
            It is not our part here to take thought only for a season, or for a few lives of Men, \
            or for a passing age of the world. We should seek a final end of this menace, \
            even if we do not hope to make one.
            """;
    }
}

/**
 * Receiver verifies the message with public key
 */
class AragornTheReceiver {
    private final PublicKey senderPublicKey;

    public AragornTheReceiver(PublicKey senderPublicKey) {
        this.senderPublicKey = senderPublicKey;
    }

    public boolean verifyMessage(String message, byte[] signature) throws Exception {
        Signature runeChecker = Signature.getInstance("SHA256withECDSA");
        runeChecker.initVerify(senderPublicKey);
        runeChecker.update(message.getBytes());
        return runeChecker.verify(signature);
    }
}

After: Signing with Quantum-Resistant ML-DSA

Like inscribing your mark in the timeless halls of Valinor.

/**
 * Sender signs message with private key
 */
class GandalfTheSender {
    private final KeyPair keyPair;

    public GandalfTheSender() throws Exception {
        KeyPairGenerator generator = KeyPairGenerator.getInstance("ML-DSA");
        keyPair = generator.generateKeyPair();
    }

    public PublicKey revealPublicRune() {
        return keyPair.getPublic();
    }

    public byte[] signMessage(String message) throws Exception {
        Signature runeEngraver = Signature.getInstance("ML-DSA");
        runeEngraver.initSign(keyPair.getPrivate());
        runeEngraver.update(message.getBytes());
        return runeEngraver.sign();
    }

    public String speakWordsOfPower() {
        return """
            It is not our part here to take thought only for a season, or for a few lives of Men, \
            or for a passing age of the world. We should seek a final end of this menace, \
            even if we do not hope to make one.
            """;
    }
}

/**
 * Receiver verifies the message with public key
 */
class AragornTheReceiver {
    private final PublicKey senderPublicKey;

    public AragornTheReceiver(PublicKey senderPublicKey) {
        this.senderPublicKey = senderPublicKey;
    }

    public boolean verifyMessage(String message, byte[] signature) throws Exception {
        Signature runeChecker = Signature.getInstance("ML-DSA");
        runeChecker.initVerify(senderPublicKey);
        runeChecker.update(message.getBytes());
        return runeChecker.verify(signature);
    }
}

Key Derivation Function API

Introduces a standardised API for key derivation functions (KDFs), replacing ad-hoc implementations with a unified interface for secure key derivation.

Before: The Manual Key Derivation

Like forging a sword in the crude fires of Mordor:

String password = "Mellon!";
byte[] salt = generateSalt();
int iterations = 65_536;
int keyLengthBits = 256;

// derive the key
PBEKeySpec spec = new PBEKeySpec(password.toCharArray(), salt, iterations, keyLengthBits);
SecretKeyFactory factory = SecretKeyFactory.getInstance("PBKDF2WithHmacSHA256");
SecretKey key = factory.generateSecret(spec);

System.out.println("Derived key: " + HexFormat.of().formatHex(key.getEncoded()));

After: The Refined KDF API

Now, like the Elven smiths of Eregion, we forge keys with precision:

KDF hkdf = KDF.getInstance("HKDF-SHA256");
byte[] password = "Mellon!".getBytes();
byte[] salt = generateSalt();
byte[] info = "Say 'Friend' and enter".getBytes();
int keyLengthBytes = 32;

// derive the key
AlgorithmParameterSpec params = HKDFParameterSpec.ofExtract()
        .addIKM(password)
        .addSalt(salt)
        .thenExpand(info, keyLengthBytes);
SecretKey key = hkdf.deriveKey("AES", params);

System.out.println("Derived key: " + HexFormat.of().formatHex(key.getEncoded()));

Foreign Function & Memory API

Replaces Java Native Interface (JNI) with a safer, more efficient way to call native code and work with off-heap memory.

I will skip package names and long file paths for simplicity. The fully working sample can be found on GitHub.

Before: The Risky JNI Approach

Like the Black Speech of Mordor - powerful but dangerous...

Create a Java class:

public class ElvenScroll {
    static {
        // Load the native library forged in C
        System.loadLibrary("mordor");
    }

    // Declare the native spell that reads the length of ancient text
    public native int countRunes(String ancientText);

    public static void main() {
        ElvenScroll scroll = new ElvenScroll();
        String runes = "Speak, friend, and enter";
        int length = scroll.countRunes(runes);
        System.out.println("Runes counted: " + length);
    }
}

Compile the ElvenScroll class with -h option:

javac -h . ElvenScroll.java

It produces the ElvenScroll.h header file.

Create a C file:

#include <jni.h>
#include <string.h>
#include "ElvenScroll.h"

JNIEXPORT jint JNICALL Java_ElvenScroll_countRunes(JNIEnv *env, jobject obj, jstring ancientText) {
    // Convert Elvish runes to C-compatible form
    const char *runes = (*env)->GetStringUTFChars(env, ancientText, NULL);
    if (runes == NULL) return 0;

    // Count the runes
    int length = (int)strlen(runes);

    // Release the spellbound memory
    (*env)->ReleaseStringUTFChars(env, ancientText, runes);
    return length;
}

Build the C library - the command below is for macOS:

gcc -shared -fpic -o libmordor.dylib \
-I ${JAVA_HOME}/include \
-I ${JAVA_HOME}/include/darwin \
mordor.c

This produces libmordor.dylib file.

Run the ElvenScroll class.

After: The Safe FFM API

Like the Elven bridges of Lothlórien - elegant and secure:

public class ElvenScroll {

    public static void main() throws Throwable {
        // Get a linker and a lookup object
        Linker linker = Linker.nativeLinker();
        SymbolLookup stdlib = linker.defaultLookup();

        // Get a handle to the foreign function ('strlen' from the C standard library)
        MethodHandle strlen = linker.downcallHandle(
            stdlib.find("strlen").orElseThrow(),
            FunctionDescriptor.of(ValueLayout.JAVA_LONG, ValueLayout.ADDRESS)
        );

        try (Arena arena = Arena.ofConfined()) {
            // Allocate off-heap memory
            String runes = "Speak, friend, and enter";
            MemorySegment cString = arena.allocateFrom(runes);

            // Call the foreign function
            long runeCount = (long) strlen.invoke(cString);
            System.out.println("Runes counted: " + runeCount);
        }
        // Memory automatically freed here - no memory leaks!
        // No native code!
    }
}

Compact Source Files And Instance Main Methods

Simplifies Java syntax for beginners by allowing single-file programs without class boilerplate and offering more flexible main() method declarations.

Before: The Verbose Incantation

Like the long-winded speeches of the Council of Elrond:

package dev.pfilaretov42.java25.csf_imm;

public class RingQuestBefore {
    public static void main(String[] args) {
        System.out.println("One does not simply walk into Mordor...");
    }
}

After: The Hobbit-Sized Version

A swift journey like Bilbo's contract:

// no package declaration
// no imports for classes in java.base module

void main() {
    IO.println("One does not simply walk into Mordor...");
}

Or with an instance method:

package dev.pfilaretov42.java25.csf_imm;

public class RingQuestAfterInstance {
    void main() {
        IO.println("One does not simply walk into Mordor...");
    }
}

Markdown Documentation Comments

Finally! 🎉 Java now supports Markdown syntax in Javadoc comments, providing a more readable and maintainable alternative to HTML tags.

Before: The HTML Way

The way of the ancients — cluttered and burdensome, like the forges of Isengard:

/**
* <h1>The One Ring</h1>
* <p>Forged by Sauron in the fires of Mount Doom.</p>
* <p><b>Warning:</b> Do not wear for extended periods.</p>
*/
public class OneRing {
  // ...
}

After: Markdown Syntax

Now, the words flow like the elven script of Lothlórien — clean, elegant, and true:

/// # The One Ring
/// Forged by Sauron in the fires of Mount Doom.
/// **Warning:** Do not wear for extended periods.
public class OneRing {
  // ...
}

Module Import Declarations

Introduces the import module syntax, allowing developers to import entire modules within regular Java files.

With the following classes...

package lothlorien;

public class Galadriel {
    public void speakLightOfEärendil() {
        // ...
    }
}

package lothlorien;

public class Celeborn {
    public void offerCounsel() {
        // ...
    }
}

package lothlorien;

public class Haldir {

    public void escort() {
        // ...
    }
}

...and the module-info.java file...

module elves.of.lothlorien {
    exports lothlorien;
}

..., here is what we have.

Before: Import Declarations

Like the endless genealogies of the House of Finwë:

import lothlorien.Celeborn;
import lothlorien.Galadriel;
import lothlorien.Haldir;

public class FarewellToLórien {
    void main() {
        Haldir guardian = new Haldir();
        guardian.escort();

        Celeborn lord = new Celeborn();
        lord.offerCounsel();

        Galadriel lady = new Galadriel();
        lady.speakLightOfEärendil();
    }
}

After: Module Import

Now organized like a well-ordered dwarven hall:

import module elves.of.lothlorien;

public class FarewellToLórien {
    void main() {
        Haldir guardian = new Haldir();
        guardian.escort();

        Celeborn lord = new Celeborn();
        lord.offerCounsel();

        Galadriel lady = new Galadriel();
        lady.speakLightOfEärendil();
    }
}

Conclusion

Hey, who said Java is old and boring? The latest Java 25 LTS version delivers some great features that are definitely worth checking out.

Dream your code, code your dream.

[Tiny] Spring Data JDBC: When a Map Pretends to Be a String

Petr Filaretov — Tue, 20 May 2025 07:39:11 +0000

When using Spring Data JDBC and PostgreSQL, we may need to store key-value pairs in a JSONB column.

Let's take an example from one of my previous posts and modify it so that the extras field does not have nested objects, but rather simple key-value pairs:

{
  "friend": {
    "fullName": "Anthony Edward Stark",
    "alias": "Iron Man",
    "extras": {
      "publisher": "Marvel Comics",
      "createdBy": "Stan Lee"
    }
  }
}

We could use the Map<String, String?>? type for the extras field in the entity...

@Table("friends")
class FriendsEntity(
    //...
    val extras: Map<String, String?>?,
) : Persistable<UUID> {
    //...
}

...and the JSONB type for the database column:

create table friends
(
    -- ...
    extras JSONB
);

Now, if we try to create an entity in the database, we get an error:

DEBUG o.s.jdbc.core.JdbcTemplate               : Executing prepared SQL statement [INSERT INTO "friends" ("alias", "extras", "full_name", "id", "superpower") VALUES (?, ?, ?, ?, ?)]
TRACE o.s.jdbc.core.StatementCreatorUtils      : Setting SQL statement parameter value: column index 1, parameter value [Iron Man], value class [java.lang.String], SQL type 12
TRACE o.s.jdbc.core.StatementCreatorUtils      : Setting SQL statement parameter value: column index 2, parameter value [{"publisher":"Marvel Comics","createdBy":"Stan Lee"}], value class [org.postgresql.util.PGobject], SQL type 12
...
ERROR o.a.c.c.C.[.[.[/].[dispatcherServlet]    : Servlet.service() for servlet [dispatcherServlet] in context with path [] threw exception [Request processing failed: org.springframework.data.relational.core.conversion.DbActionExecutionException: Failed to execute InsertRoot{entity=dev.pfilaretov42.spring.data.jdbc.jsonb.entity.FriendsEntity@2f97ec4e, idValueSource=PROVIDED}] with root cause
org.postgresql.util.PSQLException: ERROR: column "extras" is of type jsonb but expression is of type character varying

For some reason, StatementCreatorUtils treats a Map as a String:

value class [org.postgresql.util.PGobject], SQL type 12

To fix this, we have to change the map value type from String? to Any?:

@Table("friends")
class FriendsEntity(
    //...
    val extras: Map<String, Any?>?,
) : Persistable<UUID> {
  //...
}

Please let me know in the comments if you know how to fix this another way and use Map<String, String?>?.

The full source code is available on GitHub: pfilaretov42/spring-data-jdbc-jsonb.

Dream your code, code your dream.

[Tiny] Kotlin, Spring Boot, and the Journey of Duration Serialisation

Petr Filaretov — Fri, 04 Apr 2025 07:21:34 +0000

When using Spring with Kotlin, there is one interesting thing with duration fields serialisation. For instance, when you write a REST endpoint to receive the following body:

{
  "name": "Jim",
  "duration": "PT1S"
}

...and write the following DTO for it:

class KotlinDurationDto(
    val name: String,
    val duration: Duration,
)

..., then the first Duration class that the IDE suggests to import is kotlin.time.Duration. That's reasonable since you are writing in Kotlin.

And then, sending the request to that endpoint results in an HTTP 500 response and the following exception in the service logs:

com.fasterxml.jackson.databind.exc.InvalidDefinitionException: 
Cannot construct instance of `kotlin.time.Duration` (no Creators, like default constructor, exist): 
no String-argument constructor/factory method to deserialize from String value ('PT1S')

This is what you get with Spring Boot 3.3.x and 3.4.x. If you are lucky enough to use an older version, the behaviour may differ. For instance, in Spring Boot 3.2.12, the result is an HTTP 400 with the following warning in the logs:

org.springframework.http.converter.HttpMessageNotReadableException: JSON parse error:
Cannot deserialize value of type `long` from String "PT1S": not a valid `long` value

But that's not all! If the duration is of a nullable type, i.e.:

class KotlinNullableDurationDto(
    val name: String,
    val duration: Duration? = null,
)

...then you'll get another result: an HTTP 500 with the same logs as before:

com.fasterxml.jackson.databind.exc.InvalidDefinitionException: 
Cannot construct instance of `kotlin.time.Duration` (no Creators, like default constructor, exist): 
no String-argument constructor/factory method to deserialize from String value ('PT1S')

Spring Boot 3.3.x+ and the Jackson version that it brings are at least consistent when handling nullable and non-nullable types.

If you are even luckier (like me) to have a service with a lot of dependencies that cause conflicts with Jackson dependency versions (that you haven't found in time), then you may get a weird NullPointerException during serialisation, pointing to a field that is neither of type Duration nor nullable.

The solution for this could be to just use java.time.Duration instead of kotlin.time.Duration.

Here are a couple of FasterXML-related issues on GitHub:

And here is a small project on GitHub to play around with: pfilaretov42/spring-kotlin-duration.

Dream your code, code your dream.

[Tiny] You Don’t Need @EnableKafka... Or Do You?

Petr Filaretov — Thu, 27 Mar 2025 07:33:03 +0000

This week, I learned that when we use Kafka, the @EnableKafka annotation is not needed if an application is a Spring Boot application. We only need it if we are developing with Spring, not Spring Boot.

This is because Spring Boot includes KafkaAnnotationDrivenConfiguration, which is enabled when there is the @EnableKafka annotation class on the classpath. KafkaAnnotationDrivenConfiguration adds @Configuration with @EnableKafka, so that we don't need to add it again to one of our configurations:

@Configuration(proxyBeanMethods = false)
@ConditionalOnClass(EnableKafka.class)
class KafkaAnnotationDrivenConfiguration {
    // ...

    @Configuration(proxyBeanMethods = false)
    @EnableKafka
    @ConditionalOnMissingBean(name = KafkaListenerConfigUtils.KAFKA_LISTENER_ANNOTATION_PROCESSOR_BEAN_NAME)
    static class EnableKafkaConfiguration {

    }
}

And the @EnableKafka annotation class is present on the classpath when we add org.springframework.kafka:spring-kafka as a dependency.

Duplicating @EnableKafka does not hurt, however,

Why add it again if it is already there?
More importantly, we need to understand the effect of the annotations we use. If we don't, we may end up with an application that fails to start (in the best case) or has weird issues that are hard to reproduce and debug (in the worst case).

The confusion about whether the @EnableKafka annotation is required or not may come from the following:

Many sources on the Internet use @EnableKafka annotation with Spring Boot. Here is an example: Intro to Apache Kafka with Spring.
The Javadoc for @EnableKafka does not say anything about Spring Boot. It only states that we need to use this annotation on @Configuration classes. This is probably fair, since spring-kafka (which contains @EnableKafka) does not know anything about Spring Boot or auto-configurations. However, this is still misleading.

In conclusion, the next time you use Kafka with Spring Boot, you know the drill - do not duplicate @EnableKafka on your configurations.

Dream your code, code your dream.

One Container to Rule Them All - Until It Doesn’t

Petr Filaretov — Tue, 11 Mar 2025 16:14:39 +0000

TL;DR

Start the container once, let it run throughout, avoid reusable containers unless necessary, and always prepare the data before tests.

Intro

When working with Testcontainers I found a couple of things that are not very obvious at first glance. Especially when you are just starting to use Testcontainers. Let's check them out.

The full source code is available on Github: pfilaretov42/spring-testcontainers-tips.

Stop the Container

The API

Say we have a Spring Boot application with endpoints to forge and get the rings:

@RestController
@RequestMapping("/rings")
class RingController(
    private val celebrimbor: ElvenSmith<Ring>,
) {

    @PostMapping
    fun forge(): Unit {
        celebrimbor.forgeTheThreeRings()
    }

    @GetMapping
    fun getAll(): List<String> {
        return celebrimbor.getAllTreasures().map { it.name }
    }
}

"Forging," in our case, is simply saving an entity in PostgreSQL:

@Service
class Celebrimbor(
    private val treasury: RingTreasury,
) : ElvenSmith<Ring> {

    @Transactional
    override fun forgeTheThreeRings() {
        treasury.save(Ring(name = "Narya"))
        treasury.save(Ring(name = "Nenya"))
        treasury.save(Ring(name = "Vilya"))
    }

    override fun getAllTreasures(): List<Ring> = treasury.findAll().toList()
}

interface RingTreasury : CrudRepository<Ring, UUID>

The Test

Now, we want to write some tests for this API, and we will use @SpringBootTest.

We want the Spring context to start only once for the whole test suite, so let's add an abstract test class as a base for all tests:

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
abstract class AppAbstractTest {
}

To deal with the database, we will use Testcontainers.

There are a handful of ways to start Testcontainers, including JUnit4 annotations, JUnit5 annotations, ApplicationContextInitializer, JDBC URL scheme, and manual container lifecycle control. Let's choose manual control for now as the least "magic" option:

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
abstract class AppAbstractTest {

    companion object {
        private val postgresContainer = PostgreSQLContainer(DockerImageName.parse("postgres:17"))

        init {
            logger.info { "STARTING CONTAINER" }
            postgresContainer.start()
        }

        @JvmStatic
        @AfterAll
        fun tearDown() {
            logger.info { "STOPPING CONTAINER" }
            postgresContainer.stop()
        }

        // ...
    }

    // ...
}

Here we have a postgresContainer that starts when tests are loaded (init block) and stops after all tests are done (@AfterAll method).

Now, let's add a test that extends AppAbstractTest...

class RingsApiTest : AppAbstractTest() {

    @Test
    fun `should forge the three rings`() {
        logger.info { "TEST: should forge the three rings" }
        testRestTemplate.postForObject<Unit>(endpointUrl, "{}")
        val list = testRestTemplate.getForObject(endpointUrl, List::class.java)
        assertThat(list.size).isEqualTo(3)
    }

    // ...
}

...and run it in the IDE. It passes, and we can see the following logs in the output:

INFO AppAbstractTest -- STARTING CONTAINER
...
INFO RingsApiTest   : TEST: should forge the three rings
...
INFO AppAbstractTest: STOPPING CONTAINER

(I will be cutting out some irrelevant data here and below from every log string for clarity)

So far, so good.

Another API

All right, let's add another API (which we probably should have started with) - to craft the Silmarilli:

@RestController
@RequestMapping("/silmarilli")
class SilmarilliController(
    private val fëanor: ElvenSmith<Silmaril>,
) {

    @PostMapping
    fun craft(): Unit {
        fëanor.craftSilmarilli()
    }

    @GetMapping
    fun getAll(): List<String> {
        return fëanor.getAllTreasures().map { it.fate }
    }
}

Again, "crafting" here is simply saving an entity in the database, but in a different table:

@Service
class Fëanor(
    private val treasury: SilmarilTreasury,
) : ElvenSmith<Silmaril> {

    @Transactional
    override fun craftSilmarilli() {
        treasury.save(Silmaril(fate = "Air"))
        treasury.save(Silmaril(fate = "Earth"))
        treasury.save(Silmaril(fate = "Water"))
    }

    override fun getAllTreasures(): List<Silmaril> = treasury.findAll().toList()
}

interface SilmarilTreasury : CrudRepository<Silmaril, UUID>

Another Test

Now, let's add a test for the Silmarilli API. It will be pretty similar to the Rings API test:

class SilmarilliApiTest : AppAbstractTest() {

    @Test
    fun `should craft Silmarilli`() {
        logger.info { "TEST: should craft Silmarilli" }
        testRestTemplate.postForObject<Unit>(endpointUrl, "{}")
        val list = testRestTemplate.getForObject(endpointUrl, List::class.java)
        assertThat(list.size).isEqualTo(3)
    }

    // ...
}

If we run the test, it passes, and we get the following logs:

INFO AppAbstractTest -- STARTING CONTAINER
...
INFO SilmarilliApiTest: TEST: should craft Silmarilli
...
INFO AppAbstractTest  : STOPPING CONTAINER

Now, let's check that project builds with Gradle (by the way, check out my tiny post on how to enable logging from tests in the Gradle build):

./gradlew clean build

And it fails 🫤

2 tests completed, 1 failed

What's going on here? Let's check the build logs:

INFO AppAbstractTest -- STARTING CONTAINER
...
INFO RingsApiTest       : TEST: should forge the three rings
...
INFO AppAbstractTest    : STOPPING CONTAINER
...
INFO SilmarilliApiTest  : TEST: should craft Silmarilli
WARN com.zaxxer.hikari.pool.ProxyConnection   : HikariPool-1 - Connection org.postgresql.jdbc.PgConnection@64381526 marked as broken because of SQLSTATE(08006), ErrorCode(0)
org.postgresql.util.PSQLException: An I/O error occurred while sending to the backend.
...
ERROR o.a.c.c.C.[.[.[/].[dispatcherServlet]    : Servlet.service() for servlet [dispatcherServlet] in context with path [] threw exception [Request processing failed: org.springframework.transaction.TransactionSystemException: JDBC rollback failed] with root cause
java.sql.SQLException: Connection is closed
...

A-ha! We can see here that the Postgres container is started before all tests, and then stopped after RingsApiTest class is executed, not after all test classes.

And no new Postgres container is started for the SilmarilliApiTest. It happened because we started the container in the static (companion object) init block, and the class is loaded once for all tests. And that's why the SilmarilliApiTest fails - the app cannot connect to the database.

So, how do we fix it? Looks easy: the container is not starting for the SilmarilliApiTest? Let's start it then in the @BeforeAll method!

And now our AppAbstractTest class would look like this:

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
abstract class AppAbstractTest {

    companion object {
        private val postgresContainer = PostgreSQLContainer(DockerImageName.parse("postgres:17"))

        @JvmStatic
        @BeforeAll
        fun setUpAll() {
            logger.info { "STARTING CONTAINER" }
            postgresContainer.start()
        }

        @JvmStatic
        @AfterAll
        fun tearDown() {
            logger.info { "STOPPING CONTAINER" }
            postgresContainer.stop()
        }

        // ...
    }

    // ...
}

Let's run the Gradle build again, and what do we get? The second test fails again:

INFO AppAbstractTest -- STARTING CONTAINER
...
INFO RingsApiTest       : TEST: should forge the three rings
...
INFO AppAbstractTest    : STOPPING CONTAINER
...
INFO AppAbstractTest    : STARTING CONTAINER
...
INFO SilmarilliApiTest  : TEST: should craft Silmarilli
WARN com.zaxxer.hikari.pool.PoolBase          : HikariPool-1 - Failed to validate connection org.postgresql.jdbc.PgConnection@5513a46b (This connection has been closed.). Possibly consider using a shorter maxLifetime value.
...
ERROR o.a.c.c.C.[.[.[/].[dispatcherServlet]    : Servlet.service() for servlet [dispatcherServlet] in context with path [] threw exception [Request processing failed: org.springframework.transaction.CannotCreateTransactionException: Could not open JDBC Connection for transaction] with root cause
java.net.ConnectException: Connection refused

Okay, now the container is starting for the SilmarilliApiTest as expected. However, the application under test cannot connect to it 🤔

This is due to the Spring application context being started once for the whole test suite (thanks to the AppAbstractTest), and the connection details for the second container are not picked up. That's why we have connection problems for the SilmarilliApiTest.

Looks like we need to reuse the first container for all tests. And there is a Testcontainers' feature called reusable containers. It looks promising; let's try it out!

Reusable Containers

The documentation for reusable containers says:

start the container manually by calling start() method, do not call stop() method directly or indirectly

Looks easy, we just need to drop @BeforeAll and @AfterAll methods and get the init block back:

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
abstract class AppAbstractTest {

    companion object {
        private val postgresContainer = PostgreSQLContainer(DockerImageName.parse("postgres:17"))

        init {
            logger.info { "STARTING CONTAINER" }
            postgresContainer.start()
        }

        // ...
    }

    // ...
}

Then, we need to enable reusable containers. According to the same docs, we just need to

Add the following line to the ~/.testcontainers.properties file:

testcontainers.reuse.enable=true

Subscribe to reuse in the container definition:

private val postgresContainer = PostgreSQLContainer(DockerImageName.parse("postgres:17"))
    .withReuse(true)

And that's it!

Let's run the Gradle build and... it is successful! 🎉 Logs say:

INFO AppAbstractTest -- STARTING CONTAINER
...
INFO SilmarilliApiTest : TEST: should craft Silmarilli
...
INFO RingsApiTest      : TEST: should forge the three rings

So, the container is started before the first test and reused for the second test. Great!

Let's run the build again, just in case. And now it fails 😖

2 tests completed, 2 failed

The test report provides details for the failed tests:

AssertionFailedError: 
expected: 3
 but was: 6

Assertion failed for the following code:

assertThat(list.size).isEqualTo(3)

Apparently, this happens because the container started during the first execution of the tests is not stopped at all. It remains running, and the database still holds the three rings and three Silmarilli added during the tests. When all tests are executed a second time, they add three more rings and three more Silmarilli, causing the assertion to fail.

So, how do we make all tests run consistently? 🤔

Fixing Tests

As we can see, reusable containers are not stopped between test executions, and data added during each test is not deleted. Here is what we can do about it.

Clear Database

We need to delete the data in the database before each test:

class RingsApiTest : AppAbstractTest() {

    @BeforeEach
    fun setUp() {
        ringTreasury.deleteAll()
        // ...
    }

    // ...
}

class SilmarilliApiTest : AppAbstractTest() {

    @BeforeEach
    fun setUp() {
        silmarilTreasury.deleteAll()
        // ...
    }

    // ...
}

This ensures that each test starts with a fresh database table, and test results are not affected by leftovers from the other tests or previous test executions.

Do Not Use Reusable Containers

We don't actually need reusable containers since we have neither hundreds of containers nor very heavy containers that could drastically slow down the test execution.

Furthermore, "Reusable" is an experimental feature that should be used carefully. Here is what the documentation says:

Reusable containers are not suited for CI usage and as an experimental feature not all Testcontainers features are fully working (e.g., resource cleanup or networking).

So, we will let Testcontainers create a fresh container for every test execution. To do this, we need to:

Drop the testcontainers.reuse.enable property in the ~/.testcontainers.properties file.
Drop the withReuse(true) property of the container.
Start the container once in the init block.
Do not stop the container for each test class, Ryuk will take care of stopping it at the end of the test suite.

Here is how the abstract test looks like now:

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
abstract class AppAbstractTest {

    companion object {
        private val postgresContainer = PostgreSQLContainer(DockerImageName.parse("postgres:17"))

        init {
            logger.info { "STARTING CONTAINER" }
            postgresContainer.start()
        }

        // ...
    }

    // ...
}

Now, let's run the Gradle build and... it is successful 🎉 We can run it again and again, and it still passes.

Conclusion

We looked at some ways Testcontainers can be used, and here are the key takeaways:

If you use @SpringBootTest and share the same context between test classes, then likely you do not need a container per test class or per every single test, so just start the container once for the whole test suite.
Do not stop the container, leave it to
- Ryuk if you start the container manually, or
- JUnit Jupiter extension if you use the @Testcontainers and @Container annotations.
Do not use reusable containers until you really need them. Make sure you understand the pros and cons of this approach for both local development and CI/CD pipelines.
Clean up (or properly prepare) the data in a database before each test.

Dream your code, code your dream.

[Tiny] Gradle, Show Me the Test Logs!

Petr Filaretov — Fri, 07 Mar 2025 15:39:28 +0000

This week, I learned how to enable logging output for Gradle's test task.

Why did I need it?

I created a couple of tests and added some logging. I ran the tests one by one in IntelliJ IDEA and checked the logs. Then, I ran gradle build and... there were no logs from the tests in the output 🧐

So, if you, like me, are wondering "Where are my logs?", here's how to enable logging during the Gradle build.

Set the showStandardStreams property in the build.gradle file:

test {
    testLogging.showStandardStreams = true
}

This will give you logs split by test classes and test methods.

If you don't want that split and just want the logs in order of appearance, the following should do the trick:

test {
    onOutput { descriptor, event ->
        logger.lifecycle(event.message)
    }
}

Dream your code, code your dream.

Spring Boot Avengers: Uniting Spring Data JDBC and PostgreSQL's JSONB

Petr Filaretov — Tue, 01 Oct 2024 06:29:52 +0000

TL;DR

When working with Spring Data JDBC and a jsonb database column, you may face challenges in selecting the correct type for the jsonb property of the entity, implementing converters from/to database object, and defining Spring Data JDBC queries for jsonb nested properties.

Intro

I worked with Spring Data JDBC recently. The work involved the creation of an API for an entity with part of the data saved as JSON in the jsonb column in PostgreSQL.

There is little info regarding Spring Data JDBC (not Spring Data JPA) and jsonb in the wild. So, I will share my experience and some findings on the topic today.

We will build an API to create, read, update, and delete friends with superpowers.

The full source code is available on GitHub: pfilaretov42/spring-data-jdbc-jsonb.

Alright, let's go step-by-step.

Create a project

The first step is to create a new Spring Boot project in IntelliJ IDEA. Alternatively, you can use Spring Initializr website to do the same thing.

I'm going to choose Kotlin with JDK 21 and Gradle.

Then, we will need the following dependencies:

Spring Web - to build REST API.
Spring Data JDBC - to work with a database.
PostgreSQL Driver - PostgreSQL is our storage this time.
Liquibase Migration - to deal with database changes.

Create a database table

Now we have the basic project setup, so let's create a database table.

First of all, we will need a running PostgreSQL instance, e.g., in Docker. Here is a sample docker-compose YAML (located in ./docker/local-infra.yaml) to do this:

version: '3.9'
services:
  db:
    image: postgres:16.4-alpine3.20
    shm_size: 128mb
    environment:
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"

And now you can start PostgreSQL with

docker-compose -f ./docker/local-infra.yaml up

Then, let's connect to the database with postgres/postgres user/password and create a database and a user:

create database spring_data_jdbc_jsonb;
create user spring_data_jdbc_jsonb with encrypted password 'spring_data_jdbc_jsonb';
grant all privileges on database spring_data_jdbc_jsonb to spring_data_jdbc_jsonb;
alter database spring_data_jdbc_jsonb owner to spring_data_jdbc_jsonb;

Now we will need to provide database connection details in application.yaml:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/spring_data_jdbc_jsonb
    username: spring_data_jdbc_jsonb
    password: spring_data_jdbc_jsonb
  liquibase:
    driver-class-name: org.postgresql.Driver
    change-log: db/changelog/changelog.xml
    url: ${spring.datasource.url}
    user: ${spring.datasource.username}
    password: ${spring.datasource.password}

Here, we also defined parameters for Liquibase. So, let's create the changelog.xml...

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
        xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">

    <include file="db/changelog/changesets/0001-create-table.xml"/>

</databaseChangeLog>

...and add the first change set 0001-create-table.xml to create a table. The major part here is the createTable changeset:

<changeSet id="create table" author="pfilaretov42">
    <createTable tableName="friends">
        <column name="id" type="uuid" defaultValueComputed="uuid_generate_v4()">
            <constraints primaryKey="true" nullable="false"/>
        </column>
        <column name="full_name" type="varchar(255)">
            <constraints nullable="false"/>
        </column>
        <column name="alias" type="varchar(255)">
            <constraints nullable="false"/>
        </column>
        <column name="superpower" type="jsonb">
            <constraints nullable="false"/>
        </column>
    </createTable>
</changeSet>

The friends table has some basic fields (id, full_name, alias) and the jsonb field superpower, which will hold characteristics of the superpower in JSON format. Let's suppose the JSON structure is fixed here, e.g.:

{
  "abilities": [
    ...
  ],
  "weapon": [
    ...
  ],
  "rating": ...
}

Add some data

Now, we can add some data using Liquibase script 0002-add-data.xml. Here is one of the records:

INSERT INTO friends(full_name, alias, superpower)
VALUES ('Peter Parker',
        'Spider-Man',
        '{
          "abilities": [
            "Superhuman strength",
            "Precognitive spider-sense",
            "Ability to cling to solid surfaces"
          ],
          "weapon": [
            "web-shooters"
          ],
          "rating": 97
        }');

Alright, we are now ready to build the first API.

Get all friends

Let's start with the API to get all friends.

We will need a REST controller FriendsController...

@RestController
@RequestMapping("/api/v1/friends")
class FriendsController(
    private val friendsService: FriendsService,
) {

    @GetMapping
    fun getAll(): FriendsResponseDto = friendsService.getAll()
}

..., a service FriendsService for it...

@Service
class FriendsService(
    private val friendsRepository: FriendsRepository,
    private val friendsMapper: FriendsMapper,
) {
    fun getAll(): FriendsResponseDto {
        val entities = friendsRepository.findAll()
        return friendsMapper.toDto(entities)
    }
}

..., a Spring Data repository FriendsRepository...

interface FriendsRepository : CrudRepository<FriendsEntity, UUID> {
    override fun findAll(): List<FriendsEntity>
}

..., and the entity FriendsEntity:

@Table("friends")
class FriendsEntity(
    val id: UUID,
    val fullName: String,
    val alias: String,
    val superpower: String,
)

Here, we defined the superpower field simply as a String. Let's see if that works.

We will also need a mapper interface FriendsMapper to map from entity to DTO...

interface FriendsMapper {
    fun toDto(entities: List<FriendsEntity>): FriendsResponseDto
}

...with the implementation FriendsMapperImpl...

@Component
class FriendsMapperImpl(
    private val objectMapper: ObjectMapper,
) : FriendsMapper {
    override fun toDto(entities: List<FriendsEntity>) = FriendsResponseDto(
        friends = entities.map { entity ->
            FriendsFullResponseDto(
                id = entity.id,
                fullName = entity.fullName,
                alias = entity.alias,
                superpower = objectMapper.readValue(entity.superpower, FriendsSuperpowerDto::class.java)
            )
        }
    )
}

Note that we need to use objectMapper to map from the superpower string field in the entity to the superpower object field in DTO.

DTO classes are simple POJOs with nothing interesting inside, so I'll skip the code for them.

Okay, we have everything we need for now, so let's start the Spring Boot app and call the API to get all friends:

GET http://localhost:8080/api/v1/friends

What do we get back? HTTP 500 with the following error in the log:

ConverterNotFoundException: No converter found capable of converting from type [org.postgresql.util.PGobject] to type [java.lang.String]

Yup, looks like simply using the String type in FriendsEntity.superpower as a jsonb field holder does not work.

Fixing `ConverterNotFoundException`

What options do we have to fix ConverterNotFoundException? Let's start with the first thing that comes to mind. "No converter found"? No problem, we will add one! (actually, two)

To do this, we will need to add a Spring configuration that extends the AbstractJdbcConfiguration class:

@Configuration
class JdbcConfig(
    private val stringWritingConverter: StringWritingConverter,
    private val stringReadingConverter: StringReadingConverter,
) : AbstractJdbcConfiguration() {
    override fun userConverters(): MutableList<*> {
        return mutableListOf(
            stringWritingConverter,
            stringReadingConverter,
        )
    }
}

By overriding the userConverters() method, we provide custom converters for writing the String field to a jsonb database column...

@Component
@WritingConverter
class StringWritingConverter : Converter<String, PGobject> {
    override fun convert(source: String): PGobject {
        val jsonObject = PGobject()
        jsonObject.type = "jsonb"
        jsonObject.value = source
        return jsonObject
    }
}

...and reading from it:

@Component
@ReadingConverter
class StringReadingConverter : Converter<PGobject, String> {
    override fun convert(pgObject: PGobject): String? {
        return pgObject.value
    }
}

That's it. Start the app and call the API to get all friends:

GET http://localhost:8080/api/v1/friends

And now we have a list of friends with superpowers! 🎉

Fixing `ConverterNotFoundException` part 2, POJO

Okay, we have our API working now, thanks to string-to-pgobject converters. However, now we have two types of conversion:

StringReadingConverter to read data from the database into FriendsEntity
objectMapper.readValue() to convert string to object during mapping from entity to DTO in FriendsMapperImpl.toDto()

Since we know that the JSON structure in the superpower field is fixed, we can change the type of the FriendsEntity.superpower field from String to its own class SuperpowerEntity:

@Table("friends")
class FriendsEntity(
    // other fields are the same

    val superpower: SuperpowerEntity,
)

class SuperpowerEntity(
    val abilities: List<String>,
    val weapon: List<String>,
    val rating: Int,
)

And then we need a new @WritingConverter and @ReadingConverter to convert from/to SuperpowerEntity instead of String:

@Component
@WritingConverter
class SuperpowerEntityWritingConverter(
    private val objectMapper: ObjectMapper,
) : Converter<SuperpowerEntity, PGobject> {
    override fun convert(source: SuperpowerEntity): PGobject {
        val jsonObject = PGobject()
        jsonObject.type = "jsonb"
        jsonObject.value = objectMapper.writeValueAsString(source)
        return jsonObject
    }
}

@Component
@ReadingConverter
class SuperpowerEntityReadingConverter(
    private val objectMapper: ObjectMapper,
) : Converter<PGobject, SuperpowerEntity> {
    override fun convert(pgObject: PGobject): SuperpowerEntity {
        val source = pgObject.value
        return objectMapper.readValue(source, SuperpowerEntity::class.java)
    }
}

Now we can update JdbcConfig with these new converters:

@Configuration
class JdbcConfig(
    private val superpowerEntityWritingConverter: SuperpowerEntityWritingConverter,
    private val superpowerEntityReadingConverter: SuperpowerEntityReadingConverter,
) : AbstractJdbcConfiguration() {
    override fun userConverters(): MutableList<*> {
        return mutableListOf(superpowerEntityWritingConverter, superpowerEntityReadingConverter)
    }
}

And replace objectMapper.readValue() conversion in FriendsMapperImpl with a simple mapping to FriendsSuperpowerDto:

@Component
class FriendsMapperImpl : FriendsMapper {
    override fun toDto(entities: List<FriendsEntity>) = FriendsResponseDto(
        friends = entities.map { entity ->
            FriendsFullResponseDto(
                id = entity.id,
                fullName = entity.fullName,
                alias = entity.alias,
                superpower = toDto(entity.superpower),
            )
        }
    )

    private fun toDto(entity: SuperpowerEntity) = FriendsSuperpowerDto(
        abilities = entity.abilities,
        weapon = entity.weapon,
        rating = entity.rating,
    )
}

Start the app, call the API...

GET http://localhost:8080/api/v1/friends

...and it still works. Nice!

Fixing `ConverterNotFoundException` part 3, Map

FriendsEntity.superpower field is strongly typed since we rely on the fixed JSON structure. But what if we need a flexible JSON with different fields for different database records?

What do we do in any unclear situation? That's right, use the Map.

So, let's add FriendsEntity.extras field that can have anything inside:

@Table("friends")
class FriendsEntity(
    // other fields are the same

    val extras: Map<String, Any?>?,
)

Here is an example of an extras field value for Spider-Man:

{
  "species": "Human mutate",
  "publisher": "Marvel Comics",
  "createdBy": [
    "Stan Lee",
    "Steve Ditko"
  ]
}

We will also need a liquibase script 0003-add-extras.xml to add a column and update data:

<changeSet id="add extras column" author="pfilaretov42">
    <addColumn tableName="friends">
        <column name="extras" type="jsonb"/>
    </addColumn>
</changeSet>

<changeSet id="update data with extras" author="pfilaretov42">
    <update tableName="friends">
        <column name="extras" value='
            {
              "species": "Human mutate",
              "publisher": "Marvel Comics",
              "createdBy": [
                "Stan Lee",
                "Steve Ditko"
              ]
            }
        '/>
        <where>alias='Spider-Man'</where>
    </update>

    <!-- Some more updates here -->
</changeSet>

Okay, let's start the app and call the API:

GET http://localhost:8080/api/v1/friends

And we get HTTP 500:

IllegalArgumentException: Expected map like structure but found class org.postgresql.util.PGobject

Okay, we still need converters for the map.

Fixing `ConverterNotFoundException` part 4, Map with converter

To fix IllegalArgumentException we need to add @WritingConverter and @ReadingConverter to convert from/to Map...

@Component
@WritingConverter
class MapWritingConverter(
    private val objectMapper: ObjectMapper,
) : Converter<Map<String, Any?>, PGobject> {
    override fun convert(source: Map<String, Any?>): PGobject {
        val jsonObject = PGobject()
        jsonObject.type = "jsonb"
        jsonObject.value = objectMapper.writeValueAsString(source)
        return jsonObject
    }
}

@Component
@ReadingConverter
class MapReadingConverter(
    private val objectMapper: ObjectMapper,
) : Converter<PGobject, Map<String, Any?>> {
    override fun convert(pgObject: PGobject): Map<String, Any?> {
        val source = pgObject.value
        return objectMapper.readValue(source, object : TypeReference<Map<String, Any?>>() {})
    }
}

...and add them to JdbcConfig, so now it looks like this:

@Configuration
class JdbcConfig(
    private val superpowerEntityWritingConverter: SuperpowerEntityWritingConverter,
    private val superpowerEntityReadingConverter: SuperpowerEntityReadingConverter,
    private val mapWritingConverter: MapWritingConverter,
    private val mapReadingConverter: MapReadingConverter,
) : AbstractJdbcConfiguration() {
    override fun userConverters(): MutableList<*> {
        return mutableListOf(
            superpowerEntityWritingConverter,
            superpowerEntityReadingConverter,
            mapWritingConverter,
            mapReadingConverter,
        )
    }
}

We also need to add extras field to FriendsFullResponseDto...

class FriendsFullResponseDto(
    // other fields are the same

    val extras: Map<String, Any?>?,
)

...and update FriendsMapperImpl.toDto() to support the new field in DTO.

And then, you know the drill: start the app, call the API...

GET http://localhost:8080/api/v1/friends

..., and now it works.

Get a friend by ID

Alright, let's add an API to get a friend by ID. We will need to add an endpoint to FriendsController...

@GetMapping("/{id}")
fun get(@PathVariable("id") id: UUID): FriendsFullResponseDto = 
    friendsService.get(id)

...and add a method to FriendsService:

fun get(id: UUID): FriendsFullResponseDto {
    val entity = friendsRepository.findByIdOrNull(id)
        ?: throw FriendsNotFoundException("Cannot find friend with id=$id")
    return friendsMapper.toDto(entity)
}

Here entity is converted to DTO using a new method in FriendsMapperImpl:

override fun toDto(entity: FriendsEntity) = FriendsFullResponseDto(
    id = entity.id,
    fullName = entity.fullName,
    alias = entity.alias,
    superpower = toDto(entity.superpower),
    extras = entity.extras,
)

And we will also need an exception class to indicate that a friend is not found...

class FriendsNotFoundException(message: String) : RuntimeException(message)

...as well as an exception handler to return HTTP 404 when FriendsNotFoundException is thrown:

@RestControllerAdvice
class RestExceptionHandler : ResponseEntityExceptionHandler() {

    @ExceptionHandler
    fun handleNotFound(e: FriendsNotFoundException): ResponseEntity<Nothing> {
        return ResponseEntity.notFound().build()
    }
}

This is it. Let's start the app, find the id of the existing friend in the friends table and call the API with existing id:

GET http://localhost:8080/api/v1/friends/9463a880-4017-43fd-951e-233fd249091c

Result:

IllegalStateException: Required identifier property not found for class dev.pfilaretov42.spring.data.jdbc.jsonb.entity.FriendsEntity

Okay, spring cannot identify id property. We need to specify it with @Id annotation on FriendsEntity.id field:

@Id
val id: UUID,

One more time - start the app, call the API:

GET http://localhost:8080/api/v1/friends/9463a880-4017-43fd-951e-233fd249091c

And now it works. And if we call it with non-existent id:

GET http://localhost:8080/api/v1/friends/9463a880-0000-0000-0000-233fd249091c

The result is HTTP 404, as expected.

Create a friend

Let's move on and add an API to create a friend. We will need a new controller endpoint FriendsController.createFriend() with corresponding DTOs...

@PostMapping
fun createFriend(@RequestBody request: FriendsRequestDto): CreateFriendResponseDto =
    friendsService.create(request)

..., a service method FriendsService.create()...

@Transactional
fun create(request: FriendsRequestDto): CreateFriendResponseDto {
    val entity = friendsMapper.fromDto(request)
    val createdEntity = friendsRepository.save(entity)
    return CreateFriendResponseDto(createdEntity.id)
}

..., and a mapper method FriendsMapper.fromDto():

override fun fromDto(dto: FriendsRequestDto) = FriendsEntity(
    id = UUID.randomUUID(),
    fullName = dto.friend.fullName,
    alias = dto.friend.alias,
    superpower = fromDto(dto.friend.superpower),
    extras = dto.friend.extras,
)

Start the app and call the new API:

POST http://localhost:8080/api/v1/friends
Content-Type: application/json

{
  "friend": {
    "fullName": "Anthony Edward Stark",
    "alias": "Iron Man",
    "superpower": {
      "abilities": [
        "Genius-level intellect",
        "Proficient scientist and engineer"
      ],
      "weapon": [
        "Powered armor suit"
      ],
      "rating": 77
    },
    "extras": {
      "publisher": "Marvel Comics",
      "firstAppearance": {
        "comicBook": "Tales of Suspense #39",
        "year": 1963
      },
      "createdBy": [
        "Stan Lee",
        "Larry Lieber"
      ]
    }
  }
}

And the result is HTTP 500:

IncorrectUpdateSemanticsDataAccessException: Failed to update entity [dev.pfilaretov42.spring.data.jdbc.jsonb.entity.FriendsEntity@4081a76e]; Id [578f74ef-9721-4230-8be6-bc88f252c820] not found in database

Hmm, that's not what we expected. And here is what happened.

Entity id is generated in FriendsMapperImpl.fromDto() as UUID.randomUUID().

When CrudRepository.save() is called, it needs to understand whether this is create or update operation on entity parameter. To do this it checks @Id field on entity:

if @Id field is null, then it creates entity
if @Id field is not null, then
- if entity implements Persistable interface, it uses Persistable.isNew() method to choose between create and update operations
- if entity is not Persistable, then it updates entity

So, in our case, entity.id is not null and FriendsEntity is not Persistable. That's why the update operation was called instead of the create one that we expected, and it failed because there is no such record in the database.

Fixing `IncorrectUpdateSemanticsDataAccessException`

To fix the IncorrectUpdateSemanticsDataAccessException during entity creation, we have the choice:

Make sure FriendsEntity.id is null when we create a new entity. To do this, we need to make the FriendsEntity.id field nullable:

@Table("friends")
class FriendsEntity(
    @Id
    val id: UUID?,
    // ...
)

This is pretty simple approach, but the caveat is that we will need to deal with nullable id during conversion of entity to DTO. But the id should always be there for existing entity, shouldn't it?

Make FriendsEntity implement the Persistable interface. Then, we can leave the FriendsEntity.id field non-nullable and generate a new id during an object creation. Here is what FriendsEntity would look like:

@Table("friends")
class FriendsEntity(
    @Id
    val id: UUID,
    // ...
) : Persistable<UUID> {
    // ...
}

I will choose the second option, because I don't like to deal with nullable fields which cannot actually hold null values. So, here is our new FriendsEntity:

@Table("friends")
class FriendsEntity(
    @Id
    @Column("id")
    val uuid: UUID,
    // ...
) : Persistable<UUID> {

    @Transient
    var isNewEntity = false

    override fun getId(): UUID = uuid

    override fun isNew(): Boolean = isNewEntity
}

Here we have a transient field isNewEntity, which should be set to true during entity creation in FriendsService.create(). And then, the isNew() method will return true for a new entity, and we should be good during entity creation.

Also, note that we had to rename the id property to uuid. This is because the Persistable interface has a getId() method to implement, and it clashes with a generated getter for the id property.

Okay, let's start the app and call the create API once again:

POST http://localhost:8080/api/v1/friends
Content-Type: application/json

{
  "friend": {
    "fullName": "Anthony Edward Stark",
    "alias": "Iron Man",
    "superpower": {
      "abilities": [
        "Genius-level intellect",
        "Proficient scientist and engineer"
      ],
      "weapon": [
        "Powered armor suit"
      ],
      "rating": 77
    },
    "extras": {
      "publisher": "Marvel Comics",
      "firstAppearance": {
        "comicBook": "Tales of Suspense #39",
        "year": 1963
      },
      "createdBy": [
        "Stan Lee",
        "Larry Lieber"
      ]
    }
  }
}

Now it works and the entity is created.

Update a friend

Let's move on and add an API to update friends. We will need a controller endpoint FriendsController.updateFriend() with corresponding DTOs...

@PutMapping("/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)
fun updateFriend(@PathVariable("id") id: UUID, @RequestBody request: FriendsRequestDto) {
    friendsService.update(id, request)
}

...and a service method FriendsService.update():

@Transactional
fun update(id: UUID, request: FriendsRequestDto) {
    val entity = friendsMapper.fromDto(id, request)
    friendsRepository.save(entity)
}

Here we leave the FriendsEntity.isNewEntity flag with the default value of false during entity creation.

And we also need to add the id parameter to FriendsMapperImpl.fromDto():

if this is an update operation, FriendsEntity.uuid is set to existing ID
if this is a create operation, FriendsEntity.uuid is set to random UUID

override fun fromDto(id: UUID?, dto: FriendsRequestDto) = FriendsEntity(
    uuid = id ?: UUID.randomUUID(),
   // ...
)

Okay, let's start the app and call the update API:

PUT http://localhost:8080/api/v1/friends/85670f8f-aae7-4feb-aa9c-a61574e8b60f
Content-Type: application/json

{
  "friend": {
    "fullName": "Tony Stark",
    "alias": "Iron Man",
    "superpower": {
      "abilities": [
        "Genius-level intellect",
        "Proficient scientist and engineer"
      ],
      "weapon": [
        "Powered armor suit"
      ],
      "rating": 77
    },
    "extras": {
      "publisher": "Marvel Comics",
      "firstAppearance": {
        "comicBook": "Tales of Suspense #39",
        "year": 1963
      },
      "createdBy": [
        "Stan Lee",
        "Larry Lieber"
      ]
    }
  }
}

And the result is HTTP 204, as expected.

Delete a friend

Now, let's quickly add an API to delete friends, as there is nothing interesting in terms of jsonb here. We will need a controller endpoint FriendsController.deleteFriend()...

@DeleteMapping("/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)
fun deleteFriend(@PathVariable("id") id: UUID) =
    friendsService.delete(id)

...and a corresponding service method FriendsService.delete():

@Transactional
fun delete(id: UUID) =
    friendsRepository.deleteById(id)

That's it. Start the app and call the API:

DELETE http://localhost:8080/api/v1/friends/29663075-8ba3-468f-839b-63fefc5059ae

And the result is HTTP 204, as expected.

Search friends

Now we have a basic set of CRUD operations. So, it's time to add an API to search friends. Let's suppose we want to find all friends that have a superpower rating greater than 50. Remember where we store the superpower rating? It's in the FriendsEntity.superpower.rating integer field:

@Table("friends")
class FriendsEntity(
    val superpower: SuperpowerEntity,
    // ...
) : Persistable<UUID> {
    // ...
}

class SuperpowerEntity(
    val rating: Int,
    // ...
)

And superpower is the jsonb database column.

So, let's build Spring Data repository method to search by superpower rating:

interface FriendsRepository : CrudRepository<FriendsEntity, UUID> {
    fun findBySuperpowerRatingGreaterThan(rating: Int): List<FriendsEntity>

    // ...
}

Now we will need a controller endpoint FriendsController.getFriendsBySuperpowerRating()...

@GetMapping("/by-superpower")
fun getFriendsBySuperpowerRating(
    @RequestParam("rating") rating: Int,
    @RequestParam("operator") operator: ComparisonOperator,
): FriendsResponseDto =
    friendsService.getBySuperpowerRating(rating, operator)

..., enum ComparisonOperator...

enum class ComparisonOperator {
    GT, GTE, LT, LTE, BETWEEN
}

..., and a service method FriendsService.getBySuperpowerRating() that uses repository method FriendsRepository.findBySuperpowerRatingGreaterThan() created earlier:

fun getBySuperpowerRating(rating: Int, operator: ComparisonOperator): FriendsResponseDto {
    val entities = when (operator) {
        ComparisonOperator.GT -> friendsRepository.findBySuperpowerRatingGreaterThan(rating)
        else -> TODO("Not implemented yet")
    }
    return friendsMapper.toDto(entities)
}

Start the app and... it fails with the following error:

BeanCreationException: Error creating bean with name 'friendsRepository'
QueryCreationException: Could not create query for public abstract List findBySuperpower_RatingGreaterThan(int);

MappingException: Couldn't find PersistentEntity for property private final dev.pfilaretov42.spring.data.jdbc.jsonb.entity.SuperpowerEntity dev.pfilaretov42.spring.data.jdbc.jsonb.entity.FriendsEntity.superpower

Apparently, Spring Data JDBC cannot build a query based on the entity structure we have.

If we try another method name, e.g. findBySuperpower_RatingGreaterThan(int), the result is the same. I did not find a way to build the method name so that it works with the jsonb database column. Please let me know in the comments if it is possible.

Fixing `MappingException`

To fix the MappingException, we can define the query for FriendsRepository.findBySuperpowerRatingGreaterThan() method manually:

@Query("select * from friends where (superpower->>'rating')::NUMERIC > :rating")
fun findBySuperpowerRatingGreaterThan(rating: Int): List<FriendsEntity>

And now the app starts without errors. And if we call the API...

GET http://localhost:8080/api/v1/friends/by-superpower?rating=50&operator=GT

..., we will get the expected result.

Conclusion

Based on Spring Boot and Spring Data JDBC, we built the API to create, update, delete, and search for friends that hold some data as a PostgreSQL jsonb column. Challenges we faced during the API implementation included:

selecting the correct type for the jsonb property of the entity (FriendsEntity.superpower, FriendsEntity.extras)
implementing converters from/to PGobject
defining Spring Data JDBC queries for jsonb nested properties (FriendsEntity.superpower.rating)

We also looked at the CrudRepository.save() method's logic for create and update operations and the choices we have to implement them properly.

Dream your code, code your dream.

How to build your interactive resume in 4 simple and 2 easy steps

Petr Filaretov — Tue, 02 Apr 2024 21:26:13 +0000

TL;DR

Creating an interactive resume is as simple as copying the game and customising it, and as easy as publishing under your domain.

Intro

As a software engineer looking for new opportunities, have you ever asked yourself the following:

How do I stand out amongst other applicants in my job search?
How can I convey my skills, creativity, and personality to potential employers?

One of the answers to these questions is a fancy interactive resume that is engaging and fun to go through.

In this post, we will walk through the steps of building an interactive resume. By the way, here is my one:

https://cv.pfilaretov42.dev

The full source code is available on GitHub.

Okay, let's dive in!

1. Build a basic JavaScript game

Our interactive resume will be based on a Pokémon-like JavaScript game. So, the first thing is to watch this JavaScript Game Tutorial. It is very detailed and guides you through all the steps of building the game, i.e., creating a map, adding the content, and scripting characters' behaviour.

It doesn't matter if you ~~like~~ know JavaScript or not. The code is pretty simple and uses zero frameworks. Believe me, I'm not a front-end developer at all.

In the video description, you will find links to

assets (the map, images, and audio);
full source code on GitHub.

So, you will not need to type and create everything from scratch. Just watch the video to understand how things are organised, and then run the game locally from the source code.

2. Customise the map

Once you have the game up and running, it's time to customise it and turn it into a resume.

Think of a concept:

How do you want the resume to look?
How does the resume show your skills as a developer?
How do you present the information: skills, work experience, education, etc.?
Which characters are involved?
Is there any story you want to tell?

You can google for interactive resumes and other simple games for ideas and inspiration. Here are some examples:

When you decide on the high-level design of the resume, start building your map in Tiled. You can customise the map from the basic game you already have or build your one from scratch - just try and see what works best for you.

Here is a great resource of game assets that you can use: itch.io. There are tons of tilesets, backgrounds, sprites, icons, sound effects, music, and so on. Both free and paid.

So, for now, build the first draft version of the map and move on.

3. Customise the content

When the first version of the map is ready, start customising the content.

You will need to update the JS code with your own characters' map data, collisions' data, text, battle zones, etc.

Use your own characters, music, fonts, etc.

Make it work with your map.

If in doubt about how things are working and how to customise something, check out the video from point 1 again. You can find 95% of the answers there. And what about another 5%? You know the drill: GIYF.

4. Iterate, test, and iterate again

Alright, now you know how to build the map and customise the content so that everything works together. It's time for trial and error.

Try your ideas. Update the map, adapt content, and see if you like it. Iterate again and again until you are happy with the result.

It's easier said than done, yet try to adapt your resume to different browsers and screen sizes. You never know how a recruiter will look at your resume, so at least be aware of how it looks and behaves for a variety of clients.

5. Buy the domain name

Great, the hardest part is done! By now you have your interactive resume working locally. It's time to make it available to the world.

Find your favourite domain registrar and buy the domain name.

6. Publish with GitHub Pages

It's super easy to publish a static site like the resume with GitHub Pages. Just check out the docs.

For your domain name to work, you will need to go through the verification process. See Configuring a custom domain for more details.

Congratulations on creating your brand new and shiny interactive resume!

Conclusion

As you can see, creating an interactive resume is a mix of both simple and easy steps. If you want to catch potential employers' attention or are just curious and have some free time, then it is definitely worth the effort.

Dream your code, code your dream.

[Tiny] Testcontainers with private docker registry

Petr Filaretov — Tue, 05 Mar 2024 06:07:00 +0000

It is a common practice for an organisation to have a private docker registry which is the only source of images during the build in a CI/CD pipeline.

If you are using testcontainers, note that by default they are using Docker Hub as a source of images.

To use the private registry you need to add the testcontainers.properties file to the src/test/resources directory and provide your private registry as an image prefix, for instance:

hub.image.name.prefix=private-registry.example.com/

Note that trailing slash / is needed here, so that the full path to the image is built correctly.

Once this is done, you may experience some issues with the build.

Testcontainers use ryuk image under the hood. And some versions of ryuk have known security vulnerabilities. So, it would be reasonable to drop vulnerable images from the private registry and keep healthy images only.

If you are lucky enough, your testcontainers version will use the vulnerable ryuk version. In this case, you can provide the ryuk image manually in the aforementioned testcontainers.properties file, for instance:

ryuk.container.image=testcontainers/ryuk:0.3.3

Another potential issue during the build is images used in tests, for instance, database images like PostgreSQL or Neo4j. Make sure they are available in the private registry.

Dream your code, code your dream.

[Tiny] Kotlin list modification approach

Petr Filaretov — Sat, 02 Mar 2024 08:39:12 +0000

Sometimes you need a class property of a list type with the ability to modify the list at some point later.

In Kotlin we have val/var keywords to define variables and mutable/immutable list types which gives 4 possible combinations.

val with an immutable list is not an option in our case as there is no way to modify it later.

Also, var with a mutable list doesn't make much sense here, since it leaves the ability to both assign a new list and modify the existing one.

This leaves us with two options:

val with mutable list
var with immutable list

For instance:

class ClassWithLists {
    private val mutableList: MutableList<String> = mutableListOf("1", "2", "42")
    private var immutableList: List<String> = listOf("1", "2", "42")
}

Okay, but which one is the best?

As always, the answer is 42 "it depends". Both approaches are valid and have their pros and cons.

val with a mutable list looks more promising when you need to do a lot of list modifications.

On the other hand, var with an immutable list is safer. Once it is set, you can be sure it is not modified either inside or outside of the class, if you ever return it in the getter.

So, if you ask my opinion, I'd use var with an immutable list unless there are critical performance issues with this approach.

And what do you use?

Dream your code, code your dream.

[Tiny] Is a sealed class abstract? Kotlin and Java way.

Petr Filaretov — Mon, 12 Feb 2024 14:53:55 +0000

As you may know, both Kotlin and Java have a feature called sealed classes. Let's play a little with them.

Kotlin sealed classes

Kotlin goes first. What do you think will be printed here?

sealed class Hobbit
class Frodo : Hobbit()

fun main() {
    val hobbitClass = Hobbit::class
    println("Hobbit class: isAbstract=${hobbitClass.isAbstract}, isSealed=${hobbitClass.isSealed}")

    val frodoClass = Frodo::class
    println("Frodo class: isAbstract=${frodoClass.isAbstract}, isSealed=${frodoClass.isSealed}")
}

Output:

Hobbit class: isAbstract=false, isSealed=true
Frodo class: isAbstract=false, isSealed=false

According to Kotlin documentation

A sealed class is abstract by itself

However, note that isAbstract for a sealed class returns false! So, if you want to check if the class is effectively abstract, you need to check both isAbstract and isSealed.

Alright, what if we explicitly add the abstract keyword on a sealed class? What will be printed then?

abstract sealed class Human

fun main() {
    val humanClass = Human::class
    println("Human class: isAbstract=${humanClass.isAbstract}, isSealed=${humanClass.isSealed}")
}

Output:

Human class: isAbstract=false, isSealed=true

So, nothing has actually changed.

And if we simply take an abstract class, what will be the result?

abstract class Maiar

fun main() {
    val maiarClass = Maiar::class
    println("Maiar class: isAbstract=${maiarClass.isAbstract}, isSealed=${maiarClass.isSealed}")
}

Output:

Maiar class: isAbstract=true, isSealed=false

Good, nothing unexpected here.

Java sealed classes

Okay, what about Java?

With Java it is very simple: you will not be caught by isAbstract because the Class class has no such a function. And isSealed works the same way as in Kotlin:

sealed class Hobbit {}
final class Frodo extends Hobbit {}

public class TestClassProperties {
    void main() {
        var hobbitClass = Hobbit.class;
        System.out.println(STR."Hobbit class: isSealed=\{hobbitClass.isSealed()}");

        var frodoClass = Frodo.class;
        System.out.println(STR."Frodo class: isSealed=\{frodoClass.isSealed()}");
    }
}

Output:

Hobbit class: isSealed=true
Frodo class: isSealed=false

Dream your code, code your dream.

DEV Community: Petr Filaretov

MapStruct: When a Helper Method Maps More Than You Asked For

The Setup

The Pitfall

Why This Happens

How To Avoid The Surprise

1. Move the helper out of the mapper and call it via expression

2. Qualify and isolate mapping methods

3. Make the transformation type-specific

Conclusion

The Return of the LTS: What Java 25 Brings Beyond 21

Intro

Production-Ready Features in Java 25

Preview Features in Java 25

Incubator Features in Java 25

Experimental Features in Java 25

Withdrawn Features Between Java 21 and Java 25

Production-Ready Features with Examples

Scoped Values

Before: The ThreadLocal Approach

After: The ScopedValue Way

Flexible Constructor Bodies

Before: The Rigid Constructor Rules

After: The Graceful Constructor Freedom

Unnamed Variables & Patterns

Before: Forced to Name Unused Variables

After: Clean Unused Variable Declaration

Stream Gatherers

Before: Limited to Built-in Operations

After: Custom Stream Transformations

Quantum-Resistant Module-Lattice-Based Key Encapsulation Mechanism

Before: RSA Key Transport

After: Post-Quantum Key Encapsulation

Quantum-Resistant Module-Lattice-Based Digital Signature Algorithm

Before: Signing with ECDSA

After: Signing with Quantum-Resistant ML-DSA

Key Derivation Function API

Before: The Manual Key Derivation

After: The Refined KDF API

Foreign Function & Memory API

Before: The Risky JNI Approach

After: The Safe FFM API

Compact Source Files And Instance Main Methods

Before: The Verbose Incantation

After: The Hobbit-Sized Version

Markdown Documentation Comments

Before: The HTML Way

After: Markdown Syntax

Module Import Declarations

Before: Import Declarations

After: Module Import

Conclusion

[Tiny] Spring Data JDBC: When a Map Pretends to Be a String

[Tiny] Kotlin, Spring Boot, and the Journey of Duration Serialisation

[Tiny] You Don’t Need @EnableKafka... Or Do You?

One Container to Rule Them All - Until It Doesn’t

TL;DR

Intro

Stop the Container

The API

The Test

Another API

Another Test

Reusable Containers

Fixing Tests

Clear Database

Do Not Use Reusable Containers

Conclusion

[Tiny] Gradle, Show Me the Test Logs!

Spring Boot Avengers: Uniting Spring Data JDBC and PostgreSQL's JSONB

TL;DR

Intro

Create a project

Create a database table

Add some data

Get all friends

Fixing ConverterNotFoundException

Fixing ConverterNotFoundException part 2, POJO

Fixing ConverterNotFoundException part 3, Map

Fixing ConverterNotFoundException part 4, Map with converter

1. Move the helper out of the mapper and call it via `expression`

Fixing `ConverterNotFoundException`

Fixing `ConverterNotFoundException` part 2, POJO

Fixing `ConverterNotFoundException` part 3, Map

Fixing `ConverterNotFoundException` part 4, Map with converter

Fixing `IncorrectUpdateSemanticsDataAccessException`

Fixing `MappingException`