:version: 3.1.0
:reference-docs: https://docs.spring.io/spring-boot/docs/{version}/reference/html
:actuator-api-docs: https://docs.spring.io/spring-boot/docs/{version}/actuator-api/htmlsingle
:gradle-plugin-docs: https://docs.spring.io/spring-boot/docs/{version}/gradle-plugin/reference/htmlsingle
:maven-plugin-docs: https://docs.spring.io/spring-boot/docs/{version}/maven-plugin/reference/htmlsingle

== Upgrading from Spring Boot 3.0


=== Dependency Management for Apache HttpClient 4
Support for Apache HttpClient 4 with `RestTemplate` was https://github.com/spring-projects/spring-framework/issues/28925[removed in Spring Framework 6], in favor of Apache HttpClient 5. Spring Boot 3.0 includes dependency management for both HttpClient 4 and 5. Applications that continue to use HttpClient 4 can experience https://github.com/spring-projects/spring-boot/issues/33515[errors when using `RestTemplate`] that are difficult to diagnose. 

Spring Boot 3.1 removes dependency management for HttpClient 4 to encourage users to move to HttpClient 5 instead. 



=== Servlet and Filter Registrations
The `ServletRegistrationBean` and `FilterRegistrationBean` classes will now fail with an `IllegalStateException` rather than logging a warning if registration fails.
If you need the old behavior, you should call `setIgnoreRegistrationFailure(true)` on your registration bean.



=== Git Commit ID Maven Plugin Version Property
The property used to override the version of `io.github.git-commit-id:git-commit-id-maven-plugin` has been updated to align with its artifact name. To adapt to this change replace `git-commit-id-plugin.version` with `git-commit-id-maven-plugin.version` in your `pom.xml`.



=== Spring Kafka Retry Topic Auto-configuration
When using Apache Kafka with auto-configured retryable topic configuration (`spring.kafka.retry.topic.enabled: true`), with an exponential back off with a `maxDelay`, all retries at the `maxDelay` level are now sent to the same topic. 
Previously a separate topic was used for each retry, even if the max delay was exceeded.

For example, with a max retry attempts of `5`, delay of `1s`, a multiplier of `2`, and a max delay of `3s`, after the initial failure, retries will be performed at 1s, 2s, 3s, 3s. 
With previous versions of Spring Boot, the framework would create 6 topics: `someTopic`, `someTopic-retry-0`, `someTopic-retry-1`, `someTopic-retry-2`, `someTopic-retry-3`, and `someTopic-dlt`.
With this change, the `someTopic-retry-3` topic will not be created, but instead all 3 second retries will be in `someTopic-retry-2`.
After migrating from an earlier Spring Boot version, you can safely delete the `someTopic-retry-3` topic after all records have been consumed. 



=== Dependency Management for Testcontainers
Spring Boot's dependency management now includes Testcontainers.
If necessary, the version that is managed by Spring Boot can be overridden using the `testcontainers.version` property.



=== Hibernate 6.2
Spring Boot 3.1 upgrades to Hibernate 6.2. Please refer to the https://docs.jboss.org/hibernate/orm/6.2/migration-guide/migration-guide.html[Hibernate 6.2 migration guide] to learn about how this may affect your application.



=== Jackson 2.15
Spring Boot 3.1 upgrades to Jackson 2.15. Please refer to the https://github.com/FasterXML/jackson/wiki/Jackson-Release-2.15[Jackson wiki] to learn about how this may affect your application.

One notable change in 2.15 is the introduction of processing limits.
To tune these constraints, define a `Jackson2ObjectMapperBuilderCustomizer` similar to the following:

----
@Bean
Jackson2ObjectMapperBuilderCustomizer customStreamReadConstraints() {
	return (builder) -> builder.postConfigurer((objectMapper) -> objectMapper.getFactory()
		.setStreamReadConstraints(StreamReadConstraints.builder().maxNestingDepth(2000).build()));
}
----



=== Mockito 5
Spring Boot 3.1 upgrades to Mockito 5, specifically 5.3. Please refer to the
https://github.com/mockito/mockito/releases/tag/v5.0.0[Mockito release notes] to learn about the notable changes in the 5.x line of Mockito.



=== Health Group Membership Validation
The configured membership of a health group is now validated on startup.
If a health indicator that does not exist has been included or excluded, startup will fail.
This validation can be disabled, restoring the behavior of earlier versions, by setting `management.endpoint.health.validate-group-membership` to `false`.


=== Switch to `maven.compiler.release`

The `spring-boot-starter-parent` now uses `maven.compiler.release` to configure the Java version instead of `maven.compiler.source` and `maven.compiler.target`. The `source` and `target` properties have been removed. If you use them somewhere in your build, please migrate to `maven.compiler.release`.

=== Minimum Requirements Changes
None.



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



