1. Introduction

JDK 24 introduced AOT Cache with JEP 483. This cache allows applications to start faster by pre-loading and also pre-linking classes. However, the workflow of creating the cache effectively required two separate java invocations.

As a result, JDK 25 improves on that with two new JEPs. First, JEP 514 simplifies the AOT cache creation into a single command. And second, JEP 515 extends the cache to store method execution profiles, improving application warmup time.

In this article, we’ll explore both new JEPs and see how they work together. It is also important to note that we’re going ot need JDK 25 to take advantage of these features.

2. How AOT Cache Worked in JDK 24

Before we delve into the JDK 25 ways of doing AOT Caches, let’s quickly recap how AOT caching worked with JDK 24.

To create an AOT cache back then, we had to invoke the java utility twice, and thus create two separate java processes. The first invocation runs the application in record mode. It means that Runtime observes how the application behaves during a training run and saves that information into an AOT configuration file:

$ java -XX:AOTMode=record -XX:AOTConfiguration=app.aotconf -cp app.jar com.example.App

The second invocation uses that configuration generated on the previous step to actually build the cache:

$ java -XX:AOTMode=create -XX:AOTConfiguration=app.aotconf  -XX:AOTCache=app.aot

And finally, we can run the application with the generated cache, which, theoretically, should significantly reduce startup time:

$ java -XX:AOTCache=app.aot -cp app.jar com.example.App

This workflow, while it of course works, leaves us with a temporary configuration file and requires managing two separate commands. The experienced readers may note that a similar clumsy process with two phases was with AppCDS archives (effectively, a predecessor to AOT Cache). So, JEP 514 addresses exactly that for AOT Caches now.

3. One-Shot AOT Cache Creation (JEP 514)

JEP 514 introduces a new command-line non-standard (-XX) VM option: AOTCacheOutput. When we use this option alone, without any other AOT flags, the launcher automatically splits the invocation into two internal sub-invocations—one for training and one for cache creation.

So, instead of the two-step workflow above, we can simply do:

$ java -XX:AOTCacheOutput=app.aot -cp app.jar com.example.App

This single command replaces the two commands that were initially used to create the AOT Cache. The JVM runs the application as a training exercise, records the dynamics, and then just creates the AOT cache in one shot.

The production command (providing the cache to the production workload) remains the same since JDK 24:

$ java -XX:AOTCache=app.aot -cp app.jar com.example.App

But here is the thing – there is still a two-phase procedure done in the background. Effectively, the java launcher creates two subprocesses to complete the cache creation. That is important, and it has its implications.

4. The Downsides of the One-Shot Approach

One may think that a two-process setup is just the obvious choice, and it is the way to go – not quite.

As mentioned, these are two distinct java processes that are going to get launched, and both of them have their own heaps. And because they are both launched by the java launcher process (literally the one that is created by calling the java binary), the peak memory consumption is potentially doubled. So, if we specify -Xmx4g, the one-step workflow, potentially, at most, will need 8GB of heap memory in total to complete.

So, the one-step workflow is great for most scenarios, but the two-step approach also has its place, in particular in memory-constrained environments. It may easily be the case that the cloud VM that is going to host our application will not have sufficient RAM resources to serve the double-sized heap. In that case, the explicit two-step workflow is the preferred option.

5. AOT Method Profiling (JEP 515)

While JEP 514 simplifies the process of AOT cache creation, JEP 515 enhances what information the cache stores.

To understand JEP 515, we need to recall how HotSpot reaches peak performance. The JIT compiler identifies hot methods (the methods that are executed relatively frequently) and then compiles them to optimized native code. But in order to do this, it has to collect some profiling information for those methods. And this process takes time. Usually, this time is called a warmup period, and during this period, the application runs slower than it potentially can.

And frankly, it is often the case that the execution patterns of our application are roughly the same. Our production workloads often took similar if branches under the same circumstances. So the profiling information won’t really change from one app launch to another. Thus, it also makes sense to cache it ahead of time.

So, JEP 515 solves this by extending the AOT cache to include method execution profiles from the training run. When the application starts in production, those profiles are instantly available, so the JIT compiler can begin generating optimized code right away, without waiting for warmup.

The cool thing is that we don’t need to change the launch command, let alone the application code, to benefit from this feature. Profiling data is automatically collected during the training run and then stored in the AOT cache. So, this just works out-of-the-box with the one-step workflow from JEP 514:

# Training + cache creation (profiles are included automatically)
$ java -XX:AOTCacheOutput=app.aot -cp app.jar com.example.App
# Production run (benefits from both cached classes and cached profiling info)
$ java -XX:AOTCache=app.aot -cp app.jar com.example.App

In the case above, the JVM starts with the code cache that already contains certain profiling information.

6. Runtime Profiling vs. Cached Profiling

An important note here is that cached profiles don’t prevent additional profiling during production. The HotSpot JVM continues to profile and optimize the application as it runs, combining the benefits of AOT profiles, online profiling, and JIT compilation.

It is important since an application’s behavior in production can still possibly diverge from what was observed during the training run. Cached profiles just give the JIT a quick start, allowing it to compile some methods sooner. As the app runs, the HotSpot re-evaluates its understanding of workload patterns and then recompiles methods if needed.

7. Conclusion

JEP 514 and JEP 515 are both part of the OpenJDK Project Leyden effort to improve Java startup and warmup performance. JEP 514 brings a practical quality-of-life improvement — collapsing the two-step AOT cache creation into a single command. While often the preferred approach, still, in memory-constrained environments, the two-phase process might be the right way to go.

JEP 515 enriches the cached data by including method profiles, so the JIT compiler can start compiling from the very start of the app.

       

1. Introduction

In this tutorial, we’ll learn how to deserialize JSON into Java objects using multi-parameter constructors with Jackson.

By default, Jackson requires a default constructor that doesn’t accept any parameters. The fields are set using setter methods or reflection. If we want Jackson to use a non-default constructor, we need to annotate that constructor with the @JsonCreator annotation. This annotation can be applied to constructors and static factory methods of records and enums. In this tutorial, we’ll have a look at all these cases.

We’ll also look at the options Jackson provides to reduce the number of annotations needed for deserialization.

2. Setup

2.1. Maven Dependencies

In addition to the basic Jackson dependency, we need Jackson’s parameter names module:

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-core</artifactId>
    <version>2.17.2</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.module</groupId>
    <artifactId>jackson-module-parameter-names</artifactId>
    <version>2.17.2</version>
<dependency>

2.2. Java Classes

Throughout the tutorial, we’ll use the Ticket class:

public class Ticket {
    @JsonProperty("event")
    private String eventName;
    private String guest;
    private final Currency currency;
    private final int price;
    public Ticket() {
        this.price = 0;
        this.currency = Currency.EUR;
    }
    public void setGuest(String guest) {
        this.guest = guest;
    }
    
    // getters for all attributes
}

Note that we defined a setter method only for the guest attributes, while providing getters for all attributes. Here, we intentionally omit the setters for the three other attributes to demonstrate the behavior of the deserialization. Also, we use @JsonProperty on the eventName attribute to demonstrate the different ways Jackson offers to serialize a field.

Here’s the currency enum:

public enum Currency {
    EUR("Euro", "cent"),
    GBP("Pound sterling", "penny"),
    CHF("Swiss franc", "Rappen");
    private String fullName;
    private String fractionalUnit;
    Currency(String fullName, String fractionalUnit) {
        this.fullName = fullName;
        this.fractionalUnit = fractionalUnit;
    }
}

2.3. JSON To Deserialize

Here’s the JSON that we want to deserialize in the examples:

{
  "event": "Devoxx",
  "guest": "Maria Monroe",
  "currency": "EUR",
  "price": 50
}

3. Default Deserialization

We need to define a default, no-argument constructor because the class has a final attribute. If we only define a constructor that takes the currency and price as arguments, Jackson won’t be able to deserialize the object:

public Ticket(Currency currency, int price) {
    this.price = price;
    this.currency = currency;
}

Jackson will throw an exception:

com.fasterxml.jackson.databind.exc.MismatchedInputException: 
  Cannot construct instance of `com.baeldung.jackson.multiparameterconstructor.Ticket` 
  (no Creators, like default constructor, exist): cannot deserialize from Object value

4. Deserialization Using @JsonCreator

To indicate which constructor should be used for deserialization, we can use the @JsonCreator annotation.

4.1. Defining a Constructor With @JsonCreator and @JsonProperty

If we want to use the two-argument constructor, we need to annotate it with @JsonCreator and annotate the parameters with @JsonProperty:

@JsonCreator
public Ticket(@JsonProperty("currency") Currency currency, @JsonProperty("price") int price) {
    this.price = price;
    this.currency = currency;
}

Jackson will deserialize the JSON as follows:

• The two attributes, currency and price, are set in the constructor.
• The guest attribute is set using its setter method.
• The eventName attribute doesn’t have a setter method and is set using reflection.

If there is no setter method for an attribute, Jackson sets the attribute using reflection based on its name. If the Java attribute name differs from the JSON field name, we can use the @JsonProperty annotation to define the JSON field name. In our example, we annotate the eventName attribute with @JsonProperty(“event”) to indicate that the JSON field name is event, while the Java attribute name is eventName.

