
== Upgrading from Spring Boot 2.6

=== @SpringBootTest Property Source Precendence
Test property sources added by `@SpringBootTest` using either the `properties` attribute or the `@TestPropertySource` annotation are now added above the command line property source. If you are in the unlikely situation of having a `@SpringBootTest` that uses both `properties` and `args` (and with the same property name), you may need to change things around.



=== New Flyway Modules
Spring Boot 2.7 upgrades to Flyway 8.5 (from 8.0). Since the 8.0 release, Flyway's support for a number of databases has been extracted into new modules:

- `flyway-firebird` (Firebird)
- `flyway-mysql` (MariaDB and MySQL)
- `flyway-sqlserver` (SQL Server)

If you are using Flyway to manage the schema of one of the above databases, add a dependency on the appropriate new module.



=== H2 2.1
Spring Boot 2.7 has upgraded to H2 2.1.120. H2 2.x is backwards incompatible and fixes a number of security vulnerabilities. See the http://www.h2database.com/html/changelog.html[H2 changelog] and http://www.h2database.com/html/migration-to-v2.html[migration guide] for details of the changes and how to handle the upgrade.



==== jOOQ
There is no open source version of jOOQ that is compatible with both Java 8 and H2 2.x. If you are using Java 11, consider using the `jooq.version` property to upgrade to jOOQ 3.16 or later. If you are using Java 8 and cannot upgrade, consider purchasing jOOQ Professional Edition, migrating from H2 to another database or, as a last resort, downgrading to H2 1.4.x.



=== Microsoft SQL Server JDBC Driver 10
Spring Boot 2.7 has upgrade the MSSQL driver from v9 to v10.
The updated driver now enables encryption by default which may break existing applications.
You can read about the change in the "Breaking Changes" section of https://thewindowsupdate.com/2022/02/01/jdbc-driver-10-2-for-sql-server-released/[this article].

The recommended advice is to either install a trusted certificate on your server or update your JDBC connection URL to include `encrypt=false`.



=== OkHttp 4
As OkHttp 3 is no longer being maintained, Spring Boot 2.7 has upgraded to OkHTTP 4.
As part of this upgrade, the property used to control OkHttp's version has changed from `okhttp3.version` to `okhttp.version`.

OkHttp 4 is intended to be backwards compatible with OkHttp 3.
If this is not the case in your application or wish to continue using OkHttp 3 for another reason, configure the `okttp.version` property in your build.



=== Separate Dependency Management for netty-tcnative Removed
Separate dependency management for `netty-tcnative` has been removed in favor of the dependency management provided by Netty's bom.
This ensures that the version of `netty-tcnative` will align with the version that Netty uses by default.
As a result of this change, the `netty-tcnative.version` property can no longer be used to override the version of `netty-tcnative`.
The version can still be overridden by providing your own dependency management but it is recommended that it remains aligned with Netty's default version.



=== `spring.mongodb.embedded.features` Configuration Property Removed
Embedded Mongo 3.4 has dropped support for configuring Mongo features.
Reflecting this, the `spring.mongodb.embedded.features` configuration property has been removed.
For advanced configuration where features were being specified to alter the command line used to launch Mongo, a custom `MongodConfig` bean should be provided instead.



=== Servlet-specific Mustache Properties
The following Mustache-related properties that are Servlet-specific have been deprecated:

- `spring.mustache.allow-request-override`
- `spring.mustache.allow-session-override`
- `spring.mustache.cache`
- `spring.mustache.content-type`
- `spring.mustache.expose-request-attributes`
- `spring.mustache.expose-session-attributes`
- `spring.mustache.expose-spring-macro-helpers`

The following replacements have been introduced:

- `spring.mustache.servlet.allow-request-override`
- `spring.mustache.servlet.allow-session-override`
- `spring.mustache.servlet.cache`
- `spring.mustache.servlet.content-type`
- `spring.mustache.servlet.expose-request-attributes`
- `spring.mustache.servlet.expose-session-attributes`
- `spring.mustache.servlet.expose-spring-macro-helpers`



=== Default Indices Options on Auto-configured ReactiveElasticsearchTemplate
The default indices options on the auto-configured `ReactiveElasticsearchTemplate` have changed to align them with Spring Data Elasticsearch.
Previously, the defaults were `strictExpandOpenAndForbidClosed`.
They are now `strictExpandOpenAndForbidClosedIgnoreThrottled`.
To restore the old indices options, define your own `reactiveElasticsearchTemplate` bean:

