Spring Boot 3 And Java 17 Migration Guide

Henry Pham — Sat, 16 Dec 2023 14:20:09 +0000

Spring Boot 3.0 is a new major release that offers new features and improvements. However, it requires Java 17 as a minimum version and comes with numerous compatibility issues if you intend to upgrade.

I. Pros and Cons

You need to analyze the pros and cons of our migration. In my experience, there are some points you should review:

1.1. Pros

Java 17 Baseline

You’ll need to upgrade to JDK 17 before you can develop Spring Boot 3.0 applications. This means you can take advantage of the latest features and performance improvements that Java 17 offers.

GraalVM Native Image Support

GraalVM Native Images provide a new way to deploy and run Java applications. It provides various advantages, like an instant startup and reduced memory consumption (pain points of Spring Boot apps).

Improved observability with Micrometer and Micrometer Tracing

You can check more details here.

1.2. Cons

Time/Resouces constraints

Migrating to a new major release takes time and resources, especially for testing. This migration affects all your flows so needs to be tested carefully. While you can update your code within a few days, please plan for testing to span more than a week (the duration depends on the size of your project).

Risk of new bugs

As mentioned earlier, the migration affects all your flows. Therefore, if your test coverage doesn't cover all your code, please be careful. Test your end-to-end flows and scrutinize the logs for any new exceptions or discrepancies compared to the previous state.

II. Before we start

If you’re currently running with an earlier version of Spring Boot, I recommend that you upgrade to Spring Boot 2.7 before migrating to Spring Boot 3.0. It minimizes compatibility issues as much as possible.

Review Dependencies

You can review your dependencies and dependency management for 3.x to assess how your project is affected.

For dependencies that are not managed by Spring Boot, you can identify the compatible version before upgrading.

Review Deprecations

Classes, methods and properties that were deprecated in Spring Boot 2.x have been removed in this release. Before upgrading, please ensure that you are not calling any deprecated methods.

III. Migrate to Spring Boot 3 and Java 17

3.1. Spring Boot Template Project

I will use my project as an example for you guys to share how I migrated from Spring Boot 2.7 (Java 11) to Spring Boot 3 and Java 17.

Github: https://github.com/hieubz/spring-boot-template-project
Original post: https://phamduyhieu.com/spring-boot-3-and-java-17-migration-guide

This project includes the implementation of common backend features, designed to assist both myself and other Spring Boot developers in coding more efficiently. For further details, you can read more here.

If you find my project useful, please give it a star ⭐️!

3.2. Migration Steps

3.2.1. Configuration Properties Migration

Let's add the migrator by adding the following to your Maven pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-properties-migrator</artifactId>
    <scope>runtime</scope>
</dependency>

This will analyze your application’s environment and print diagnostics at startup console logs. Then you can based on that update your properties accordingly.

3.2.2. Update Dependencies

We start with the parent pom spring-boot-starter-parent and Java version

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.1.5</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <properties>
        <java.version>17</java.version>
    </properties>

Tips: We shouldn't specify the version of Spring Data JPA, Spring Web, Spring Data Redis,... because their compatible versions are already declared in the parent POM.

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

If you are working with MySQL, let's replace your mysql-connector-java by:

        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <version>8.1.0</version>
        </dependency>

If you are using logback for logging, let's update it to v1.4.11

        <dependency>
            <groupId>ch.qos.logback</groupId>
            <artifactId>logback-classic</artifactId>
            <version>1.4.11</version>
        </dependency>

If you are using Openfeign for integrations, let's update it to v4.x

        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-openfeign</artifactId>
            <version>4.0.4</version>
        </dependency>

If you are using Spring JDBC, let's update it to v6.x

        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-jdbc</artifactId>
            <version>6.0.12</version>
        </dependency>

If you are using Jackson for data binding, let's update it to v2.15.x

        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.15.3</version>
        </dependency>

        <!--  support Java 8 Date/time Serialize/Deserialize  -->
        <dependency>
            <groupId>com.fasterxml.jackson.datatype</groupId>
            <artifactId>jackson-datatype-jsr310</artifactId>
            <version>2.15.3</version>
        </dependency>