=== Service Connections
A new service connection concept has been introduced.
Such connections are represented in an application by `ConnectionDetails` beans.
These beans provide the necessary details to establish a connection to a remove service and Spring Boot's auto-configuration has been updated to consume `ConnectionDetails` beans.
When such beans are available, they will take precedence over any connection-related configuration properties.
Configuration properties that are not related to the connection itself, such as properties that control the size and behavior of a connection pool, will still used.

This low-level feature is intended as a building block for other higher-level features that auto-configure service connections by defining `ConnectionDetails` beans. 



==== Property-based ConnectionDetails Beans
In the absence of an appropriate `…ConnectionDetails` bean being defined elsewhere, Spring Boot's auto-configurations have been updated to define their own based backed by the relevant configuration properties.
This allows `…ConnectionDetails` to be injected without having to handle the case where no such bean is available and a fallback to property-based configuration is required.



=== Testcontainers



==== Using Testcontainers at Development Time
Support for using Testcontainers to manage external services at development time has been introduced. 

A new Maven goal (`spring-boot:test-run`) and Gradle task (`bootTestRun`) can be used to launch an application through a test main method when using {reference-docs}/features.html#features.testing.testcontainers.at-development-time[Testcontainers at development time].

Classes declaring Testcontainers `Container` instances as static fields can be imported using a new `@ImportTestcontainers` annotation. Please refer to the {reference-docs}/features.html#features.testing.testcontainers.at-development-time.importing-container-declarations[reference documentation] for further details.

Management of Testcontainers lifecycle has been improved, ensuring that containers are initialized first and destroyed last.
Support for reusable containers has also been improved.


To contribute properties from `Container` `@Bean` methods, `DynamicPropertyRegistry` can now be injected.
This works in a similar way to `@DynamicPropertySource` that you can use in tests. 
Please refer to the {reference-docs}/features.html#features.testing.testcontainers.at-development-time.dynamic-properties[reference documentation] for further details.





==== Testcontainers Service Connections
When using Testcontainers, `@DynamicPropertySource` is commonly used to configure application properties based on the container's settings:

[source,java]
----
@Container
static GenericContainer redis = new GenericContainer(DockerImageName.parse("redis").withTag("4.0.14"));

// …

@DynamicPropertySource
static void redisProperties(DynamicPropertyRegistry registry) {
	registry.add("spring.data.redis.host", redis::getHost);
	registry.add("spring.data.redis.port", redis::getFirstMappedPort);
}
----

This can now be simplified to the following

[source,java]
----
@Container
@ServiceConnection
static GenericContainer redis = new GenericContainer(DockerImageName.parse("redis").withTag("4.0.14"));
----

Here, `@ServiceConnection` indicates that the container should be used a source of Redis connection details. The `spring-boot-testcontainers` module, which provides the `@ServiceConnection` annotation, will extract those details from the container while still allowing the Testcontainers API to be used to define and configure it.

Please see the {reference-docs}/features.html#features.testing.testcontainers.service-connections[reference documentation] for a complete list of the services that are currently supported by the `@ServiceConnection` annotation.



=== Docker Compose
A new module, `spring-boot-docker-compose`, provides integration with Docker Compose.
When your app is starting up, the Docker Compose integration will look for a configuration file in the current working directory.
The following files are supported:

- `compose.yaml`
- `compose.yml`
- `docker-compose.yaml`
- `docker-compose.yml`

To use a non-standard file, set the `spring.docker.compose.file` property.

By default, the services declared in the configuration file will be started up using `docker compose up` and connection details beans for those services will be added to the application context so that the services can be used without any further configuration.
When the application stops, the services will then be shut down using `docker compose down`.
This lifecycle management and the commands used to start up and shut down the services can be customized using the `spring.docker.compose.lifecycle-management`, `spring.docker.compose.startup.command`, and `spring.docker.compose.shutdown.command` configuration properties.

Please refer to the {reference-docs}/features.html#features.docker-compose[reference documentation] for further details, including the list of services that are currently supported.



=== SSL Configuration
SSL trust material such as Java KeyStores and PEM-encoded certificates can now be configured using properties and applied to connections of various types such as embedded web servers, data services, `RestTemplate` and `WebClient` in a more consistent manner.

Please refer to the {reference-docs}/features.html#features.ssl[reference documentation] for more information.  



=== Auto-configuration for Spring Authorization Server
This release ships support for https://spring.io/projects/spring-authorization-server[the Spring Authorization Server] project along with a new `spring-boot-starter-oauth2-authorization-server` starter. More information can be found in the {reference-docs}/web.html#web.security.oauth2.authorization-server[Authorization Server section of the Spring Boot reference documentation]. 



=== Docker Image Building



