Upgrading to Spring Framework 5.x

Juergen Hoeller edited this page Sep 21, 2018 · 16 revisions

This page provides guidance on upgrading to Spring Framework 5.0 and 5.1. See also the Spring-Framework-5-FAQ and What's New in Spring Framework 5.x.

Currently active branches: Spring Framework 4.3.19+ and Spring Framework 5.1, with Spring Framework 5.0.x phased out in favor of 5.1 by early 2019. Please upgrade to the latest 5.1.x or 4.3.x release at your earliest convenience!

Upgrading to Version 5.1

JDK 11

Spring Framework 5.1 requires JDK 8 or higher and specifically supports JDK 11 (as the next long-term support release) for the first time. We strongly recommend an upgrade to Spring Framework 5.1 for any applications targeting JDK 11, delivering a warning-free experience on the classpath as well as the module path.

Please note that developing against JDK 11 is not officially supported with any older version of the core framework. Spring Framework 5.0.9+ and 4.3.19+ just support deploying Java 8 based applications to a JVM 11 runtime environment (using -target 1.8; see below), accepting JVM-level warnings on startup.


Spring Framework 5.1 uses a patched ASM 7.0 fork which is prepared for JDK 11/12 and their new bytecode levels but not battle-tested yet. Spring Framework 5.1.x will track further ASM revisions on the way to JDK 12, also hardening bytecode compatibility with JDK 11.

For a defensive upgrade strategy, consider compiling your application code with JDK 8 as a target (-target 1.8), simply deploying it to JDK 11. This makes your bytecode safer to parse not only for Spring's classpath scanning but also for other bytecode processing tools.


Spring Framework 5.1 uses a patched CGLIB 3.2 fork that delegates to JDK 9+ API for defining classes at runtime. Since this code path is only active when actually running on JDK 9 or higher (in particular necessary on JDK 11 where an alternative API for defining classes has been removed), side effects might show up when upgrading existing applications to JDK 11.

Spring has a fallback in place which tries to mitigate class definition issues, possibly leading to a JVM warning being logged, whereas the standard code path delivers a warning-free experience on JDK 11 for regular class definition purposes. Consider revisiting your class definitions and bytecode processing tools in such a scenario, upgrading them to JDK 11 policies.

Core Container

The core container has been fine-tuned for Graal compatibility (native images on Substrate VM) and generally optimized for less startup overhead and less garbage collection pressure. As part of this effort, several introspection algorithms have been streamlined towards avoiding unnecessary reflection steps, potentially causing side effects for annotations declared outside of well-defined places.

Nested Configuration Class Detection

As per their original definition, nested configuration classes are only detected on top-level @Configuration or other @Component-stereotyped classes now, not on plain usage of @Import or @ComponentScan. Older versions of Spring over-introspected nested classes on non-stereotyped classes, causing significant startup overhead in some scenarios.

In case of accidentally relying on nested class detection on plain classes, simply declare those containing classes with a configuration/component stereotype.

Web Applications

Forwarded Headers

"Forwarded" and "X-Forwarded-*" headers, which reflect the client's original address, are no longer checked individually in places where they apply, e.g. same origin CORS checks, MvcUriComponentsBuilder, etc.

Applications are expected to use one of:

  • Spring Framework's own ForwardedHeaderFilter.
  • Support for forwarded headers from the HTTP server or proxy.

Note that ForwardedHeaderFilter can be configured in a safe mode where it checks and discards such headers so they cannot impact the application.

Encoding Mode of DefaultUriBuilderFactory

The encoding mode of DefaultUriBuilderFactory has been switched to enforce stricter encoding of URI variables by default. This could impact any application using the WebClient with default settings, or any application using DefaultUriBuilderFactory directly. See the "Encoding URIs" section and also the Javadoc for DefaultUriBuilderFactory#setEncodingMode.

Content Negotiation for Error Responses

The produces condition of an @RequestMapping no longer impacts the content type of error responses.

Multipart and Query Values

The integration with Apache Commons FileUpload now aggregates multipart parameter values with other request parameters from the query, as required by Servlet spec, section 3.1. Previously it returned only multipart parameter values if present.