[source,java,indent=0,subs="verbatim"]
----
@Bean
ReactiveElasticsearchTemplate reactiveElasticsearchTemplate(ReactiveElasticsearchClient client,
        ElasticsearchConverter converter) {
    ReactiveElasticsearchTemplate template = new ReactiveElasticsearchTemplate(client, converter);
    template.setIndicesOptions(IndicesOptions.strictExpandOpenAndForbidClosed());
    return template;
}
----



=== MongoDB Property Precedence
Previously, if `spring.data.mongodb.uri` was configured alongside any of the equivalent separate properties such as `spring.data.mongodb.host` and `spring.data.mongodb.port` an exception would be thrown.
The `uri` property now takes precedence over any of the separate properties – they're ignored when `spring.data.mongodb.uri` is set.
This aligns the behavior with other similar properties such as `spring.redis.url`.



=== Running Your Application in the Maven Process
The `spring-boot:run` and `spring-boot:start` goals of the Maven Plugin run your application in a forked processed by default.
It is possible to disable this behavior using the `fork` attribute of the plugin.
This attribute is now deprecated with no replacement.



=== Ordered Exit Code Generators
``ExitCodeGenerator``s are now ordered based on their `Ordered` implementation and `@Order` annotation.
The first non-zero exit code that is generated is used.



=== Metric Tag Keys Renamed
Metric tag keys that were in `camelCase` have been renamed to comply with Micrometer's recommendation to use all lower-case and a `.` separator.
The following metrics and tag keys are affected:

[cols="1,1,1"] 
|=== 
| Metric | Old Tag Key | New Tag Key

| `application.ready.time`
| `main-application-class`
| `main.application.class`

| `application.started.time`
| `main-application-class`
| `main.application.class`

| `cache.*` 
| `cacheManager`
| `cache.manager`

| `http.client.requests`
| `clientName`
| `client.name`

|===

If you need to restore the previous names, define a `MeterFilter` bean that implements the `map(Id)` method to modify the tag keys.



=== Support for Elasticsearch's RestHighLevelClient is Deprecated
Elasticsearch has deprecated its `RestHighLevelClient`.
In alignment with this, Spring Boot's auto-configuration for `RestHighLevelClient` has been deprecated.
Where possible, the auto-configured low-level `RestClient` should be used instead.
Alternatively, consider manually configuring https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/migrate-hlrc.html[the new client].



=== R2DBC Driver Changes
In the https://r2dbc.io/2022/02/04/r2dbc-borca-released[Borca release], the group ID of `r2dbc-postgresql`, the driver for PostgreSQL, has changed from `io.r2dbc` to `org.postgresql`. `r2dbc-mysql`, the driver for MySQL, as been removed. Consider using `r2dbc-mariadb` as a replacement.



=== Migrating From WebSecurityConfigurerAdapter to SecurityFilterChain
Spring Boot 2.7 upgrades to Spring Security 5.7 which has deprecated `WebSecurityConfigurerAdapter`. When https://spring.io/blog/2022/02/21/spring-security-without-the-websecurityconfigureradapter[configuring Spring Security without `WebSecurityConfigurerAdapter`] and using Spring Boot's sliced tests such as `@WebMvcTest`, you may need to make some changes to your application to make your `SecurityFilterChain` beans available to your tests by `@Import` ing your security configuration class. See https://docs.spring.io/spring-boot/docs/2.7.x/reference/html/howto.html#howto.testing.slice-tests[the reference documentation] for further details.


=== Building Jars With Maven Shade Plugin and Gradle Shadow Plugin
Spring Boot 2.7 has changed the way that auto-configuration and management context classes are discovered.
They are now declared in files named `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` and
`META-INF/spring/org.springframework.boot.actuate.autoconfigure.web.ManagementContextConfiguration.imports` respectively.

==== Configuration of Maven Shade Plugin
If you are using the `maven-shade-plugin` and are not depending on `spring-boot-starter-parent`, add the following `AppendingTransformer` configuration:

```xml
<transformer implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
  <resource>META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports</resource>
</transformer>
<transformer implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
  <resource>META-INF/spring/org.springframework.boot.actuate.autoconfigure.web.ManagementContextConfiguration.imports</resource>
</transformer>
```