==== Image Created Date and Time
The `spring-boot:build-image` Maven goal and `bootBuildImage` Gradle task now have a `createdDate` configuration option that can be used to set the value of the `Created` field in the generated image's metadata to a user-specified date or to `now` to use the current date and time. See the {gradle-plugin-docs}/#build-image.customization[Gradle] and {maven-plugin-docs}/#build-image.customization[Maven] plugin documentation for more information. 



==== Image Application Directory
The `spring-boot:build-image` Maven goal and `bootBuildImage` Gradle task now have an `applicationDirectory` configuration option that can be used to set the location in the builder image that application content will be uploaded to for buildpacks to consume. This will also be the location of the application content in the generated image. See the {gradle-plugin-docs}/#build-image.customization[Gradle] and {maven-plugin-docs}/#build-image.customization[Maven] plugin documentation for more information.



=== Spring for GraphQL 



==== Exception Handling
`@GraphQlExceptionHandler` methods declared in controllers or `@ControllerAdvice` are now supported out-of-the box by Spring for GraphQL for controller method invocations. Additionally, Spring Boot auto-configures `@ControllerAdvice` exception handling for other (non-controller) `DataFetcher` implementations like `QueryDslDataFetcher`, `QueryByExampleDataFetcher`, and others through configuration of the `GraphQlSource`.



==== Pagination and Sorting
When Spring Data is on the classpath, Spring for GraphQL is now auto-configured with support for pagination and sorting.



==== Improved Schema Type Generation
The `GraphQlSource` is now auto-configured with a `ConnectionTypeDefinitionConfigurer`.
It generates "Connection" types by looking for fields whose type definition name ends in "Connection", considered by the
https://relay.dev/graphql/connections.htm[GraphQL Cursor Connections Specification] to be a `Connection Type`, and adding the required type definitions if they don't already exist.



=== Support for Exporting Traces Using OTLP
When `io.opentelemetry:opentelemetry-exporter-otlp` is on the classpath, an `OtlpHttpSpanExporter` will be auto-configured.
The configuration of the exporter can be customized using the `management.otlp.tracing.*` configuration properties.



=== Wavefront Span Tag Customization
If you're using Wavefront and you want to https://docs.wavefront.com/tracing_customize_spans_and_alerts.html[customize span tags for RED metrics], there's now a new property called `management.wavefront.trace-derived-custom-tag-keys` which allows you to do this. See https://github.com/spring-projects/spring-boot/issues/34194[#34194] for details.



=== Different log levels for file and console
If you're using Logback or Log4j2, there's now the option to have different log levels for console logs and file logs. This can be set using the configuration properties `logging.threshold.console` and `logging.threshold.file`.



=== Maximum HTTP Response Header Size
You can now limit the maximum HTTP response header size if you are using Tomcat or Jetty.
For Tomcat you can use the `server.tomcat.max-http-response-header-size` property and for Jetty you can use `server.jetty.max-http-response-header-size`.
By default, response headers are limited to `8kb`.


=== ActiveMQ Support
Support for auto-configuration of an ActiveMQ client, which was removed in Spring Boot 3.0, has been restored.
Support for an embedded ActiveMQ broker has not be restored as ActiveMQ's broker does not yet support JMS 3.0.

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

* https://github.com/spring-projects/spring-authorization-server/releases/tag/1.1.0[Spring Authorization Server 1.1.0]
* https://github.com/spring-projects/spring-batch/releases/tag/v5.0.2[Spring Batch 5.0.2]
* https://github.com/spring-projects/spring-data-commons/wiki/Spring-Data-2023.0-%28Ullman%29-Release-Notes[Spring Data 2023.0.0]
* https://github.com/spring-projects/spring-framework/releases/tag/v6.0.9[Spring Framework 6.0.9]
* https://github.com/spring-projects/spring-graphql/releases/tag/v1.2.0[Spring GraphQL 1.2.0]
* https://github.com/spring-projects/spring-hateoas/releases/tag/2.1.0[Spring HATEOAS 2.1.0]
* https://github.com/spring-projects/spring-integration/releases/tag/v6.1.0[Spring Integration 6.1.0]
* https://github.com/spring-projects/spring-kafka/releases/tag/v3.0.7[Spring Kafka 3.0.7]
* https://github.com/spring-projects/spring-ldap/releases/tag/3.1.0-RC1[Spring LDAP 3.1.0]
* https://github.com/spring-projects/spring-security/releases/tag/6.1.0[Spring Security 6.1.0]
* https://github.com/spring-projects/spring-session/releases/tag/3.1.0[Spring Session 3.1.0]
* https://github.com/spring-projects/spring-ws/releases/tag/v4.0.4[Spring Web Services 4.0.4]


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