If you are using Redisson as a Redis client, let's update it to v3.24.x

        <dependency>
            <groupId>org.redisson</groupId>
            <artifactId>redisson-spring-boot-starter</artifactId>
            <version>3.24.3</version>
        </dependency>
        <dependency>
            <groupId>org.redisson</groupId>
            <artifactId>redisson-spring-data-31</artifactId>
            <version>3.24.3</version>
        </dependency>

You should use the default spring-boot-starter-test for unit testing. However, If you are customizing mockito-core, let's update it to v5.3.x

        <dependency>
            <groupId>org.mockito</groupId>
            <artifactId>mockito-core</artifactId>
            <version>5.3.1</version>
            <scope>test</scope>
        </dependency>

If you are using jjwt for authentication, let's update it to 0.12.x

        <dependency>
            <groupId>io.jsonwebtoken</groupId>
            <artifactId>jjwt</artifactId>
            <version>0.12.3</version>
        </dependency>

If you are using Springdoc for API documentation, let's replace your springdoc-openapi-ui by:

        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.2.0</version>
        </dependency>

If you are using spring-kafka as your Kafka client, let's update it to v3.0.x

        <dependency>
            <groupId>org.springframework.kafka</groupId>
            <artifactId>spring-kafka</artifactId>
            <version>3.0.10</version>
        </dependency>

3.2.3. Rebuild and change the code

After updating your dependencies, let's rebuild your code first and check for any issues

  mvn clean package

Spring Boot 3.0 has migrated from Java EE to Jakarta EE APIs for all dependencies. So you should face the javax issue in your first build:

Then you just need to replace all javax in your imports by jakarta (should use Ctrl+Shift+R to replace on IntelliJ)

If the Spring migrator is working, you can see a WARNING log in the startup console:

Simply update as suggested.

In Hibernate 6, you can use MySQLDialect for all MySQL versions (MySQL5Dialect, MySQL8Dialect have been deprecated)

spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQLDialect

JPA SpringPhysicalNamingStrategy is replaced by CamelCaseToUnderscoresNamingStrategy

org.springframework.boot.orm.jpa.hibernate.SpringPhysicalNamingStrategy

==> org.hibernate.boot.model.naming.CamelCaseToUnderscoresNamingStrategy

Spring Security is not working if you are using WebSecurityConfigurerAdapter (deprecated). Besides, in v3.x, you have to use lambda to configure filterChain.

So you have to remove the extension of WebSecurityConfigurerAdapter class.

// Now
@Configuration
@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class WebSecurityConfig extends WebSecurityConfigurerAdapter {}

// Then without extension
@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class WebSecurityConfig {}

Then do several updates for AuthenticationManager bean creation:

// Now with the class extends WebSecurityConfigurerAdapter
  @Bean
  @Override
  public AuthenticationManager authenticationManagerBean() throws Exception {
    // Get AuthenticationManager bean
    return super.authenticationManagerBean();
  }

// Then without extension
  @Bean
  public AuthenticationManager authenticationManager(AuthenticationConfiguration authConfig) throws Exception {
    return authConfig.getAuthenticationManager();
  }

And SecurityFilterChain:

/** We have to use Lambda for SecurityFilterChain configuration **/

// Now with the class extends WebSecurityConfigurerAdapter
  @Override
  protected void configure(HttpSecurity http) throws Exception {
      http.cors().and().csrf().disable();
      http.authorizeRequests().antMatchers(AUTH_WHITELIST).permitAll().anyRequest().authenticated();
      http.sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS);
      http.exceptionHandling().authenticationEntryPoint(authEntryPointJwt);
      http.addFilterBefore(jwtAuthenticationFilter(), UsernamePasswordAuthenticationFilter.class);
  }

