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.

       

1. Introduction

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

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

2. Understanding the Serialization Contract

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

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

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

3. Reproducing the Sonar Warning

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

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

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

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

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

4. Making the Field Serializable

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

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

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

5. Using the static Modifier

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

This is the standard solution for loggers and constants:

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

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

6. Leveraging the transient Keyword

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

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

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

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

7. Handling Framework Dependencies

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

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

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

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

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

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

8. Conclusion

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

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

       

1. Introduction

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

2. Why Distributed Transactions?

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

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

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

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

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

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

3. What Is Apache Seata?

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

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

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

4. Seata Server

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

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

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

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

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

5. Using Spring Boot

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

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

5.1. Configuring Seata

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

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

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

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

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

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

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

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

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

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

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

5.2. Global Transactions

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

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

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

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

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

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

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

5.3. Transaction Propagation

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

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

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

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

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

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

We must then ensure that our RestClient always uses this:

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

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

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

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

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

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

6. Using Spring Cloud

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

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

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

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

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

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

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

7. Summary

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

       

1. Spring and Java

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

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

Also worth reading:

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

Webinars and presentations:

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

Time to upgrade:

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

2. Technical & Musings

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

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

Also worth reading:

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

3. Pick of the Week

And our sale is about to end:

>> All Access for 4 More Days

       

1. Overview

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

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

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

2. Maven Dependencies

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

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

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

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

3. Creating a Sample MCP Tool

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

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

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

The API response looks something similar to:

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

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

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

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

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

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

4. Unit Test

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

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

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

5. Creating an MCP Test Client

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

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

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

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

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

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

6. Verifying Tool Registration

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

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

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

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

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

7. Testing Tool Invocation

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

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

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

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

8. Conclusions

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

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