:reference-docs: https://docs.spring.io/spring-boot/reference

== Upgrading From Spring Boot 3.2



=== Jersey Observability
Micrometer 1.13 has deprecated its Jersey support in favor of Jersey's `jersey-micrometer` module.
If you application uses Jersey metrics, add a dependency on `org.glassfish.jersey.ext:jersey-micrometer` when upgrading.

To support observations with Jersey, the `MetricsApplicationEventListener` has been replaced with a `ObservationApplicationEventListener`.
If you were using a `JerseyTagsProvider` to customize the tags, you'll now need to implement a `JerseyObservationConvention` bean to do that. 



=== Dependency Management for Dropwizard Metrics Removed
Dependency management for Dropwizard Metrics has been removed.
Spring Boot does not depend directly upon Dropwizard Metrics and, therefore, does not require a specific version.
If your application depends on Dropwizard Metrics directly, update your build configuration to specify a version that meets its needs.



=== Prometheus Client 1.x
Spring Boot 3.3 includes https://github.com/prometheus/client_java/releases/tag/v1.0.0[support for the Prometheus Client 1.x].
This release of the client contains some breaking changes, e.g. changes to the exported metric names.
Use of the Prometheus Push Gateway is not supported with the 1.x client, until this support has been added from the Prometheus maintainers.

If you want to continue to use the 0.x version of the Prometheus client, remove `io.micrometer:micrometer-registry-prometheus` from your dependencies and add `io.micrometer:micrometer-registry-prometheus-simpleclient` instead.
Spring Boot contains auto-configuration for simpleclient in a deprecated form which will be removed in Spring Boot 3.5.0.

For a more detailed migration guide, please see https://github.com/micrometer-metrics/micrometer/wiki/1.13-Migration-Guide[this section] of the Micrometer wiki.



=== Flyway 10
This release upgrades to Flyway 10.
Flyway 10 is more modular than previous versions and support for several databases has been moved into a number of new, database-specific modules.
If you are using any of the following databases, update your dependencies accordingly:

- DB2 (`flyway-database-db2`)
- Derby (`flyway-database-derby`)
- HSQLDB (`flyway-database-hsqldb`)
- Informix (`flyway-database-informix`)
- PostgreSQL (`flyway-database-postgresql`)
- Redshift (`flyway-database-redshift`)
- SAP HANA (`flyway-database-saphana`)
- Snowflake (`flyway-database-snowflake`)
- Sybase ASE (`flyway-database-sybasease`)



=== Infinispan 15
This release upgrades to Infinispan 15.
Infinispan 15 has raised its Jakarta EE baseline and, as such, a number of its `-jakarta` modules, such as `infinispan-core-jakarta`, no longer exist. Use their standard alternatives, such as `infinispan-core`, instead.



=== Git Commit ID Maven Plugin
The plugin has been upgraded to 8.0.x.
As part of this upgrade, the default date format is now `yyyy-MM-dd'T'HH:mm:ssXXX`.
This provides compatibility with Maven's reproducible builds feature.



=== Minimum Requirements Changes



==== Native Build Tools
If you're using the Native Build Tools to build your project with GraalVM, make sure you're using at least a 0.10.x version of the plugin.
Maven users should get the correct version automatically when using the Spring Boot parent.

Gradle users should update the plugin version in the `plugins` block:

[source,groovy]
----
plugins {
  // ...
  id 'org.graalvm.buildtools.native' version '0.10.2'
  // ...
}
----

See https://github.com/spring-projects/spring-boot/issues/39068[#39068] for details.



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



=== CDS Support
https://docs.spring.io/spring-framework/reference/integration/cds.html[CDS] is a JVM feature that can help reduce the startup time and memory footprint of Java applications. Spring Boot now has support for easy creation of a CDS friendly layout. This layout can be created by  extracting the uber JAR with the help of the `tools` jarmode:

```
java -Djarmode=tools -jar your-application.jar extract
```

This creates a `your-application/your-application.jar` and the needed libraries in a `your-application/lib` folder. The application can then be executed with `java -jar your-application/your-application.jar`.

The `tools` jarmode supports two commands at the moment:

* `extract`, as shown above. This supersedes `-Djarmode=layertools extract`.
* `list-layers`, which supersedes `-Djarmode=layertools list-layers`.

Run

```
java -Djarmode=tools -jar your-application.jar help <command>
```

to get more details.

