Migration

Spring Boot 2.0 is a major release; it will require care when migrating from Spring Boot 1.x, as a lot has changed. Migration is unavoidable, as existing applications require the use of new features and enhancements available in the latest Spring Boot 2.0 release. The official migration guide can be read at https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-2.0-Migration-Guide and in this section, the most notable migration tips will be discussed.

Using the correct JDK and JVM

Spring Boot 2.0 doesn't support Java 6 or Java 7, which are still widely used in many production environments. So the first thing that needs to be done is to upgrade both development environments and runtime environments to at least Java 8 or above.

Running on Java 9

Since Java 9 was a major release and has one of the most complex enhancement modifications made to Java since its inception (the modular system), special care needs to be taken when running the Spring Boot 2.0 application on it. The following tips will help you get started.

Tackling JAXBException

The following exception can be expected as soon as a Spring Boot 2.0 application is run on Java 9:

java.lang.NoClassDefFoundError: javax/xml/bind/JAXBException

This is because Hibernate requires JAXB, which is not shipped by default in Java 9. The following dependency needs to be added in pom.xml to include it:

<dependency>
    <groupId>javax.xml.bind</groupId>
    <artifactId>jaxb-api</artifactId>
    <version>2.3.0</version>
</dependency>

Instead, you can add the java.xml.bind module to Java 9 directly to get rid of this exception.

Using the correct AspectJ version

Java 9 requires AspectJ version 1.9 (currently in Release Candidate version) if JDK weaving of classes is required. Spring Boot 2.0, however, can work with the lower version 1.8 that is shipped by default.

Being aware of limitations on Apache Cassandra drivers

Apache Cassandra drivers that run on Spring Boot 2.0 are not fully supported by Java 9 at the time of writing this book, so if a Spring Boot 2.0 application uses these then it must be properly tested. The issue can be followed at https://github.com/spring-projects/spring-boot/issues/10453 for more updates.

Being aware of issues with the Maven Surefire Plugin

Maven Surefire Plugin version 2.20.1 has re-introduced a bug that was fixed on other Java versions and only raised when running tests on Java 9. In order to fix this, the Maven Surefire Plugin has to be downgraded to 2.20.0 or the java.se.ee module needs to be excluded from the runtime while running tests.

Using the upgraded Spring Framework 5.0

Spring Boot 2.0 by default uses and supports Spring Framework 5.0. Thus, any change to it will affect migration to Spring Boot 2.0. Some notable changes are explained in the following topics.

Modified CORS support behavior

The @CrossOrigin annotations property allowCredentials now has the default value false. This means that it needs to be explicitly set if cookies or authentication are required.

Removed packages, classes, and methods

The following packages, classes, and methods are no longer supported in the Spring Framework 5.0 release:

• The beans.factory.access package, including the class SpringBeanAutowiringInterceptor.
• The jdbc.support.nativejdbc package, which is replaced by JDBC 4 implementation.
• The mock.staticmock package, with which AnnotationDrivenStaticEntityMockingControl is no longer supported.
• The web.views.tiles2 package, with the minimum version requirement for tiles being version 3.
• The orm.hibernate3/hibernate4 packages, with the minimum version requirement for Hibernate being version 5.
• Most of the deprecated classes in the previous version have been removed.
• Some methods in JSP Standard Tag Library (JSTL) have been removed. For example, FormTag commandName is no longer available.

Dropped support for frameworks

Spring Framework 5.0 no longer supports the following frameworks:

• Google Guava
• Velocity
• XMLBeans
• JDO
• Portlet
• JasperReports

Using the updated configuration properties

A lot of configuration properties have been renamed/replaced from Spring Boot 1.x to Spring Boot 2.0. So these changes must be incorporated in the application.yml/application.properties file to do a successful migration. To ease this process, Spring Boot has released the spring-boot-properties-migrator properties migrator, which can be used in the Maven configuration as follows:

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

When this dependency is used, it will analyze the application environment, print out any diagnostics at startup, and even temporarily migrate properties at runtime.