==== Configuration of Gradle Shadow Plugin
Add the following configuration to append the `.imports` files:

```groovy
tasks.withType(ShadowJar).configureEach {
    append("META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports")
    append("META-INF/spring/org.springframework.boot.actuate.autoconfigure.web.ManagementContextConfiguration.imports")
}
```


=== MIMEPull
Dependency management for `org.jvnet.mimepull:mimepull` has been removed.
If you have declared a dependency on `mimepull`, add a version that meets your needs to that declaration.



=== Support for Hazelcast 3.0 is Deprecated
Hazelcast 3 support is deprecated.
If you still need to downgrade to Hazelcast 3, `hazelcast-client` should be added to the classpath to configure a client.



=== Spring MVC's `requestMappingHandlerMapping` is No Longer Primary
Since Spring Framework 5.1, Spring MVC has supported multiple `RequestMappingHandlerMapping` beans.
To align with this, Spring Boot 2.7 no longer defines MVC's main `requestMappingHandlerMapping` bean as `@Primary`.
In the unlikely event that you were injecting `RequestMappingHandlerMapping`, if there are multiple such beans in the context you will now need to use `@Qualifier` to select the candidate that you wish to be injected.
Alternatively, all candidates can be injected using `List<RequestMappingHandlerMapping>`.



=== MySQL JDBC Driver
The coordinates of the MySQL JDBC driver have changed. 8.0.31 is published to `com.mysql:mysql-connector-j` in addition to `mysql:mysql-connector-java`. In 8.0.32 and later it is only published to `com.mysql:mysql-connector-j`. Spring Boot 2.7.8 upgraded to 8.0.32. If you are using the MySQL JDBC driver, update its coordinates accordingly when upgrading to Spring Boot 2.7.8 and later.



=== Deprecations from Spring Boot 2.5
Classes, methods and properties that were deprecated in Spring Boot 2.5 have been removed in this release.
Please ensure that you aren't calling deprecated methods before upgrading.



=== Minimum Requirements Changes
None.



== New and Noteworthy
TIP: Check link:Spring-Boot-2.7-Configuration-Changelog[the configuration changelog] for a complete overview of the changes in configuration.



=== New Spring GraphQL starter
Spring Boot 2.7 ships support for https://github.com/spring-projects/spring-graphql[the Spring GraphQL project] with a new `spring-boot-starter-graphql` starter. You'll find more information in https://docs.spring.io/spring-boot/docs/2.7.x-SNAPSHOT/reference/html/web.html#web.graphql[the GraphQL section of the Spring Boot reference documentation].


=== Support for RabbitStreamTemplate
A `RabbitStreamTemplate` is auto-configured if a stream name is set using the `spring.rabbitmq.stream.name` property.
A `RabbitStreamTemplateConfigurer` is provided, similar to `RabbitTemplateConfigurer` to customize additional instances whilst retaining auto-configuration.



=== Hazelcast `@SpringAware` Support
The auto-configured Hazelcast embedded server now uses `SpringManagerContext` by default.
This makes it possible to inject Spring managed beans into objects instantiated by Hazelcast.
A `HazelcastConfigCustomizer` callback interface has also been introduced and can be used to further tune the Hazelcast server config.



=== Operating System Information in Info endpoint
An `OsInfoContributor` can expose some information about the Operating System the application is running on:

```json
{
  "os": {
    "name": "Linux",
    "version": "5.4.0-1051-gke",
    "arch": "amd64"
  }
}
```

This new contributor is disabled by default.
It can be enabled using the `management.info.os.enabled` property.



=== Java Vendor Information in Info endpoint
The existing `JavaInfoContributor` has been improved to offer a dedicated section for the vendor information, including the vendor-specific version.
Rather than a top-level `vendor` simple attribute, it is now a dedicated object with `name` and `version` attributes:

```json
{
  "java": {
    "vendor": {
       "name": "Eclipse Adoptium",
        "version": "Temurin-17.0.1+12"
    },
    "..."
}
```

Note that not all vendors expose a `java.vendor.version` system property so the `version` attribute may be `null`.



=== Accessing the Authenticated Principal in RSocket Handler Methods
An RSocket handler method can now inject the `@Authenticated` `Principal`:

```java
@MessageMapping ("test") 
Mono<String> hello (@Authenticated Principal p){ 
    return Mono.just ("Hello, "  + p.getName()) ;
}
```