The built-in support for HTTP OPTIONS in @RequestMapping methods now consistently adds HTTP OPTIONS as one of the supported HTTP methods, whereas previously it did not.

Upgrading to Version 5.0

Baseline update

Spring Framework 5.0 requires JDK 8 (Java SE 8) or above, since its entire codebase is now based on Java 8 source code level, and provides full compatibility with JDK 9 on the classpath as well as the module path (Jigsaw).

The Java EE 7 API level is required in Spring's corresponding modules now, with runtime support for the EE 8 level:

  • Servlet 3.1 / 4.0
  • JPA 2.1 / 2.2
  • Bean Validation 1.1 / 2.0
  • JMS 2.0
  • JSON Binding API 1.0 (as an alternative to Jackson / Gson)

Web Servers

  • Tomcat 8.5+
  • Jetty 9.4+
  • WildFly 10+
  • WebSphere 9+
  • with the addition of Netty 4.1 and Undertow 1.4 for Spring WebFlux


  • Jackson 2.9+
  • EhCache 2.10+
  • Hibernate 5.0+
  • OkHttp 3.0+
  • XmlUnit 2.0+

Removed Packages, Classes and Methods

  • Package beans.factory.access (BeanFactoryLocator mechanism).
    • Including SpringBeanAutowiringInterceptor for EJB3 which was based on such a statically shared context. Preferably integrate a Spring backend via CDI instead.
  • Package jdbc.support.nativejdbc (NativeJdbcExtractor mechanism).
    • Superseded by the native Connection.unwrap mechanism in JDBC 4. There is generally very little need for unwrapping these days, even against the Oracle JDBC driver.
  • Package mock.staticmock removed from spring-aspects module.
    • No support for AnnotationDrivenStaticEntityMockingControl anymore.
  • Packages web.view.tiles2 and orm.hibernate3/hibernate4 dropped.
    • Minimum requirement: Tiles 3 and Hibernate 5 now.
  • Many deprecated classes and methods removed across the codebase.
    • A few compromises made for commonly used methods in the ecosystem.
  • Note that several deprecated methods have been removed from the JSP tag library as well.
    • e.g. FormTag's "commandName" attribute, superseded by "modelAttribute" years ago.

Dropped support

The Spring Framework no longer supports: Portlet, Velocity, JasperReports, XMLBeans, JDO, Guava (replaced by the Caffeine support). If those are critical to your project, you should stay on Spring Framework 4.3.x (supported until 2020). Alternatively, you may create custom adapter classes in your own project (possibly derived from Spring Framework 4.x).

Commons Logging setup

Spring Framework 5.0 comes with its own Commons Logging bridge in the form of the 'spring-jcl' module that 'spring-core' depends on. This replaces the former dependency on the 'commons-logging' artifact which required an exclude declaration for switching to 'jcl-over-slf4j' (SLF4J / Logback) and an extra bridge declaration for 'log4j-jcl' (Log4j 2.x).

Now, 'spring-jcl' itself is a very capable Commons Logging bridge with first-class support for Log4j 2, SLF4J and JUL (java.util.logging), working out of the box without any special excludes or bridge declarations for all three scenarios.

You may still exclude 'spring-jcl' from 'spring-core' and bring in 'jcl-over-slf4j' as your choice, in particular for upgrading an existing project. However, please note that 'spring-jcl' can easily supersede 'jcl-over-slf4j' by default for a streamlined Maven dependency setup, reacting to the plain presence of the Log4j 2.x / Logback core jars at runtime.

Please note: For a clean classpath arrangement (without several variants of Commons Logging on the classpath), you might have to declare explicit excludes for 'commons-logging' and/or 'jcl-over-slf4j' in other libraries that you're using.

CORS support

CORS support has been updated to be more secured by default and more flexible.

When upgrading, be aware that allowCredentials default value has been changed to false and now requires to be explicitly set to true if cookies or authentication are needed in CORS requests. This can be done at controller level via @CrossOrigin(allowCredentials="true") or configured globally via WebMvcConfigurer#addCorsMappings.

CORS configuration combination logic has also been slightly modified to differentiate user defined * values where additive logic should be used and default @CrossOrigin values which should be replaced by any user provided values.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.