We can annotate only one constructor with @JsonCreator. If we annotate a second constructor in addition to the one we have already defined:

@JsonCreator
public Ticket(@JsonProperty("currency") Currency currency, @JsonProperty("price") int price, @JsonProperty("guest") String guest) {
    this.price = price;
    this.currency = currency;
    this.guest = guest;
}

Jackson will throw an exception:

com.fasterxml.jackson.databind.JsonMappingException: 
  com.fasterxml.jackson.databind.exc.InvalidDefinitionException: 
    Conflicting property-based creators: 
    already had explicitly marked creator [constructor for `com.baeldung.jackson.multiparameterconstructor.Ticket` (2 args), 
    annotations: {interface com.fasterxml.jackson.annotation.JsonCreator=@com.fasterxml.jackson.annotation.JsonCreator(mode=DEFAULT)}, 
    encountered another: [constructor for `com.baeldung.jackson.multiparameterconstructor.Ticket` (3 args), 
    annotations: {interface com.fasterxml.jackson.annotation.JsonCreator=@com.fasterxml.jackson.annotation.JsonCreator(mode=DEFAULT)}

4.2. Constructor Without @JsonProperty

Jackson uses reflection to map JSON field names to Java class attributes. This works for class attributes but doesn’t work for method parameter names. Therefore, if we define a constructor without @JsonProperty annotations:

@JsonCreator
public Ticket(Currency currency, int price, String guest) {
    this.price = price;
    this.currency = currency;
    this.guest = guest;
}

We get an exception:

com.fasterxml.jackson.databind.exc.InvalidDefinitionException: 
  Invalid type definition for type `com.baeldung.jackson.multiparameterconstructor.Ticket`: 
  Argument #0 of constructor [constructor for `com.baeldung.jackson.multiparameterconstructor.Ticket` (2 args), 
  annotations: {interface com.fasterxml.jackson.annotation.JsonCreator=@com.fasterxml.jackson.annotation.JsonCreator(mode=DEFAULT)} 
  has no property name (and is not Injectable): can not use as property-based Creator

Java does not retain method parameter names at runtime, so we need to annotate the parameters with @JsonProperty to specify the JSON field name that should be mapped to each parameter.

If we want to avoid annotating the parameters with @JsonProperty, we can register the ParameterNamesModule and add the parameters flag to the compiler.

First, we need to add the Maven dependency:

<dependency>
    <groupId>com.fasterxml.jackson.module</groupId>
    <artifactId>jackson-module-parameter-names</artifactId>
    <version>2.21.1</version>
</dependency>

Then, we need to register the ParameterNamesModule with the object mapper:

ObjectMapper mapper = JsonMapper.builder()
  .constructorDetector(ConstructorDetector.USE_PROPERTIES_BASED)
  .addModule(new ParameterNamesModule(JsonCreator.Mode.PROPERTIES))
  .build();

And add the parameters flag to the compiler:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <compilerArgs>
            <arg>-parameters</arg>
        </compilerArgs>
    </configuration>
</plugin>

4.3. Configuration With ConstructorDetector

We still need to add the @JsonCreator annotation to mark the constructor that we want to use for deserialization.

As of Jackson 2.12, we can register a ConstructorDetector to specify the constructor that should be used for deserialization without the need to annotate it with @JsonCreator:

ObjectMapper mapper = JsonMapper.builder()
  .constructorDetector(ConstructorDetector.USE_PROPERTIES_BASED)
  .addModule(new ParameterNamesModule(JsonCreator.Mode.PROPERTIES))
  .constructorDetector(ConstructorDetector.USE_PROPERTIES_BASED)
  .build();

Notably,  if we configure Jackson to detect the constructor and also annotate one of multiple constructors with @JsonCreator, then the annotated constructor has preference over a constructor that would be detected otherwise.

5. Records

Jackson can deserialize records using the canonical constructor, which is present by default. Let’s consider the following record:

public record Guest(@JsonProperty("firstname") String firstname, @JsonProperty("surname") String surname) {}

And the following JSON:

{
  "firstname": "Maria",
  "surname": "Monroe"
}

Jackson can deserialize JSON to Java records without the need for a no-argument constructor. If we register the ParameterNamesModule and compile with the parameters flag, we don’t need to annotate the record components with @JsonProperty:

public record Guest(String firstname, String surname) {}

In some cases, we might want to customize the canonical constructor:

public Guest(String firstname, String surname) {
    this.firstname = firstname;
    this.surname = surname;
    // some validation
}

Again, we don’t need to annotate the constructor with @JsonCreator because Jackson will use the canonical constructor by default.

One case where we do need the @JsonCreator annotation is when we want to add a static factory method:

@JsonCreator
public static Guest fromJson(String firstname, String surname) {
    // some validation
    return new Guest(firstname, surname);
}

A difference to using a constructor is that a static factory method can have additional arguments:

@JsonCreator
public static Guest fromJson(String firstname, String surname, int id) {
    // some validation
    return new Guest(firstname, surname);
}

Whereas a non-canonical constructor won’t be used even if it’s annotated with @JsonCreator:

@JsonCreator
public Guest(String firstname, String surname, int id) {
    this(firstname, surname)
    // some validation
}

Jackson will ignore this constructor and use the canonical constructor instead.

6. Enums

@JsonCreator can also be used to deserialize enums. By default, Jackson deserializes enums using their name.

We can change the default behavior by annotating the enum with @JsonFormat:

@JsonFormat(shape = JsonFormat.Shape.OBJECT)
public enum Currency {
    EUR("Euro", "cent"),
    GBP("Pound sterling", "penny"),
    CHF("Swiss franc", "Rappen");
    private String fullName;
    private String fractionalUnit;
    Currency(String fullName, String fractionalUnit) {
        this.fullName = fullName;
        this.fractionalUnit = fractionalUnit;
    }
    
    // getters for all attributes
}

The enum value EUR will then be serialized to the following JSON:

{
  "fullName": "Euro",
  "fractionalUnit": "cent"
}

However, the deserialization will fail with the following exception:

com.fasterxml.jackson.databind.exc.MismatchedInputException: 
  Cannot deserialize value of type `com.baeldung.jackson.multiparameterconstructor.Currency` 
  from Object value (token `JsonToken.START_OBJECT`)

That’s because Jackson attempts to deserialize the enum based on its name: EUR. We might think that annotating the constructor with @JsonCreator would solve the problem:

@JsonCreator
Currency(String fullName, String fractionalUnit) {
    this.fullName = fullName;
    this.fractionalUnit = fractionalUnit;
}

That doesn’t work because enum constructors are private and cannot be used by Jackson. The solution is to define a
static factory method and annotate it with @JsonCreator:

@JsonCreator
public static Currency fromJsonString(String fullName, String fractionalUnit) {
    for (Currency c : Currency.values()) {
        if (c.fullName.equalsIgnoreCase(fullName) && c.fractionalUnit.equalsIgnoreCase(fractionalUnit)) {
            return c;
        }
    }
    throw new IllegalArgumentException("Unknown currency: " + fullName + " " + franctionalUnit);
}

7. Conclusion

In this article, we’ve learned how to deserialize JSON into a Java object using multi-parameter constructors. We’ve seen how to use the @JsonCreator in Java classes, enums, and records. In addition, we’ve learnt that the parameter names module and the constructor detector setting help reduce the number of necessary annotations.

As usual, the code in this article is available over on GitHub.

       

1. Overview

In this tutorial, we’ll deep dive into what JMOD is and how it differs from JAR files. Then, we’ll create a sample modular project, package it as a JMOD file, and use jlink to generate a minimal Java runtime tailored specifically to the application.

2. What’s JMOD?

Before Java 9, Java applications were packaged primarily as JAR files with build tools such as Maven and Gradle. With the introduction of the Java Platform Module System in Java 9, Java gained a formal module system and introduced the JMOD file format.

A JMOD file is a packaging format for Java modules that are intended to be used during compile and link time, but not directly at runtime.

Unlike JAR files, we can’t place JMOD files on the classpath or module path when running an application.

Like JAR files, JMOD files can contain compiled class files and resources. However, JMOD files can also include additional artifacts such as native libraries, configuration files, and legal notices.

2.1. Its Relationship With JPMS

Moreover, JMOD is tightly related to JPMS. It serves as a packaging format for modules that may need more than just compiled bytecode files.

In the JPMS architecture, source code is compiled into bytecode. Then, the bytecode is packaged into modules (JAR or JMOD). Then, at link time, we can use jlink to assemble modules into a custom runtime image.

Link time is the phase between compilation and execution. During this phase, the Java linker analyzes module dependencies and bundles only the required modules into a runtime image. JMOD files are specifically designed to participate in the linking process.

2.2. The Purpose of JMOD and How It Differs From Modular JARs

While JPMS supports modular JAR files, JMOD was introduced to address the limitations of JAR packaging. A modular JAR contains compiled classes and resources and can be used directly at runtime.

On the other hand, a JMOD file may contain native code and additional metadata. It’s intended for link-time processing and can’t be executed directly. Unlike a JAR file, it isn’t meant to be published to repositories such as Maven Central.

Its primary purpose is to support the creation of custom runtime images using jlink. For instance, packaging an application together with a full JRE can significantly increase distribution size. Instead, JMOD enables the creation of a custom Java runtime that contains only the modules required by the application. This results in a smaller and more learner-friendly distribution size.

3. Practical Example: Creating a Custom JRE

To better understand how the JMOD file format works, let’s build a simple modular Java application and use it to create a custom runtime image.

3.1. Sample Application

Let’s bootstrap a simple Java project that logs “Hello Baeldung!” to the console:

public class Hello {
    private static final Logger LOG = Logger.getLogger(Main.class.getName());
    public static void main(String[] args) {
        LOG.info("Hello Baeldung!");
    }
}

In the code above, we define a class named Hello and use the java.util.logging API to log a message to the console.

Next, let’s make the project a Java module by adding a module-info.java file at the root of the module source directory:

module com.baeldung.jmod_sample {
    requires java.logging;
}

Here, com.baeldung.jmod_sample is the module name. While every module implicitly depends on java.base, additional modules such as java.logging must be implicitly declared.

Next, let’s compile our program:

$ javac -d output $(find -name \*.java)

The command above locates all .java files inside the src directory and compiles them. Then, it outputs the generated .class files into the output directory.

3.2. Packaging to JMOD

Next, let’s prepare our modular application for a custom runtime creation by packaging it into a JMOD file.

To create a JMOD file, we can use the jmod create command:

$ jmod create \
  --class-path output/ \
  --main-class com.baeldung.jmod_sample.Hello \
  --module-version 1.0.0 -p output hello.jmod

Here, –class-path output/ specifies the directory containing the compiled classes. Also, we define the entry point of the module and the name of the generated JMOD file.

After executing the command, a hello.jmod file is created in the current directory.

Next, let’s inspect the JMOD file to see what it contains by running the jmod describe command:

$ jmod describe hello.jmod

This outputs the content of the file to the console:

com.baeldung.jmod_sample@1.0.0
requires java.base mandated
requires java.logging
contains com.baeldung.jmod_sample
main-class com.baeldung.jmod_sample.Hello

This confirms that the JMOD file correctly encapsulates the compile module and its metadata, making it ready for use during link time with jlink.

3.3. Creating a Custom Runtime Using jlink

Now that we have generated our JMOD file, let’s use it create a custom Java runtime using jlink:

$ jlink \
  --module-path $JAVA_HOME/jmods:hello.jmod \
  --add-modules com.baeldung.jmod_sample \
  --launcher hello=com.baeldung.jmod_sample/com.baeldung.jmod_sample.Hello \
  --strip-debug \
  --compress=2 \
  --no-header-files \
  --no-man-pages \
  --output custom-runtime-min

Here, the  –module-path $JAVA_HOME/jmods:hello.jmod specifies where jlink should locate require modules. Next, the –add-modules option indicates the root module to include in the runtime image.

Then we use the launcher option to create a launcher script that runs the Hello class. After executing the command, jlink produces a new directory named “custom-runtme-min“.

We can check the size of the generated runtime image:

$ du -sh custom-runtime-min

Here’s the output:

35M     custom-runtime-min/

The resulting runtime is approximately 35 MB, significantly smaller than a full JDK installation, which typically exceeds 400 MB.

Let’s verify which modules were bundled into the runtime image:

$ ./custom-runtime-min/bin/java --list-modules

Here’s the output:

com.baeldung.jmod_sample@1.0.0
java.base@25.0.2
java.logging@25.0.2

This confirms that only the required modules were included.

Finally, let’s run the generate launcher:

$ ./custom-runtime-min/bin/hello

The command above produces:

Mar 01, 2026 10:15:38 AM com.baeldung.jmod_sample.Hello main
INFO: Hello Baeldung!

The application runs successfully using the custom runtime image.

4. Conclusion

In this article, we learned what a JMOD file is, what it can contain, how it differs from a  JAR file, and when it should be used. Also, we built a simple modular Java application, packaged it into a JMOD file, and used it with jlink to generate a lean, custom Java runtime image tailored specifically to our application.

As usual, the complete source code for the example is available over on GitHub.

       

1. Spring and Java

>> One tip for successful OpenTelemetry projects [frankel.ch]

Adopting OpenTelemetry doesn’t have to mean instrumenting the entire codebase. Here’s a pragmatic way to get observability up and running fast.

Also worth reading:

• >> Grails Isn’t Done Yet (Part 2): EOL, Spring Boot, and What Comes Next [foojay.io]
• >> Using Spring Data JPA with Kotlin [jetbrains.com]
• >> AI-Assisted Java Application Development with Agent Skills [jetbrains.com]
• >> Managing Sensitive Data in jOOQ 3.21+ Logs [jooq.org]

Webinars and presentations:

• >> A Bootiful Podcast: Daniel Garnier-Moiroux on MCP Security [spring.io]
• >> A Typo Led to the Creation of Spring Cloud Contract [toomuchcoding.com]
• >> Analysing Crashed JVMs – Inside Java Newscast #109 [nipafx.dev]

Time to upgrade:

• >> Spring Modulith 2.1 M4, 2.0.5, and 1.4.10 released [spring.io]
• >> Spring AI 2.0.0-M4, 1.1.4 and 1.0.5 are available now [spring.io]
• >> Amper 0.10 – JDK Provisioning, a Maven Converter, Custom Compiler Plugins, and More [jetbrains.com]
• >> Jetty 12.1.8 and 12.0.34 [github.com/eclipse]
• >> Eclipse Vert.x 5.0.10 [github.com/eclipse-vertx]
• >> Quarkus 3.34.2 [github.com/quarkusio]
• >> Micronaut 4.10.20 and 4.10.19 [github.com/micronaut-projects]
• >> Netflix Zuul 3.5.7 [github.com/Netflix]
• >> Grails 7.0.10 [github.com/grails]

2. Technical & Musings

>> Encoding Team Standards [martinfowler.com]

Instead of relying on tacit knowledge held by senior engineers, encode your team’s coding standards as executable AI instructions stored in version control. Words to live (or code) by

Also worth reading:

• >> Beyond the Hype: Is AI taking the fun out of software development? [scottlogic.com]
• >> The one where Oskar explains Example Mapping [event-driven.io]
• >> 5 Best Practices for Working with AI Agents, Subagents, Skills and MCP [foojay.io]
• >> Understanding Performance [dandreamsofcoding.com]

3. Pick of the Week

>> 1,000 True Fans [kk.org]

       

1. Introduction

Single-page applications (SPAs) such as those built with React, Angular, or Vue often rely on client-side routing. When served from a Spring Boot backend, refreshing the page or accessing a wrong link sends a request for a non-existent server path. Spring Boot then returns a 404 error.

To make the SPA work correctly, we need to forward all unmatched requests to index.html with HTTP status 200. This lets the frontend router handle the path.

In this tutorial, we’ll learn how to configure Spring Boot so that all unknown routes are redirected to the SPA’s index.html.

2. Maven Dependency

Let’s start by importing the spring-boot-starter-web dependency to our pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.3.2</version>
</dependency>

3. Setting Up a Basic SPA with Spring Boot

Let’s consider an SPA deployed with Spring Boot, where the compiled frontend files are placed inside the resources directory:

src/main/resources/static

For example, a minimal index.html could look like:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Baeldung</title>
</head>
<body>
    <h1>Home Page</h1>
</body>
</html>

Next, we create a simple controller to forward the root path:

@Controller
public class HomeController {
    @RequestMapping("/")
    public String getHome(){
        return "forward:/index.html";
    }
}

When a user accesses the root path http://localhost:8080/, Spring Boot serves index.html correctly.

However, if the user refreshes a client-side route like http://localhost:8080/dashboard, Spring Boot tries to find a server mapping for /dashboard and returns 404 Not Found. Instead, we want Spring Boot to return index.html so the SPA router can handle the route.

4. Redirecting 404 Not Found Errors

In this section, we describe some solutions for redirecting unmatched requests to index.html.

4.1. Using a Controller to Forward Unknown Routes

Let’s create a controller that forwards all unmapped paths to index.html:

@Controller
public class SpaForwardController {
    @RequestMapping(value = "/{path:[^\\.]*}")
    public String redirect() {
        return "forward:/";
    }
}

The unmatched requests without a file extension are forwarded to “/”, which returns index.html.

If a specific mapping exists (for example, @GetMapping(“/dashboard”)), Spring selects it with higher precedence, and the catch-all pattern is ignored. For any other path without a matching handler (such as /settings), the request falls through to the catch-all mapping and gets forwarded to index.html.

Also, we need to support deeper routes like /dashboard/settings. To do this, we can expand the controller mapping:

@Controller
public class SpaForwardController {
    @RequestMapping(value = {
        "/{path:[^\\.]*}",
        "/{path:[^\\.]*}/**/{subpath:[^\\.]*}"
    })
    public String redirect() {
        return "forward:/";
    }
}

4.2. Using a Custom Error Controller

Another approach is to intercept 404 errors and redirect them to the SPA entry point:

@Controller
public class SpaErrorController implements ErrorController {
    @RequestMapping("/error")
    public String handleError() {
        return "forward:/index.html";
    }
}

This method ensures that any unknown route eventually loads the SPA.

However, this approach may also intercept real backend 404 errors, which may not always be desirable.

4.3. Using WebMvcConfigurer

Another approach is to centralize error handling and avoid the need to explicitly match route patterns.

We can achieve this by implementing the WebMvcConfigurer interface and registering a custom error page:

@Configuration
public class WebApplicationConfig implements WebMvcConfigurer {
    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addViewController("/notFound")
          .setViewName("forward:/index.html");
    }
    @Bean
    public WebServerFactoryCustomizer<ConfigurableServletWebServerFactory> containerCustomizer() {
        return container -> {
            container.addErrorPages(new ErrorPage(HttpStatus.NOT_FOUND, "/notFound"));
        };
    }
}

In this configuration, any request that results in a 404 Not Found error is redirected to /notFound. This endpoint then forwards the request to index.html.

However, it also means that all 404 errors—including those from backend APIs—are redirected to the SPA, which may not always be desirable.

5. Test

After starting the Spring Boot application, we can verify the configuration by accessing different URLs.

First, we request the root path:

$ curl -i http://localhost:8080/

The response returns 200 along with the contents of index.html:

HTTP/1.1 200
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Baeldung</title>
</head>
<body>
    <h1>Home Page</h1>
</body>
</html>

Next, we simulate accessing a client-side route:

$ curl -i http://localhost:8080/dashboard

Instead of returning a 404 Not Found, the application responds with 200 and serves index.html. This confirms that the request is forwarded and handled by the SPA router.

6. Conclusion

In this article, we explored how to forward unknown routes to index.html when serving a single-page application with Spring Boot. We examined multiple approaches, including using a custom controller, configuring WebMvcConfigurer, and handling errors via a custom error mapping.

       

1. Introduction

When working with Java’s native serialization combined with SonarQube’s code evaluation tool, sometimes we encounter “Fields in a ‘Serializable’ class should either be ‘transient’ or ‘Serializable'” (rule key: java:S1948) warning. This rule is an important guardrail and it prevents a common runtime failure: the NotSerializableException.

In this tutorial, we’ll explore why this warning occurs. Also, we’ll talk about the underlying mechanics of Java serialization, and the best strategies to resolve it.

2. Understanding the Serialization Contract

To make a Java object serializable, its class must implement the java.io.Serializable interface. This is a marker interface that tells the JVM the object’s state is converted into a byte stream for storage or network transfer.

As such, the fundamental rule of this contract is recursive: if a class is serializable, all its non-static and non-transient member fields must also be serializable. If the serialization mechanism encounters a field that doesn’t implement Serializable and isn’t marked as transient, the process will fail at runtime. Sonar flags these fields during static analysis and helps us catch this error before the code even runs.

In addition, it’s important to remember that serialization isn’t just about the top-level class; it’s about the entire object graph.

3. Reproducing the Sonar Warning

Let’s look at a typical scenario that triggers the java:s1948 warning. First, let’s add the SLF4J dependency to our pom.xml:

<dependency>
    <groupId>org.slf4j</groupId>
     <artifactId>slf4j-api</artifactId>
     <version>2.0.17</version>
</dependency>

Now, let’s create a User class that we want to store in a distributed session or cache. This class also contains a reference to another class, Address, which does not implement the Serializable interface. We’ll start with a simple implementation:

public class User implements Serializable {
    private static final long serialVersionUID = 1L;
         
    private String username;
    private Address address; // Sonar Warning: Make "address" transient or serializable
    private final Logger logger = LoggerFactory.getLogger(User.class); // Sonar Warning
         
     public User(String username, Address address) {
        this.username = username;
        this.address = address;
     }
}

In this example, the User class correctly implements Serializable. However, if the Address class is defined without the interface, Sonar will flag the address field. Similarly, since the SLF4J Logger does not implement Serializable, it will also trigger the warning. Furthermore, if we try to serialize an instance of User, the JVM will throw a NotSerializableException at runtime. This is exactly what Sonar is trying to help us avoid. Now, let’s look at some ways we can tackle this warning.

4. Making the Field Serializable

The most straightforward fix is to ensure that the nested class also implements the Serializable interface. This is the preferred approach when the field represents a core part of the object’s state that must be preserved. As such, if we own the source code of the nested object, we should simply update the class definition:

public class Address implements Serializable {
    private static final long serialVersionUID = 1L;
        
    private String street;
    private String city;
        
    public Address(String street, String city) {
        this.street = street;
        this.city = city;
    }
}

By adding implements Serializable and providing a serialVersionUID, we satisfy the contract requirements. It’s a best practice to always include serialVersionUID to ensure compatibility during the deserialization process. Especially if the class structure evolves over time.

5. Using the static Modifier

Another effective way to resolve the warning for certain fields is to declare them as static. In Java, static fields are not serialized because they belong to the class itself rather than a specific instance. Since they are excluded from the serialization process by the JVM, SonarQube does not flag them.

This is the standard solution for loggers and constants:

public class User implements Serializable {
    private static final long serialVersionUID = 1L;
       
    private static final Logger logger = LoggerFactory.getLogger(User.class); // No Warning
    private String username;
    private Address address;
    // getters, setters ...
 }

By making the logger static, the warning disappears, and we follow the common Java pattern for logger declarations. This approach is ideal for any field that is shared across all instances of the class and does not represent the unique state of an individual object.

6. Leveraging the transient Keyword

If a field is instance-specific but shouldn’t be serialized (like a reference to a temporary cache, or a non-serializable third-party object) we use the transient keyword. This modifier tells the JVM to skip the field during the serialization process:

public class User implements Serializable {
    private static final long serialVersionUID = 1L;
       
    private String username;
    private Address address;
    private transient List<String> temporaryCache; // Warning Resolved
    // getters and setters ...
}

We need to take into consideration that when an object is deserialized, all transient fields are initialized to their default values: null for objects and 0 for primitives. As such, if a transient field is required for the object to function after being restored, we must re-initialize it. A way to achieve this is to use the readObject method:

private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {
    in.defaultReadObject();
    this.temporaryCache = new ArrayList<>();
}

7. Handling Framework Dependencies

In modern Java frameworks like Spring, this warning often appears in @SessionScoped beans when injecting a @Service or @Repository. Since these services are managed by the container and typically aren’t serializable, they should be marked as transient:

@SessionScoped
public class UserPreferences implements Serializable {
    @Autowired
    private transient PreferenceService service; // Fixed by marking it with transient
}

Spring handles the dependency injection, so it will re-inject the service when the bean is restored from the session, provided the framework’s proxy mechanism supports it. This keeps our session-scoped beans serializable while allowing them to interact with stateless services.

Furthermore, we might encounter situations where we use third-party library classes that do not implement Serializable. If we cannot modify their source code, we have two main options:

• Wrap the object: Create a serializable DTO that holds only the necessary primitive data.\
• Custom Serialization: Use transient for the third-party object and manually handle its state during serialization using the writeObject and readObject methods.

For example, if we have a non-serializable Metadata object, we can store its state as a serializable Map or and reconstruct it upon deserialization. This keeps our domain models serializable while still utilizing powerful third-party tools.

8. Conclusion

In this tutorial, we’ve covered how to handle the Sonar warning “Make Transient or Serializable”. Although the warning is helpful to ensure runtime stability in Java applications, it can cause confusion. As such, by understanding the recursive nature of Java serialization, we can choose the correct fix based on the field’s role in our application.

Implement Serializable if the field is a core part of the object’s state. Use static for loggers, constants and shared class-level members. Mark as transient if the field is a resource, or temporary data. Refactor the design if we’re trying to serialize stateless services or third-party objects that aren’t meant to be persisted.

       

1. Introduction

In this tutorial, we’re going to take a look at Apache Seata, formally from Alibaba but now part of the Apache Incubator project. We’ll see what it is, how to use it and what we can do with it.

2. Why Distributed Transactions?

To write robust applications, we often make use of database transactions to ensure that any changes to our data are atomic. That is, either the entire change happens, or none of it does. This helps ensure that our data remains in a valid state at all times.

When we have a single service that manages our data, this is easy to achieve. We start a new transaction when a request comes into our system. All data changes occur within this transaction, and we commit only if the entire request succeeds.

Here, if something goes wrong when recording the bill for the user, the order and inventory changes are reverted, and the system remains in the correct state.

If we move towards running this as many distributed services, suddenly our transactions are distributed as well:

This is exactly the same flow, but by splitting our inventory, order and billing services into separate applications, we’ve also split them into separate transactions. Now, if recording the bill fails, the inventory and order changes have already been committed and cannot easily be reverted.

This is where distributed transactions come in. If we have a way to maintain our database transactions across multiple applications, we get both the benefits of splitting our system up, as well as the benefits of a single transaction for the entire user action.

3. What Is Apache Seata?

Apache Seata is an open source project, originally part of Alibaba group, that helps us to manage distributed transactions in our Java microservices applications.

When using Seata, we run an additional service that acts as the Transaction Coordinator. When a request comes into our application, the originating service, acting as the Transaction Manager, starts a new distributed transaction within the transaction coordinator. All other services then take part in this same transaction until it either gets persisted or reverted:

Here, our flow is essentially the same, but we’ve also added in our transaction coordinator and wrapped everything in a single distributed transaction. This will ensure that all three databases either commit or rollback together, and so our overall system remains in a valid state.

4. Seata Server

Before we can use Seata, we need to ensure that we have a running Seata Server. This acts as the transaction coordinator in our overall system.

The easiest way to get this working is as a Docker container that we can run in our environment. For example, we can include it in a Docker Compose file as follows:

services:
  seata-server:
    image: apache/seata-server:2.6.0

By default, this listens on port 8091 and uses the local filesystem within the container to track distributed transactions.

We’re then ready to set up our application to work with Seata.

5. Using Spring Boot

Seata provides a Spring Boot starter that we can use to set it up. If we’re using Maven, we can include this dependency in our pom.xml file:

<dependency>
    <groupId>org.apache.seata</groupId>
    <artifactId>seata-spring-boot-starter</artifactId>
    <version>2.6.0</version>
</dependency>

5.1. Configuring Seata

We then need to provide a configuration file for Seata. This needs to be present on the classpath, so we’ll create it as src/main/resources/seata.conf:

transport {
  type = "TCP"
  server = "NIO"
  heartbeat = true
  thread-factory {
    boss-thread-prefix = "NettyBoss"
    worker-thread-prefix = "NettyServerNIOWorker"
    server-executor-thread-size = 100
    share-boss-worker = false
    client-selector-thread-size = 1
    client-selector-thread-prefix = "NettyClientSelector"
    client-worker-thread-prefix = "NettyClientWorkerThread"
  }
  shutdown {
    wait = 3
  }
  serialization = "seata"
  compressor = "none"
}
service {
  vgroupMapping.my_tx_group = "default"
  default.grouplist = "seata-server:8091"
  enableDegrade = false
  disableGlobalTransaction = false
}
client {
  rm {
    asyncCommitBufferLimit = 10000
    lock {
      retryInterval = 10
      retryTimes = 30
      retryPolicyBranchRollbackOnConflict = true
    }
    reportRetryCount = 5
    tableMetaCheckEnable = false
    reportSuccessEnable = false
    sagaBranchRegisterEnable = false
  }
  tm {
    commitRetryCount = 5
    rollbackRetryCount = 5
    defaultGlobalTransactionTimeout = 60000
    degradeCheck = false
  }
  undo {
    dataValidation = true
    logSerialization = "jackson"
    logTable = "undo_log"
    compress {
      enable = true
      type = "zip"
      threshold = "64k"
    }
  }
  log {
    exceptionRate = 100
  }
}

Most of this is standard, but note we have to configure the host and port of the Seata server in the field service.default.grouplist.

We also need to add some configuration to Spring to enable it to work with Seata. We do this within our application.properties file:

seata.enabled=true
seata.application-id=${spring.application.name}
seata.tx-service-group=my_tx_group
seata.registry.type=file
seata.registry.file.name=seata.conf
seata.config.type=file
seata.config.file.name=seata.conf
seata.service.vgroup-mapping.my_tx_group=default
seata.service.grouplist.default=seata-server:8091
seata.data-source-proxy-mode=AT
seata.enable-auto-data-source-proxy=true

This also contains the host and port of the Seata server in the seata.service.grouplist.default property. We also need to ensure that several of the properties match up with the Seata configuration file, and that the seata.registry.file.name and seata.config.file.name properties point to our seata.conf file.

Finally, if we’re using AT mode as configured here, we’ll need to create a special undo_log table in our service database:

CREATE TABLE IF NOT EXISTS undo_log (
    id            BIGSERIAL    NOT NULL,
    branch_id     BIGINT       NOT NULL,
    xid           VARCHAR(128) NOT NULL,
    context       VARCHAR(128) NOT NULL,
    rollback_info BYTEA        NOT NULL,
    log_status    INT          NOT NULL,
    log_created   TIMESTAMP(0) NOT NULL,
    log_modified  TIMESTAMP(0) NOT NULL,
    CONSTRAINT pk_undo_log PRIMARY KEY (id),
    CONSTRAINT ux_undo_log UNIQUE (xid, branch_id)
);

We configure the exact table name in our seata.conf file.

At this point, Seata integrates with our service. If we start our project now, we’ll see several log messages indicating this:

2026-03-14T07:53:37.728Z  INFO 1 --- [apache-seata-a] [           main] o.a.s.s.b.a.SeataAutoConfiguration       : Automatically configure Seata
2026-03-14T07:53:37.802Z  INFO 1 --- [apache-seata-a] [           main] ServiceLoader$InnerEnhancedServiceLoader : Load compatible class io.seata.spring.annotation.ScannerChecker
2026-03-14T07:53:37.984Z  INFO 1 --- [apache-seata-a] [           main] ServiceLoader$InnerEnhancedServiceLoader : Load compatible class io.seata.integration.tx.api.remoting.RemotingParser
2026-03-14T07:53:37.996Z  INFO 1 --- [apache-seata-a] [           main] o.a.s.s.a.GlobalTransactionScanner       : Initializing Global Transaction Clients ...
.....
2026-03-14T07:53:45.533Z  INFO 1 --- [apache-seata-a] [           main] o.a.s.c.rpc.netty.RmNettyRemotingClient  : RM will register :jdbc:postgresql://postgres:5432/seata
2026-03-14T07:53:45.540Z  INFO 1 --- [apache-seata-a] [           main] o.a.s.c.rpc.netty.NettyPoolableFactory   : NettyPool create channel to transactionRole:RMROLE,address:172.18.0.2:8091,msg:< RegisterRMRequest{resourceIds='jdbc:postgresql://postgres:5432/seata', version='2.6.0', applicationId='apache-seata-a', transactionServiceGroup='my_tx_group', extraData='null'} >
2026-03-14T07:53:45.586Z  INFO 1 --- [apache-seata-a] [           main] o.a.s.c.rpc.netty.RmNettyRemotingClient  : register RM success. client version:2.6.0, server version:2.6.0,channel:[id: 0x0a28dceb, L:/172.18.0.6:39884 - R:172.18.0.2/172.18.0.2:8091]
2026-03-14T07:53:45.590Z  INFO 1 --- [apache-seata-a] [           main] o.a.s.c.rpc.netty.NettyPoolableFactory   : register success, cost 34 ms, version:2.6.0,role:RMROLE,channel:[id: 0x0a28dceb, L:/172.18.0.6:39884 - R:172.18.0.2/172.18.0.2:8091]
2026-03-14T07:53:45.634Z  INFO 1 --- [apache-seata-a] [           main] .s.s.a.d.SeataAutoDataSourceProxyCreator : Auto proxy data source 'dataSource' by 'AT' mode.

5.2. Global Transactions

Once Spring fully integrates with Seata, we can start using it. We do this with the @GlobalTransaction annotation, which we use to mark the start of a transaction that should be distributed between services:

@PostMapping("/a/{mode}")
@GlobalTransactional
public void handle() {
    // Controller logic here
}

We can use this anywhere that we’d typically use the @Transactional annotation, and this will start a new database transaction. This transaction registers with Seata and can span multiple services instead of remaining local.

Note that we only include this annotation at the start of the global transaction. Subsequent services in the same transaction needn’t include it. We’ll manage them differently, as we’ll see shortly.

If we wish, we can also provide some configuration for our transaction in a familiar way to the standard @Transactional annotation:

@GlobalTransactional(rollbackFor = MyException.class, timeoutMills = 10000)

Here, we indicate that the transaction should roll back for any subclasses of MyException, with a 10-second timeout.

5.3. Transaction Propagation

Unfortunately, if we try this now, then we’ll discover that the transactions don’t propagate correctly. We’d see log messages in our service indicating that it’s registered with Seata, but subsequent services wouldn’t do anything.

Seata manages this by passing a special XID value between services. Typically, this goes in the HTTP header TX_XID on the calls between our services.

If we’re using standard Spring then we need to manage this ourselves. This includes adding it to all outgoing HTTP calls and receiving it on all incoming calls.

If we’re using Spring RestClient then we can write a ClientHttpRequestInterceptor implementation that will do this for us:

public class SeataXidClientInterceptor implements ClientHttpRequestInterceptor {
    @Override
    public ClientHttpResponse intercept(HttpRequest request, byte[] body, ClientHttpRequestExecution execution)
        throws IOException {
        String xid = RootContext.getXID();
        if (StringUtils.hasText(xid)) {
            request.getHeaders().add(RootContext.KEY_XID, xid);
        }
        return execution.execute(request, body);
    }
}

This simply adds our XID value to the outgoing HTTP request.

We must then ensure that our RestClient always uses this:

@Bean
public RestClient restClient() {
    return RestClient.builder()
        .requestInterceptor(new SeataXidClientInterceptor())
        .build();
}

We can do the exact same with any other HTTP clients too – e.g. WebClient or RestTemplate.

At this point, all of our outbound calls will indicate the XID for our global transactions. However, we still need to consume them in our downstream services. We can do this with a servlet filter:

@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class SeataXidFilter implements Filter {
    @Override
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
        throws IOException, ServletException {
        HttpServletRequest httpRequest = (HttpServletRequest) req;
        String xid = httpRequest.getHeader(RootContext.KEY_XID);
        boolean bound = false;
        if (StringUtils.hasText(xid) && !xid.equals(RootContext.getXID())) {
            RootContext.bind(xid);
            bound = true;
        }
        try {
            chain.doFilter(req, res);
        } finally {
            if (bound) {
                RootContext.unbind();
            }
        }
    }
}

This does the exact opposite – if there’s an XID present on the incoming HTTP request then bind it to the local service before continuing with the request, and ensure that we unbind it at the end.

At this point, our transaction now correctly spans our services and the entire set will commit or roll back together.

6. Using Spring Cloud

Unlike Spring Boot, Spring Cloud can handle some of this automatically for us.

In a Spring Cloud setup, we need to use a different dependency in our project. We also need to be careful with the versions here – the newest 2025.1.0.0 version only works with Spring Boot 4, whereas the 2025.0.0.0 version requires Spring Boot 3.

This dependency comes as a BOM that we can import into our dependency management section to manage versions, and then as the actual starter dependency:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-alibaba-dependencies</artifactId>
            <version>2025.0.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
...
<dependencies>
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-seata</artifactId>
    </dependency>
</dependencies>

We still need to do the same configuration as before, using our seata.conf and application.properties files. However, the framework handles most transaction propagation for us.

The Spring Cloud Starter will automatically set our service up so that any incoming HTTP requests will join a global transaction if required. This removes the need for our servlet filter.

The starter also configures RestTemplate beans to automatically forward the XID value to downstream services, so if we’re using this, then we don’t need additional setup here either. Unfortunately, it doesn’t work with RestClient or WebClient, so if we’re using those, then we’ll still need to configure it manually.

7. Summary

In this article, we’ve taken a quick look at Apache Seata. We’ve seen what it is, and how we can use it in our applications. Next time you’re writing transactional services, why not give it a go?

       

1. Spring and Java

>> JavaScript (No, Not That One): Modern Automation with Java [foojay.io]

Modern Java is a thing to behold :). It has quietly become quite a capable scripting language — single-file execution, JBang, and Picocli make it a practical alternative to Bash or Python for automation. Good stuff.

