You are here
Home > java >

Spring Boot 3 Migration- Migrate Spring Boot 2 To Spring Boot 3

Spring Boot 3 Migration: How To Migrate Spring Boot 2 To Spring Boot 3?After going through the major highlights of ‘New Features in Spring Boot 3.0, it’s time to check the process of Spring Boot 3 Migration (‘How To Migrate Spring Boot 2 To Spring Boot 3’). Here in this article we will be talking about the step by step migration process to Spring Boot 3. Before getting into to the spring boot 3 migration process, you should go through any documentation to understand the important artifacts in the same. It always helps in minimizing any potential risk factor in the process. Let’s start discussing ‘How To Migrate Spring Boot 2 To Spring Boot 3’.

Spring Boot 3 Migration: How To Migrate Spring Boot 2 To Spring Boot 3?

Let’s go through step by step spring boot 3 migration guide and migrate your project to Spring Boot 3.0 from Spring Boot 2.0.

Step#1: Install JDK 17 in your System

If you are still using JDK versions lower than JDK 17, the Spring Boot 3.0 will no longer support it and migration will not be successful. Hence, now it’s  mandatory to get JDK 17 installed on your system if not done already. Spring Boot 3.0 requires JDK 17 as a minimum JDK to work with it. You may visit the FAQ section of this article at very below to know ‘How to migrate to JDK 17 from the lower versions of JDK.

Step#2: Upgrade your project to latest available Spring Boot 2.7.x version 

It is recommended that first upgrade to the latest available 2.7.x version. It is always a good migration strategy to upgrade step by step, otherwise you may require to change a lot of configurations because of multiple new features and API changes and it may also make the migration too complicated. This approach will also make sure that you are building against the most recent dependencies of that line.

Step#3: Review Existing Dependencies

Since Spring Boot 3.0 has upgraded a multiple number of dependencies, review of dependencies becomes important. Spring Boot official migration guidelines provide the list of dependencies for both 2.7.x and 3.0.x versions. In order to access how your project can be affected due to dependencies, you can review dependency management for 2.7.x with dependency management for 3.0.x.

Apart from that, you may also be using some external dependencies (not managed by Spring Boot) such as Spring Cloud dependencies for microservices based applications and many others as well. In this case, you need to identify the compatible version from the list before upgrading as your project may be using a specific version for those.

Review Specific to Spring Security Dependency

Spring Boot 3.0 uses Spring Security 6.0. The Spring Security team has released Spring Security 5.8 to simplify upgrading to Spring Security 6.0. Hence, it is recommended to upgrade your Spring Boot 2.7 application to Spring Security 5.8. The Spring Security team has prepared a Spring Boot Security migration guide that will help you to do so. In addition to this, we have an example of Spring Security UserDetailsService Using Spring Boot 3.0, which can be utilized as a step by step migration guide.

Step#4: Review Deprecations from Spring Boot 2.x

Some of the classes, methods, properties and annotations that were deprecated in Spring Boot 2.x have been removed in this release. For example, WebSecurityConfigurerAdapter class, @EnableGlobalWebSecurity annotation has been removed. Methods authorizeRequests() and antMatchers() are also changed to authorizeHttpRequests() and requestMatchers() respectively. However, this step is just to make a note of artifacts that you need to upgrade. These changes will be done in Step#6.

Step#5: Upgrade to Spring Boot 3

Now it’s time to do the actual upgrade in Spring Boot 3.0. It is always recommended to upgrade to the latest available maintenance release of Spring Boot 3.0. As we are doing this exercise just after the release of Spring Boot 3.0, we will use Spring Boot 3.0.0 for the upgrade. Open your project’s pom.xml and update the version of Spring Boot as below.

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

Once updated, save the pom.xml and let the maven download the new dependencies. In this stage the maven tool will do the maximum job for you by upgrading all the required dependencies that are compatible with Spring Boot 3.0.0.

Step#6: Fix Compilation Errors and Deprecated elements

Once upgrade to Spring Boot 3.0.0 completes, you will see the actual effect of artifacts that you collected in Step#4. You have to fix compilation errors and deprecated elements based on the data that you have collected in Step#4. You may also not see any compilation error or deprecated warnings at all. It totally depends on the modules of Spring that are used in your project. Simply put, if your project uses such a module of Spring where there are no API changes, then there will be a minimum possibility to see any compilation errors or deprecated warnings.

Step#7: Configuration Properties Migration

A few configuration properties were also renamed/removed in Spring Boot 3.0. Hence, we need to update our ‘application.properties’ or ‘application.yml’ accordingly. Spring Boot provides a ‘spring-boot-properties-migrator’ module in order to help us in migrating it. Once we added this module as a dependency to our project, this will temporarily migrate properties at runtime for us. Apart from that, it will also analyze our application’s environment and print diagnostics at startup.

We can add the ‘spring-boot-properties-migrator’ by adding the following dependency to our ‘pom.xml’:

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

In case if you use Gradle, below is the dependency needs to be added:

runtime("org.springframework.boot:spring-boot-properties-migrator")

Note: Once you have completed your migration, please remove this dependency from the ‘pom.xml’.

Step#8: Update packages starting from ‘javax’ to ‘jakarta’