This dependency is only required during migration and could/should be removed when the migration is complete.

Using the changed servlet-specific server properties

With the introduction of Reactive Web Programming out of the box in Spring Boot 2.0, there needs to be a differentiation between properties for a servlet stack and properties for a reactive stack, so that previous properties such as server.*, which was related to the server ServletContext path, is not changed to server.servlet.* , avoiding verbosity in property naming.

Using the modified template engine extension handling

In Spring Boot 2.0 the file extension for the mustache template engine has been changed from .html to .mustache. With the spring.mustache.suffix configuration property this behavior can be overridden if required.

Using the changed actuator configuration properties

The following changes have been introduced in the Spring Boot Actuator configuration properties in Spring Boot 2.0:

• endpoints.* properties have been moved under management.*
• management.* properties have been moved under management.server.*
• endpoints.<id>.* properties have been moved under management.endpoint.<id>.*
• Shutdown endpoint must be explicitly enabled by setting the management.endpoint.shutdown.enabled configuration property to true

These changes have the potential to break existing code, and so must be changed accordingly when migrating.

Using the changed actuator base path

Now, the /actuator path contains all Spring Boot Actuator-related endpoints. In order to get the previous version's behavior, the management.endpoints.web.base-path=/ configuration property needs to be set. Another change is the addition of a new purpose for management.server.servlet.context-path, which is the counterpart of server.servlet.context-path related to Spring Boot Actuator endpoints.

As an example, if management.server.servlet.context-path=/actuator is set, along with management.endpoints.web.base-path=/application, then the endpoints will be accessible under the /actuator/application/<endpoint> path.

Using the renamed actuator endpoints

The following Spring Boot Actuator endpoints have been changed:

• /autoconfig has been renamed to /conditions
• /trace has been renamed to /httptrace

Applications depending on these endpoints need to be changed to use the renamed endpoints.

Using the changed Embedded Container Configuration

EmbeddedServletContainer is changed to WebServer. Also, the org.springframework.boot.context.embedded package is refactored to org.springframework.boot.web.embedded. If TomcatEmbeddedServletContainerFactory was used to configure an embedded Tomcat with a custom port in an application as in the following, then it will need to be changed:

@Bean
public EmbeddedServletContainerFactory servletContainer() {
 TomcatEmbeddedServletContainerFactory tomcat = new TomcatEmbeddedServletContainerFactory();
 Connector connector = new Connector("org.apache.coyote.http11.Http11NioProtocol");
 connector.setScheme("http");
 connector.setPort(9090); 
 tomcat.addAdditionalTomcatConnectors(connector);
 return tomcat;
}

It must be changed to use TomcatServletWebServerFactory instead, as in the following:

@Bean
public TomcatServletWebServerFactory webServer() {
    TomcatServletWebServerFactory tomcat = new 
    TomcatServletWebServerFactory(9090);
    return tomcat;
}

Using the changed default behavior for path mapping

The default behavior of map extensions such as .json and .xml to existing controller request mappings has changed in Spring Boot 2.0. Consider the following URL mapping:

@GetMapping("/users")

If it is expected to cater to the /users.json URL in a Spring Boot 1.x application, then it won't be supported in Spring Boot 2.0. This means new mappings need to be added as necessary.

Using the changed default dispatcher types for the servlet filter

The default dispatcher type for the servlet filter in Spring Boot 2.0 is DispatcherType.REQUEST. This is changed to be in line with the default in the servlet specification. If other dispatcher types are required then a FilterRegistrationBean must be used to register the filter.

Using the modified transitive dependency to spring-boot-web-starter

Spring Boot 1.x had the transitive dependency spring-boot-starter-web whenever one of the following template engine starters was used:

• spring-boot-starter-freemarker
• spring-boot-starter-thymeleaf
• spring-boot-starter-mustache

This was done because Spring Web MVC was running on top of the Servlet API, which is the only web application framework that was available at that time.