Also worth reading:

• >> Spring Boot Actuator Health for MicroProfile Developers [foojay.io]
• >> How We Built a Java AI Agent by Connecting the Dots the Ecosystem Already Had [foojay.io]
• >> Grails Isn’t Done Yet (Part 1): Inside the ASF Reboot [foojay.io]
• >> Does Language Still Matter in the Age of AI? Yes — But the Tradeoff Has Changed [foojay.io]
• >> How is Leyden improving Java Performance? Part 3 of 3 [foojay.io]
• >> JDK 26 Security Enhancements [inside.java]
• >> Apache Polaris is powered by Quarkus [quarkus.io]

Webinars and presentations:

• >> A Bootiful Podcast: Cay Horstmann, legendary Java professor, author, lecturer [spring.io]
• >> Episode 52 “Carrier Classes & Discussing Syntax” [AtA] [inside.java]
• >> KotlinConf’26 Speakers: In Conversation with Josh Long [jetbrains.com]
• >> JavaOne and JavaFX [inside.java]
• >> Moritz Halbritter on Spring Boot [youtube.com]
• >> The IntelliJ IDEA Documentary [youtube.com]

Time to upgrade:

• >> Spring Boot 4.1.0-M4, 4.0.5, and 3.5.13 [spring.io]
• >> Spring Cloud Config 5.0.2, 4.3.2, 4.2.6, 4.1.9, 3.1.13 Released, includes fix for CVE-2026-22739 [spring.io]
• >> Spring Boot 4.1.0-M3, 4.0.4, and 3.5.12 [spring.io]
• >> Spring Security 6.5.9, 7.0.4, and 7.1.0-M3 available now [spring.io]
• >> Spring Batch 6.0.3 and 5.2.5 available now [spring.io]
• >> IntelliJ IDEA 2026.1 [jetbrains.com]
• >> Quarkus 3.34, 3.33 LTS [quarkus.io]
• >> Quarkus 3.27.3 and 3.20.6 [quarkus.io]
• >> Hibernate Reactive 4.3.0.Final [in.relation.to]
• >> Hibernate Search 8.3.0.Final [in.relation.to]
• >> Elasticsearch 9.3.2 and 9.2.7 and 8.19.13 [github.com/elastic]
• >> Netflix Zuul 3.5.1 and 3.5.2 [github.com/Netflix]
• >> Apache Camel 4.18.1 [github.com/apache]
• >> Eclipse Vert.x 5.0.9 and 4.5.26 [github.com/eclipse-vertx]

