1. Overview

When we work with regular expressions in Java, even a small syntax mistake can break our application at runtime. One of the most common errors we encounter is:

java.util.regex.PatternSyntaxException: Unclosed character class

In this tutorial, we’ll explore why this happens, how to reproduce it, and how to fix it. We also cover a real-world issue involving split() that often triggers this exception.

2. Understanding Character Classes

A character class in regex allows us to match any one character from a given set. This is one of the most commonly used regex constructs in Java.
Let us first look at a simple example of a character class:

"[abc]"

In this pattern, the regex engine matches either a, b, or c. We should always remember that a character class starts with [ and must end with ]. We can also define ranges when working with larger sets of characters:

"[a-z]"

This pattern matches any lowercase English letter from a to z. If we forget to close the bracket, Java will throw a runtime exception.

3. Reproducing the Exception

To better understand the problem, let us intentionally write an invalid regex pattern. This helps us see exactly how Java reacts:

public class RegexExample {
    public static void main(String[] args) {
        Pattern.compile("[a-z");
    }
}

In the above example, we try to compile a regex that starts a character class but never closes it. When we run this code, Java throws the following exception:

java.util.regex.PatternSyntaxException: Unclosed character class near index 4
[a-z
    ^

This clearly indicates that the regex parser expected a closing ] but did not find one.

4. Fixing the Exception

Now that we understand the problem, fixing it becomes straightforward. We simply need to close the character class properly:

Pattern.compile("[a-z]");

After making this change, the pattern compiles successfully without any errors. We should always verify that every opening bracket has a corresponding closing bracket.

5. Common Causes of This Exception

Let’s have a look at some of the common causes of PatternSyntaxException.

5.1. Missing Closing Bracket

One of the most frequent mistakes is forgetting to close the character class:

Pattern.compile("[0-9");

This pattern is incomplete and results in a runtime exception. We can fix it by adding the missing closing bracket:

Pattern.compile("[0-9]");

Even a small omission like this can break the entire regex.

5.2. Incorrect Nested Patterns

Sometimes, while writing a complex regex, we accidentally introduce extra brackets:

Pattern.compile("[a-zA-Z[0-9]");