If you have used `layers.enabled = false` in your Gradle build file or `<layers><enabled>false</enabled></layers>` in your Maven `pom.xml`, please note that disabling layers no longer prevents the inclusion of the jarmode JAR. Use `includeTools` on the `BootJar` or `BootWar` task or `<configuration><includeTools>false</includeTools></configuration>` on the `spring-boot-maven-plugin` for that.



=== Observability Improvements
Observations can now be enabled for the simple, direct and stream listener and on the `RabbitTemplate` via properties.

Support for the Micrometer `@SpanTag` annotation has been added.

Added support for tagged fields for both Brave and OpenTelemetry.
Support for local fields has been added for Brave.

Added a process `InfoContributor`, which can be enabled with `management.info.process.enabled=true`.

If no application name is explicitly set, `unknown_service` is now used for OpenTelemetry.
This aligns the Spring Boot default to the OpenTelemetry specification.



==== Spring for Apache Pulsar
The properties `spring.pulsar.listener.observation-enabled` and `spring.pulsar.template.observations-enabled` changed their default value from `true` to `false`. This has been done to unify the `observation-enabled` properties, all of which now default to `false`. If you were relying on Pulsar observations and didn't enable them explicitly, add the properties `spring.pulsar.listener.observation-enabled=true` and `spring.pulsar.template.observations-enabled=true` to your configuration to restore the old behavior.



==== Brave and Zipkin
Brave has been updated to 6.0, and Zipkin to 3.0. With that upgrade, the Zipkin support in Spring Boot got new features, like specifying the encoding in which data is reported to the Zipkin API. See https://github.com/spring-projects/spring-boot/pull/39049[#39049] for details.

A new JDK `HttpClient` based Zipkin sender has been implemented. This sender only depends on the JDK and will be the default sender in Spring Boot 3.5.0, superseding the `WebClient` and `RestTemplate` sender implementations.



=== Spring for Apache Pulsar Improvements
There are now properties to configure cluster-level failover for Pulsar under the `spring.pulsar.client.failover` namespace.



=== Spring Security Improvements
A `JwtAuthenticationConverter` (or a `ReactiveJwtAuthenticationConverter`) is now auto-configured if one of the properties is set:

* `spring.security.oauth2.resourceserver.jwt.authority-prefix`
* `spring.security.oauth2.resourceserver.jwt.principal-claim-name`
* `spring.security.oauth2.resourceserver.jwt.authorities-claim-name`


=== Service Connections

==== Support for Apache ActiveMQ Artemis
Service connection support for Apache ActiveMQ Artemis has been added.
The Testcontainers support works with the `ArtemisContainer` container, the Docker Compose support works with the `apache/activemq-artemis` image.

==== Support for the official ActiveMQ Classic images
The ActiveMQ service connection now supports the `apache/activemq-classic` docker image and the `ActiveMQContainer` testcontainer.

==== Support for LDAP
Service connection support for LDAP with the `osixia/openldap` container has been added

==== Bitnami Container Images
The Spring Boot support for Docker Compose will detect and configure containers from https://bitnami.com/[Bitnami] in addition to official images for several of the supported technologies, including Cassandra, Elasticsearch, MariaDB, MySQL, MongoDB, Neo4j, PostgreSQL, RabbitMQ, and Redis. See the {reference-docs}/features/dev-services.html#features.dev-services.docker-compose[updated reference documentation] for more information.



=== Virtual Threads
If a `AsyncTaskExecutor` is available in the context, it is now registered on the websocket `ChannelRegistration`.
If using virtual threads, this will usually be a virtual threads enabled `SimpleAsyncTaskExecutor`, making Websockets virtual thread capable.



=== Batch Transaction Manager
A `@BatchTransactionManager` annotation has been introduced to make it easier to configure Spring Batch to use a custom transaction manager. 
See the https://docs.spring.io/spring-boot/3.3/how-to/batch.html#howto.batch.specifying-a-transaction-manager[updated documentation] for more information.



=== Base64 Resources
Resources can now be loaded as Base64 encoded text values using a `base64:` prefix. 
This can be useful with resources such as SSL certificates, as in this example: 

```
spring:
  ssl:
    bundle:
      pem:
        mybundle:
          keystore:
            certificate: "base64:LS0tLS1CRUdJTi..."
            private-key: "base64:QmFnIEF0dHJpYn..."
```



=== SBOM Actuator Endpoint
The `spring-boot-actuator` module now includes a new SBOM endpoint.
By default the endpoint will serve `META-INF/sbom/bom.json` or `META-INF/sbom/application.cdx.json` files located in your jar.