Now, with the introduction of the Spring Reactive Web starter spring-boot-starter-webflux, which is completely independent of the Servlet API, transitive dependencies from those template engine starters have been removed. This means that, when a template engine starter dependency is added, a developer needs to manually add a dependency to either Spring Web MVC starter or Spring Web Flux starter based on the requirement.

Using the changed default proxying strategy

Spring Boot 2.0 uses CGLIB as the default proxying strategy including for aspect-oriented programming (AOP). If proxy based proxying is required, the following configuration property needs to be set:

spring.aop.proxy-target-class=false.

Using the modified configuration location strategy

With Spring Boot 2.0, the spring.config.location configuration will no longer append to the list of configurations; instead, it will replace it. So, if append logic is required, then spring.config.additional-location must be used.

Using the changed Jackson/JSON support

With Spring Boot 2.0, Jackson's configuration was modified to write JSR-310 dates as ISO-8601 strings. For its previous behavior, the property spring.jackson.serialization.write-dates-as-timestamps=true needs to be set.

Using the changed Spring Boot Actuator security

The separate security auto-configuration for actuators has been removed in Spring Boot 2.0; thus, management.security.* properties are no longer supported. The endpoints.<id>.sensitive flag for each endpoint is no longer available, and if an application is dependent on this behavior then it must use a custom configuration for Spring Security to permit or restrict access to those endpoints.

Using the changed HikariCP default connection pool for JPA

With Spring Boot 2.0, the default connection pool for JPA has been changed from Tomcat to HikariCP. Thus it is no longer required to use the configuration property spring.datasource.type as an override to use HikariCP. Using the following dependency will by default use HikariCP:

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

Using the changed default database initialization strategy

With Spring Boot 2.0, the default basic DataSource initialization is only enabled for embedded databases and will be disabled as soon as a production database is used. The configuration property spring.datasource.initialization-mode (with values always or never), which replaces the old spring.datasource.initialize configuration property, can be used for more control.

Using the changed database schema creation strategy

The default behavior for embedded databases used with a schema manager such as Liquibase, Flyway, and so on will be dropping existing tables and creating a new one, which is similar to create-drop for the configuration property spring.jpa.hibernate.ddl-auto .If no schema manager is used then the default behavior is to do nothing, which is similar to setting none for the aforementioned configuration property.

Using the changed testing support

The following test annotations are no longer supported for Mockito 1.x:

• @MockBean
• @SpyBean

If testing needs to be done using the aforementioned annotations then Spring Boot 2.0 spring-boot-starter-test must be used or Mockito 2.x must be used explicitly.

Using the revised Spring Security

There are some Spring Security-related changes made for Spring Boot 2.0's release, which need to be incorporated when migrating. Some of the most notable ones are explained in the following sections.

Using the changed default security auto-configuration strategy

Spring Security has changed its auto-configuration strategy to make use of defaults in most cases instead of enabling multiple configuration options. Notable cases are when Spring Security authorization with content negotiation is used.

Spring Security OAuth2 is migrated to Spring Security core

The OAuth2 project is now part of the Spring Security core project and released out of the box. Thus dependencies for OAuth2 will not be maintained separately as of Spring Security 5.0. If a Spring Boot application makes use of a non-migrated feature then dependencies for those need to be added explicitly.

Using the AuthenticationManager bean

Exposing a custom AuthenticationManager bean can now be done with an overriding WebSecurityConfigurerAdapter.authenticationManagerBean method annotated with a @Bean annotation.

Understanding removed features

Some features that were available in Spring Boot 1.x but are no longer supported in Spring Boot 2.0 are as follows:

• Disabled CRaSH support—Spring Boot 1.x had an integrated Java shell that was used to SSH and Telnet in a Spring Boot application. This is no longer available and the spring-boot-starter-remote-shell dependency can no longer provide support in monitoring and manage Spring Boot applications.
• Removed auto-configuration support for Spring Mobile.
• Removed auto-configuration support for Spring Social.
• Removed dependency management support for commons-digester.