* https://docs.couchbase.com/java-sdk/current/project-docs/sdk-release-notes.html#version-3-4-6-4-may-2023[Couchbase Java Client 3.4.6]
* https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/release-highlights.html#_version_8_7[Elasticsearch Client 8.7]
* https://in.relation.to/2023/03/30/orm-62-final/[Hibernate 6.2]
* https://github.com/graphql-java/graphql-java/releases/tag/v20.1[GraphQL Java 20.1]
* https://github.com/FasterXML/jackson/wiki/Jackson-Release-2.15#changes-compatibility[Jackson 2.15.0]
* https://downloads.apache.org/kafka/3.4.0/RELEASE_NOTES.html[Kafka 3.4.0]
* https://github.com/JetBrains/kotlin/releases/tag/v1.8.21[Kotlin 1.8.21]
* https://forum.liquibase.org/t/liquibase-4-20-released/7874[Liquibase 4.20]
* https://github.com/micrometer-metrics/micrometer/releases/tag/v1.11.0[Micrometer 1.11.0]
* https://github.com/micrometer-metrics/tracing/releases/tag/v1.1.1[Micrometer Tracing 1.1.1]
* https://github.com/mockito/mockito/releases/tag/v5.3.0[Mockito 5.3]
* https://github.com/graalvm/native-build-tools/releases/tag/0.9.22[Native Build Tools 0.9.22]
* https://github.com/neo4j/neo4j-java-driver/releases/tag/5.8.0[Neo4j Java Driver 5.8.0]
* https://github.com/open-telemetry/opentelemetry-java/releases/tag/v1.24.0[OpenTelemetry 1.24.0]
* https://github.com/rabbitmq/rabbitmq-java-client/releases/tag/v5.17.0[Rabbit AMQP Client 5.17.0]
* https://github.com/reactor/reactor/releases/tag/2022.0.7[Reactor BOM 2022.0.7]
* https://github.com/testcontainers/testcontainers-java/releases/tag/1.18.0[Testcontainers 1.18]
* Undertow 2.3.6.Final



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

* Spring Kafka `ContainerCustomizer` beans are now applied to the auto-configured `KafkaListenerContainerFactory`.
* A `management.otlp.metrics.export.headers` property has been added to support sending headers to an OTLP registry.
* `JoranConfigurators` beans can now be used in AOT processing.
* Additional `close-timeout`, `operation-timeout`, `auto-startup` and `auto-create` properties have been added to `spring.kafka.admin`
* `BatchInterceptor` beans are now applied to the auto-configured `ConcurrentKafkaListenerContainerFactory`.
* Nomad has been added to the list of recognized `CloudPlaform` values.
* You can now specify a `registration-policy` property for `spring.jmx`.
* A `withSanitizedValue` utility method has been added to `SanitizableData`
* `RabbitTemplateCustomizer` has been introduced. Beans of this type will customize the auto-configured `RabbitTemplate`
* CNB Platform API 0.11 is now supported
* `build-info` goal can now be skipped by setting `-Dspring-boot.build-info.skip`
* Aggregation temporality configuration support for Micrometer's `OtlpMeterRegistry`.
* Support for additional colors in Log4j2 and Logback.
* Dependency management for the R2DBC MySQL driver (`io.asyncer:r2dbc-mysql`) has been added.
* Dependency management for the R2DBC MariaDB driver (`org.mariadb:r2dbc-mariadb`) has been added.
* When using OpenTelemetry, the `SdkTracerProviderBuilder` that is used to create the auto-configured `SdkTracerProvider` can be customised by defining an `SdkTracerProviderBuilderCustomizer` bean.
* `MockServerRestTemplateCustomizer` now supports enable content buffering through a new `setBufferContent` method.
* The conversion service using by Spring Batch when it is auto-configured can now be customised by defining a `BatchConversionServiceCustomizer` bean.
* The builder used to create the JTW decoder for a JWK Set URI can be customised by defining a `JwkSetUriReactiveJwtDecoderBuilderCustomizer` or `JwkSetUriJwtDecoderBuilderCustomizer` bean.
* Dependency management for `io.r2dbc:r2dbc-mssql` has been reinstated
* Logback's root log level is now defaulted to `INFO` as early as possible
* By default, Docker Compose is now stopped using `stop` rather than `down`



== Deprecations in Spring Boot 3.1.0
* The `spring.kafka.streams.cache-max-size-buffering` has been deprecated in favor of `spring.kafka.streams.state-store-cache-max-size`.
* `MongoPropertiesClientSettingsBuilderCustomizer` in favor of `StandardMongoClientSettingsBuilderCustomizer`
* `org.springframework.boot.autoconfigure.security.oauth2.client.OAuth2ClientPropertiesRegistrationAdapter` in favor of `org.springframework.boot.autoconfigure.security.oauth2.client.OAuth2ClientPropertiesMapper`.
* `org.springframework.boot.web.server.SslStoreProvider` has been deprecated in favor of SSL bundles.