Additional configuration has also been provided in the `spring-boot-parent-starter` POM to make SBOM plugins easier to configure.
See the https://docs.spring.io/spring-boot/reference/actuator/endpoints.html#actuator.endpoints.sbom[documentation for more details].



=== Documentation Updates
The https://docs.spring.io/spring-boot/3.3/[Spring Boot documentation] has been migrated to Antora, providing more structure as well as better search capabilities.


=== Auto-configure Embedded Web Server SSL with SNI
When configuring a Tomcat, Netty, or Undertow embedded web server with SSL/TLS, it is now possible to configure multiple hostnames with unique trust material for each to support Server Name Indication (SNI). 
See the https://docs.spring.io/spring-boot/how-to/webserver.html#howto.webserver.configure-ssl[updated documentation] for more information on the configuration options. 



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

* https://github.com/spring-projects/spring-authorization-server/releases/tag/1.3.0[Spring Authorization Server 1.3.0]
* https://github.com/spring-projects/spring-data-commons/wiki/Spring-Data-2024.0-Release-Notes[Spring Data 2024.0.0]
* https://github.com/spring-projects/spring-graphql/releases/tag/v1.3.0-M1[Spring GraphQL 1.3.0]
* https://github.com/spring-projects/spring-hateoas/releases/tag/2.3.0[Spring HATEOAS 2.3.0]
* https://github.com/spring-projects/spring-integration/releases/tag/v6.3.0-M1[Spring Integration 6.3.0]
* https://github.com/spring-projects/spring-kafka/releases/tag/v3.2.0-M1[Spring Kafka 3.2.0]
* https://github.com/spring-projects/spring-pulsar/releases/tag/v1.1.0-M1[Spring Pulsar 1.1.0]
* https://github.com/spring-projects/spring-security/releases/tag/6.3.0[Spring Security 6.3.0]
* https://github.com/spring-projects/spring-session/releases/tag/3.3.0[Spring Session 3.3.0]

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



* https://github.com/assertj/assertj/releases/tag/assertj-build-3.25.0[AssertJ 3.25]
* https://github.com/openzipkin/brave/releases/tag/6.0.0[Brave 6.0]
* https://commons.apache.org/proper/commons-dbcp/changes-report.html#a2.12.0[Commons DBCP2 2.12]
* https://www.elastic.co/guide/en/elasticsearch/reference/8.13/es-release-notes.html[Elasticsearch Client 8.13]
* https://documentation.red-gate.com/flyway/release-notes-and-older-versions/release-notes-for-flyway-engine[Flyway 10.10]
* https://docs.hazelcast.com/operator/5.4/release-notes[Hazelcast 5.4]
* https://docs.jboss.org/hibernate/orm/6.5/migration-guide/migration-guide.html[Hibernate 6.5]
* HikariCP 5.1.0
* https://infinispan.org/blog/2024/03/13/infinispan-15[Infinispan 15.0]
* https://github.com/FasterXML/jackson/wiki/Jackson-Release-2.17[Jackson 2.17]
* JMustache 1.16
* https://downloads.apache.org/kafka/3.7.0/RELEASE_NOTES.html[Kafka 3.7]
* https://docs.liquibase.com/start/release-notes/liquibase-release-notes/liquibase-4.27.0.html[Liquibase 4.27]
* https://github.com/micrometer-metrics/micrometer/releases/tag/v1.13.0[Micrometer 1.13]
* https://github.com/micrometer-metrics/micrometer-tracing/releases/tag/v1.3.0[Micrometer Tracing 1.3.0]
* https://github.com/mockito/mockito/releases/tag/v5.11.0[Mockito 5.11]
* https://dev.mysql.com/doc/relnotes/mysql/8.3/en/news-8-3-0.html[MySQL 8.3]
* https://github.com/open-telemetry/opentelemetry-java/releases/tag/v1.37.0[OpenTelemetry 1.37]
* https://github.com/oracle/oracle-r2dbc/releases/tag/1.2.0[Oracle R2DBC 1.2.0]
* https://github.com/rabbitmq/rabbitmq-java-client/releases/tag/v5.21.0[Rabbit AMQP Client 5.21]
* https://github.com/rabbitmq/rabbitmq-stream-java-client/releases/tag/v0.15.0[Rabbit Stream Client 0.15]
* https://raw.githubusercontent.com/rest-assured/rest-assured/rest-assured-5.4.0/changelog.txt[REST Assured 5.4]



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