2. Technical & Musings

>> Bliki: Architecture Decision Record [martinfowler.com]

This is a lightweight document capturing a log of architectural decisions along with its context and trade-offs, stored in version control alongside code. Quite useful and often missed.

Also worth reading:

• >> The Software Architect Elevator [frankel.ch]
• >> Some Things Just Take Time [lucumr.pocoo.org]
• >> Your Inbox As Options, Not Obligations [jbrains.ca]
• >> Using AI to Evaluate Internet Standards (Part Two) [mnot.net]
• >> TestBox 7: Real-Time Feedback, a Browser-Based IDE, and Modern Testing Workflows on the JVM [foojay.io]

3. Pick of the Week

And our sale is about to end:

>> All Access for 4 More Days

       

1. Overview

Model Context Protocol (MCP) is an open standard protocol that defines how a large language model (LLM) discovers and invokes external tools to extend its capabilities. MCP is a client-server architecture that allows the MCP client, usually an LLM integrated application, to interact with one or more MCP servers that expose tools for invocation.

Testing tools exposed by MCP servers are crucial to validate that they are correctly registered on MCP servers and are discoverable by MCP clients. Unlike LLM responses, which are non-deterministic, MCP tools behave deterministically because they’re just normal application code, which enables us to write automated tests to verify correctness.