=== Opaque Token Introspection Without the OIDC SDK
If you are using opaque token introspection in your OAuth2 resource server, the auto-configured introspector no longer requires a dependency on `com.nimbusds:oauth2-oidc-sdk`.
Depending on other usages of the SDK, you may be able to remove the dependency from your application.



=== @DataCouchbaseTest
A new `@DataCouchbaseTest` annotation for testing applications that use Spring Data Couchbase has been introduced. See the https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.testing.spring-boot-applications.autoconfigured-spring-data-couchbase[updated reference documentation] for details.



=== @DataElasticsearchTest
A new `@DataElasticsearchTest` annotation for testing applications that use Spring Data Elasticsearch has been introduced. See the https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.testing.spring-boot-applications.autoconfigured-spring-data-elasticsearch[updated reference documentation] for details.


=== Auto-configuration for SAML2 logout
If you use Spring Security's SAML2 support, you can configure RP-initiated or AP-initiated logout via configuration properties.
See the https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#web.security.saml2.relying-party[updated reference documentation] for details. 



=== Changes to Auto-configuration

==== Auto-configuration Registration
If you have created your own auto-configurations, you should move the registration from `spring.factories` under the `org.springframework.boot.autoconfigure.EnableAutoConfiguration` key to a new file named `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`. Rather than a single comma-separate list, each line contains the fully qualified name of an auto-configuration class. See https://github.com/spring-projects/spring-boot/blob/main/spring-boot-project/spring-boot-autoconfigure/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports[the included auto-configurations] for an example.

For backwards compatibility, entries in `spring.factories` will still be honored.
Furthermore, entries can be listed in both files and will be de-duplicated.
This allows a library to target versions of Spring Boot that only support `spring.factories` and versions of Spring Boot that only support `AutoConfiguration.imports`.



==== New @AutoConfiguration Annotation

A new `@AutoConfiguration` annotation has been introduced. It should be used to annotate top-level auto-configuration classes that are listed in the new `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` file, replacing `@Configuration`. Configuration classes that are nested within or imported by an `@AutoConfiguration` class should continue to use `@Configuration` as before.

For your convenience, `@AutoConfiguration` also supports auto-configuration ordering via the `after`, `afterNames`, `before` and `beforeNames` attributes. This can be used as a replacement for `@AutoConfigureAfter` and `@AutoConfigureBefore`.



=== Test Slice Configuration
If you have created your own test-slices, you should move the registration from `spring.factories` to the new place under `META-INF/spring/<name of your test slice annotation>.imports`. The format is the same as the new file described in the "Auto-configuration Registration" section, see above.

See https://github.com/spring-projects/spring-boot/blob/main/spring-boot-project/spring-boot-test-autoconfigure/src/main/resources/META-INF/spring/[the included test slices for an example].



=== FailureAnalyzer Injection 

`FailureAnalyzer` implementations can now get access to the `BeanFactory` and `Environment` of the current application context by providing a constructor that takes one or both of these values as a parameter. Support for injecting the `BeanFactory` by implementing `BeanFactoryAware` and injecting the `Environment` by implementing `EnvironmentAware` in a `FailureAnalyzer` is deprecated and will be removed in a future release.



=== Redis Sentinel Username Support
Support for specifying a username for authenticating to Sentinel(s) has been added using the `spring.redis.sentinel.username` property.



=== Overriding Built-in Sanitization
`SanitizingFunction` beans are now called in order, stopping once a function has changed the value of the `SanitizableData`.
If no `SanitizingFunction` bean sanitizes the value, the built-in key-based sanitization is performed.
Functions are ordered through their `@Order` annotations or their `Ordered` implementation.




=== Docker Image Building 



==== Podman Support
The Maven and Gradle plugins now support using the Podman container engine as an alternative to Docker Engine when building images using Cloud Native Buildpacks.

See the updated https://docs.spring.io/spring-boot/docs/2.7.0-SNAPSHOT/gradle-plugin/reference/htmlsingle/#build-image.examples.docker.podman[Gradle] and https://docs.spring.io/spring-boot/docs/2.7.0-SNAPSHOT/maven-plugin/reference/htmlsingle/#build-image.examples.docker.podman[Maven] reference documentation for more details.



=== Cache2k Support
Dependency management and auto-configuration for https://cache2k.org/[Cache2k] has been added.
Default cache settings can be customized by defining a `Cache2kBuilderCustomizer` bean.



