GitHub-Spring
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Updated Upgrading to Spring Framework 5.x (markdown)

master
Brian Clozel 1 year ago
parent
faed7c90c2
commit
59ad4023ba
1 changed files with 2 additions and 149 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 151
      Upgrading-to-Spring-Framework-5.x.md

151
Upgrading-to-Spring-Framework-5.x.md
Unescape

@ -5,158 +5,11 @@ Note that Spring Framework 4.3.x and therefore Spring Framework 4 overall reache @@ -5,158 +5,11 @@ Note that Spring Framework 4.3.x and therefore Spring Framework 4 overall reache
## Upgrading to Version 5.3
### Third-Party APIs and Libraries
For Kotlin:
* Kotlin support has been upgraded to Kotlin 1.4 and is still compatible with Kotlin 1.3+.
* Kotlin Coroutines 1.4 (which builds on Kotlin 1.4) or above is now required for coroutines support.
* For Kotlin scripting, Kotlin 1.4 users should declare the `kotlin-scripting-jsr223` dependency instead of `kotlin-scripting-jsr223-embeddable`.
Spring Framework 5.3 ships with a WildFly manifest that makes Objenesis work on JDK 9+. This is known to cause an incompatibility with WildFly 9; please upgrade to a more recent version of WildFly - or patch your copy of `spring-core.jar` to drop the `Dependencies` manifest entry.
Hibernate support has been upgraded to a Hibernate ORM 5.2+ baseline, with a focus on ORM 5.4.x. Please note that Hibernate Search needs to be upgraded to 5.11.6 for Spring Framework 5.3 JPA compatibility; see [Hibernate JIRA](https://hibernate.atlassian.net/browse/HSEARCH-4107).
Jackson support covers Jackson 2.9 to 2.12 now, generally with the latest releases in each branch.
Groovy 3.0 is the officially supported version now, with Groovy 2.x support getting phased out.
Support for RxJava 1.x is deprecated; RxJava 2.x is the new baseline and 3.x is now supported.
JCA CCI support is deprecated, in favor of specific data access APIs (or native CCI usage if there is no alternative).
Several remoting technologies have been deprecated with no direct replacement (Hessian, RMI, HTTP Invoker, JMS Invoker).
`MimeMessageHelper` has been aligned with JavaMail 1.5+, not explicitly encoding attachment filenames by default anymore.
### Core Container
The properties-based bean definition format and all support classes based on it (such as `PropertiesBeanDefinitionReader`, `JdbcBeanDefinitionReader` and `ResourceBundleViewResolver`) are deprecated now, in favor of Spring's common bean definition formats and/or custom reader implementations.
`InstantiationAwareBeanPostProcessorAdapter` is deprecated now, in favor of the existing default methods in `(Smart)InstantiationAwareBeanPostProcessor`.
`BeanNameAutoProxyCreator` now honors the configured `beanNames` list when applying a custom `TargetSourceCreator`. Consequently, a `BeanNameAutoProxyCreator` no longer proxies beans whose names do not match the configured `beanNames` list. See [gh-24915](https://github.com/spring-projects/spring-framework/issues/24915).
`@EventListener` methods use an implicit order value of `Ordered.LOWEST_PRECEDENCE` now, in alignment with transaction synchronizations and `@TransactionalEventListener` methods. If custom ordering is needed, please consistently declare `@Order` values on all listener methods.
Caching within the core container is consistently optimized for bean definitions with stable bean types per bean name, even for prototype beans. This is partially also the case for the 5.2.x line. Performance regressions might require some bean definition redesign; see e.g. [gh-26369](https://github.com/spring-projects/spring-framework/issues/26369).
### Data Access and Transactions
Several `JdbcTemplate` signatures with `Object[]` arguments are deprecated, in favor of their existing varargs equivalents.
`HibernateJpaVendorAdapter` exposes `Session(Factory)` as `EntityManager(Factory)` extension interface by default (following Hibernate ORM 5.2+).
`TransactionSynchronization` extends the `Ordered` interface by default now, as a replacement for the deprecated `TransactionSynchronizationAdapter`. As a consequence, `@Order` annotations on synchronization instances - which were not officially supported despite effectively working since 4.2 - do not work anymore. Synchronization objects are low-level callback objects, please express any attached order with a programmatic `getOrder` implementation.
Reactive transactions consistently roll back on a Reactive Streams cancel signal now, preventing partial commits for common datastore transactions.
### Web Applications
CORS configuration where `allowCredentials` is set to true now requires an explicit declaration of specific domains to allow via `allowedOrigins` or use of the newly added `allowedOriginPatterns`.
When using the `PathPatternParser` for request mapping, patterns with double-wildards in the middle of the pattern, such as `"/path/**/other"`, are now rejected. This parser is used by default in WebFlux applications and can be used as an opt-in for MVC applications as of Spring Framework 5.3. See [gh-24952](https://github.com/spring-projects/spring-framework/issues/24952).
The `ForwardedHeaderFilter` (Servlet) and `ForwardedHeaderTransformer` (WebFlux) have been enhanced and now support multiple values in `X-Forwarded-Prefix` and the new `X-Forwarded-For` / `Forwarded: for=` HTTP request headers. See [gh-25254](https://github.com/spring-projects/spring-framework/issues/25254) and [gh-23582](https://github.com/spring-projects/spring-framework/pull/23582).
`@ExceptionHandler` methods now check all exception causes when looking for a match. Previously, going back to 4.3 only the first cause was checked.
`@RequestParam`, `@RequestHeader`, and other controller method argument annotations that depend on type conversion from String values to other types such as `UUID`, `Long`, and others, now detect a `null` conversion result value and treat as missing. For example, a query parameter with an empty value is now treated as missing if it requires type conversion and the conversion results in `null`. In order to allow an empty value to be injected as a `null` argument, either set `required=false` on the argument annotation, e.g. `@RequestParam(required=false)`, or declare the argument as `@Nullable`.
`WebSocketConfigurationSupport` and `WebSocketMessageBrokerConfigurationSupport` have been refactored to not require CGLIB proxies, see [related commit](https://github.com/spring-projects/spring-framework/commit/017242463502f451c6c71a823b9c5232276dd78e).
### Spring MVC
`LocaleResolver`, `ThemeResolver`, `FlashMapManager` and `RequestToViewNameTranslator` beans are now declared at `WebMvcConfigurationSupport` and `DelegatingWebMvcConfiguration` level with `@Bean` annotations for improved consistency with other Spring MVC default beans and to improve GraalVM compatibility by reducing reflection done otherwise in `DispatcherServlet`. Spring Boot or XML application context based projects shouldn't be impacted, but non Spring Boot projects using JavaConfig overriding one of those default beans may require an update since the bean declaration should now happen in the configuration class annotated with `@EnableWebMvc` (still using their [well-known names](https://docs.spring.io/spring-framework/docs/5.3.x/javadoc-api/constant-values.html#org.springframework.web.servlet.DispatcherServlet.FLASH_MAP_MANAGER_BEAN_NAME)), for example for the `LocaleResolver`:
```
@Configuration
public class WebConfig extends DelegatingWebMvcConfiguration {
@Bean
@Override
public LocaleResolver localeResolver() {
return new FixedLocaleResolver(new Locale("fr", "FR"));
}
}
```
`@RequestParam` and `@RequestPart` enforce at least one element in a `MultipartFile` and Servlet `Part` collection/array when the argument is required (i.e. not explicitly marked as optional), consistent with individual `MultipartFile`/`Part` declarations, resolving the argument to `null` otherwise.
Spring MVC no longer performs `.*` suffix pattern matching by default, and likewise path extensions are no longer used by default to interpret the requested content type (e.g. `/person.pdf`, `/person.xml`, etc). Please, see the ["Suffix Match"](https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html#mvc-ann-requestmapping-suffix-pattern-match) section of the reference documentation.
In case of JSON serialization errors while writing to the HTTP response, the JSON `HttpMessageConverter` will still flush to the response and clean up resources. If you were previously relying on the response not being written to, note that this was not an intended behavior and that we can't guarantee error handling for this case. See [gh-26246](https://github.com/spring-projects/spring-framework/issues/26246) for an example of that.
A `java.security.Principal` argument is no longer resolved eagerly, if it is annotated in some way such as `@AuthenticationPrincipal`, thus allowing a custom resolver to resolve it first, before using default resolution resolution via `HttpServletRequest#getUserPrincipal`. This can cause issues for existing applications that are trying to inject the Spring Security `Authentication` but also have it annotated with `@AuthenticationPrincipal` which now results in the injection of `Authentication#getPrincipal` as per the intent for the annotation. Removing `@AuthenticationPrincipal` results in the injection of the top level `Authentication` object which is also a `Principal` and would be resolved via `HttpServletRequest#getUserPrincipal` after the change.
### Spring WebFlux
`@RequestPart` with `List<T>` now converts the 1st part to `List<T>` consistent with Spring MVC and with how it works for `T[]`. Previously each part was converted to `T`, see [gh-22973](https://github.com/spring-projects/spring-framework/issues/22973).
`@EnableWebFlux` now includes a declaration of a `WebSocketHandlerAdapter` bean. It should not interfere with any declared by the application due to a lower priority but if you have one, you can remove it.
WebClient now wraps emitted exceptions in either a `WebClientRequestException`, or a `WebClientResponseException`. `CodecExceptions` are not wrapped and still propagated. as before. See [gh-23842](https://github.com/spring-projects/spring-framework/issues/23842).
A `UriComponentsBuilder` argument injected into an `@Controller` method is now application relative (i.e. it includes the contextPath) where previously it contained no path at all.
`org.synchronoss.cloud:nio-multipart-parser` is no longer a required dependency for multipart support in WebFlux. Instead, there is now the `DefaultPartHttpMessageReader` with no dependencies, see [gh-21659](https://github.com/spring-projects/spring-framework/issues/21659)
### Testing
The _Spring TestContext Framework_ now provides first-class support for inheriting and overriding test-related annotations from enclosing classes. This improves the programming model for using JUnit Jupiter `@Nested` test classes with Spring's testing support. Note, however, that annotations from enclosing classes will now be inherited by default. This is a change in behavior that may cause some of your `@Nested` test classes to fail after upgrading to Spring Framework 5.3. To revert to the behavior present in Spring Framework 5.0 - 5.2.x, you can annotate top-level, enclosing classes for your `@Nested` test classes with `@NestedTestConfiguration(OVERRIDE)`. To switch to `OVERRIDE` mode for an entire project, you can configure `spring.test.enclosing.configuration=override` via a JVM system property or an entry in a `spring.properties` file in the root of the classpath (for example, in `src/test/resources/spring.properties`).
Consult the [Javadoc for `@NestedTestConfiguration`](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/test/context/NestedTestConfiguration.html) and the [reference manual](https://docs.spring.io/spring-framework/docs/current/reference/html/testing.html#testcontext-junit-jupiter-nested-test-configuration) for details.
Users of `MockMvc` Kotlin DSL could experience some breakages when using property syntax like `isOk`, `isOk()` should be used instead. There maybe be some other slight variations due to the improved Kotlin DSL, see [this commit](https://github.com/spring-projects/spring-framework/commit/d04c5f8b2cb274b8f44c47b3783e5d29f3e21b43) for more details.
[[See Spring Framework 5.3 Release Notes|Spring-Framework-5.3-Release-Notes]].
## Upgrading to Version 5.2
### Libraries
Spring Framework 5.2 now requires Jackson 2.9.7+ and explicitly supports the recently released Jackson 2.10 GA. See [gh-23522](https://github.com/spring-projects/spring-framework/issues/23522).
In Reactor Core 3.3, the Kotlin extensions are deprecated and replaced by a dedicated [reactor-kotlin-extensions](https://github.com/reactor/reactor-kotlin-extensions/) project/repo. You may have to add `io.projectreactor.kotlin:reactor-kotlin-extensions` dependency to your project and update related packages to use the non-deprecated variants.
### Core Container
Spring's annotation retrieval algorithms have been completely revised for efficiency and consistency, as well as for potential optimizations through annotation presence hints (e.g. from a compile-time index). This may have side effects -- for example, finding annotations in places where they haven't been found before or not finding annotations anymore where they have previously been found accidentally. While we don't expect common Spring applications to be affected, annotation declaration accidents in application code may get uncovered when you upgrade to 5.2. For example, all annotations must now be annotated with `@Retention(RetentionPolicy.RUNTIME)` in order for Spring to find them. See [gh-23901](https://github.com/spring-projects/spring-framework/issues/23901), [gh-22886](https://github.com/spring-projects/spring-framework/issues/22886), and [gh-22766](https://github.com/spring-projects/spring-framework/issues/22766).
### Web Applications
#### `@RequestMapping` without path attribute
`@RequestMapping()` and meta-annotated variants `@GetMapping()`, `PostMapping()`, etc., without explicitly declared `path` patterns are now equivalent to `RequestMapping("")` and match only to URLs with no path. In the absence of declared patterns previously the path was not checked thereby matching to any path. If you would like to match to all paths, please use `"/**"` as the pattern. [gh-22543](https://github.com/spring-projects/spring-framework/issues/22543)
#### `@EnableWebMvc` and `@EnableWebFlux` Infrastructure
`@Bean` methods in `Web**ConfigurationSupport` now declare bean dependencies as method arguments rather than use method calls to make it possible to avoid creating proxies for bean methods via `@Configuration(proxyBeanMethods=false)` which Spring Boot 2.2 now does. This should not affect existing applications but if sub-classing `Web**ConfigurationSupport` (or `DelegatingWeb**Configuration`) and using `proxyBeanMethods=false` be sure to also to declare dependent beans as method arguments rather than using method calls. See [gh-22596](https://github.com/spring-projects/spring-framework/pull/22596)
#### Deprecation of `MediaType.APPLICATION_JSON_UTF8` and `MediaType.APPLICATION_PROBLEM_JSON_UTF8`
Since the [related Chrome bug](https://bugs.chromium.org/p/chromium/issues/detail?id=438464) is now fixed since September 2017, Spring Framework 5.2 deprecates `MediaType.APPLICATION_JSON_UTF8` and `MediaType.APPLICATION_PROBLEM_JSON_UTF8` in favor of `MediaType.APPLICATION_JSON` and `MediaType.APPLICATION_PROBLEM_JSON` and uses them by default. As a consequence, integration tests relying on the default JSON content type may have to be updated. See [gh-22788](https://github.com/spring-projects/spring-framework/issues/22788) for more details.
#### CORS handling
CORS handling has been [significantly updated](https://github.com/spring-projects/spring-framework/commit/d27b5d0ab6e8b91a77e272ad57ae83c7d81d810b) in Spring Framework 5.2:
- CORS processing is now only used for CORS-enabled endpoints
- CORS processing for skipped for same-origin requests with an `Origin` header
- Vary headers are added for non-CORS requests on CORS endpoints
These changes introduce an `AbstractHandlerMapping#hasCorsConfigurationSource` method (in both Spring MVC and WebFlux) in order to be able to check CORS endpoints efficiently. When upgrading to Spring Framework 5.2, handler mapping extending `AbstractHandlerMapping` and supporting CORS should override `hasCorsConfigurationSource` with their custom logic.
#### Use of Path Extensions Deprecated in Spring MVC
Config options for suffix pattern matching in `RequestMappingHandlerMapping` have been deprecated, and likewise config options to resolve acceptable media types from the extension of a request path in `ContentNegotiationManagerFactoryBean` have also been deprecated. This is aligned with defaults in Spring Boot auto configuration and Spring WebFlux does not offer such options. See [gh-24179](https://github.com/spring-projects/spring-framework/issues/24179) and related issues for details and further plans towards 5.3.
#### `Encoder` Contract
Custom implementations of `Encoder` must implement the new [encodeValue](https://github.com/spring-projects/spring-framework/blob/13183c89ce1eb178793e542753cd78f3d9908164/spring-core/src/main/java/org/springframework/core/codec/Encoder.java#L85) which is invoked from `ServerSentEventHttpMessageWriter` or otherwise that would fail at runtime.
### Testing
The mock JNDI support in the `spring-test` module has been deprecated. If you have been using classes such as the `SimpleNamingContext` and `SimpleNamingContextBuilder`, you are encouraged to migrate to a complete JNDI solution from a third party such as [Simple-JNDI](https://github.com/h-thurow/Simple-JNDI). [[gh-22779]](https://github.com/spring-projects/spring-framework/issues/22779)
[[See Spring Framework 5.2 Release Notes|Spring-Framework-5.2-Release-Notes]].
## Upgrading to Version 5.1

Write Preview
Loading…
Cancel
Save