In this tutorial, we’ll explore how to test MCP tools on MCP servers in Spring AI using different test strategies.

2. Maven Dependencies

We’ll test the MCP tools in a Spring Boot application. Hence, we must add the Spring AI MCP server dependency to our pom.xml:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server</artifactId>
    <version>1.1.2</version>
</dependency>

We’ll also require the Spring Boot Test dependency for our testing:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>

3. Creating a Sample MCP Tool

In this section, we’ll implement a simple MCP tool using Spring AI and demonstrate different testing strategies.

First, let’s create a simple ExchangeRateService that uses a third-party open-source service, Frankfurter, to fetch the currency exchange rate using an HTTP GET request. This API requires a mandatory query parameter base:

@Service
public class ExchangeRateService {
    private static final String FRANKFURTER_URL = "https://api.frankfurter.dev/v1/latest?base={base}";
    private final RestClient restClient;
    public ExchangeRateService(RestClient.Builder restClientBuilder) {
        this.restClient = restClientBuilder.build();
    }
    public ExchangeRateResponse getLatestExchangeRate(String base) {
        if (base == null || base.isBlank()) {
            throw new IllegalArgumentException("base is required");
        }
        return restClient.get()
          .uri(FRANKFURTER_URL, base.trim().toUpperCase())
          .retrieve()
          .body(ExchangeRateResponse.class);
    }
}