As Java EE has been changed to Jakarta EE, Spring Boot 3.0 has also upgraded from Java EE to Jakarta EE APIs for all dependencies. Wherever possible, Jakarta EE 10 compatible dependencies have been opted. Hence, the package names starting with ‘javax’ need to be changed to ‘jakarta’ accordingly. For example, some of the commonly used packages will be changed as shown below:

javax.persistence.*   -> jakarta.persistence.*

javax.validation.*    -> jakarta.validation.*

javax.servlet.*       -> jakarta.servlet.*

javax.annotation.*    -> jakarta.annotation.*

javax.transaction.*   -> jakarta.transaction.*

Note: Please note that packages such as javax.sql.* and javax.crypto.* will not change to ‘jakarta.*’ as they are part of Java 17 JDK, not of Java EE. Only those packages which are part of Java EE will change to Jakarta EE.

Instead of utilizing Spring Boot’s starter dependencies, if you are using your own dependencies, you should ensure that you have completed these upgrades accordingly. Basically, you have to replace your dependencies from Java EE to Jakarta accordingly, as Jakarta EE now uses ‘jakarta’ packages rather than ‘javax’. Once you have updated your dependencies you may find compilation warnings on import statements in your project that need to be updated accordingly.

Step#9: Verify upgrades on Core Changes if any

Several changes have been made to the core of Spring Boot that will be appropriate to most applications.

Image Banner Support Removed

1) Support for image-based application banners has been removed. banner.gif, banner.jpg, and banner.png files are now ignored and should be replaced with a text-based banner.txt file.

Logging Date Format Changed

2) The default format for the date and time component of log messages for Logback and Log4j2 has changed. The new format is now align with the ISO-8601 standard. The new default format will be ‘yyyy-MM-dd’T’HH:mm:ss.SSSXXX’. It uses a ‘T’ character as a separator between the date and time rather than a space character. Additionally, it also adds the timezone offset to the end.

If you want to restore the previous default value of ‘yyyy-MM-dd HH:mm:ss.SSS’, you can use the LOG_DATEFORMAT_PATTERN environment variable or ‘logging.pattern.dateformat’ property.

@ConstructingBinding No Longer Needed at the Type Level

3) @ConstructorBinding annotation is not required at the type level on @ConfigurationProperties annotated classes and it should be removed. However, if a class or record has multiple constructors, it may still be used on a constructor to represent which one should be used for property binding.

YamlJsonParser Has Been Removed

4) Since SnakeYAML’s JSON parsing was inconsistent with the other parser implementations, YamlJsonParser has been removed. If you were using YamlJsonParser directly, you are supposed to migrate to one of the other JsonParser implementations.

Auto-configuration Files 

5) Spring Boot 2.7 introduced a new ‘META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports’ file for registering auto-configurations, while maintaining backwards compatibility with registration in ‘spring.factories’. With Spring Boot 3.0 release, support for registering auto-configurations in ‘spring.factories’ has been removed in favor of the imports file.

Step#10: Review Upgrades on Web Applications

Most Importantly, If you are upgrading a web application, you need to verify the following section.

1) Spring MVC and WebFlux URL Matching Changes

Let’s consider the below Controller of Spring MVC:

@RestController
public class EmployeeController {

  @GetMapping("/emp/register")
  public String showRegisterPage {
    return "register";
  }
}

As of Spring Framework 6.0, the trailing slash matching configuration option has been deprecated. This means that previously the above controller would match both “/emp/register” and “/emp/register/”. After this Spring Framework upgrade, now onward “/emp/register/” doesn’t match anymore with “/emp/register” by default and will result in an HTTP 404 error. Hence, don’t insert trailing slash while matching the URLs.

Until your application fully adapts to this new change, you can change the default with the following global configuration:

@Configuration
public class WebConfiguration implements WebMvcConfigurer {

    @Override
    public void configurePathMatch(PathMatchConfigurer configurer) {
      configurer.setUseTrailingSlashMatch(true);
    }
}

2) If you are using Jetty 

Jetty does not yet support Servlet 6.0. Hence, in order to use Jetty with Spring Boot 3.0, you will have to downgrade the Servlet API to 5.0. You can use the jakarta-servlet.version property to do so.

Here in this article, we have covered most of the upgrades and how to do it. Obviously, there are many more to come. We will update the article time to time accordingly.

FAQ

How to migrate JDK from JDK 8 to JDK 17?

There is no need to remove JDK 8 before installing JDK 17 in your system. You can have multiple versions of JDK in your system according to your requirement.

You need to download the zip file by clicking the JDK 17 download link according to your operating system. However, you can visit the oracle site and search for the latest build of JDK 17 to get it installed. Then, you need to unzip the zip file and paste the ‘jdk-17’ folder in the directory where other JDK versions exist. However, in my case, it is ‘C:\Program Files\Java’ which is the native place of JDK installation.

If you are using Eclipse/STS as an IDE to build your project, you can visit a separate article on ‘How to add JDK 17 support in your Eclipse‘,

3 thoughts on “Spring Boot 3 Migration- Migrate Spring Boot 2 To Spring Boot 3

Leave a Reply


Top