=== Simplified Registration of Jackson Mixins
Auto-configuration for Jackson will now scan your application's packages for classes annotated with `@JsonMixin`.
Any class that are found are automatically registered as mixins with the auto-configured `ObjectMapper`.



=== Web Server SSL Configuration Using PEM-encoded Certificates
Embedded web servers can be configured to use SSL with PEM-encoded certificate and private key files using the properties `server.ssl.certificate` and `server.ssl.certificate-private-key`, as well as the optional `server.ssl.trust-certificate` and `server.ssl.trust-certificate-private-key`. Management endpoints can be secured using similar `management.server.ssl.*` properties.  
See https://docs.spring.io/spring-boot/docs/2.7.0-SNAPSHOT/reference/htmlsingle/#howto.webserver.configure-ssl[the documentation] for an example. 
This is provided as an alternative to configuring SSL with Java KeyStore files. 



=== Dependency Upgrades
Spring Boot 2.7 moves to new versions of several Spring projects:

* https://github.com/spring-projects/spring-data-commons/wiki/Release-Train-2021.2-%28Raj%29-Release-Notes[Spring Data 2021.2]
* https://github.com/spring-projects/spring-hateoas/releases/tag/1.5.0[Spring HATEOAS 1.5]
* https://github.com/spring-projects/spring-ldap/releases/tag/2.4.0[Spring LDAP 2.4]
* https://github.com/spring-projects/spring-security/releases/tag/5.7.0[Spring Security 5.7]
* Spring Session 2021.2

Numerous third-party dependencies have also been updated, some of the more noteworthy of which are the following:

- Elasticsearch 7.17
- Flyway 8.5
- H2 2.1
- https://docs.hazelcast.com/hazelcast/5.0/release-notes.html[Hazelcast 5.0]
- https://infinispan.org/blog/2021/10/12/infinispan-13-final[Infinispan 13]
- Json 2.9
- Json Path 2.7
- Kafka 3.1
- MariaDB 3.0
- https://github.com/micrometer-metrics/micrometer/releases/tag/v1.9.0[Micrometer 1.9]
- MongoDB 4.5
- OkHTTP 4.9
- REST Assured 4.5
- https://r2dbc.io/2022/02/04/r2dbc-borca-released[R2DBC `Borca`]



=== Miscellaneous
Apart from the changes listed above, there have also been lots of minor tweaks and improvements including:

* Kafka `idlePartitionEventInterval` can be configured using the `spring.kafka.listener.idle-partition-event-interval` property.
* `KafkaTemplate` `transactionIdPrefix` property can be configured using the `spring.kafka.template.transaction-id-prefix` property.
* Netty `maxKeepAliveRequests` can be configured using the `server.netty.max-keep-alive-requests` property.
* `@DataJdbcTest` automatically scans for `AbstractJdbcConfiguration` beans.
* A `UserDetailsService` bean is no longer auto-configured when SAML 2.0 Login is being used.
* The transaction isolation level of Spring Batch can be configured using the `spring.batch.jdbc.isolation-level-for-create` property.
* The filter used to record Spring MVC metrics can now be replaced by defining your own `FilterRegistrationBean<WebMvcMetricsFilter>` bean.
* The ID of `DatabaseDriver.MARIADB` has changed from `mysql` to `mariadb`
* The `InputStream` returned by `RandomAccessDataFile` in `spring-boot-loader` now implements `available()`.
* Spring Kafka's `immediateStop` is configurable using the `spring.kafka.listener.immediate-stop` property.
* A new property, `spring.mustache.reactive.media-types`, can be used to configure the media types supported by a reactive Mustache view.
* Elasticsearch `RestClientBuilder` and `RestClient` beans are now auto-configured when `elasticsearch-rest-client` is on the classpath. If `elasticsearch-rest-high-level-client` is on the classpath, a `RestHighLevelClient` bean will still be auto-configured as before, but note that support for `RestHighLevelClient` is now deprecated.



== Deprecations in Spring Boot 2.7

* Loading auto-configurations from `spring.factories` is deprecated. See above for more details.
* `DatabaseDriver.GAE`
* Properties under `spring.security.saml2.relyingparty.registration.{id}.identityprovider` have been moved to `spring.security.saml2.relyingparty.registration.{id}.assertingparty`. Using the old property names result in log messages on WARN level on startup.