The API response looks something similar to:

{
  "amount": 1,
  "base": "GBP",
  "date": "2026-03-06",
  "rates": {
    "AUD": 1.9034,
    "BRL": 7.0366,
    ......
  }
}

Thus, we create the following Java record to map the JSON response:

public record ExchangeRateResponse(double amount, String base, String date, Map<String, Double> rates) {
}

Now, let’s create an MCP tool that invokes the ExchangeRateService to return currency exchange rates based on the base currency.

The tool description explains what the parameter is for, such that MCP clients know what they should provide when calling it:

@Component
public class ExchangeRateMcpTool {
    private final ExchangeRateService exchangeRateService;
    public ExchangeRateMcpTool(ExchangeRateService exchangeRateService) {
        this.exchangeRateService = exchangeRateService;
    }
    @McpTool(description = "Get latest exchange rates for a base currency")
    public ExchangeRateResponse getExchangeRate(
        @McpToolParam(description = "Base currency code, e.g. GBP, USD", required = true) String base) {
        return exchangeRateService.getLatestExchangeRate(base);
    }
}

4. Unit Test

We could verify the ExchangeRateMcpTool logic in isolation by unit test. Therefore, we mock the external dependency so that we can provide a mocked response.

The verification process is fairly simple to validate that the service gets invoked correctly, and also the response is returned as expected:

class ExchangeRateMcpToolUnitTest {
    @Test
    void whenBaseIsNotBlank_thenGetExchangeRateShouldReturnResponse() {
        ExchangeRateService exchangeRateService = mock(ExchangeRateService.class);
        ExchangeRateResponse expected = new ExchangeRateResponse(1.0, "GBP", "2026-03-08",
          Map.of("USD", 1.27, "EUR", 1.17));
        when(exchangeRateService.getLatestExchangeRate("gbp")).thenReturn(expected);
        ExchangeRateMcpTool tool = new ExchangeRateMcpTool(exchangeRateService);
        ExchangeRateResponse actual = tool.getExchangeRate("gbp");
        assertThat(actual).isEqualTo(expected);
        verify(exchangeRateService).getLatestExchangeRate("gbp");
    }
}