// Then with lambda
  @Bean
  protected SecurityFilterChain configure(HttpSecurity http) throws Exception {
      http.cors(AbstractHttpConfigurer::disable).csrf(AbstractHttpConfigurer::disable);
      http.authorizeHttpRequests(auth -> auth.requestMatchers(AUTH_WHITELIST).permitAll().anyRequest().authenticated());
      http.sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS));
      http.exceptionHandling(ex -> ex.authenticationEntryPoint(authEntryPointJwt));
      http.addFilterBefore(jwtAuthenticationFilter(), UsernamePasswordAuthenticationFilter.class);
      return http.build();
  }

Powermock is not working with Spring Boot 3 and JDK 17. Its latest update is in Feb 2022. So you need to move to Mockito if you are using Powermock.
The jjwt library updates its API, so we update our code:

// Now
  public String generateJwtToken(Long userId) {
    return Jwts.builder()
        .setSubject(userId.toString())
        .setIssuedAt(new Date())
        .setExpiration(new Date(new Date().getTime() + jwtExpirationMs))
        .signWith(SignatureAlgorithm.HS256, jwtSecret.getBytes(StandardCharsets.UTF_8))
        .compact();
  }


// Then
  public String generateJwtToken(Long userId) {
    return Jwts.builder()
        .subject(userId.toString())
        .issuedAt(new Date())
        .expiration(new Date(new Date().getTime() + jwtExpirationMs))
        .signWith(Keys.hmacShaKeyFor(jwtSecret.getBytes(StandardCharsets.UTF_8)), Jwts.SIG.HS256)
        .compact();
  }

And the JWT parser:

// Now
public Claims getJwtTokenClaim(String jwt) {
   return Jwts.parser()
        .setSigningKey(jwtSecret.getBytes(StandardCharsets.UTF_8))
        .parseClaimsJws(jwt)
        .getBody();
}

// Then
public Claims getJwtTokenClaim(String jwt) {
    return Jwts.parser()
        .verifyWith(Keys.hmacShaKeyFor(jwtSecret.getBytes(StandardCharsets.UTF_8)))
        .build()
        .parseSignedClaims(jwt)
        .getPayload();
}

Finally, rebuild and check for any issues. In my project, there are no issues left, so I stopped updating the code here.

3.2.4. Testing

Since this is a major upgrade, carefully test all APIs for discrepancies or exceptions. Review them one by one and monitor logs.

IV. Conclusion

We just completed the migration to Spring Boot 3 and JDK 17. There are many issues during this process, so stay calm and get things done :))). I hope this is helpful for anyone planning the migration.

Anw, If you find this project useful, please give it a star ⭐️!
Henry Pham.

Spring Boot Template Project Introduction

Henry Pham — Wed, 13 Dec 2023 16:04:09 +0000

Whenever I need to implement a new feature, I typically start by researching available solutions on Google. Then I will experiment with one or more solutions to select the best one.

However, after several months, I might forget how to implement that feature. Consequently, I end up having to revisit internet resources, conduct research once again, and reattempt the implementation.

The above situation is very common, not just for me but also among my friends and colleagues. We waste a lot of time recalling and researching solutions - things could be synthesized in a template project for the next implementation.

So I have developed this project which includes implementations designed to assist both myself and other Spring Boot developers in seamlessly diving into coding. Each commit within the project represents the implementation of a specific technique.

Github: Spring Boot Template Project

Tech stack: Java 17, Spring Boot 3.1.5

Whenever I need to implement a feature in my list, I simply search by relevant keywords associated with that feature (e.g., Redis, retry, email,...) to find the corresponding commit. By doing so, I can apply the code of that commit for my feature, with no need to Google or remember boilerplate code.

Features

We have basic features as below:

or advanced things:

There are also modules related to Unit Tests and monitoring:

Conclusion

I hope this project helps Spring Boot developers increase their productivity, allowing them to allocate more time to other important activities.

If you find this project useful, please give it a star ⭐️!

Forem: Henry Pham