Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Upgrading to 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
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.
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
@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.
"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,
Applications are expected to use one of:
- Spring Framework's own
- Support for forwarded headers from the HTTP server or proxy.
ForwardedHeaderFilter can be configured in a safe mode where it checks and discards such headers so they cannot impact the application.
Encoding Mode of
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
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
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)
- 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).
SpringBeanAutowiringInterceptorfor 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.unwrapmechanism in JDBC 4. There is generally very little need for unwrapping these days, even against the Oracle JDBC driver.
- Superseded by the native
- No support for
- No support for
- 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.
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 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
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.