5. Creating an MCP Test Client

If we want to test the MCP tools end-to-end, we could create an MCP client that connects to the MCP server.

HTTP-based MCP servers expose different endpoints depending on the protocol configuration property spring.ai.mcp.server.protocol in the application.yml. Spring AI uses the SSE by default if we don’t set the property explicitly:

In addition to the different endpoints, each protocol requires a different McpClientTransport instance to create the McpSyncClient.

Since Spring AI does not provide a factory class that automatically creates the client based on the protocol, we create a test component, TestMcpClientFactory, handling the McpSyncClient creation, to simplify our testing:

@Component
public class TestMcpClientFactory {
    private final String protocol;
    public TestMcpClientFactory(@Value("${spring.ai.mcp.server.protocol:sse}") String protocol) {
        this.protocol = protocol;
    }
    public McpSyncClient create(String baseUrl) {
        String resolvedProtocol = protocol.trim().toLowerCase();
        return switch (resolvedProtocol) {
            case "sse" -> McpClient.sync(HttpClientSseClientTransport.builder(baseUrl)
              .sseEndpoint("/sse")
              .build()
            ).build();
            case "streamable" -> McpClient.sync(HttpClientStreamableHttpTransport.builder(baseUrl)
              .endpoint("/mcp")
              .build()
            ).build();
            default -> throw new IllegalArgumentException("Unknown MCP protocol: " + protocol);
        };
    }
}

We support the SSE and streamable protocol only in our factory class to demonstrate the idea.

6. Verifying Tool Registration

The MCP server exposes an HTTP endpoint to list all available tools that MCP clients can invoke. As such, we could initialize an MCP client to verify the tool’s registration on the MCP server.

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class ExchangeRateMcpToolIntegrationTest {
    @LocalServerPort
    private int port;
    @Autowired
    private TestMcpClientFactory testMcpClientFactory;
    @MockBean
    private ExchangeRateService exchangeRateService;
    private McpSyncClient client;
    @BeforeEach
    void setUp() {
        client = testMcpClientFactory.create("http://localhost:" + port);
        client.initialize();
    }
    @AfterEach
    void cleanUp() {
        client.closeGracefully();
    }
}

Once we initialize an MCP client, we invoke the client listTools() method to find out all tools that an MCP server has registered:

@Test
void whenMcpClientListTools_thenTheToolIsRegistered() {
    boolean registered = client.listTools().tools().stream()
      .anyMatch(tool -> Objects.equals(tool.name(), "getLatestExchangeRate"));
    assertThat(registered).isTrue();
}

The test returns a list of registered tools, and we assert that getLatestExchangeRate is one of them to confirm successful registration.

7. Testing Tool Invocation

In addition, we could also verify the MCP tool by invoking it from an MCP client. We mock the ExchangeRateService in this test to avoid making a genuine HTTP call to the Frankfurter API.

The invocation flow includes discovering the tools from the MCP server, building a CallToolRequest with all required arguments, and calling it to obtain the response from the server:

@Test
void whenMcpClientCallTool_thenTheToolReturnsMockedResponse() {
    when(exchangeRateService.getLatestExchangeRate("GBP")).thenReturn(
      new ExchangeRateResponse(1.0, "GBP", "2026-03-08", Map.of("USD", 1.27))
    );
    McpSchema.Tool exchangeRateTool = client.listTools().tools().stream()
      .filter(tool -> "getLatestExchangeRate".equals(tool.name()))
      .findFirst()
      .orElseThrow();
    String argumentName = exchangeRateTool.inputSchema().properties().keySet().stream()
      .findFirst()
      .orElseThrow();
    McpSchema.CallToolResult result = client.callTool(
      new McpSchema.CallToolRequest("getLatestExchangeRate", Map.of(argumentName, "GBP"))
    );
    assertThat(result).isNotNull();
    assertThat(result.isError()).isFalse();
    assertTrue(result.toString().contains("GBP"));
}

The assertions ensure the tool call returns a valid response without errors.

8. Conclusions

In this article, we created a sample MCP server tool, validated its correctness, ensured the MCP server registered with it, and tested the tool invocation via an MCP client.

With both unit tests and integration tests in place, we can be confident that the tool is working correctly and is exposed properly so that MCP clients can invoke it.

       

1. Spring and Java

>> Blending Chat with Rich UIs with Spring AI and MCP Apps [spring.io]

If you’ve been wondering how to move beyond pure chat interfaces without sacrificing the conversational layer, this is a practical starting point.

>> Java 26 in IntelliJ IDEA [jetbrains.com]

Java 26 lands with five finalized JEPs — including HTTP/3 support (nice) and GC improvements — plus four preview features. And, of course, IntelliJ IDEA’s deep integration means you can explore all of it right away. Good stuff.

Also worth reading:

• >> Koog Comes to Java: The Enterprise AI Agent Framework From JetBrains [jetbrains.com]
• >> HubSpot’s Sidekick: Multi-Model AI Code Review with 90% Faster Feedback and 80% Engineer Approval [infoq.com]
• >> Java 26 Delivers Language Innovation, Library Improvements, Performance and Security [infoq.com]
• >> How is Leyden improving Java Performance? Part 1 of 3 and Part 2 of 3 [foojay.io]
• >> Java 26 Is Here, And With It a Solid Foundation for the Future [foojay.io]
• >> Language Learning Flashcard System — Part 1 [foojay.io]
• >> Secure, Scalable JVM Diagnostics for Kubernetes with JMS [inside.java]
• >> Introducing Tracy: The AI Observability Library for Kotlin [jetbrains.com]

Webinars and presentations:

• >> Java 26 in definitely UNDER 3 minutes [inside.java]
• >> A Bootiful Podcast: Spring Messaging Legend Soby Chacko [spring.io]
• >> Andres Almiray on How to Release Any Software to Any OS with JReleaser [infoq.com]
• >> Watch AI Build a Microservice. Watch Me Break It in 60 s – Lightning Session recording [toomuchcoding.com]
• >> Foojay Podcast #92: Java 26 Is Here: What’s New, What’s Gone, and Why It Matters in 2026 [foojay.io]
• >> Episode 51 “Unboxing Java 26 for Developers” [inside.java]

Time to upgrade:

• >> The Arrival of Java 26 [inside.java]
• >> Spring Framework 6.2.17 and 7.0.6 available now [spring.io]
• >> Spring AI 2.0.0-M3, 1.1.3 and 1.0.4 Available Now [spring.io]
• >> Spring Integration 7.1.0-M3 Available [spring.io]
• >> Spring Web Services 5.0.1 and 4.1.3 [spring.io]
• >> IntelliJ IDEA 2025.3.4 [jetbrains.com]
• >> Kotlin 2.3.20 [jetbrains.com]
• >> BoxLang 1.11.0 [foojay.io]
• >> Grails 7.0.9 [github.com/grails]
• >> Micronaut 4.10.18 and 3.8.13 [github.com/micronaut-projects]
• >> Payara 7.2026.3 [github.com/payara]

2. Technical & Musings

>> Context Anchoring [martinfowler.com]

AI coding sessions degrade as context drifts — and Fowler’s team tackles this head-on with a document-driven anchoring strategy. Definitely worth being on your weekend reading list.

Also worth reading:

• >> Writing an agent skill [frankel.ch]
• >> If AI Writes the Code, Who Builds the Next Open Source Project? [scottlogic.com]
• >> Interactive Rubber Ducking with GenAI [event-driven.io]
• >> tdocker: A Terminal UI for Everyday Docker Commands [4comprehension.com]
• >> QCon London 2026: Behind Booking.com’s AI Evolution: The Unpolished Story [infoq.com]

3. Pick of the Week

The first sale of the year:

>> All Access and Pro, both at 30% off until the end of the month

We only do three of these every year

       

1. Overview

Although H2 databases were initially developed to function in-memory only, the engine now supports secondary storage and even server modes. Because of this, use cases have also increased, leading to two closely related needs: creating reliable backups for recovery and exporting data for inspection or reuse. Although both move data out of the database, they serve different purposes and rely on different mechanisms. Still, H2 meets these needs through SQL commands directly inside the engine. This way, the database can keep running while maintenance is underway.

In this tutorial, we explain backup and export mechanisms for H2. First, we go through the basic concepts of both actions. After that, we understand backup methods, see why copying database files is unreliable, and how the built-in commands operate while the database is online. Finally, we cover CSV and SQL-based exports and briefly note additional complementary techniques that fit naturally into H2-based workflows.

2. H2 Backup and Export Concepts

Before delving into specifics, it’s important to understand how backups and exports differ for H2. We also consider the environment and operating conditions.

2.1. Backups and Exports

In general, backups preserve entire instances for later restoration. In the case of H2, this means creating a package that includes all tables, any created indices, and metadata. Backups relate to a particular point in time and primarily exist for recovery scenarios, such as data loss or environment rebuilds.