In this pattern, we have an extra [ inside the character class. Character classes do not support nesting using [ like this, so the regex becomes invalid. As a result, Java throws a PatternSyntaxException.

To fix this, we should remove the unnecessary bracket and define the character set correctly:

Pattern.compile("[a-zA-Z0-9]");

Now the pattern is valid and matches any alphanumeric character. Instead of nesting, we should combine all required characters within a single character class.

6. Issue with split()

Let us now look at a practical example that often causes confusion in real projects. Before jumping into the issue, we first define a sample 2D array.

String[][] array2d = {
    {"a", "b"},
    {"c", "d"}
};

In many cases, we convert this array into a string using Arrays.deepToString() for quick inspection or processing:

String str = Arrays.deepToString(array2d);
System.out.println(str);

When we run this, the output looks like:

[[a, b], [c, d]]

Notice that the output contains nested square brackets. This is important for understanding the issue. Now, let us attempt to split this string into individual rows. At first glance, the following code looks correct:

String[][] split = new String[1][rows];
split[0] = str.split("], [");

However, when we run this code, we encounter a runtime exception:

java.util.regex.PatternSyntaxException: Unclosed character class

This happens because split() expects a regex, not a plain string. The pattern: “], [” is interpreted incorrectly, since [ and ] are special characters in regex. As a result, the regex engine treats [ as the start of a character class, leading to the exception.
To resolve this issue, we need to escape the square brackets so they are treated as literal characters:

split[0] = str.split("\\], \\[");

With this change, the regex becomes valid, and the code works as expected. Proper escaping ensures that special characters do not break our regex. Although the fix works, we can further improve the solution for cleaner output. The result of Arrays.deepToString() contains outer brackets that we may want to remove:

String str = Arrays.deepToString(array2d);
str = str.substring(1, str.length() - 1);
String[] result = str.split("\\], \\[");

By trimming the outer brackets, we get a cleaner split result. This makes the output easier to process and avoids unwanted characters.

7. Conclusion

In this article, we saw that the PatternSyntaxException: Unclosed character class is a common yet avoidable issue in Java. It usually occurs due to missing brackets or incorrect handling of special characters like [ and ]. By carefully writing regex patterns, properly escaping characters in methods like split(), and validating inputs, we can build more reliable applications. A small attention to detail in regex can prevent major runtime issues.

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

       

1. Overview

Spring Boot allows us to easily schedule a job, for example, using the @Scheduled annotation. Sometimes, we don’t want to hardcode the scheduling parameters, such as the cron expression. Instead, we would like to schedule a job using a cron expression from a database.

In this tutorial, we’ll first explore two approaches to achieve it. Further, we’ll discuss when to use which.

2. Introduction to the Problem

When we work with Spring scheduling, the most straightforward option is usually to place the cron expression directly in @Scheduled, for example:

@Scheduled(cron = "*/5 * * * * ?")
public void run() {
    // job logic
}

This works well, but it also hardcodes the schedule into the application.

The problem appears when we want to fetch the cron expression from a database. This is because we cannot simply write something like this:

private String cronExpression = loadFromDatabase();
@Scheduled(cron = cronExpression)
public void run() {
    // invalid approach
}

If we compile this code, the compiler will complain:

java: element value must be a constant expression

The reason is that the cron attribute in an annotation cannot be populated from an arbitrary runtime variable. In practice, we either need an indirection that Spring can resolve for us, or we need to move away from annotation-driven scheduling altogether.

In this tutorial, we’ll explore both approaches. But let’s do some preparation before we dive into the solutions.

3. Preparing Data in a Database

For this tutorial, we use a small H2 in-memory database. Also, for simplicity, we’ll skip Spring Data JPA configurations

3.1. Creating a Simple Table

We want our Spring Boot application to automatically create a database table and insert some data into it when it starts. Therefore, let’s prepare a schema.sql file:

CREATE TABLE IF NOT EXISTS cron_config (
    id BIGINT PRIMARY KEY,
    cron_expression VARCHAR(255) NOT NULL
);

As we can see, the cron_config table is intentionally minimal. We only need an identifier and the cron expression itself.

Next, let’s create a data.sql file to insert a row into the table:

INSERT INTO cron_config (id, cron_expression) VALUES (1, '*/5 * * * * ?');

We insert a single row so the application has a cron value as soon as it starts. So by default, the schedule runs every five seconds.

3.2. Preparing the Entity and the Repository Classes

The corresponding JPA entity is equally small:

@Entity
@Table(name = "cron_config")
public class CronEntity {
    @Id
    private Long id;
    private String cronExpression;
    // ... the default constructor, getters and setters are omitted
}

The repository is just as simple and gives us the CRUD operations we need:

public interface CronConfigRepository extends JpaRepository<CronEntity, Long> {
}

With these pieces in place, we can read and update cron values from the database.

Now, let’s see how to tell Spring to schedule jobs using the cron expression we stored in the database.

4. Using a cronLoader Bean

In our first approach, we would like to keep the @Scheduled annotation, but avoid placing the cron expression directly in the annotation. Instead, we’ll create a Spring Bean to read the cron expression from our database and reference the bean in @Scheduled’s cron attribute.

4.1. Defining the cronLoader Bean to Load the Cron Expression

We start with a small configuration class that defines a bean named cronLoader:

@Configuration
public class CronLoaderConfig {
    @Bean
    String cronLoader(CronConfigRepository repository) {
        return repository.findById(1L)
          .map(CronEntity::getCronExpression)
          .orElseThrow(() -> new RuntimeException("Cron expression not found in DB"));
    }
}

As the code above shows, this bean is pretty straightforward. It reads the cron expression from the row with id = 1 and returns it as a String.

4.2. Referencing the Bean from @Scheduled

Next, we can reference that bean through SpEL in our scheduled job:

@Component
public class AnnotationScheduledJob {
    private static final Logger log = LoggerFactory.getLogger(AnnotationScheduledJob.class);
    @Scheduled(cron = "#{@cronLoader}")
    public void run() {
        log.info("✅ [{}] Job executed - cron loaded from DB via @Scheduled", now());
    }
}

This is the key idea: we still use @Scheduled, but the cron expression comes from the cronLoader bean instead of being embedded directly in the annotation.

Also, our job does nothing but print a line with the execution time, so we can verify whether the executions match our cron expression in the database.

Next, let’s verify if the job scheduling works as we expected.

4.3. Starting the Application and Observing the Console Outputs

If we start our Spring Boot application, we can see these lines in the console log:

...
... AnnotationScheduledJob : ✅ [10:00:05.002] Job executed - cron loaded from DB via @Scheduled
... AnnotationScheduledJob : ✅ [10:00:10.001] Job executed - cron loaded from DB via @Scheduled
... AnnotationScheduledJob : ✅ [10:00:15.000] Job executed - cron loaded from DB via @Scheduled
... AnnotationScheduledJob : ✅ [10:00:20.001] Job executed - cron loaded from DB via @Scheduled
...

Because our data.sql inserts “*/5 * * * * ?” as the cron expression, we see the annotation-based job log roughly every five seconds. This gives us a straightforward way to verify that the cron value is being loaded from the database.

4.4. Limitation of the cronLoader Bean Approach

This approach is convenient, but it comes with an important limitation.

Spring loads the cron value when it creates the cronLoader bean during application startup. After that, the scheduled method continues using the resolved value.

If we update the cron_config table later, the schedule won’t automatically change for the running application. In practice, we would typically need to restart the application to pick up the new value.

So, this approach is a good fit only when loading the schedule once at startup is acceptable.

5. Using Spring’s SchedulingConfigurer

If we want our scheduled jobs to react to database changes without restarting, we need a more dynamic solution. Next, let’s dive in.

5.1. Implementing SchedulingConfigurer

Instead of relying on the @Scheduled annotation, we can implement Spring’s SchedulingConfigurer and register our own trigger task.

First, let’s create a DynamicScheduledConfig configuration class implementing SchedulingConfigurer:

@Configuration
public class DynamicScheduledConfig implements SchedulingConfigurer {
    private static final Logger log = LoggerFactory.getLogger(DynamicScheduledConfig.class);
    private final CronConfigRepository repository;
    public DynamicScheduledConfig(CronConfigRepository repository) {
        this.repository = repository;
    }
    @Override
    public void configureTasks(ScheduledTaskRegistrar taskRegistrar) {
        taskRegistrar.addTriggerTask(() -> log.info(
          "✅ [{}] DynamicScheduledConfig executed - cron re-read from DB per execution",
          now()), triggerContext -> {
            String cronExpression = repository.findById(1L)
              .map(CronEntity::getCronExpression)
              .orElseThrow(() -> new RuntimeException("Cron expression not found in DB"));
            return new CronTrigger(cronExpression).nextExecution(triggerContext);
        });
    }
}

Next, let’s understand how the configureTasks() method works:

First, we register a task with the addTriggerTask(…) method. The addTriggerTask() method has two parameters: a Runnable (the “What”) that contains the work we want to execute in this task and a Trigger object (the “When”) that specifies when the task should be triggered.

In our example, our task simply prints a log with the current time.

The Trigger parameter is the “magic” part of the implementation. It calculates the next execution time every time the task finishes:

• Fetching the cron expression from our database using the injected repository
• Creating a new CronTrigger object from the cron expression on the fly, and Spring asks that trigger for the next execution time

This means that if we change the cron expression in our database, the trigger callback will pick up the new value immediately when it calculates the next execution time. This is the main difference from the cronLoader bean approach: the cron expression is re-read from the database whenever Spring calculates the next execution time.

5.2. A Simple REST Controller to Update the Cron Expression in Our Database

For easier testing, let’s create a simple REST controller that allows us to quickly update the database record by HTTP request:

@RestController
public class CronController {
    private static final Logger log = LoggerFactory.getLogger(CronController.class);
    private final CronConfigRepository repository;
    public CronController(CronConfigRepository repository) {
        this.repository = repository;
    }
    @GetMapping("/cron")
    public String updateCron() {
        CronEntity cronEntity = repository.findById(1L)
          .orElseThrow(() -> new RuntimeException("Cron expression not found in database"));
        cronEntity.setCronExpression("*/10 * * * * ?");
        repository.save(cronEntity);
        String msg = "[DB] ⏰ Updated cron expression in DB to: */10 * * * * ?";
        log.info(msg);
        return msg;
    }
}

As the example shows, for simplicity, this endpoint always sets the cron to run every 10 seconds.

Next, let’s verify if the SchedulingConfigurer approach can always reschedule the job according to the database change.

5.3. Starting the Application and Observing the Console Outputs

To make the logs easier to read during the demonstration, we can temporarily comment out the annotation-based scheduling line in AnnotationScheduledJob so that only the dynamic task is running:

@Component
public class AnnotationScheduledJob {
    // ...
    // @Scheduled(cron = "#{@cronLoader}")  <-- comment out
    public void run() {
        // ...
    }
}

Next, let’s launch our Spring Boot application. Once it starts, the scheduled job will also begin. Log outputs similar to these will appear in the console:

... DynamicScheduledConfig : ✅ [10:05:05.001] DynamicScheduledConfig executed - cron re-read from DB per execution
... DynamicScheduledConfig : ✅ [10:05:10.001] DynamicScheduledConfig executed - cron re-read from DB per execution
... DynamicScheduledConfig : ✅ [10:05:15.001] DynamicScheduledConfig executed - cron re-read from DB per execution
... DynamicScheduledConfig : ✅ [10:05:20.000] DynamicScheduledConfig executed - cron re-read from DB per execution

Because the data.sql file still seeds “*/5 * * * * ?”, the dynamic task initially runs about every five seconds.

Next, let’s call the “/cron” endpoint to update the cron expression. For example, we can launch this curl command to send a GET request:

curl http://localhost:8080/cron

Then, in the Spring Boot application console, we can see this log, meaning the cron expression has been changed to “every 10 seconds”:

... CronController : [DB] ⏰ Updated cron expression in DB to: */10 * * * * ?

After that, the dynamic task should start following the new interval. In other words, instead of firing every five seconds, subsequent executions should move to a ten-second rhythm:

... DynamicScheduledConfig : ✅ [10:05:30.000] DynamicScheduledConfig executed - cron re-read from DB per execution
... DynamicScheduledConfig : ✅ [10:05:40.002] DynamicScheduledConfig executed - cron re-read from DB per execution
... DynamicScheduledConfig : ✅ [10:05:50.000] DynamicScheduledConfig executed - cron re-read from DB per execution
... DynamicScheduledConfig : ✅ [10:05:60.000] DynamicScheduledConfig executed - cron re-read from DB per execution

This demonstrates the main benefit of SchedulingConfigurer: we can change the cron expression in the database and let the running application adapt without a restart.

6. Conclusion

In this article, we explored two ways to get a scheduled job’s cron value from a database in Spring Boot.

With the cronLoader bean approach, we keep the implementation simple and continue using @Scheduled, but we only load the cron value once during startup.

With SchedulingConfigurer, we take control of task registration and re-read the cron expression from the database whenever Spring calculates the next execution time. This makes the schedule dynamic and allows runtime updates.

So if we only need a startup-time value, a bean-backed @Scheduled setup is often enough. But if we want truly dynamic scheduling, SchedulingConfigurer is the better choice.

As always, the complete source code for the examples is available over on GitHub.

       

1. Introduction

Gaussian blur is a widely used image processing technique for reducing image noise and detail. However, achieving accurate Gaussian blur can be computationally expensive, especially for high-resolution images with large blur radii.

In this tutorial, we’ll explore a faster, more computationally efficient solution for implementing Gaussian blur in Java.

2. Problem Overview

We implement a standard Gaussian blur on a grayscale image by convolving it with a 2D Gaussian kernel. Here, for each pixel in an image, the algorithm first examines a surrounding grid of pixels (the kernel). Then, it multiplies each pixel’s intensity by a specific weight. Finally, it sums them up.

For an image with n pixels and a blur radius of r, our kernel size is (2r + 1)  x  (2r + 1). Thus, the standard 2D convolution algorithm has a time complexity of O(n.r²). As the blur radius r grows, the performance degrades quadratically. Thus, it is not optimal for real-time processing over large images.

3. The Fast Approximation Algorithm

Our fast approximations make two key enhancements to the standard Gaussian 2D blur method.

3.1. Separable Filters

A 2D Gaussian kernel can be seen and used as two 1D Gaussian vectors. In other words, we can separate them as horizontal and vertical vectors. So, instead of applying a 2D matrix to every pixel of the image, we can achieve the same result by applying a horizontal 1D blur across all rows, followed by a vertical 1D blur down all columns.

This simple separation reduces our average-case time complexity from O(n.r²) to O(n.r).

3.2. Repeated Box Blurs

We repeat a specific blur operation (box blur) to achieve the desired effect.

We define box blur as the simplest form of blurring, assigning equal weight to every pixel within the blur radius. Then, we make use of the Central Limit Theorem to approximate a valid and matching Gaussian distribution. According to the Central Limit Theorem, applying a simple Box Blur multiple times closely approximates an accurate Gaussian distribution. We run five consecutive passes of a box blur to get a visually indistinguishable result from a strict Gaussian blur with a fraction of the computational overhead.

Furthermore, we make all weights in a Box Blur equal, so we don’t need to re-sum the entire radius for every pixel. This gives us the freedom to use a sliding window or a moving average. As the window shifts to the right by one pixel, we subtract the leaving pixel and add the entering pixel. This drops our average time complexity to O(n), making the performance entirely independent of the blur radius r!

4. Solution

Let’s move to the solution.

4.1. The Sliding Window Box Blur

First, we define a function, horizontalBoxBlur(), that performs a 1D horizontal blur using the sliding-window technique.

Here, we process the image row by row. We don’t recalculate the pixel sum at every position. Instead, we initialize windowSum for the very first pixel in a row. As it moves left to right, it subtracts the value of the pixel beyond the trailing edge of the radius and adds the value of the pixel at the leading edge.

Lastly, we clamp edges to ensure that if the radius extends beyond the image boundaries, our logic duplicates the edge pixels rather than throwing an ArrayIndexOutOfBoundsException.

private static void horizontalBoxBlur(int[] source, int[] target, int width, int height, int radius) {
    double scale = 1.0 / (radius * 2 + 1);
    for (int y = 0; y < height; y++) {
        int windowSum = 0;
        int offset = y * width;        
        for (int x = -radius; x <= radius; x++) {
            int safeX = Math.min(Math.max(x, 0), width - 1);
            windowSum += source[offset + safeX];
        }        
        for (int x = 0; x < width; x++) {
            target[offset + x] = (int) Math.round(windowSum * scale);
            int leftX = Math.max(x - radius, 0);
            int rightX = Math.min(x + radius + 1, width - 1);
            windowSum -= source[offset + leftX];
            windowSum += source[offset + rightX];
        }
    }
}

The verticalBoxBlur() is identical in logic, but here we traverse columns rather than rows (top to bottom):

private static void verticalBoxBlur(int[] source, int[] target, int width, int height, int radius) {
    double scale = 1.0 / (radius * 2 + 1);
    for (int x = 0; x < width; x++) {
        int windowSum = 0;
        for (int y = -radius; y <= radius; y++) {
            int safeY = Math.min(Math.max(y, 0), height - 1);
            windowSum += source[safeY * width + x];
        }
        for (int y = 0; y < height; y++) {
            target[y * width + x] = (int) Math.round(windowSum * scale);
            int topY = Math.max(y - radius, 0);
            int bottomY = Math.min(y + radius + 1, height - 1);
            windowSum -= source[topY * width + x];
            windowSum += source[bottomY * width + x];
        }
    }
}

4.2.  Integration

This is our orchestrator.

Leveraging the Central Limit Theorem, we apply a horizontal and vertical box blur three times (configurable). This smooths out peaky regions, thus creating a near-perfect approximation of a true Gaussian bell curve. It uses a temp array (temp) to safely ping-pong the data between passes without corrupting the source:

public static int[] applyFastGaussianBlur(int[] source, int numPasses, int width, int height, int radius) {
    int[] target = new int[source.length];
    int[] temp = new int[source.length];
    System.arraycopy(source, 0, target, 0, source.length);
    for (int i = 0; i < numPasses; i++) {
        horizontalBoxBlur(target, temp, width, height, radius);
        verticalBoxBlur(temp, target, width, height, radius);
    }
    return target;
}

5. Test

5.1. Test Using Impulse Image

First, let’s test this method using an impulse image (artificial images with a single black pixel). Our main objective is to verify if  our algorithm handles edges correctly and applies a smoothing effect:

void givenSharpImage_whenAppliedBlur_thenCenterIsSmoothed() {
    int width = 5;
    int height = 5;
    int numPasses = 5;
    int[] image = new int[width * height];
    image[12] = 255; 
    int[] blurredImage = FastGaussianBlur.applyFastGaussianBlur(image, numPasses, width, height, 1);
    assertTrue(blurredImage[12] < 255);
    assertTrue(blurredImage[12] > 0);
    assertTrue(blurredImage[11] > 0); // Left neighbor
    assertTrue(blurredImage[13] > 0); // Right neighbor
}

We begin by creating a 5×5 image (25 pixels) and set all pixels to 0, making them pure black. Then we set the exact center pixel (index 12) to 255, making it pure white. This sharp point is our impulse or peak. Then we apply the fast blur algorithm with a radius of 1.

Our main claim is that blur, when applied correctly, spreads the brightness of the central pixel outwards into the surrounding black pixels. Further, assertTrue(blurredImage[12] < 255) confirms the center pixel has dimmed because it shared its brightness, and assertTrue(blurredImage[11] > 0) and assertTrue(blurredImage[13] > 0) confirm that the immediate left and right neighbors (both black) have absorbed that dispersed brightness.

5.2. Test Using Real Image

We take an open-source image and blur it using our algorithm. Here is the sample image:

Please check the blurred version:

We used a single channel of integer values for our impulse image (grayscale) test case. For this case, we use real images. Each real image is packed with 32-bit ARGB (Alpha, Red, Green, Blue) data. So, here we extract the ARGB channels, then blur each of the RGB channels independently, and finally pack them back together:

public static BufferedImage blurRealImage(@Nonnull BufferedImage image, int radius, int numPasses) {
    int width = image.getWidth();
    int height = image.getHeight();
    int[] pixels = image.getRGB(0, 0, width, height, null, 0, width);
    int[] a = new int[pixels.length];
    int[] r = new int[pixels.length];
    int[] g = new int[pixels.length];
    int[] b = new int[pixels.length];
    for (int i = 0; i < pixels.length; i++) {
        a[i] = (pixels[i] >> 24) & 0xff;
        r[i] = (pixels[i] >> 16) & 0xff;
        g[i] = (pixels[i] >> 8) & 0xff;
        b[i] = pixels[i] & 0xff;
    }
    r = FastGaussianBlur.applyFastGaussianBlur(r, width, height, radius, numPasses);
    g = FastGaussianBlur.applyFastGaussianBlur(g, width, height, radius, numPasses);
    b = FastGaussianBlur.applyFastGaussianBlur(b, width, height, radius, numPasses);
    int[] resultPixels = new int[pixels.length];
    for (int i = 0; i < pixels.length; i++) {
        resultPixels[i] = (a[i] << 24) | (r[i] << 16) | (g[i] << 8) | b[i];
    }
    BufferedImage result = new BufferedImage(width, height, BufferedImage.TYPE_INT_ARGB);
    result.setRGB(0, 0, width, height, resultPixels, 0, width);
    return result;
}

6. Conclusion

In this article, we learned a faster Gaussian blur method in Java. We made two key enhancements to the standard Gaussian blur implementation to achieve linear time complexity. First, we decomposed a 2D convolution matrix into separable 1D arrays, and second, we used a moving-average sliding window across three box-blur passes. Thus, our solution works in a constant processing time that is independent of the blur radius.

As always, the complete code examples are available over on GitHub.

       

1. Spring and Java

>> Beyond RAG: Architecting Context-Aware AI Systems with Spring Boot [infoq.com]

A solid look at Context-Augmented Generation (CAG) — an architectural layer on top of RAG that adds user identity, session state, and business constraints before the retrieval step. With Boot of course.

Also worth reading:

• >> Thread-Safe Native Memory in Java: VarHandle Access Modes Explained [foojay.io]
• >> From Zero to Full Observability with Dash0 [foojay.io]
• >> Does Java Really Use Too Much Memory? Let’s Look at the Facts (JEPs) [foojay.io]
• >> Spring AI Agentic Patterns (Part 6): AutoMemoryTools — Persistent Agent Memory Across Sessions [spring.io]
• >> Announcing ADK for Java 1.0.0: Building the Future of AI Agents in Java [googleblog.com]
• >> ACP Java SDK: Building IDE Agents in Java [blog.pollack.ai]

Webinars and presentations:

• >> A Bootiful Podcast: Java developer advocate Ana-Maria Mihalceanu [spring.io]
• >> Java and Post-Quantum Cryptography [inside.java]
• >> Episode 53 “Analyzing Crashed JVMs” [inside.java]

Time to upgrade:

• >> Spring Cloud 2025.0.2 (aka Northfields) Has Been Released [spring.io]
• >> Hibernate 7.3.0.Final [in.relation.to]
• >> Helidon 4.4.0 Introduces Alignment with OpenJDK Cadence and Support via Java Verified Portfolio [infoq.com]
• >> Quarkus 3.34.3 [github.com/quarkusio]
• >> Elasticsearch 9.3.3, 9.2.8, and 8.19.14 [github.com/elastic]
• >> TornadoVM 4.0.0 [github.com/beehive-lab]
• >> Netflix Zuul 3.5.8 [github.com/Netflix]

2. Technical & Musings

>> S3 Files and the changing face of S3 [allthingsdistributed.com]

AWS’s new S3 Files feature mounts S3 buckets as network filesystems via EFS, letting you use standard file operations on object storage without copying data around. Bout time

Also worth reading:

• >> Feedback Flywheel [martinfowler.com]
• >> Harness engineering for coding agent users [martinfowler.com]
• >> Experimenting with AI subagents [frankel.ch]
• >> Absurd In Production [lucumr.pocoo.org]
• >> Synchronizing the Senses: Powering Multimodal Intelligence for Video Search [netflixtechblog.com]

3. Pick of the Week

>> Do Things that Don’t Scale [paulgraham.com]

       

1. Introduction

When consuming RESTful services in Spring, RestTemplate is a reliable workhorse for synchronous HTTP communication. However, one of the most common and frustrating hurdles developers face is the RestClientException. Specifically, the following error message:

Could not extract response: no suitable HttpMessageConverter found for response type and content type...

This error typically occurs when the client receives a response that it doesn’t know how to deserialize into the desired Java object. In this article, we’ll explore why this happens and how to configure our application to handle non-standard API responses effectively without encountering any such errors.

2. Project Setup

To get started, we’ll need the standard Spring Boot Starter Web dependency:

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

For JSON processing, Spring Boot includes Jackson by default. To better understand it, we’ll ensure jackson-databind is on our classpath, as it provides the underlying logic for the MappingJackson2HttpMessageConverter.

3. Understanding and Identifying the Root Cause

To fix this error, we’ll first understand how Spring maps the raw HTTP response to Java objects. The issue is rarely with the data itself, but rather a mismatch in the expected communication protocol. We’ll now examine the internal conversion mechanism, identify common misleading media types, and learn how to inspect the actual response headers.

3.1. How RestTemplate Converts Responses

RestTemplate relies on a list of HttpMessageConverter beans to transform HTTP request and response bodies. When a response arrives, Spring looks at the Content-Type header sent by the server. It then iterates through its registered converters to find one that supports both that MediaType and the target Java class.

3.2. Common Mismatched Media Types

The issue usually isn’t that the data is invalid, but that the metadata is misleading. Many legacy or third-party APIs return valid JSON, but set the Content-Type header to something other than application/json. Common mismatched types include text/plain, text/javascript, and application/octet-stream.

The default MappingJackson2HttpMessageConverter only claims to support application/json and application/*+json. It ignores any other type of responses, leading to the “Could not extract response: no suitable HttpMessageConverter found for response type and content type” error.

3.3. Checking API Response Headers

To diagnose this, we must inspect the headers. If we can’t access external logs, we can enable debug logging for Spring Web in our application.properties:

logging.level.org.springframework.web.client.RestTemplate=DEBUG

This will reveal the exact Content-Type the server is providing, allowing us to target the specific mismatch.

4. Solving the Error: Configuration Strategies

In this section, we’ll create a config class named RestTemplateConverterConfig to inject the RestTemplate bean, which will help us resolve this error. The following section mentions the details on it:

4.1. Adding Support for Custom Media Types

The most surgical fix is to tell the Jackson converter to treat these uncommon media types as JSON. We can create an instance of MappingJackson2HttpMessageConverter and update its supported media types:

@Configuration
public class RestTemplateConverterConfig {
    @Bean("specificMediaTypesRestTemplate")
    public RestTemplate specificMediaTypesRestTemplate() {
        RestTemplate restTemplate = new RestTemplate();
        List<HttpMessageConverter<?>> converters = restTemplate.getMessageConverters();
        MappingJackson2HttpMessageConverter jsonConverter = new MappingJackson2HttpMessageConverter();
        jsonConverter.setSupportedMediaTypes(Arrays.asList(
          MediaType.APPLICATION_JSON,
          MediaType.TEXT_PLAIN,
          MediaType.valueOf("text/javascript")
        ));
        converters.add(jsonConverter);
        restTemplate.setMessageConverters(converters);
        return restTemplate;
    }
}

Here we explicitly list only the media types we expect to encounter. This keeps the converter’s scope narrow and intentional. Other unexpected content types, such as application/octet-stream, would still fail, which is often the desired behavior in a controlled environment.

4.2. Manually Registering Converters in RestTemplate

If we want a more permissive setup, within the same RestTemplateConverterConfig class, we’ll register another Jackson converter with MediaType.ALL. This instructs the RestTemplate to handle any content type the server returns:

@Bean
public RestTemplate restTemplate() {
    RestTemplate restTemplate = new RestTemplate();
    List<HttpMessageConverter<?>> converters = restTemplate.getMessageConverters();
    MappingJackson2HttpMessageConverter jsonConverter = new MappingJackson2HttpMessageConverter();
    jsonConverter.setSupportedMediaTypes(Collections.singletonList(MediaType.ALL));
    converters.add(jsonConverter);
    restTemplate.setMessageConverters(converters);
    return restTemplate;
}

Here, we call the getMessageConverters() method and append to the existing list rather than replacing it. This preserves all the default converters Spring registers, such as those for String and byte[], and simply adds our custom Jackson converter at the end.

4.3. Using RestTemplate.exchange() With ParameterizedTypeReference

Sometimes the error arises because we are trying to deserialize into a generic collection, like List<User>. In this example, the User class is a simple POJO with id and name fields that Jackson maps from the JSON response.

Using getForObject() with List.class loses generic type information at runtime due to type erasure. Instead, we should use the restTemplate.exchange() method with a ParameterizedTypeReference:

ResponseEntity<List<User>> response = restTemplate.exchange(
  "/users",
  HttpMethod.GET,
  null,
  new ParameterizedTypeReference<List<User>>() {}
);

The anonymous subclass of ParameterizedTypeReference captures the full generic type List<User> at compile time, giving Jackson enough information to correctly deserialize each element in the array into a User object.

5. Testing and Verification

To verify our configurations, we’ll use MockRestServiceServer. This allows us to simulate the exact mismatched header scenarios that typically trigger the RestClientException without needing a live external API.

5.1. Testing the Surgical Fix

In this first scenario, we use the @Qualifier to inject our specificMediaTypesRestTemplate. We’ll simulate a response that is explicitly labeled as text/plain. This proves that our surgical inclusion of that specific media type works as intended:

@Autowired
@Qualifier("specificMediaTypesRestTemplate")
private RestTemplate specificMediaTypesRestTemplate;
@Test
void givenSpecificMediaTypesRestTemplate_whenTextPlainResponse_thenDeserializeCorrectly() {
    MockRestServiceServer mockServer = MockRestServiceServer.createServer(specificMediaTypesRestTemplate);
    mockServer.expect(requestTo("/user"))
      .andRespond(withSuccess("{\"id\":1,\"name\":\"Sudarshan\"}", MediaType.TEXT_PLAIN));
    User user = specificMediaTypesRestTemplate.getForObject("/user", User.class);
    assertNotNull(user);
    assertEquals("Sudarshan", user.getName());
}

5.2. Testing the Permissive Fix

Next, we test the primary RestTemplate bean configured with MediaType.ALL. This test confirms that, by making the converter permissive, it ignores the misleading text/plain header and defaults to Jackson for deserialization.

@Test
void givenMockServer_whenTextPlainResponse_thenDeserializeCorrectly() {
    MockRestServiceServer mockServer = MockRestServiceServer.createServer(restTemplate);
    mockServer.expect(requestTo("/user"))
      .andRespond(withSuccess("{\"id\":1,\"name\":\"Sudarshan\"}", MediaType.TEXT_PLAIN));
    User user = restTemplate.getForObject("/user", User.class);
    assertNotNull(user);
    assertEquals("Sudarshan", user.getName());
}

5.3. Verifying Generic Type Resolution

Finally, we verify that our restTemplate.exchange() strategy correctly handles collections. Even with a mismatched text/plain header, the ParameterizedTypeReference ensures that the generic information List<User> is preserved during the conversion process:

@Test
void givenMockServer_whenTextPlainResponseForList_thenDeserializeWithParameterizedTypeReference() {
    MockRestServiceServer mockServer = MockRestServiceServer.createServer(restTemplate);
    mockServer.expect(requestTo("/users"))
      .andRespond(
        withSuccess(
          "[{\"id\":1,\"name\":\"Sudarshan\"},{\"id\":2,\"name\":\"Baeldung\"}]",
          MediaType.TEXT_PLAIN));
    ResponseEntity<List<User>> response = restTemplate.exchange(
      "/users",
      HttpMethod.GET,
      null,
      new ParameterizedTypeReference<List<User>>() {}
    );
    assertNotNull(response.getBody());
    assertEquals(2, response.getBody().size());
    assertEquals("Sudarshan", response.getBody().get(0).getName());
}

6. Conclusion

In this tutorial, we understood that the “No Suitable HttpMessageConverter” error is rarely a sign of broken data; it’s a communication breakdown between the server’s headers and the client’s expectations. By identifying the returned Content-Type and explicitly configuring our MappingJackson2HttpMessageConverter to support it, we can bridge this gap.

Whether you choose to support all media types via MediaType.ALL or strictly list the exceptions, like text/plain, understanding the converter registration process is key to building resilient Spring clients.

As always, the complete code samples used in this article are available over on GitHub.

       

1. Overview

Bit manipulation is a fundamental concept in programming that involves working with individual bits of binary data. One common operation is flipping all bits in an integer, converting every 0 to 1 and every 1 to 0.

In this tutorial, we’ll explain what bit flipping means and explore several Java methods to flip the bits of an integer. For completeness, we’ll cover both full 32-bit flipping and flipping only the significant bits.

2. Understanding Bit Flipping

Before we learn how to flip bits in an integer, it’s best to look at a visual example.

To begin with, let’s consider the decimal number 21 and, more specifically, its binary representation:

10101

The goal is to invert each bit so that every 0 becomes a 1 and every 1 becomes a 0:

01010

This corresponds to the decimal value 10 (8+2).

During this transformation, each bit at position i in the original number gets inverted in the result. However, there’s an important distinction to make. When we flip all 32 bits of an integer, i.e., its full size, the result differs from flipping only the significant bits. For instance, flipping all 32 bits of the integer 21 produces -22 due to two’s complement representation, whereas flipping only the significant bits (10101 -> 01010) yields 10.

In the following sections, let’s explore both scenarios in detail.

3. Using the Bitwise NOT Operator

The most direct approach to flip bits is the bitwise NOT operator ~. This unary operator inverts every bit in the integer’s binary representation:

public static int flipAllBits(int n) {
    return ~n;
}

The operator flips all 32 bits of the integer. This means that ~ inverts every bit, including leading zeros, turning a positive number into a negative one due to the two’s complement representation in Java.

Let’s verify the results using a JUnit 5 test and AssertJ matchers:

@Test
void givenPositiveInteger_whenFlipAllBits_thenReturnsNegativeComplement() {
    assertThat(flipAllBits(21)).isEqualTo(-22);
    assertThat(flipAllBits(0)).isEqualTo(-1);
    assertThat(flipAllBits(-1)).isEqualTo(0);
}

As we can see, flipping all 32 bits of 21 gives us -22, not 10. This is because Java’s int type is a signed 32-bit integer.

To get a result like 10 from 21, we need to flip only the significant bits. Let’s cover this case next.

4. Flipping Only the Significant Bits

In many practical scenarios, we want to flip only the bits that are actually used in the binary representation of the number, excluding leading zeros. For instance, flipping the significant bits of 21 (10101) should give us 10 (01010).

4.1. Using a Mask With Bit Length Calculation

The idea is straightforward: we create a mask with a 1 at each significant bit position, then XOR the number with this mask. The XOR operation flips only the bits where the mask has a 1:

public static int flipSignificantBits(int n) {
    if (n == 0) {
        return 0;
    }
    int bitLength = Integer.SIZE - Integer.numberOfLeadingZeros(n);
    int mask = (1 << bitLength) - 1;
    return n ^ mask;
}

First, we handle the edge case where n is 0. Then, we calculate the number of significant bits using Integer.numberOfLeadingZeros(). With this value, we create a mask by shifting 1 left by bitLength positions and subtracting 1, which gives us a sequence of 1s matching the significant bit length.

Finally, the XOR operation (^) flips only the significant bits, since XOR with 1 inverts a bit while XOR with 0 leaves it unchanged.

Let’s verify this with a test:

@Test
void givenPositiveInteger_whenFlipSignificantBits_thenReturnsFlippedValue() {
    assertThat(flipSignificantBits(21)).isEqualTo(10);
    assertThat(flipSignificantBits(26)).isEqualTo(5);
    assertThat(flipSignificantBits(0)).isEqualTo(0);
    assertThat(flipSignificantBits(1)).isEqualTo(0);
    assertThat(flipSignificantBits(7)).isEqualTo(0);
}

To illustrate, let’s trace through the example with 26 (binary 11010):

n     = 11010  (26)
mask  = 11111  (31)
n ^ mask = 00101  (5)

This approach effectively and efficiently flips only the significant bits.

4.2. Using Integer.highestOneBit()

We can also use the built-in Integer.highestOneBit() method to build the mask. This method returns a value with only the highest bit of the input set:

public static int flipSignificantBitsUsingHighestOneBit(int n) {
    if (n == 0) {
        return 0;
    }
    int mask = (Integer.highestOneBit(n) << 1) - 1;
    return n ^ mask;
}

Here, Integer.highestOneBit(n) returns the value of the most significant bit. By shifting it left by one position and subtracting 1, we create a mask with a 1 at each significant bit. Then, a XOR operation with this mask again flips only those bits.

4.3. Using the Bitwise NOT With a Mask

Instead of XOR, we can also combine the bitwise NOT operator with a mask to get the same result:

public static int flipSignificantBitsUsingNot(int n) {
    if (n == 0) {
        return 0;
    }
    int bitLength = Integer.SIZE - Integer.numberOfLeadingZeros(n);
    int mask = (1 << bitLength) - 1;
    return ~n & mask;
}

This function first computes the bitwise NOT of n, which flips all 32 bits. Then, the AND operation with the mask zeroes out all the bits beyond the significant ones. Simply put, the result is equivalent to flipping only the significant bits.

5. Alternative Methods

Apart from the standard bitwise operators, there are other, more unorthodox ways to flip all 32 bits of an integer.

5.1. Using Arithmetic Negation

Due to the two’s complement representation, flipping all bits of n is equivalent to computing -n – 1:

public static int flipBitsArithmetic(int n) {
    return -n - 1;
}

This works because, in two’s complement, the negation of n is the bitwise complement plus 1 (-n = ~n + 1). Therefore, ~n = -n – 1, which gives the same result as the bitwise NOT operator.

5.2. Using XOR With -1

Another way to flip all bits is to XOR the number with -1. In binary, we represent -1 as all 1s (11111111…1 in 32 bits). Notably, ~0 also evaluates to -1, so we can use either interchangeably:

public static int flipBitsXorMinusOne(int n) {
    return n ^ -1;
}

Since XOR with 1 flips a bit, performing XOR with a value where all bits are 1 effectively flips every bit in the integer. This produces the same result as the ~ operator.

6. Conclusion

In this article, we explored several approaches for flipping bits of an integer in Java. We started with the bitwise NOT operator for full 32-bit flipping. Next, we looked at mask-based methods for flipping only the significant bits using XOR and AND operations. Finally, we covered alternative approaches using arithmetic negation and XOR.

As always, all the source code is available over on GitHub.

       

1. Overview

Authentication is the first line of defense in all web applications. Traditionally, applications rely on a username and password to verify a user’s identity. However, experts no longer consider relying on a single authentication factor secure for modern systems.

Multi-Factor Authentication (MFA) addresses this by requiring users to verify their identity using multiple independent factors before accessing a system.

Spring Security 7 introduces built-in support for multi-factor authentication, allowing developers to enforce multiple authentication steps using the existing authorization model. In this article, we’ll explore how MFA works in Spring Security 7 and how to implement it in a Spring Boot application.

2. Understanding MFA in Spring Security 7

Spring Security 7 introduces a new way to model authentication factors using authorities. Instead of treating MFA as a separate authentication mechanism, Spring Security progressively grants authorities for each successful authentication factor.

Multi-Factor Authentication (MFA) strengthens security by requiring users to verify their identity using multiple independent factors. These factors typically fall into three categories: something the user knows, such as a password or PIN, something the user has, such as a mobile device or email token, and something the user is, such as a fingerprint or other biometric data. By combining these factors, applications significantly reduce the risk of compromised credentials and unauthorized access.

Each time a user successfully authenticates with a specific factor, Spring Security adds a corresponding authority to the authentication object. This authority represents the factor that has already been verified during the authentication process. Some common examples include FACTOR_PASSWORD for password-based authentication, FACTOR_X509 for certificate-based authentication, and FACTOR_OTT for one-time token authentication. These authorities are represented internally by the FactorGrantedAuthority class and become part of the authenticated user’s security context.

This design allows authorization rules to verify that the required authentication factors are satisfied before granting access to protected resources.

3. Project Setup

Before implementing multi-factor authentication, we’ll set up a simple Spring Boot application using Spring Initializr with Spring Security 7. First, we need to configure the required dependencies.

We include Spring Boot starters for web, security, starter-test, webmvc-test, and security-testing:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>4.0.3</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
    <version>4.0.3</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <version>4.0.3</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webmvc-test</artifactId>
    <version>4.0.3</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-test</artifactId>
    <version>7.0.0</version>
    <scope>test</scope>
</dependency>

This configuration adds the core dependencies required for our application. It includes Spring Boot’s web support for building REST endpoints, the Spring Security framework for implementing authentication and authorization, and Spring Security testing utilities for writing security-focused unit tests.

With these dependencies in place, the application now has everything required to configure and enable multi-factor authentication.

4. Enabling Multi-Factor Authentication Globally

Spring Security 7 introduces a convenient annotation called @EnableMultiFactorAuthentication. This annotation allows developers to define which authentication factors are required for all protected endpoints.

The following configuration enables MFA globally using password and X509 authentication factors:

@Configuration
@EnableWebSecurity
@EnableMultiFactorAuthentication(
  authorities = { FactorGrantedAuthority.PASSWORD_AUTHORITY, FactorGrantedAuthority.X509_AUTHORITY }
)
public class GlobalMfaSecurityConfig {
    @Bean
    @Order(3)
    SecurityFilterChain defaultSecurityFilterChain(HttpSecurity http) throws Exception {
        http.securityMatcher("/**").authorizeHttpRequests(auth ->auth.requestMatchers("/public")
          .permitAll().anyRequest().authenticated()).formLogin(withDefaults());
        return http.build();
    }
}

This configuration enables Spring Security for the application and enables multi-factor authentication globally. As part of the setup, it specifies that the user must complete two authentication factors before the system considers them fully authenticated.

In this case, the required factors are password and X.509 certificate authentication. Once the configuration is active, every secured endpoint in the application requires both factors for access to be granted. Applying MFA globally like this helps avoid inconsistencies and reduces the risk of missing MFA rules in individual authorization configurations.

5. Applying MFA to Specific Endpoints

In many applications, MFA should be required only for sensitive endpoints, such as account settings, financial operations, or admin actions. Spring Security provides the AuthorizationManagerFactory API to define MFA rules programmatically.

The following configuration requires MFA only for admin endpoints:

@Configuration
@EnableWebSecurity
public class AdminMfaSecurityConfig {
    @Bean
    @Order(1)
    SecurityFilterChain adminSecurityFilterChain(HttpSecurity http) throws Exception {
        AuthorizationManagerFactory<Object> mfa = AuthorizationManagerFactories.multiFactor()
          .requireFactors(
            FactorGrantedAuthority.PASSWORD_AUTHORITY,
            FactorGrantedAuthority.X509_AUTHORITY)
          .build();
        http.securityMatcher("/admin/**").authorizeHttpRequests(auth ->auth.requestMatchers("/admin/**")
          .access(mfa.hasRole("ADMIN")).anyRequest().authenticated()).formLogin(withDefaults());
        return http.build();
    }
}

In this configuration, multi-factor authentication is applied only to requests that match the /admin/** endpoints. When a user attempts to access these routes, Spring Security checks whether the required authentication factors are present.

In addition to completing both authentication factors, the user must also have the ADMIN role. This approach provides fine-grained control over security rules, allowing developers to enforce MFA only on sensitive endpoints while keeping the rest of the application accessible with standard authentication.

6. Implementing Time-Based Authentication Rules

Some applications require users to re-authenticate before performing sensitive actions. For example, a banking application may require a fresh login before updating payment information. Spring Security 7 supports time-based MFA rules.

The following configuration requires the user to authenticate the password factor within the last five minutes:

@Configuration
@EnableWebSecurity
public class TimeBasedMfaSecurityConfig {
    @Bean
    @Order(2)
    SecurityFilterChain profileSecurityFilterChain(HttpSecurity http) throws Exception {
        AuthorizationManagerFactory<Object> recentLogin = AuthorizationManagerFactories.
          multiFactor().requireFactor(
            factor -> factor.passwordAuthority().validDuration(Duration.ofMinutes(5)))
          .build();
        http.securityMatcher("/profile", "/profile/**").authorizeHttpRequests(
          auth -> auth.requestMatchers("/profile", "/profile/**")
            .access(recentLogin.authenticated())
            .anyRequest().
            authenticated()).formLogin(withDefaults());
        return http.build();
    }
}

This rule allows users to navigate most parts of the application using their existing authenticated session. However, when a user attempts to access endpoints under */profile/**, the system verifies whether the password authentication was completed recently.

If the password factor is older than five minutes, Spring Security requires the user to authenticate again before granting access. This approach commonly allows users to perform sensitive operations, ensuring they complete critical actions only after a recent, verified authentication step.

7. Implementing User-Based MFA Rules

Sometimes MFA rules apply only to specific users. For example, administrators may be required to use MFA while regular users can log in with a single factor. Spring Security allows implementing custom authorization managers to support such scenarios.

The following example enforces MFA only for the admin user:

@Component
public class AdminMfaAuthorizationManager implements AuthorizationManager<Object> {
    AuthorizationManager<Object> mfa =
      AllAuthoritiesAuthorizationManager.hasAllAuthorities(FactorGrantedAuthority.OTT_AUTHORITY,
        FactorGrantedAuthority.PASSWORD_AUTHORITY);
    @Override
    public AuthorizationResult authorize(Supplier<? extends Authentication> authentication, Object context) {
        Authentication auth = authentication.get();
        if (auth != null && "admin".equals(auth.getName())) {
            return mfa.authorize(authentication, context);
        }
        return new AuthorizationDecision(true);
    }
}

This logic checks the authenticated user’s identity and applies MFA rules conditionally. If the authenticated user is an admin, the system verifies that the user has completed both required authentication factors before granting access.

For all other users, the system allows the request without enforcing additional MFA checks. This approach is useful when introducing MFA gradually, allowing organizations to enforce stronger security for high-privilege users first before extending it to the entire user base.

8. Writing Unit Tests for MFA

Testing authentication flows is essential to ensure that security rules behave as expected. Without proper tests, it becomes difficult to verify whether authentication requirements such as roles, permissions, or MFA factors are correctly enforced.

Spring Security provides dedicated testing utilities that make it easier to simulate authenticated users and validate authorization behavior. These tools allow developers to write focused tests that verify that security configurations function correctly without requiring a full authentication setup.

8.1. Controller Example

Before writing tests, we define a simple controller that exposes the endpoints secured by our MFA configurations:

@RestController
public class DemoController {
    @GetMapping("/public")
    public String publicEndpoint() {
        return "public endpoint";
    }
    @GetMapping("/profile")
    public String profileEndpoint() {
        return "profile endpoint";
    }
    @GetMapping("/admin/dashboard")
    public String adminDashboard() {
        return "admin dashboard";
    }
}

This controller exposes three endpoints /public, /profile, and /admin/dashboard that help demonstrate different MFA enforcement strategies.

8.2. MFA Security Test

This test verifies how the system behaves when it enforces multi-factor authentication globally:

@SpringBootTest(classes = Application.class)
@AutoConfigureMockMvc
class GlobalMfaSecurityTest {
    @Autowired
    MockMvc mockMvc;
    @Test
    void givenUserWithoutMfa_whenAccessProfile_thenForbidden() throws Exception {
        mockMvc.perform(get("/profile").with(user("user").roles("USER")))
          .andExpect(status().is3xxRedirection())
          .andExpect(header().string("Location", containsString("/login")));
    }
}

This test simulates a user attempting to access the admin endpoint without completing the required MFA factors. Since the authentication request only contains the basic role and does not include the necessary factor authorities, the request does not satisfy the configured security rules. As a result, Spring Security returns a 403 Forbidden response because the user has not completed all required authentication factors.

8.3. Admin Endpoint MFA Test

Next, we’ll verify that the system enforces MFA for admin endpoints:

@SpringBootTest(classes = Application.class)
@AutoConfigureMockMvc
class AdminMfaSecurityTest {
    @Autowired
    MockMvc mockMvc;
    @Test
    void givenAdminWithoutMfa_whenAccessAdminEndpoint_thenForbidden() throws Exception {
        mockMvc.perform(get("/admin/dashboard").with(user("admin").roles("ADMIN")))
          .andExpect(status().is3xxRedirection())
          .andExpect(header().string("Location", containsString("/login")));
    }
}

This test simulates an administrator attempting to access the /admin/dashboard endpoint. Although the user has the required ADMIN role, the request does not include the required MFA authorities. Because the authentication factors are incomplete, Spring Security redirects the request to the login page. This confirms that MFA enforcement works correctly for privileged endpoints.

8.4. Time-Based MFA Security Test

Some operations require users to authenticate recently to ensure no one has compromised the session. The following test verifies that the profile endpoint requires a recent authentication:

@SpringBootTest(classes = Application.class)
@AutoConfigureMockMvc
class TimeBasedMfaSecurityTest {
    @Autowired
    MockMvc mockMvc;
    @Test
    void givenUserWithoutRecentAuthentication_whenAccessProfile_thenForbidden() throws Exception {
        mockMvc.perform(get("/profile").with(user("user").roles("USER")))
          .andExpect(status().is3xxRedirection())
          .andExpect(header().string("Location", containsString("/login")));
    }
}

This test checks that the /profile endpoint requires a recent authentication. Since the simulated request does not include the necessary MFA factor information, Spring Security redirects the request to the login page. This confirms that the system correctly enforces the time-based MFA rule.

9. Conclusion

Multi-Factor Authentication (MFA) is a critical security measure for modern applications, helping reduce the risk of unauthorized access by requiring multiple verification factors.

Spring Security 7 provides built-in support for MFA, allowing developers to enforce multiple authentication steps using the existing authorization model. In this article, we explored how FactorGrantedAuthority models MFA, how to enable it globally with @EnableMultiFactorAuthentication, and how to apply it selectively to specific endpoints using AuthorizationManagerFactory. We also covered time-based rules, custom user-based policies, and testing MFA behavior using Spring Security test utilities.

By leveraging these features, developers can build secure and flexible authentication flows. As security threats continue to evolve, implementing MFA is no longer optional but an essential step in protecting user data and critical systems. As always, the code for this example is available over on GitHub.

       

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.

       

Comments

• In reply to fantaman. Hey, Fantaman. Thanks for the ... by Ulisses Lima
• Should the backend not redirect (instead of forward) to ... by fantaman