1. Overview
In this article, we’re going to take a look at how we can migrate an existing Spring Framework application to a Spring Boot application.
Spring Boot is not intended to replace Spring, but to make working with it faster and easier. As a result, most of the changes needed for migrating an application are related to configuration. For the most part, our custom controllers and other components will remain the same.
Developing with Spring Boot brings several advantages:
- simpler dependency management
- default auto-configuration
- embedded web server
- application metrics and health checks
- advanced externalized configuration
2. Spring Boot Starters
First, we’ll need a new set of dependencies. Spring Boot provides convenient starter dependencies, which are dependency descriptors that can bring in all the necessary technology for certain functionality.
These have the advantage that you no longer need to specify a version for each dependency, but instead, let the starter manage dependencies for you.
The quickest way to get started is by adding the spring-boot-starter-parent pom.xml:
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.5.6.RELEASE</version>
</parent>
This will take care of dependency management.
We’ll go through some more starters in the next sections, depending on which functionality we will migrate. For reference, you can find the full list of starters here.
As a more general note, we will want to remove any explicitly defined dependency version which is also managed by Spring Boot. If not, we may encounter incompatibilities between our defined versions and those used by Boot.
3. Application Entry Point
Each application built using Spring Boot needs to define the main entry point. This is usually a Java class with the main method, annotated with @SpringBootApplication:
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
The @SpringBootApplication annotation adds the following annotations:
- @Configuration – which marks the class as a source of bean definitions
- @EnableAutoConfiguration – which tells the framework to add beans based on the dependencies on the classpath automatically
- @ComponentScan – which scans for other configurations and beans in the same package as the Application class or below
By default, the @SpringBootApplication annotation scans all classes in the same package or below. Therefore, a convenient package structure could look like this:
If your application is a non-web application which creates an ApplicationContext, this code can be removed and replaced with the @SpringBootApplication class above.
An issue we may encounter has multiple configuration classes which conflict. To avoid this, we have the possibility of filtering the classes which are scanned:
@SpringBootAppliaction
@ComponentScan(excludeFilters = {
@ComponentScan.Filter(type = FilterType.REGEX,
pattern = "com.baeldung.config.*")})
public class Application {
//...
}
4. Import Configuration and Components
Spring Boot relies heavily on annotations for configuration, but you can still import your existing configuration in both annotation and XML format.
For your existing @Configuration or component classes to be picked up, you have two options:
- move the existing classes to a package that is the same or below the main Application class package
- import the classes explicitly
To import the classes explicitly, you can use the @ComponentScan or @Import annotations on the main class:
@SpringBootApplication
@ComponentScan(basePackages="com.baeldung.config")
@Import(UserRepository.class)
public class Application {
//...
}
The official documentation recommends using annotations over XML configuration. However, if you already have XML files you do not wish to convert to Java configuration, you can still import these using @ImportResource:
@SpringBootApplication
@ImportResource("applicationContext.xml")
public class Application {
//...
}
5. Migrate Application Resources
By default, Spring Boot looks for resource files in one of the following locations:
- /resources
- /public
- /static
- /META-INF/resources
To migrate, we can move all our resource files to one of these locations, or we can customize the resource locations by setting the spring.resources.static-locations property:
spring.resources.static-locations=classpath:/images/,classpath:/jsp/
6. Migrate Application Properties
The framework will automatically load any properties defined in files called application.properties or application.yml placed in one of these locations:
- a /config subdirectory of the current directory
- the current directory
- a /config directory on the classpath
- the classpath root
To avoid loading properties explicitly, we can move them to a file with this name in one of these locations. For example, into the /resources folder which should be present on the classpath.
We can also automatically load profile-specific properties from files called application-{profile}.properties.
Also, a large number of predefined property names are available for configuring different application behaviors.
Each Spring framework module that you use in your application will require slight modifications, mainly relating to the configuration. Let’s take a look at some of the most commonly used functionalities.
7. Migrate a Spring Web Application
7.1. Web Starter
Spring Boot provides a starter for web applications that will bring in all the necessary dependencies. This means we can remove all the web-specific dependencies from the Spring framework and replace them with spring-boot-starter-web:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
Since Spring Boot attempts to auto-configure an application whenever possible based on the classpath, adding this dependency will result in having the @EnableWebMvc annotation added to the main Application class, as well as setting up a DispatcherServlet bean.
If you had a WebApplicationInitializer class that sets up a DispatcherServlet, this is no longer necessary, nor is the @EnableWebMvc annotation.
We can, of course, define our beans if we want a custom behavior, and in that case, our beans will be used.
If we explicitly use the @EnableWebMvc annotation on a @Configuration class, then the MVC auto-configuration will no longer be enabled.
Adding the web starter also determines the auto-configuration of the following beans:
- support for serving static content from a directory called /static, /public, /resources or /META-INF/resources on the classpath
- HttpMessageConverter beans for common use cases such as JSON and XML
- a /error mapping that handles all errors
7.2. View Technologies
As far as building web pages go, the official documentation recommends not using JSP files and using a template engine instead. Auto-configuration is included for the following template engines: Thymeleaf, Groovy, FreeMarker, Mustache. All we need to do to use one of them is add the specific starter:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
The template files should be placed in /resources/templates folder.
If we want to continue using JSP files, we need to configure the application so that it can resolve JSPs. For example, if our files are in /webapp/WEB-INF/views, then we need to set the following properties:
spring.mvc.view.prefix=/WEB-INF/views/
spring.mvc.view.suffix=.jsp
7.3. Embedded Web Server
Also, we can also run our application using an embedded Tomcat server, which will be auto-configured on port 8080 by adding the spring-boot-starter-tomcat dependency:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-tomcat</artifactId>
</dependency>
Other web servers for which Spring Boot provides auto-configuration are Jetty and Undertow.
8. Migrate a Spring Security Application
The starter for enabling Spring Security is spring-boot-starter-security:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
By default, this will create a user called “user” with a randomly generated password logged during startup and secure all endpoints with basic authentication. However, we usually want to add our security configuration, which is different than the default.
For this reason, we will keep our existing class annotated with @EnableWebSecurity which creates a SecurityFilterChain bean and defines a custom configuration:
@Configuration
@EnableWebSecurity
public class SecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
// ...
}
}
9. Migrate a Spring Data Application
Depending on which Spring Data implementation we are using, we will need to add the corresponding starter. For example, for JPA, we can add the spring-boot-starter-data-jpa dependency:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
If we want to use an in-memory database, adding the corresponding dependency enabled auto-configuration for databases of type H2, Derby, and HSQLDB.
For example, to work with an H2 in-memory database, all we need is the h2 dependency:
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
</dependency>
If we want to work with a different database type and configuration, such as a MySQL database, then we need the dependency as well as to define a configuration.
For this, we can either keep our DataSource bean definition or make use of pre-defined properties:
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
spring.datasource.url=jdbc:mysql://localhost:3306/myDb?createDatabaseIfNotExist=true
spring.datasource.username=user
spring.datasource.password=pass
Spring Boot will auto-configure Hibernate as the default JPA provider, as well as a transactionManager bean.
10. Conclusion
In this article, we have shown some common scenarios encountered when migrating an existing Spring application to the newer Spring Boot framework.
Overall, your experience when migrating will, of course, be highly dependent on the application you have built.