On the other hand, exporting usually focuses on data portability instead of recovery. Usually, an export is in a text-based format such as a CSV file or SQL script. Critically, the data within an export often contains only specific tables or query results. Although we can use exports for analysis and partial migration, they rarely provide the same guarantees as a full backup in terms of content. For instance, an export might only include part of the tables, no metadata, or other limitations.

2.2. Online Operations

Many H2 databases run continuously in embedded mode as part of an application. In these cases, backups and exports should be able to complete successfully while data is being read and written.

To that end, the recommended approaches for the H2 engine rely on SQL commands executed through normal database connections. Thus, the engine itself can ensure consistency instead of relying on external file operations that are unaware of the internal state.

3. Backing Up an Online H2 Database

For offline scenarios where downtime is acceptable, shutting down the database cleanly and then copying files can be a viable option. However, this approach is usually reserved for controlled maintenance windows and isn’t a real substitute for online backups in continuously running systems.

Since uninterrupted operation can be critical in many cases, having a backup solution for an H2 database that’s currently in use can be crucial.

3.1. Database File Copying (Unsafe)

Because, like other database engines, H2 often stores data in files, copying those files may appear to be an easy backup solution. However, when the database is running, pages may be in the middle of an update. Thus, copying files at any given moment can lead to internal inconsistencies, such as partially written rows or mismatched tables, depending on the query.

Another issue is long-term reliability. Unlike standardized languages and formats, the H2 engine database files may change across versions. Due to that, a separate copy of a database file may fail to open after an upgrade, which limits its usefulness as a dependable backup.

3.2. Online Backups With BACKUP TO

To avoid offline backups and address problems related to database files, H2 provides a special command. Specifically, the BACKUP TO SQL statement creates a ZIP archive with a consistent snapshot of the database at a given point in time, even while the database is running:

// JDBC-based online backup
String backupFile =
    "backup-" + java.time.LocalDateTime.now()
      .format(java.time.format.DateTimeFormatter.ofPattern("yyyyMMdd-HHmmss"))
    + ".zip";
try (Connection con = DriverManager.getConnection(
       "jdbc:h2:./db/mydb", "user", "password");
     PreparedStatement ps =
       con.prepareStatement("BACKUP TO '" + backupFile + "'")) {
  ps.executeUpdate();
}

Because the backup is executed by the database engine, it avoids the consistency risks associated with copying filesystem objects. Further, we can run such commands via both plain JDBC or with frameworks such as Spring Data using native queries, keeping backup logic close to application code.

4. Exporting Data From H2

Conversely, exports can be a bit more flexible, since they usually don’t have the rigorous requirements of a backup.

4.1. CSV Exports With CSVWRITE

For data inspection or sharing, the H2 engine supports the CSVWRITE function. It writes the result of an SQL query directly to a CSV file, making it easy to extract data in a widely supported format:

CALL CSVWRITE(
  '<BACKUP_FILE_PATH>',
  'SELECT * FROM <TABLE_NAME>'
);

In this case, since the export is a SELECT statement, it can also include filters, joins, and ordering. This makes CSVWRITE particularly useful for reporting, debugging, and transferring subsets of data to other tools such as spreadsheets or analytics systems.

Importantly, this export is fairly simplistic in that it deals mainly with data and doesn’t really handle metadata in depth.

4.2. Logical Exports With SCRIPT

When both schema and data are needed, the H2 engine command SCRIPT can be used to get a logical export as SQL statements. Just like with other tools that produce SQL statements, these output scripts can recreate tables and insert data when executed later:

SCRIPT SIMPLE TO '<BACKUP_SQL_SCRIPT_PATH>'
TABLE PUBLIC.<TABLE_NAME>;

Unlike CSV exports, SQL scripts preserve structural information. Because of this, migrations, reproducible test setups, and version-controlled snapshots of database state are often facilitated by this export method. For instance, SQL scripts produced by SCRIPT can be restored using RUNSCRIPT, providing a simple logical backup-and-restore loop for development or testing environments.

5. Summary

In this article, we looked at ways to back up or export data from H2 databases.

In summary, online backups rely on the BACKUP TO command to produce consistent, restorable archives without stopping the database. On the other hand, data exports rely on CSVWRITE for portable, query-driven CSV files and SCRIPT for schema-aware SQL output. Together, these tools cover recovery, portability, and inspection needs while avoiding the risks associated with direct file copying.

In conclusion, H2 provides built-in, engine-managed mechanisms for both backups and exports.

       

1. Overview

While converting one type of number to another is a pretty straightforward operation. In some cases, we might have problems with the representation of numbers due to differences in byte orderings. Thus, we should always consider it during processing and conversion, especially if we receive raw data from outside. In this tutorial, we’ll learn how to convert bytes to shorts and vice versa. We also discuss the problem and the reason for this difference in representation, and we will see how to address it in code.

2. Byte Order

A combination of zeros and ones represents all the numbers in a computer. However, there is a difference between the two types of representation. One of them is called big-endian, the other is called little-endian. In big-endian, we use the most significant bytes on the left, so it’s written from left to right. At the same time, in little-endian, the least significant bytes are on the left, so the order is inverted:

3. Bytes to Shorts

public static short[] bytesToShortsBigEndianUsingLoop(byte[] bytes) {
    int n = bytes.length / 2;
    short[] shorts = new short[n];
    for (int i = 0; i < n; i++) {
        shorts[i] = (short) (((bytes[2 * i] & 0xFF) << 8) | (bytes[2 * i + 1] & 0xFF));
    }
    return shorts;
}

public static short[] bytesToShortsBigEndianUsingStream(byte[] bytes) {
    int n = bytes.length / 2;
    short[] shorts = new short[n];
    IntStream.range(0, n).forEach(i ->
        shorts[i] = (short) (((bytes[2 * i] & 0xFF) << 8) | (bytes[2 * i + 1] & 0xFF)));
    return shorts;
}

public static short[] bytesToShortsLittleEndianUsingLoop(byte[] bytes) {
    int n = bytes.length / 2;
    short[] shorts = new short[n];
    for (int i = 0; i < n; i++) {
        shorts[i] = (short) ((bytes[2 * i] & 0xFF) | ((bytes[2 * i + 1] & 0xFF) << 8));
    }
    return shorts;
}

The logic is pretty simple: we have to swap the bytes so that the first one takes the least significant positions and the second the most significant ones.

4. Shorts to Bytes

The opposite operation is pretty similar. We cannot use downcasting, as our goal is to use individual bytes. Thus, we have to extract bytes with masks and bit shifts:

public static byte[] shortsToBytesBigEndianUsingLoop(short[] shorts) {
    byte[] bytes = new byte[shorts.length * 2];
    for (int i = 0; i < shorts.length; i++) {
        short value = shorts[i];
        bytes[2 * i] = (byte) ((value >>> 8) & 0xFF);
        bytes[2 * i + 1] = (byte) (value & 0xFF);
    }
    return bytes;
}

Little-endian would require mostly the same code, but we should flip the order in which we write the bytes:

public static byte[] shortsToBytesLittleEndianUsingLoop(short[] shorts) {
    byte[] bytes = new byte[shorts.length * 2];
    for (int i = 0; i < shorts.length; i++) {
        short value = shorts[i];
        bytes[2 * i] = (byte) (value & 0xFF);
        bytes[2 * i + 1] = (byte) ((value >>> 8) & 0xFF);
    }
    return bytes;
}

It’s important to remember that the byte order affects only the bytes inside the multi-byte values. We don’t need to change the order of bytes or the order of values themselves.

5. ByteBuffer

To simplify the process, we will use existing classes to handle the conversion out of the box. With the ByteBuffer and ByteOrder classes, the conversion:

public static short[] bytesToShortsLittleEndian(byte[] bytes) {
    short[] shorts = new short[bytes.length / 2];
    ByteBuffer.wrap(bytes).order(ByteOrder.LITTLE_ENDIAN).asShortBuffer().get(shorts);
    return shorts;
}

Here we wrap the bytes with a buffer and change the interpretation of the bytes (if required), without changing the actual order. As implied by the method name, we don’t copy or modify the original array, so any mutation may affect the result and processing. Reading the shorts also makes things easier, since we can pass an empty array to read the data into. However, we have the same limitation with odd-sized arrays. Thus, even with library methods, we should be careful about the amount of data we work with.

To use big-endian order, we can either provide an explicit value to the order method or omit it and use the default (big-endian). The default configuration isn’t platform-dependent and defined by the JVM. However, explicit configuration is always preferable, as it makes the code more readable and helps avoid bugs. With ByteBuffer, writing shorts into a byte array using little-endian also becomes a pretty trivial task:

public static byte[] shortsToBytesLittleEndian(short[] shorts) {
    ByteBuffer buffer = ByteBuffer.allocate(shorts.length * 2).order(ByteOrder.LITTLE_ENDIAN);
    buffer.asShortBuffer().put(shorts);
    return buffer.array();
}

Java provides many convenient classes that can make our code cleaner, and ByteBuffer is a good example. While we won’t use it daily, it’s useful to know it exists.

6. Conclusion

In this article, we discussed the conversion between bytes and shorts and also reviewed possible issues with byte order. While we might assume that the number representation is the same across platforms, that’s not the case. The difference in byte order might introduce some hard-to-debug problems. We always need to consider it while working with data, especially when we work with data from different systems.