Spring Boot 3.1 Release Notes

Upgrading from Spring Boot 3.0

Dependency Management for Apache HttpClient 4

Support for Apache HttpClient 4 with RestTemplate was 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 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 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 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 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 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 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 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 documentation for further details.

Testcontainers Service Connections

When using Testcontainers, @DynamicPropertySource is commonly used to configure application properties based on the container’s settings:

@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

@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 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 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 documentation for more information.

Auto-configuration for Spring Authorization Server

This release ships support for the Spring Authorization Server project along with a new spring-boot-starter-oauth2-authorization-server starter. More information can be found in the 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 and 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 and 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 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 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 #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:

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

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.