* `spring.config.activate.on-cloud-platform=none` will now match when the active cloud platform is `null`
* Added a configuration option for "path" field inclusion in error responses. This can be controlled by the `server.error.include-path` property. It defaults to `always`
* The WebFlux `DefaultErrorAttributes` now use `request.requestPath().value()` to populate path error attribute
* Added the property `server.tomcat.threads.max-queue-capacity` to configure the maximum queue size for the Tomcat web server connector
* The configuration processor now checks the `additional-spring-configuration-metadata.json` for superfluous keys and fails if it encounters any
* Added a property named `spring.task.execution.pool.shutdown.accept-tasks-after-context-close` to control if the `ThreadPoolTaskExecutor` accepts tasks after the context shutdown has been initiated
* Added the property `server.reactive.session.max-sessions` to control the number of maximum sessions when using WebFlux
* `ExecutionContextSerializer` beans are now automatically applied to the Spring Batch configuration.
  If none is provided, `DefaultExecutionContextSerializer` is used
* The started log messages produced by the four supported web servers (Jetty, Netty, Tomcat, and Undertow) are now more consistent
* Added `client-id` and `subscription-durable` properties for JMS connections
* If a class implements multiple servlet interfaces, like `Filter` or `Servlet`, it will now be registered for all of the interfaces (e.g. one registration for a filter and one for a servlet)
* The new reactive `sessions` actuator endpoint can now return sessions for a given username
* The environment's default profiles are now included in the env actuator endpoint's response
* Added the new property `spring.liquibase.ui-service` to specify the default UI service logger used by Liquibase
* Added the new property `spring.security.saml2.relyingparty.registration.*.name-id-format` to specify the NameID format of a SAML registration
* Added the new property `server.mime-mappings` which allows additional custom MIME type mappings to be configured
* `jakarta.inject:jakarta.inject-api` is now included in Spring Boot's dependency management
* The date format of the `git-commit-id-maven-plugin` has been changed to `yyyy-MM-dd'T'HH:mm:ssXXX` to allow reproducible builds. See https://github.com/spring-projects/spring-boot/pull/39606[#39606] for details
* The `spring-boot-starter-jetty` no longer includes `jetty-jndi` by default. If you need JNDI support, please add `org.eclipse.jetty:jetty-jndi` to your dependencies
* On Windows it's now possible to start the application with `mvn spring-boot:run` even if it has an extremely large number of dependencies. Before 3.3.0 it would fail with a "The filename or extension is too long" exception due to the length of the classpath
* The new property `spring.data.jdbc.dialect` can be used to set the dialect for Spring Data JDBC. If not set, the dialect will be auto-detected
* Add more gap between the orders of `CloudFoundryVcapEnvironmentPostProcessor` and `ConfigDataEnvironmentPostProcessor`
* The Cassandra driver changed coordinates from `com.datastax.oss` to `org.apache.cassandra`
* Setting the new property `management.observations.long-task-timer.enabled` to `false` now prevents the creation of a `LongTaskTimer` for every observation
* Beans in the infrastructure role are now automatically excluded from lazy initialization
* Spring Config now uses the conversion service from the environment when resolving properties
* Set the new property `spring.docker.compose.start.skip` to `never` to always execute the Docker Compose startup command
* A new `spring.graphql.websocket.keep-alive` property has been added
* JPA auto-configuration now uses a `ManagedClassNameFilter` bean if one is defined
* A new `spring.rabbitmq.template.allow-list-patterns` property has been added



== Deprecations in Spring Boot 3.3.0
* `ZipkinRestTemplateBuilderCustomizer` and `ZipkinWebClientBuilderCustomizer` in favor of the new `ZipkinHttpClientBuilderCustomizer`
* `-Djarmode=layertools extract` in favor of `-Djarmode=tools extract --layers`
* `-Djarmode=layertools list` in favor of `-Djarmode=tools list-layers`
* `layers.includeLayerTools` on the `BootJar` and `BootWar` task in favor of `includeTools`
* `<layers><enabled>...</enabled></layers>` in favor of `<includeTools>...</includeTools>`
* The `@ServletEndpoint`, `@ControllerEndpoint` and `@RestControllerEndpoint` annotations for declaring Actuator endpoints have been deprecated. Instead, applications should https://docs.spring.io/spring-boot/reference/actuator/endpoints.html#actuator.endpoints.implementing-custom[use the `@Endpoint` / `@ReadOperation` / `@WriteOperation` model for contributing endpoints]. See https://github.com/spring-projects/spring-boot/issues/31768#issuecomment-2057414222[#31768]
