Use fully-qualified names for ambiguous type references
Update type references to use a fully qualified name when we have more than one candidate available to us. See gh-41614
This commit is contained in:
@@ -63,7 +63,7 @@ Subject to xref:actuator/endpoints.adoc#actuator.endpoints.sanitization[sanitiza
|
||||
|
||||
| `liquibase`
|
||||
| Shows any Liquibase database migrations that have been applied.
|
||||
Requires one or more `Liquibase` beans.
|
||||
Requires one or more `liquibase.Liquibase` beans.
|
||||
|
||||
| `metrics`
|
||||
| Shows "`metrics`" information for the current application.
|
||||
@@ -223,14 +223,14 @@ NOTE: Before setting the `management.endpoints.web.exposure.include`, ensure tha
|
||||
If Spring Security is on the classpath and no other `SecurityFilterChain` bean is present, all actuators other than `/health` are secured by Spring Boot auto-configuration.
|
||||
If you define a custom `SecurityFilterChain` bean, Spring Boot auto-configuration backs off and lets you fully control the actuator access rules.
|
||||
|
||||
If you wish to configure custom security for HTTP endpoints (for example, to allow only users with a certain role to access them), Spring Boot provides some convenient `RequestMatcher` objects that you can use in combination with Spring Security.
|
||||
If you wish to configure custom security for HTTP endpoints (for example, to allow only users with a certain role to access them), Spring Boot provides some convenient `org.springframework.security.web.util.matcher.RequestMatcher` objects that you can use in combination with Spring Security.
|
||||
|
||||
A typical Spring Security configuration might look something like the following example:
|
||||
|
||||
include-code::typical/MySecurityConfiguration[]
|
||||
|
||||
The preceding example uses `EndpointRequest.toAnyEndpoint()` to match a request to any endpoint and then ensures that all have the `ENDPOINT_ADMIN` role.
|
||||
Several other matcher methods are also available on `EndpointRequest`.
|
||||
Several other matcher methods are also available on `org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest`.
|
||||
See the xref:api:rest/actuator/index.adoc[API documentation] for details.
|
||||
|
||||
If you deploy applications behind a firewall, you may prefer that all your actuator endpoints can be accessed without requiring authentication.
|
||||
@@ -427,7 +427,7 @@ This will happen automatically if you use Spring Boot's Gradle plugin or if you
|
||||
==== Input Type Conversion
|
||||
|
||||
The parameters passed to endpoint operation methods are, if necessary, automatically converted to the required type.
|
||||
Before calling an operation method, the input received over JMX or HTTP is converted to the required types by using an instance of `ApplicationConversionService` as well as any `Converter` or `GenericConverter` beans qualified with `@EndpointConverter`.
|
||||
Before calling an operation method, the input received over JMX or HTTP is converted to the required types by using an instance of `ApplicationConversionService` as well as any `org.springframework.core.convert.converter.Converter` or `org.springframework.core.convert.converter.GenericConverter` beans qualified with `@EndpointConverter`.
|
||||
|
||||
|
||||
|
||||
@@ -453,7 +453,7 @@ The path of the predicate is determined by the ID of the endpoint and the base p
|
||||
The default base path is `/actuator`.
|
||||
For example, an endpoint with an ID of `sessions` uses `/actuator/sessions` as its path in the predicate.
|
||||
|
||||
You can further customize the path by annotating one or more parameters of the operation method with `@Selector`.
|
||||
You can further customize the path by annotating one or more parameters of the operation method with `@org.springframework.boot.actuate.endpoint.annotation.Selector`.
|
||||
Such a parameter is added to the path predicate as a path variable.
|
||||
The variable's value is passed into the operation method when the endpoint operation is invoked.
|
||||
If you want to capture all remaining path elements, you can add `@Selector(Match=ALL_REMAINING)` to the last parameter and make it a type that is conversion-compatible with a `String[]`.
|
||||
@@ -569,7 +569,7 @@ Health information is collected from the content of a javadoc:org.springframewor
|
||||
Spring Boot includes a number of auto-configured `HealthContributor` beans, and you can also write your own.
|
||||
|
||||
A `HealthContributor` can be either a `HealthIndicator` or a `CompositeHealthContributor`.
|
||||
A `HealthIndicator` provides actual health information, including a `Status`.
|
||||
A `HealthIndicator` provides actual health information, including a `org.springframework.boot.actuate.health.Status`.
|
||||
A `CompositeHealthContributor` provides a composite of other `HealthContributor` instances.
|
||||
Taken together, contributors form a tree structure to represent the overall system health.
|
||||
|
||||
@@ -689,10 +689,10 @@ TIP: Health indicators are usually called over HTTP and need to respond before a
|
||||
Spring Boot will log a warning message for any health indicator that takes longer than 10 seconds to respond.
|
||||
If you want to configure this threshold, you can use the configprop:management.endpoint.health.logging.slow-indicator-threshold[] property.
|
||||
|
||||
In addition to Spring Boot's predefined javadoc:org.springframework.boot.actuate.health.Status[] types, `Health` can return a custom `Status` that represents a new system state.
|
||||
In addition to Spring Boot's predefined `org.springframework.boot.actuate.health.Status` types, `Health` can return a custom `org.springframework.boot.actuate.health.Status` that represents a new system state.
|
||||
In such cases, you also need to provide a custom implementation of the javadoc:org.springframework.boot.actuate.health.StatusAggregator[] interface, or you must configure the default implementation by using the configprop:management.endpoint.health.status.order[] configuration property.
|
||||
|
||||
For example, assume a new `Status` with a code of `FATAL` is being used in one of your `HealthIndicator` implementations.
|
||||
For example, assume a new `org.springframework.boot.actuate.health.Status` with a code of `FATAL` is being used in one of your `HealthIndicator` implementations.
|
||||
To configure the severity order, add the following property to your application properties:
|
||||
|
||||
[configprops,yaml]
|
||||
|
||||
@@ -5,7 +5,7 @@ Java Management Extensions (JMX) provide a standard mechanism to monitor and man
|
||||
By default, this feature is not enabled.
|
||||
You can turn it on by setting the configprop:spring.jmx.enabled[] configuration property to `true`.
|
||||
Spring Boot exposes the most suitable `MBeanServer` as a bean with an ID of `mbeanServer`.
|
||||
Any of your beans that are annotated with Spring JMX annotations (`@ManagedResource`, `@ManagedAttribute`, or `@ManagedOperation`) are exposed to it.
|
||||
Any of your beans that are annotated with Spring JMX annotations (`@org.springframework.jmx.export.annotation.ManagedResource`, `@org.springframework.jmx.export.annotation.ManagedAttribute`, or `@org.springframework.jmx.export.annotation.ManagedOperation`) are exposed to it.
|
||||
|
||||
If your platform provides a standard `MBeanServer`, Spring Boot uses that and defaults to the VM `MBeanServer`, if necessary.
|
||||
If all that fails, a new `MBeanServer` is created.
|
||||
|
||||
@@ -57,7 +57,7 @@ management:
|
||||
enabled: false
|
||||
----
|
||||
|
||||
Spring Boot also adds any auto-configured registries to the global static composite registry on the `Metrics` class, unless you explicitly tell it not to:
|
||||
Spring Boot also adds any auto-configured registries to the global static composite registry on the `io.micrometer.core.instrument.Metrics` class, unless you explicitly tell it not to:
|
||||
|
||||
[configprops,yaml]
|
||||
----
|
||||
@@ -364,7 +364,7 @@ Micrometer provides a default `HierarchicalNameMapper` that governs how a dimens
|
||||
[TIP]
|
||||
====
|
||||
To take control over this behavior, define your `GraphiteMeterRegistry` and supply your own `HierarchicalNameMapper`.
|
||||
An auto-configured `GraphiteConfig` and `Clock` beans are provided unless you define your own:
|
||||
Auto-configured `GraphiteConfig` and `io.micrometer.core.instrument.Clock` beans are provided unless you define your own:
|
||||
|
||||
include-code::MyGraphiteConfiguration[]
|
||||
====
|
||||
@@ -440,7 +440,7 @@ Micrometer provides a default `HierarchicalNameMapper` that governs how a dimens
|
||||
[TIP]
|
||||
====
|
||||
To take control over this behavior, define your `JmxMeterRegistry` and supply your own `HierarchicalNameMapper`.
|
||||
An auto-configured `JmxConfig` and `Clock` beans are provided unless you define your own:
|
||||
Auto-configured `JmxConfig` and `io.micrometer.core.instrument.Clock` beans are provided unless you define your own:
|
||||
|
||||
include-code::MyJmxConfiguration[]
|
||||
====
|
||||
@@ -543,7 +543,7 @@ scrape_configs:
|
||||
----
|
||||
|
||||
https://prometheus.io/docs/prometheus/latest/feature_flags/#exemplars-storage[Prometheus Exemplars] are also supported.
|
||||
To enable this feature, a `SpanContext` bean should be present.
|
||||
To enable this feature, a `io.prometheus.metrics.tracer.common.SpanContext` bean should be present.
|
||||
If you're using the deprecated Prometheus simpleclient support and want to enable that feature, a `SpanContextSupplier` bean should be present.
|
||||
If you use {url-micrometer-tracing-docs}[Micrometer Tracing], this will be auto-configured for you, but you can always create your own if you want.
|
||||
Please check the https://prometheus.io/docs/prometheus/latest/feature_flags/#exemplars-storage[Prometheus Docs], since this feature needs to be explicitly enabled on Prometheus' side, and it is only supported using the https://github.com/OpenObservability/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#exemplars[OpenMetrics] format.
|
||||
@@ -801,8 +801,8 @@ You can customize the name by setting the configprop:management.observations.htt
|
||||
|
||||
See the {url-spring-framework-docs}/integration/observability.html#observability.http-server.servlet[Spring Framework reference documentation for more information on produced observations].
|
||||
|
||||
To add to the default tags, provide a `@Bean` that extends `DefaultServerRequestObservationConvention` from the `org.springframework.http.server.observation` package.
|
||||
To replace the default tags, provide a `@Bean` that implements `ServerRequestObservationConvention`.
|
||||
To add to the default tags, provide a `@Bean` that extends `org.springframework.http.server.observation.DefaultServerRequestObservationConvention` from the `org.springframework.http.server.observation` package.
|
||||
To replace the default tags, provide a `@Bean` that implements `org.springframework.http.server.observation.ServerRequestObservationConvention`.
|
||||
|
||||
|
||||
TIP: In some cases, exceptions handled in web controllers are not recorded as request metrics tags.
|
||||
@@ -822,8 +822,8 @@ You can customize the name by setting the configprop:management.observations.htt
|
||||
|
||||
See the {url-spring-framework-docs}/integration/observability.html#observability.http-server.reactive[Spring Framework reference documentation for more information on produced observations].
|
||||
|
||||
To add to the default tags, provide a `@Bean` that extends `DefaultServerRequestObservationConvention` from the `org.springframework.http.server.reactive.observation` package.
|
||||
To replace the default tags, provide a `@Bean` that implements `ServerRequestObservationConvention`.
|
||||
To add to the default tags, provide a `@Bean` that extends `org.springframework.http.server.reactive.observation.DefaultServerRequestObservationConvention` from the `org.springframework.http.server.reactive.observation` package.
|
||||
To replace the default tags, provide a `@Bean` that implements `org.springframework.http.server.reactive.observation.ServerRequestObservationConvention`.
|
||||
|
||||
TIP: In some cases, exceptions handled in controllers and handler functions are not recorded as request metrics tags.
|
||||
Applications can opt in and record exceptions by xref:web/reactive.adoc#web.reactive.webflux.error-handling[setting handled exceptions as request attributes].
|
||||
@@ -880,8 +880,8 @@ You can customize the name by setting the configprop:management.observations.htt
|
||||
|
||||
See the {url-spring-framework-docs}/integration/observability.html#observability.http-client[Spring Framework reference documentation for more information on produced observations].
|
||||
|
||||
To customize the tags when using `RestTemplate` or `RestClient`, provide a `@Bean` that implements `ClientRequestObservationConvention` from the `org.springframework.http.client.observation` package.
|
||||
To customize the tags when using `WebClient`, provide a `@Bean` that implements `ClientRequestObservationConvention` from the `org.springframework.web.reactive.function.client` package.
|
||||
To customize the tags when using `RestTemplate` or `RestClient`, provide a `@Bean` that implements `org.springframework.http.client.observation.ClientRequestObservationConvention` from the `org.springframework.http.client.observation` package.
|
||||
To customize the tags when using `WebClient`, provide a `@Bean` that implements `org.springframework.web.reactive.function.client.ClientRequestObservationConvention` from the `org.springframework.web.reactive.function.client` package.
|
||||
|
||||
|
||||
|
||||
@@ -898,7 +898,7 @@ Tomcat metrics are published under the `tomcat.` meter name.
|
||||
[[actuator.metrics.supported.cache]]
|
||||
=== Cache Metrics
|
||||
|
||||
Auto-configuration enables the instrumentation of all available `Cache` instances on startup, with metrics prefixed with `cache`.
|
||||
Auto-configuration enables the instrumentation of all available `org.springframework.cache.Cache` instances on startup, with metrics prefixed with `cache`.
|
||||
Cache instrumentation is standardized for a basic set of metrics.
|
||||
Additional, cache-specific metrics are also available.
|
||||
|
||||
@@ -910,7 +910,7 @@ The following cache libraries are supported:
|
||||
* Any compliant JCache (JSR-107) implementation
|
||||
* Redis
|
||||
|
||||
Metrics are tagged by the name of the cache and by the name of the `CacheManager`, which is derived from the bean name.
|
||||
Metrics are tagged by the name of the cache and by the name of the `org.springframework.cache.CacheManager`, which is derived from the bean name.
|
||||
|
||||
NOTE: Only caches that are configured on startup are bound to the registry.
|
||||
For caches not defined in the cache’s configuration, such as caches created on the fly or programmatically after the startup phase, an explicit registration is required.
|
||||
@@ -972,14 +972,14 @@ spring:
|
||||
[[actuator.metrics.supported.spring-data-repository]]
|
||||
=== Spring Data Repository Metrics
|
||||
|
||||
Auto-configuration enables the instrumentation of all Spring Data `Repository` method invocations.
|
||||
Auto-configuration enables the instrumentation of all Spring Data `org.springframework.data.repository.Repository` method invocations.
|
||||
By default, metrics are generated with the name, `spring.data.repository.invocations`.
|
||||
You can customize the name by setting the configprop:management.metrics.data.repository.metric-name[] property.
|
||||
|
||||
The `@Timed` annotation from the `io.micrometer.core.annotation` package is supported on `Repository` interfaces and methods.
|
||||
If you do not want to record metrics for all `Repository` invocations, you can set configprop:management.metrics.data.repository.autotime.enabled[] to `false` and exclusively use `@Timed` annotations instead.
|
||||
The `@io.micrometer.core.annotation.Timed` annotation from the `io.micrometer.core.annotation` package is supported on `org.springframework.data.repository.Repository` interfaces and methods.
|
||||
If you do not want to record metrics for all `org.springframework.data.repository.Repository` invocations, you can set configprop:management.metrics.data.repository.autotime.enabled[] to `false` and exclusively use `@io.micrometer.core.annotation.Timed` annotations instead.
|
||||
|
||||
NOTE: A `@Timed` annotation with `longTask = true` enables a long task timer for the method.
|
||||
NOTE: A `@io.micrometer.core.annotation.Timed` annotation with `longTask = true` enables a long task timer for the method.
|
||||
Long task timers require a separate metric name and can be stacked with a short task timer.
|
||||
|
||||
By default, repository invocation related metrics are tagged with the following information:
|
||||
@@ -988,10 +988,10 @@ By default, repository invocation related metrics are tagged with the following
|
||||
| Tag | Description
|
||||
|
||||
| `repository`
|
||||
| The simple class name of the source `Repository`.
|
||||
| The simple class name of the source `org.springframework.data.repository.Repository`.
|
||||
|
||||
| `method`
|
||||
| The name of the `Repository` method that was invoked.
|
||||
| The name of the `org.springframework.data.repository.Repository` method that was invoked.
|
||||
|
||||
| `state`
|
||||
| The result state (`SUCCESS`, `ERROR`, `CANCELED`, or `RUNNING`).
|
||||
@@ -1117,15 +1117,15 @@ management:
|
||||
[[actuator.metrics.supported.jetty]]
|
||||
=== Jetty Metrics
|
||||
|
||||
Auto-configuration binds metrics for Jetty's `ThreadPool` by using Micrometer's `JettyServerThreadPoolMetrics`.
|
||||
Metrics for Jetty's `Connector` instances are bound by using Micrometer's `JettyConnectionMetrics` and, when configprop:server.ssl.enabled[] is set to `true`, Micrometer's `JettySslHandshakeMetrics`.
|
||||
Auto-configuration binds metrics for Jetty's `org.eclipse.jetty.util.thread.ThreadPool` by using Micrometer's `JettyServerThreadPoolMetrics`.
|
||||
Metrics for Jetty's `org.eclipse.jetty.server.Connector` instances are bound by using Micrometer's `JettyConnectionMetrics` and, when configprop:server.ssl.enabled[] is set to `true`, Micrometer's `JettySslHandshakeMetrics`.
|
||||
|
||||
|
||||
|
||||
[[actuator.metrics.supported.timed-annotation]]
|
||||
=== @Timed Annotation Support
|
||||
|
||||
To enable scanning of `@Timed` annotations, you will need to set the configprop:management.observations.annotations.enabled[] property to `true`.
|
||||
To enable scanning of `@io.micrometer.core.annotation.Timed` annotations, you will need to set the configprop:management.observations.annotations.enabled[] property to `true`.
|
||||
Please refer to the {url-micrometer-docs-concepts}/timers.html#_the_timed_annotation[Micrometer documentation].
|
||||
|
||||
|
||||
@@ -1166,7 +1166,7 @@ For example, if you want to rename the `mytag.region` tag to `mytag.area` for al
|
||||
include-code::MyMetricsFilterConfiguration[]
|
||||
|
||||
NOTE: By default, all `MeterFilter` beans are automatically bound to the Spring-managed `MeterRegistry`.
|
||||
Make sure to register your metrics by using the Spring-managed `MeterRegistry` and not any of the static methods on `Metrics`.
|
||||
Make sure to register your metrics by using the Spring-managed `MeterRegistry` and not any of the static methods on `io.micrometer.core.instrument.Metrics`.
|
||||
These use the global registry that is not Spring-managed.
|
||||
|
||||
|
||||
|
||||
@@ -90,9 +90,9 @@ the metrics and traces use the semantic conventions described in the Spring proj
|
||||
Spring Boot's actuator module includes basic support for OpenTelemetry.
|
||||
|
||||
It provides a bean of type `OpenTelemetry`, and if there are beans of type `SdkTracerProvider`, `ContextPropagators`, `SdkLoggerProvider` or `SdkMeterProvider` in the application context, they automatically get registered.
|
||||
Additionally, it provides a `Resource` bean.
|
||||
The attributes of the auto-configured `Resource` can be configured via the configprop:management.opentelemetry.resource-attributes[] configuration property.
|
||||
If you have defined your own `Resource` bean, this will no longer be the case.
|
||||
Additionally, it provides a `io.opentelemetry.sdk.resources.Resource` bean.
|
||||
The attributes of the auto-configured `io.opentelemetry.sdk.resources.Resource` can be configured via the configprop:management.opentelemetry.resource-attributes[] configuration property.
|
||||
If you have defined your own `io.opentelemetry.sdk.resources.Resource` bean, this will no longer be the case.
|
||||
|
||||
NOTE: Spring Boot does not provide auto-configuration for OpenTelemetry metrics or logging.
|
||||
OpenTelemetry tracing is only auto-configured when used together with xref:actuator/tracing.adoc[Micrometer Tracing].
|
||||
@@ -104,5 +104,5 @@ The next sections will provide more details about logging, metrics and traces.
|
||||
[[actuator.observability.annotations]]
|
||||
== Micrometer Observation Annotations support
|
||||
|
||||
To enable scanning of metrics and tracing annotations like `@Timed`, `@Counted`, `@MeterTag` and `@NewSpan` annotations, you will need to set the configprop:management.observations.annotations.enabled[] property to `true`.
|
||||
To enable scanning of metrics and tracing annotations like `@io.micrometer.core.annotation.Timed`, `@Counted`, `@MeterTag` and `@NewSpan` annotations, you will need to set the configprop:management.observations.annotations.enabled[] property to `true`.
|
||||
This feature is supported Micrometer directly. Please refer to the {url-micrometer-docs-concepts}/timers.html#_the_timed_annotation[Micrometer] and {url-micrometer-tracing-docs}/api.html#_aspect_oriented_programming[Micrometer Tracing] reference docs.
|
||||
|
||||
@@ -197,7 +197,7 @@ TIP: If you want to create a span without creating a metric, you need to use the
|
||||
[[actuator.micrometer-tracing.baggage]]
|
||||
== Baggage
|
||||
|
||||
You can create baggage with the `Tracer` API:
|
||||
You can create baggage with the `io.micrometer.tracing.Tracer` API:
|
||||
|
||||
include-code::CreatingBaggage[]
|
||||
|
||||
|
||||
@@ -243,7 +243,7 @@ Spring Boot offers several conveniences for working with Neo4j, including the `s
|
||||
|
||||
To access a Neo4j server, you can inject an auto-configured `org.neo4j.driver.Driver`.
|
||||
By default, the instance tries to connect to a Neo4j server at `localhost:7687` using the Bolt protocol.
|
||||
The following example shows how to inject a Neo4j `Driver` that gives you access, amongst other things, to a `Session`:
|
||||
The following example shows how to inject a Neo4j `org.neo4j.driver.Driver` that gives you access, amongst other things, to a `org.neo4j.driver.Session`:
|
||||
|
||||
include-code::MyBean[]
|
||||
|
||||
@@ -260,9 +260,9 @@ spring:
|
||||
password: "secret"
|
||||
----
|
||||
|
||||
The auto-configured `Driver` is created using `ConfigBuilder`.
|
||||
The auto-configured `org.neo4j.driver.Driver` is created using `org.neo4j.driver.Config$ConfigBuilder`.
|
||||
To fine-tune its configuration, declare one or more `ConfigBuilderCustomizer` beans.
|
||||
Each will be called in order with the `ConfigBuilder` that is used to build the `Driver`.
|
||||
Each will be called in order with the `org.neo4j.driver.Config$ConfigBuilder` that is used to build the `org.neo4j.driver.Driver`.
|
||||
|
||||
|
||||
|
||||
@@ -273,7 +273,7 @@ Spring Data includes repository support for Neo4j.
|
||||
For complete details of Spring Data Neo4j, see the {url-spring-data-neo4j-docs}[reference documentation].
|
||||
|
||||
Spring Data Neo4j shares the common infrastructure with Spring Data JPA as many other Spring Data modules do.
|
||||
You could take the JPA example from earlier and define `+City+` as Spring Data Neo4j `@Node` rather than JPA `@Entity` and the repository abstraction works in the same way, as shown in the following example:
|
||||
You could take the JPA example from earlier and define `+City+` as Spring Data Neo4j `@org.springframework.data.neo4j.core.schema.Node` rather than JPA `@Entity` and the repository abstraction works in the same way, as shown in the following example:
|
||||
|
||||
include-code::CityRepository[]
|
||||
|
||||
@@ -336,7 +336,7 @@ spring:
|
||||
|
||||
If you have `elasticsearch-rest-client` on the classpath, Spring Boot will auto-configure and register a `RestClient` bean.
|
||||
In addition to the properties described previously, to fine-tune the `RestClient` you can register an arbitrary number of beans that implement `RestClientBuilderCustomizer` for more advanced customizations.
|
||||
To take full control over the clients' configuration, define a `RestClientBuilder` bean.
|
||||
To take full control over the clients' configuration, define a `org.elasticsearch.client.RestClientBuilder` bean.
|
||||
|
||||
|
||||
|
||||
@@ -401,7 +401,7 @@ Spring Data includes repository support for Elasticsearch.
|
||||
As with the JPA repositories discussed earlier, the basic principle is that queries are constructed for you automatically based on method names.
|
||||
|
||||
In fact, both Spring Data JPA and Spring Data Elasticsearch share the same common infrastructure.
|
||||
You could take the JPA example from earlier and, assuming that `+City+` is now an Elasticsearch `@Document` class rather than a JPA `@Entity`, it works in the same way.
|
||||
You could take the JPA example from earlier and, assuming that `+City+` is now an Elasticsearch `@org.springframework.data.elasticsearch.annotations.Document` class rather than a JPA `@Entity`, it works in the same way.
|
||||
|
||||
Repositories and documents are found through scanning.
|
||||
By default, the xref:using/auto-configuration.adoc#using.auto-configuration.packages[auto-configuration packages] are scanned.
|
||||
@@ -519,7 +519,7 @@ If you add your own `@Bean` of type `CassandraTemplate`, it replaces the default
|
||||
=== Spring Data Cassandra Repositories
|
||||
|
||||
Spring Data includes basic repository support for Cassandra.
|
||||
Currently, this is more limited than the JPA repositories discussed earlier and needs `@Query` annotated finder methods.
|
||||
Currently, this is more limited than the JPA repositories discussed earlier and needs `@org.springframework.data.cassandra.repository.Query` annotated finder methods.
|
||||
|
||||
Repositories and entities are found through scanning.
|
||||
By default, the xref:using/auto-configuration.adoc#using.auto-configuration.packages[auto-configuration packages] are scanned.
|
||||
@@ -541,7 +541,7 @@ There are `spring-boot-starter-data-couchbase` and `spring-boot-starter-data-cou
|
||||
[[data.nosql.couchbase.connecting]]
|
||||
=== Connecting to Couchbase
|
||||
|
||||
You can get a `Cluster` by adding the Couchbase SDK and some configuration.
|
||||
You can get a `com.couchbase.client.java.Cluster` by adding the Couchbase SDK and some configuration.
|
||||
The `spring.couchbase.*` properties can be used to customize the connection.
|
||||
Generally, you provide the https://github.com/couchbaselabs/sdk-rfcs/blob/master/rfc/0011-connection-string.md[connection string], username, and password, as shown in the following example:
|
||||
|
||||
@@ -555,7 +555,7 @@ spring:
|
||||
----
|
||||
|
||||
It is also possible to customize some of the `ClusterEnvironment` settings.
|
||||
For instance, the following configuration changes the timeout to open a new `Bucket` and enables SSL support with a reference to a configured xref:features/ssl.adoc[SSL bundle]:
|
||||
For instance, the following configuration changes the timeout to open a new `com.couchbase.client.java.Bucket` and enables SSL support with a reference to a configured xref:features/ssl.adoc[SSL bundle]:
|
||||
|
||||
[configprops,yaml]
|
||||
----
|
||||
@@ -585,7 +585,7 @@ You can customize the locations to look for repositories and documents by using
|
||||
For complete details of Spring Data Couchbase, see the {url-spring-data-couchbase-docs}[reference documentation].
|
||||
|
||||
You can inject an auto-configured `CouchbaseTemplate` instance as you would with any other Spring Bean, provided a `CouchbaseClientFactory` bean is available.
|
||||
This happens when a `Cluster` is available, as described above, and a bucket name has been specified:
|
||||
This happens when a `com.couchbase.client.java.Cluster` is available, as described above, and a bucket name has been specified:
|
||||
|
||||
[configprops,yaml]
|
||||
----
|
||||
@@ -602,10 +602,10 @@ include-code::MyBean[]
|
||||
There are a few beans that you can define in your own configuration to override those provided by the auto-configuration:
|
||||
|
||||
* A `CouchbaseMappingContext` `@Bean` with a name of `couchbaseMappingContext`.
|
||||
* A `CustomConversions` `@Bean` with a name of `couchbaseCustomConversions`.
|
||||
* A `org.springframework.data.convert.CustomConversions` `@Bean` with a name of `couchbaseCustomConversions`.
|
||||
* A `CouchbaseTemplate` `@Bean` with a name of `couchbaseTemplate`.
|
||||
|
||||
To avoid hard-coding those names in your own config, you can reuse `BeanNames` provided by Spring Data Couchbase.
|
||||
To avoid hard-coding those names in your own config, you can reuse `org.springframework.data.couchbase.config.BeanNames` provided by Spring Data Couchbase.
|
||||
For instance, you can customize the converters to use, as follows:
|
||||
|
||||
include-code::MyCouchbaseConfiguration[]
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
= SQL Databases
|
||||
|
||||
The {url-spring-framework-site}[Spring Framework] provides extensive support for working with SQL databases, from direct JDBC access using `JdbcClient` or `JdbcTemplate` to complete "`object relational mapping`" technologies such as Hibernate.
|
||||
{url-spring-data-site}[Spring Data] provides an additional level of functionality: creating `Repository` implementations directly from interfaces and using conventions to generate queries from your method names.
|
||||
{url-spring-data-site}[Spring Data] provides an additional level of functionality: creating `org.springframework.data.repository.Repository` implementations directly from interfaces and using conventions to generate queries from your method names.
|
||||
|
||||
|
||||
|
||||
@@ -90,7 +90,7 @@ Otherwise, Spring Boot tries to auto-configure an embedded database.
|
||||
TIP: Spring Boot can deduce the JDBC driver class for most databases from the URL.
|
||||
If you need to specify a specific class, you can use the configprop:spring.datasource.driver-class-name[] property.
|
||||
|
||||
NOTE: For a pooling `DataSource` to be created, we need to be able to verify that a valid `Driver` class is available, so we check for that before doing anything.
|
||||
NOTE: For a pooling `DataSource` to be created, we need to be able to verify that a valid `java.sql.Driver` class is available, so we check for that before doing anything.
|
||||
In other words, if you set `spring.datasource.driver-class-name=com.mysql.jdbc.Driver`, then that class has to be loadable.
|
||||
|
||||
See javadoc:org.springframework.boot.autoconfigure.jdbc.DataSourceProperties[] API documentation for more of the supported options.
|
||||
@@ -219,7 +219,7 @@ Traditionally, JPA "`Entity`" classes are specified in a `persistence.xml` file.
|
||||
With Spring Boot, this file is not necessary and "`Entity Scanning`" is used instead.
|
||||
By default the xref:using/auto-configuration.adoc#using.auto-configuration.packages[auto-configuration packages] are scanned.
|
||||
|
||||
Any classes annotated with `@Entity`, `@Embeddable`, or `@MappedSuperclass` are considered.
|
||||
Any classes annotated with `@jakarta.persistence.Entity`, `@jakarta.persistence.Embeddable`, or `@jakarta.persistence.MappedSuperclass` are considered.
|
||||
A typical entity class resembles the following example:
|
||||
|
||||
include-code::City[]
|
||||
@@ -249,7 +249,7 @@ include-code::CityRepository[]
|
||||
|
||||
Spring Data JPA repositories support three different modes of bootstrapping: default, deferred, and lazy.
|
||||
To enable deferred or lazy bootstrapping, set the configprop:spring.data.jpa.repositories.bootstrap-mode[] property to `deferred` or `lazy` respectively.
|
||||
When using deferred or lazy bootstrapping, the auto-configured `EntityManagerFactoryBuilder` will use the context's `AsyncTaskExecutor`, if any, as the bootstrap executor.
|
||||
When using deferred or lazy bootstrapping, the auto-configured `org.springframework.boot.orm.jpa.EntityManagerFactoryBuilder` will use the context's `AsyncTaskExecutor`, if any, as the bootstrap executor.
|
||||
If more than one exists, the one named `applicationTaskExecutor` will be used.
|
||||
|
||||
[NOTE]
|
||||
@@ -322,7 +322,7 @@ If you do not want this behavior, you should set `spring.jpa.open-in-view` to `f
|
||||
== Spring Data JDBC
|
||||
|
||||
Spring Data includes repository support for JDBC and will automatically generate SQL for the methods on `CrudRepository`.
|
||||
For more advanced queries, a `@Query` annotation is provided.
|
||||
For more advanced queries, a `@org.springframework.data.jdbc.repository.query.Query` annotation is provided.
|
||||
|
||||
Spring Boot will auto-configure Spring Data's JDBC repositories when the necessary dependencies are on the classpath.
|
||||
They can be added to your project with a single dependency on `spring-boot-starter-data-jdbc`.
|
||||
@@ -466,9 +466,9 @@ You can also create your own `org.jooq.Configuration` `@Bean` if you want to tak
|
||||
|
||||
The Reactive Relational Database Connectivity (https://r2dbc.io[R2DBC]) project brings reactive programming APIs to relational databases.
|
||||
R2DBC's `io.r2dbc.spi.Connection` provides a standard method of working with non-blocking database connections.
|
||||
Connections are provided by using a `ConnectionFactory`, similar to a `DataSource` with jdbc.
|
||||
Connections are provided by using a `io.r2dbc.spi.ConnectionFactory`, similar to a `DataSource` with jdbc.
|
||||
|
||||
`ConnectionFactory` configuration is controlled by external configuration properties in `+spring.r2dbc.*+`.
|
||||
`io.r2dbc.spi.ConnectionFactory` configuration is controlled by external configuration properties in `+spring.r2dbc.*+`.
|
||||
For example, you might declare the following section in `application.properties`:
|
||||
|
||||
[configprops,yaml]
|
||||
@@ -487,7 +487,7 @@ Information specified in the URL takes precedence over individual properties, th
|
||||
|
||||
TIP: The "`How-to Guides`" section includes a xref:how-to:data-initialization.adoc#howto.data-initialization.using-basic-sql-scripts[section on how to initialize a database].
|
||||
|
||||
To customize the connections created by a `ConnectionFactory`, that is, set specific parameters that you do not want (or cannot) configure in your central database configuration, you can use a `ConnectionFactoryOptionsBuilderCustomizer` `@Bean`.
|
||||
To customize the connections created by a `io.r2dbc.spi.ConnectionFactory`, that is, set specific parameters that you do not want (or cannot) configure in your central database configuration, you can use a `ConnectionFactoryOptionsBuilderCustomizer` `@Bean`.
|
||||
The following example shows how to manually override the database port while the rest of the options are taken from the application configuration:
|
||||
|
||||
include-code::MyR2dbcConfiguration[]
|
||||
@@ -496,7 +496,7 @@ The following examples show how to set some PostgreSQL connection options:
|
||||
|
||||
include-code::MyPostgresR2dbcConfiguration[]
|
||||
|
||||
When a `ConnectionFactory` bean is available, the regular JDBC `DataSource` auto-configuration backs off.
|
||||
When a `io.r2dbc.spi.ConnectionFactory` bean is available, the regular JDBC `DataSource` auto-configuration backs off.
|
||||
If you want to retain the JDBC `DataSource` auto-configuration, and are comfortable with the risk of using the blocking JDBC API in a reactive application, add `@Import(DataSourceAutoConfiguration.class)` on a `@Configuration` class in your application to re-enable it.
|
||||
|
||||
|
||||
|
||||
@@ -328,7 +328,7 @@ The `+TestMyApplication+` class can use the `SpringApplication.from(...)` method
|
||||
|
||||
include-code::launch/TestMyApplication[]
|
||||
|
||||
You'll also need to define the `Container` instances that you want to start along with your application.
|
||||
You'll also need to define the `org.testcontainers.containers.Container` instances that you want to start along with your application.
|
||||
To do this, you need to make sure that the `spring-boot-testcontainers` module has been added as a `test` dependency.
|
||||
Once that has been done, you can create a `@TestConfiguration` class that declares `@Bean` methods for the containers you want to start.
|
||||
|
||||
@@ -339,7 +339,7 @@ A typical Testcontainers configuration would look like this:
|
||||
|
||||
include-code::test/MyContainersConfiguration[]
|
||||
|
||||
NOTE: The lifecycle of `Container` beans is automatically managed by Spring Boot.
|
||||
NOTE: The lifecycle of `org.testcontainers.containers.Container` beans is automatically managed by Spring Boot.
|
||||
Containers will be started and stopped automatically.
|
||||
|
||||
TIP: You can use the configprop:spring.testcontainers.beans.startup[] property to change how containers are started.
|
||||
@@ -358,7 +358,7 @@ TIP: You can use the Maven goal `spring-boot:test-run` or the Gradle task `bootT
|
||||
[[features.dev-services.testcontainers.at-development-time.dynamic-properties]]
|
||||
==== Contributing Dynamic Properties at Development Time
|
||||
|
||||
If you want to contribute dynamic properties at development time from your `Container` `@Bean` methods, you can do so by injecting a `DynamicPropertyRegistry`.
|
||||
If you want to contribute dynamic properties at development time from your `org.testcontainers.containers.Container` `@Bean` methods, you can do so by injecting a `DynamicPropertyRegistry`.
|
||||
This works in a similar way to the xref:testing/testcontainers.adoc#testing.testcontainers.dynamic-properties[`@DynamicPropertySource` annotation] that you can use in your tests.
|
||||
It allows you to add properties that will become available once your container has started.
|
||||
|
||||
@@ -373,7 +373,7 @@ NOTE: Using a `@ServiceConnection` is recommended whenever possible, however, dy
|
||||
[[features.dev-services.testcontainers.at-development-time.importing-container-declarations]]
|
||||
==== Importing Testcontainer Declaration Classes
|
||||
|
||||
A common pattern when using Testcontainers is to declare `Container` instances as static fields.
|
||||
A common pattern when using Testcontainers is to declare `org.testcontainers.containers.Container` instances as static fields.
|
||||
Often these fields are defined directly on the test class.
|
||||
They can also be declared on a parent class or on an interface that the test implements.
|
||||
|
||||
@@ -386,7 +386,7 @@ To do so, add the `@ImportTestcontainers` annotation to your test configuration
|
||||
|
||||
include-code::MyContainersConfiguration[]
|
||||
|
||||
TIP: If you don't intend to use the xref:testing/testcontainers.adoc#testing.testcontainers.service-connections[service connections feature] but want to use xref:testing/testcontainers.adoc#testing.testcontainers.dynamic-properties[`@DynamicPropertySource`] instead, remove the `@ServiceConnection` annotation from the `Container` fields.
|
||||
TIP: If you don't intend to use the xref:testing/testcontainers.adoc#testing.testcontainers.service-connections[service connections feature] but want to use xref:testing/testcontainers.adoc#testing.testcontainers.dynamic-properties[`@DynamicPropertySource`] instead, remove the `@ServiceConnection` annotation from the `org.testcontainers.containers.Container` fields.
|
||||
You can also add `@DynamicPropertySource` annotated methods to your declaration class.
|
||||
|
||||
|
||||
@@ -396,7 +396,7 @@ You can also add `@DynamicPropertySource` annotated methods to your declaration
|
||||
|
||||
When using devtools, you can annotate beans and bean methods with `@RestartScope`.
|
||||
Such beans won't be recreated when the devtools restart the application.
|
||||
This is especially useful for Testcontainer `Container` beans, as they keep their state despite the application restart.
|
||||
This is especially useful for Testcontainer `org.testcontainers.containers.Container` beans, as they keep their state despite the application restart.
|
||||
|
||||
include-code::MyContainersConfiguration[]
|
||||
|
||||
|
||||
@@ -120,7 +120,7 @@ Spring Boot will automatically find and load `application.properties` and `appli
|
||||
.. Immediate child directories of the `config/` subdirectory
|
||||
|
||||
The list is ordered by precedence (with values from lower items overriding earlier ones).
|
||||
Documents from the loaded files are added as `PropertySources` to the Spring `Environment`.
|
||||
Documents from the loaded files are added as `PropertySource` instances to the Spring `Environment`.
|
||||
|
||||
If you do not like `application` as the configuration file name, you can switch to another file name by specifying a configprop:spring.config.name[] environment property.
|
||||
For example, to look for `myproject.properties` and `myproject.yaml` files you can run your application as follows:
|
||||
@@ -636,7 +636,7 @@ my.servers[0]=dev.example.com
|
||||
my.servers[1]=another.example.com
|
||||
----
|
||||
|
||||
TIP: Properties that use the `[index]` notation can be bound to Java `List` or `Set` objects using Spring Boot's `Binder` class.
|
||||
TIP: Properties that use the `[index]` notation can be bound to Java `java.util.List` or `java.util.Set` objects using Spring Boot's `Binder` class.
|
||||
For more details see the xref:features/external-config.adoc#features.external-config.typesafe-configuration-properties[] section below.
|
||||
|
||||
WARNING: YAML files cannot be loaded by using the `@PropertySource` or `@TestPropertySource` annotations.
|
||||
@@ -648,7 +648,7 @@ So, in the case that you need to load values that way, you need to use a propert
|
||||
=== Directly Loading YAML
|
||||
|
||||
Spring Framework provides two convenient classes that can be used to load YAML documents.
|
||||
The `YamlPropertiesFactoryBean` loads YAML as `Properties` and the `YamlMapFactoryBean` loads YAML as a `Map`.
|
||||
The `YamlPropertiesFactoryBean` loads YAML as `Properties` and the `YamlMapFactoryBean` loads YAML as a `java.util.Map`.
|
||||
|
||||
You can also use the `YamlPropertySourceLoader` class if you want to load YAML as a Spring `PropertySource`.
|
||||
|
||||
@@ -752,11 +752,11 @@ Unless your record has multiple constructors, there is no need to use `@Construc
|
||||
|
||||
Nested members of a constructor bound class (such as `+Security+` in the example above) will also be bound through their constructor.
|
||||
|
||||
Default values can be specified using `@DefaultValue` on constructor parameters and record components.
|
||||
Default values can be specified using `@org.springframework.boot.context.properties.bind.DefaultValue` on constructor parameters and record components.
|
||||
The conversion service will be applied to coerce the annotation's `String` value to the target type of a missing property.
|
||||
|
||||
Referring to the previous example, if no properties are bound to `+Security+`, the `MyProperties` instance will contain a `null` value for `security`.
|
||||
To make it contain a non-null instance of `+Security+` even when no properties are bound to it (when using Kotlin, this will require the `username` and `password` parameters of `+Security+` to be declared as nullable as they do not have default values), use an empty `@DefaultValue` annotation:
|
||||
To make it contain a non-null instance of `+Security+` even when no properties are bound to it (when using Kotlin, this will require the `username` and `password` parameters of `+Security+` to be declared as nullable as they do not have default values), use an empty `@org.springframework.boot.context.properties.bind.DefaultValue` annotation:
|
||||
|
||||
include-code::nonnull/MyProperties[tag=*]
|
||||
|
||||
@@ -768,9 +768,9 @@ This will happen automatically if you use Spring Boot's Gradle plugin or if you
|
||||
|
||||
NOTE: The use of `java.util.Optional` with `@ConfigurationProperties` is not recommended as it is primarily intended for use as a return type.
|
||||
As such, it is not well-suited to configuration property injection.
|
||||
For consistency with properties of other types, if you do declare an `Optional` property and it has no value, `null` rather than an empty `Optional` will be bound.
|
||||
For consistency with properties of other types, if you do declare an `java.util.Optional` property and it has no value, `null` rather than an empty `java.util.Optional` will be bound.
|
||||
|
||||
TIP: To use a reserved keyword in the name of a property, such as `my.service.import`, use the `@Name` annotation on the constructor parameter.
|
||||
TIP: To use a reserved keyword in the name of a property, such as `my.service.import`, use the `@org.springframework.boot.context.properties.bind.Name` annotation on the constructor parameter.
|
||||
|
||||
|
||||
|
||||
@@ -909,7 +909,7 @@ TIP: We recommend that, when possible, properties are stored in lower-case kebab
|
||||
[[features.external-config.typesafe-configuration-properties.relaxed-binding.maps]]
|
||||
==== Binding Maps
|
||||
|
||||
When binding to `Map` properties you may need to use a special bracket notation so that the original `key` value is preserved.
|
||||
When binding to `java.util.Map` properties you may need to use a special bracket notation so that the original `key` value is preserved.
|
||||
If the key is not surrounded by `[]`, any characters that are not alpha-numeric, `-` or `.` are removed.
|
||||
|
||||
For example, consider binding the following properties to a `Map<String,String>`:
|
||||
@@ -925,7 +925,7 @@ my:
|
||||
|
||||
NOTE: For YAML files, the brackets need to be surrounded by quotes for the keys to be parsed properly.
|
||||
|
||||
The properties above will bind to a `Map` with `/key1`, `/key2` and `key3` as the keys in the map.
|
||||
The properties above will bind to a `java.util.Map` with `/key1`, `/key2` and `key3` as the keys in the map.
|
||||
The slash has been removed from `key3` because it was not surrounded by square brackets.
|
||||
|
||||
When binding to scalar values, keys with `.` in them do not need to be surrounded by `[]`.
|
||||
@@ -954,7 +954,8 @@ To convert a property name in the canonical-form to an environment variable name
|
||||
For example, the configuration property `spring.main.log-startup-info` would be an environment variable named `SPRING_MAIN_LOGSTARTUPINFO`.
|
||||
|
||||
Environment variables can also be used when binding to object lists.
|
||||
To bind to a `List`, the element number should be surrounded with underscores in the variable name.
|
||||
To bind to a `java.util.List`, the element number should be surrounded with underscores in the variable name.
|
||||
|
||||
For example, the configuration property `my.service[0].other` would use an environment variable named `MY_SERVICE_0_OTHER`.
|
||||
|
||||
Support for binding from environment variables is applied to the `systemEnvironment` property source and to any additional property source whose name ends with `-systemEnvironment`.
|
||||
@@ -1018,7 +1019,7 @@ If the `dev` profile is not active, `MyProperties.list` contains one `MyPojo` en
|
||||
If the `dev` profile is enabled, however, the `list` _still_ contains only one entry (with a name of `my another name` and a description of `null`).
|
||||
This configuration _does not_ add a second `MyPojo` instance to the list, and it does not merge the items.
|
||||
|
||||
When a `List` is specified in multiple profiles, the one with the highest priority (and only that one) is used.
|
||||
When a `java.util.List` is specified in multiple profiles, the one with the highest priority (and only that one) is used.
|
||||
Consider the following example:
|
||||
|
||||
[configprops%novalidate,yaml]
|
||||
@@ -1042,7 +1043,7 @@ my:
|
||||
In the preceding example, if the `dev` profile is active, `MyProperties.list` contains _one_ `MyPojo` entry (with a name of `my another name` and a description of `null`).
|
||||
For YAML, both comma-separated lists and YAML lists can be used for completely overriding the contents of the list.
|
||||
|
||||
For `Map` properties, you can bind with property values drawn from multiple sources.
|
||||
For `java.util.Map` properties, you can bind with property values drawn from multiple sources.
|
||||
However, for the same property in multiple sources, the one with the highest priority is used.
|
||||
The following example exposes a `Map<String, MyPojo>` from `MyProperties`:
|
||||
|
||||
@@ -1190,20 +1191,20 @@ Doing so gives a transparent upgrade path while supporting a much richer format.
|
||||
[[features.external-config.typesafe-configuration-properties.validation]]
|
||||
=== @ConfigurationProperties Validation
|
||||
|
||||
Spring Boot attempts to validate `@ConfigurationProperties` classes whenever they are annotated with Spring's `@Validated` annotation.
|
||||
Spring Boot attempts to validate `@ConfigurationProperties` classes whenever they are annotated with Spring's `@org.springframework.validation.annotation.Validated` annotation.
|
||||
You can use JSR-303 `jakarta.validation` constraint annotations directly on your configuration class.
|
||||
To do so, ensure that a compliant JSR-303 implementation is on your classpath and then add constraint annotations to your fields, as shown in the following example:
|
||||
|
||||
include-code::MyProperties[]
|
||||
|
||||
TIP: You can also trigger validation by annotating the `@Bean` method that creates the configuration properties with `@Validated`.
|
||||
TIP: You can also trigger validation by annotating the `@Bean` method that creates the configuration properties with `@org.springframework.validation.annotation.Validated`.
|
||||
|
||||
To ensure that validation is always triggered for nested properties, even when no properties are found, the associated field must be annotated with `@Valid`.
|
||||
The following example builds on the preceding `MyProperties` example:
|
||||
|
||||
include-code::nested/MyProperties[]
|
||||
|
||||
You can also add a custom Spring `Validator` by creating a bean definition called `configurationPropertiesValidator`.
|
||||
You can also add a custom Spring `org.springframework.validation.Validator` by creating a bean definition called `configurationPropertiesValidator`.
|
||||
The `@Bean` method should be declared `static`.
|
||||
The configuration properties validator is created very early in the application's lifecycle, and declaring the `@Bean` method as static lets the bean be created without having to instantiate the `@Configuration` class.
|
||||
Doing so avoids any problems that may be caused by early instantiation.
|
||||
|
||||
@@ -6,7 +6,7 @@ By default, Spring Boot looks for the presence of a `messages` resource bundle a
|
||||
|
||||
NOTE: The auto-configuration applies when the default properties file for the configured resource bundle is available (`messages.properties` by default).
|
||||
If your resource bundle contains only language-specific properties files, you are required to add the default.
|
||||
If no properties file is found that matches any of the configured base names, there will be no auto-configured `MessageSource`.
|
||||
If no properties file is found that matches any of the configured base names, there will be no auto-configured `org.springframework.context.MessageSource`.
|
||||
|
||||
The basename of the resource bundle as well as several other attributes can be configured using the `spring.messages` namespace, as shown in the following example:
|
||||
|
||||
|
||||
@@ -23,10 +23,10 @@ Several configuration properties are provided for xref:how-to:spring-mvc.adoc#ho
|
||||
[[features.json.jackson.custom-serializers-and-deserializers]]
|
||||
=== Custom Serializers and Deserializers
|
||||
|
||||
If you use Jackson to serialize and deserialize JSON data, you might want to write your own `JsonSerializer` and `JsonDeserializer` classes.
|
||||
If you use Jackson to serialize and deserialize JSON data, you might want to write your own `com.fasterxml.jackson.databind.JsonSerializer` and `com.fasterxml.jackson.databind.JsonDeserializer` classes.
|
||||
Custom serializers are usually https://github.com/FasterXML/jackson-docs/wiki/JacksonHowToCustomSerializers[registered with Jackson through a module], but Spring Boot provides an alternative `@JsonComponent` annotation that makes it easier to directly register Spring Beans.
|
||||
|
||||
You can use the `@JsonComponent` annotation directly on `JsonSerializer`, `JsonDeserializer` or `KeyDeserializer` implementations.
|
||||
You can use the `@JsonComponent` annotation directly on `com.fasterxml.jackson.databind.JsonSerializer`, `com.fasterxml.jackson.databind.JsonDeserializer` or `com.fasterxml.jackson.databind.KeyDeserializer` implementations.
|
||||
You can also use it on classes that contain serializers/deserializers as inner classes, as shown in the following example:
|
||||
|
||||
include-code::MyJsonComponent[]
|
||||
|
||||
@@ -34,7 +34,7 @@ TIP: These dependencies and plugins are provided by default if one bootstraps a
|
||||
|
||||
One of Kotlin's key features is {url-kotlin-docs}/null-safety.html[null-safety].
|
||||
It deals with `null` values at compile time rather than deferring the problem to runtime and encountering a `NullPointerException`.
|
||||
This helps to eliminate a common source of bugs without paying the cost of wrappers like `Optional`.
|
||||
This helps to eliminate a common source of bugs without paying the cost of wrappers like `java.util.Optional`.
|
||||
Kotlin also allows using functional constructs with nullable values as described in this https://www.baeldung.com/kotlin-null-safety[comprehensive guide to null-safety in Kotlin].
|
||||
|
||||
Although Java does not allow one to express null-safety in its type system, Spring Framework, Spring Data, and Reactor now provide null-safety of their API through tooling-friendly annotations.
|
||||
|
||||
@@ -291,7 +291,7 @@ You can force Spring Boot to use a particular logging system by using the `org.s
|
||||
The value should be the fully qualified class name of a `LoggingSystem` implementation.
|
||||
You can also disable Spring Boot's logging configuration entirely by using a value of `none`.
|
||||
|
||||
NOTE: Since logging is initialized *before* the `ApplicationContext` is created, it is not possible to control logging from `@PropertySources` in Spring `@Configuration` files.
|
||||
NOTE: Since logging is initialized *before* the `ApplicationContext` is created, it is not possible to control logging from `@org.springframework.context.annotation.PropertySources` in Spring `@Configuration` files.
|
||||
The only way to change the logging system or disable it entirely is through System properties.
|
||||
|
||||
Depending on your logging system, the following files are loaded:
|
||||
@@ -564,10 +564,10 @@ NOTE: The lookup key should be specified in kebab case (such as `my.property-nam
|
||||
=== Log4j2 System Properties
|
||||
|
||||
Log4j2 supports a number of https://logging.apache.org/log4j/2.x/manual/systemproperties.html[System Properties] that can be used to configure various items.
|
||||
For example, the `log4j2.skipJansi` system property can be used to configure if the `ConsoleAppender` will try to use a https://github.com/fusesource/jansi[Jansi] output stream on Windows.
|
||||
For example, the `log4j2.skipJansi` system property can be used to configure if the `org.apache.logging.log4j.core.appender.ConsoleAppender` will try to use a https://github.com/fusesource/jansi[Jansi] output stream on Windows.
|
||||
|
||||
All system properties that are loaded after the Log4j2 initialization can be obtained from the Spring `Environment`.
|
||||
For example, you could add `log4j2.skipJansi=false` to your `application.properties` file to have the `ConsoleAppender` use Jansi on Windows.
|
||||
For example, you could add `log4j2.skipJansi=false` to your `application.properties` file to have the `org.apache.logging.log4j.core.appender.ConsoleAppender` use Jansi on Windows.
|
||||
|
||||
NOTE: The Spring `Environment` is only considered when system properties and OS environment variables do not contain the value being loaded.
|
||||
|
||||
|
||||
@@ -268,7 +268,7 @@ Application events are sent in the following order, as your application runs:
|
||||
The above list only includes ``SpringApplicationEvent``s that are tied to a `SpringApplication`.
|
||||
In addition to these, the following events are also published after `ApplicationPreparedEvent` and before `ApplicationStartedEvent`:
|
||||
|
||||
- A `WebServerInitializedEvent` is sent after the `WebServer` is ready.
|
||||
- A `WebServerInitializedEvent` is sent after the `org.springframework.boot.web.server.WebServer` is ready.
|
||||
`ServletWebServerInitializedEvent` and `ReactiveWebServerInitializedEvent` are the servlet and reactive variants respectively.
|
||||
- A `ContextRefreshedEvent` is sent when an `ApplicationContext` is refreshed.
|
||||
|
||||
@@ -410,7 +410,7 @@ That's because virtual threads are scheduled on a JVM wide platform thread pool
|
||||
|
||||
WARNING: One side effect of virtual threads is that they are daemon threads.
|
||||
A JVM will exit if all of its threads are daemon threads.
|
||||
This behavior can be a problem when you rely on `@Scheduled` beans, for example, to keep your application alive.
|
||||
This behavior can be a problem when you rely on `@org.springframework.scheduling.annotation.Scheduled` beans, for example, to keep your application alive.
|
||||
If you use virtual threads, the scheduler thread is a virtual thread and therefore a daemon thread and won't keep the JVM alive.
|
||||
This not only affects scheduling and can be the case with other technologies too.
|
||||
To keep the JVM running in all cases, it is recommended to set the property configprop:spring.main.keep-alive[] to `true`.
|
||||
|
||||
@@ -132,8 +132,8 @@ An `SslBundle` can be retrieved from the auto-configured `SslBundles` bean and u
|
||||
The `SslBundle` provides a layered approach of obtaining these SSL objects:
|
||||
|
||||
- `getStores()` provides access to the key store and trust store `java.security.KeyStore` instances as well as any required key store password.
|
||||
- `getManagers()` provides access to the `java.net.ssl.KeyManagerFactory` and `java.net.ssl.TrustManagerFactory` instances as well as the `java.net.ssl.KeyManager` and `java.net.ssl.TrustManager` arrays that they create.
|
||||
- `createSslContext()` provides a convenient way to obtain a new `java.net.ssl.SSLContext` instance.
|
||||
- `getManagers()` provides access to the `javax.net.ssl.KeyManagerFactory` and `javax.net.ssl.TrustManagerFactory` instances as well as the `javax.net.ssl.KeyManager` and `javax.net.ssl.TrustManager` arrays that they create.
|
||||
- `createSslContext()` provides a convenient way to obtain a new `javax.net.ssl.SSLContext` instance.
|
||||
|
||||
In addition, the `SslBundle` provides details about the key being used, the protocol to use and any option that should be applied to the SSL engine.
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
[[features.task-execution-and-scheduling]]
|
||||
= Task Execution and Scheduling
|
||||
|
||||
In the absence of an `Executor` bean in the context, Spring Boot auto-configures an `AsyncTaskExecutor`.
|
||||
In the absence of an `java.util.concurrent.Executor` bean in the context, Spring Boot auto-configures an `AsyncTaskExecutor`.
|
||||
When virtual threads are enabled (using Java 21+ and configprop:spring.threads.virtual.enabled[] set to `true`) this will be a `SimpleAsyncTaskExecutor` that uses virtual threads.
|
||||
Otherwise, it will be a `ThreadPoolTaskExecutor` with sensible defaults.
|
||||
In either case, the auto-configured executor will be automatically used for:
|
||||
@@ -13,9 +13,9 @@ In either case, the auto-configured executor will be automatically used for:
|
||||
|
||||
[TIP]
|
||||
====
|
||||
If you have defined a custom `Executor` in the context, both regular task execution (that is `@EnableAsync`) and Spring for GraphQL will use it.
|
||||
If you have defined a custom `java.util.concurrent.Executor` in the context, both regular task execution (that is `@EnableAsync`) and Spring for GraphQL will use it.
|
||||
However, the Spring MVC and Spring WebFlux support will only use it if it is an `AsyncTaskExecutor` implementation (named `applicationTaskExecutor`).
|
||||
Depending on your target arrangement, you could change your `Executor` into an `AsyncTaskExecutor` or define both an `AsyncTaskExecutor` and an `AsyncConfigurer` wrapping your custom `Executor`.
|
||||
Depending on your target arrangement, you could change your `java.util.concurrent.Executor` into an `AsyncTaskExecutor` or define both an `AsyncTaskExecutor` and an `AsyncConfigurer` wrapping your custom `java.util.concurrent.Executor`.
|
||||
|
||||
The auto-configured `ThreadPoolTaskExecutorBuilder` allows you to easily create instances that reproduce what the auto-configuration does by default.
|
||||
====
|
||||
|
||||
@@ -36,7 +36,7 @@ TIP: It is also possible to transparently {url-spring-framework-docs}/integratio
|
||||
|
||||
The cache abstraction does not provide an actual store and relies on abstraction materialized by the `org.springframework.cache.Cache` and `org.springframework.cache.CacheManager` interfaces.
|
||||
|
||||
If you have not defined a bean of type `CacheManager` or a `CacheResolver` named `cacheResolver` (see javadoc:{url-spring-framework-javadoc}/org.springframework.cache.annotation.CachingConfigurer[]), Spring Boot tries to detect the following providers (in the indicated order):
|
||||
If you have not defined a bean of type `org.springframework.cache.CacheManager` or a `org.springframework.cache.interceptor.CacheResolver` named `cacheResolver` (see javadoc:{url-spring-framework-javadoc}/org.springframework.cache.annotation.CachingConfigurer[]), Spring Boot tries to detect the following providers (in the indicated order):
|
||||
|
||||
. xref:io/caching.adoc#io.caching.provider.generic[]
|
||||
. xref:io/caching.adoc#io.caching.provider.jcache[] (EhCache 3, Hazelcast, Infinispan, and others)
|
||||
@@ -50,14 +50,14 @@ If you have not defined a bean of type `CacheManager` or a `CacheResolver` named
|
||||
|
||||
Additionally, {url-spring-boot-for-apache-geode-site}[Spring Boot for Apache Geode] provides {url-spring-boot-for-apache-geode-docs}#geode-caching-provider[auto-configuration for using Apache Geode as a cache provider].
|
||||
|
||||
TIP: If the `CacheManager` is auto-configured by Spring Boot, it is possible to _force_ a particular cache provider by setting the configprop:spring.cache.type[] property.
|
||||
TIP: If the `org.springframework.cache.CacheManager` is auto-configured by Spring Boot, it is possible to _force_ a particular cache provider by setting the configprop:spring.cache.type[] property.
|
||||
Use this property if you need to xref:io/caching.adoc#io.caching.provider.none[use no-op caches] in certain environments (such as tests).
|
||||
|
||||
TIP: Use the `spring-boot-starter-cache` starter to quickly add basic caching dependencies.
|
||||
The starter brings in `spring-context-support`.
|
||||
If you add dependencies manually, you must include `spring-context-support` in order to use the JCache or Caffeine support.
|
||||
|
||||
If the `CacheManager` is auto-configured by Spring Boot, you can further tune its configuration before it is fully initialized by exposing a bean that implements the `CacheManagerCustomizer` interface.
|
||||
If the `org.springframework.cache.CacheManager` is auto-configured by Spring Boot, you can further tune its configuration before it is fully initialized by exposing a bean that implements the `CacheManagerCustomizer` interface.
|
||||
The following example sets a flag to say that `null` values should not be passed down to the underlying map:
|
||||
|
||||
include-code::MyCacheManagerConfiguration[]
|
||||
@@ -72,7 +72,7 @@ You can have as many customizers as you want, and you can also order them by usi
|
||||
=== Generic
|
||||
|
||||
Generic caching is used if the context defines _at least_ one `org.springframework.cache.Cache` bean.
|
||||
A `CacheManager` wrapping all beans of that type is created.
|
||||
A `org.springframework.cache.CacheManager` wrapping all beans of that type is created.
|
||||
|
||||
|
||||
|
||||
@@ -99,13 +99,13 @@ Even if the JSR-107 standard does not enforce a standardized way to define the l
|
||||
NOTE: When a cache library offers both a native implementation and JSR-107 support, Spring Boot prefers the JSR-107 support, so that the same features are available if you switch to a different JSR-107 implementation.
|
||||
|
||||
TIP: Spring Boot has xref:io/hazelcast.adoc[general support for Hazelcast].
|
||||
If a single `HazelcastInstance` is available, it is automatically reused for the `CacheManager` as well, unless the configprop:spring.cache.jcache.config[] property is specified.
|
||||
If a single `HazelcastInstance` is available, it is automatically reused for the `javax.cache.CacheManager` as well, unless the configprop:spring.cache.jcache.config[] property is specified.
|
||||
|
||||
There are two ways to customize the underlying `javax.cache.CacheManager`:
|
||||
|
||||
* Caches can be created on startup by setting the configprop:spring.cache.cache-names[] property.
|
||||
If a custom `javax.cache.configuration.Configuration` bean is defined, it is used to customize them.
|
||||
* `org.springframework.boot.autoconfigure.cache.JCacheManagerCustomizer` beans are invoked with the reference of the `CacheManager` for full customization.
|
||||
* `org.springframework.boot.autoconfigure.cache.JCacheManagerCustomizer` beans are invoked with the reference of the `javax.cache.CacheManager` for full customization.
|
||||
|
||||
TIP: If a standard `javax.cache.CacheManager` bean is defined, it is wrapped automatically in an `org.springframework.cache.CacheManager` implementation that the abstraction expects.
|
||||
No further customization is applied to it.
|
||||
@@ -116,10 +116,10 @@ No further customization is applied to it.
|
||||
=== Hazelcast
|
||||
|
||||
Spring Boot has xref:io/hazelcast.adoc[general support for Hazelcast].
|
||||
If a `HazelcastInstance` has been auto-configured and `com.hazelcast:hazelcast-spring` is on the classpath, it is automatically wrapped in a `CacheManager`.
|
||||
If a `HazelcastInstance` has been auto-configured and `com.hazelcast:hazelcast-spring` is on the classpath, it is automatically wrapped in a `org.springframework.cache.CacheManager`.
|
||||
|
||||
NOTE: Hazelcast can be used as a JCache compliant cache or as a Spring `CacheManager` compliant cache.
|
||||
When setting configprop:spring.cache.type[] to `hazelcast`, Spring Boot will use the `CacheManager` based implementation.
|
||||
NOTE: Hazelcast can be used as a JCache compliant cache or as a Spring `org.springframework.cache.CacheManager` compliant cache.
|
||||
When setting configprop:spring.cache.type[] to `hazelcast`, Spring Boot will use the `org.springframework.cache.CacheManager` based implementation.
|
||||
If you want to use Hazelcast as a JCache compliant cache, set configprop:spring.cache.type[] to `jcache`.
|
||||
If you have multiple JCache compliant cache providers and want to force the use of Hazelcast, you have to xref:io/caching.adoc#io.caching.provider.jcache[explicitly set the JCache provider].
|
||||
|
||||
@@ -140,7 +140,7 @@ spring:
|
||||
----
|
||||
|
||||
Caches can be created on startup by setting the configprop:spring.cache.cache-names[] property.
|
||||
If a custom `ConfigurationBuilder` bean is defined, it is used to customize the caches.
|
||||
If a custom `org.infinispan.configuration.cache.ConfigurationBuilder` bean is defined, it is used to customize the caches.
|
||||
|
||||
To be compatible with Spring Boot's Jakarta EE 9 baseline, Infinispan's `-jakarta` modules must be used.
|
||||
For every module with a `-jakarta` variant, the variant must be used in place of the standard module.
|
||||
@@ -223,7 +223,7 @@ spring:
|
||||
----
|
||||
|
||||
If a `com.github.benmanes.caffeine.cache.CacheLoader` bean is defined, it is automatically associated to the `CaffeineCacheManager`.
|
||||
Since the `CacheLoader` is going to be associated with _all_ caches managed by the cache manager, it must be defined as `CacheLoader<Object, Object>`.
|
||||
Since the `com.github.benmanes.caffeine.cache.CacheLoader` is going to be associated with _all_ caches managed by the cache manager, it must be defined as `CacheLoader<Object, Object>`.
|
||||
The auto-configuration ignores any other generic type.
|
||||
|
||||
|
||||
@@ -266,7 +266,7 @@ This is similar to the way the "real" cache providers behave if you use an undec
|
||||
=== None
|
||||
|
||||
When `@EnableCaching` is present in your configuration, a suitable cache configuration is expected as well.
|
||||
If you have a custom `CacheManager`, consider defining it in a separate `@Configuration` class so that you can override it if necessary.
|
||||
If you have a custom ` org.springframework.cache.CacheManager`, consider defining it in a separate `@Configuration` class so that you can override it if necessary.
|
||||
None uses a no-op implementation that is useful in tests, and slice tests use that by default via `@AutoConfigureCache`.
|
||||
|
||||
If you need to use a no-op cache rather than the auto-configured cache manager in a certain environment, set the cache type to `none`, as shown in the following example:
|
||||
|
||||
@@ -21,7 +21,7 @@ spring:
|
||||
"[mail.smtp.writetimeout]": 5000
|
||||
----
|
||||
|
||||
It is also possible to configure a `JavaMailSender` with an existing `Session` from JNDI:
|
||||
It is also possible to configure a `JavaMailSender` with an existing `jakarta.mail.Session` from JNDI:
|
||||
|
||||
[configprops,yaml]
|
||||
----
|
||||
|
||||
@@ -29,7 +29,7 @@ We also check if the `hazelcast.config` system property is set.
|
||||
See the https://docs.hazelcast.org/docs/latest/manual/html-single/[Hazelcast documentation] for more details.
|
||||
|
||||
TIP: By default, `@SpringAware` on Hazelcast components is supported.
|
||||
The `ManagementContext` can be overridden by declaring a `HazelcastConfigCustomizer` bean with an `@Order` higher than zero.
|
||||
The `ManagedContext` can be overridden by declaring a `HazelcastConfigCustomizer` bean with an `@Order` higher than zero.
|
||||
|
||||
NOTE: Spring Boot also has xref:io/caching.adoc#io.caching.provider.hazelcast[explicit caching support for Hazelcast].
|
||||
If caching is enabled, the `HazelcastInstance` is automatically wrapped in a `CacheManager` implementation.
|
||||
If caching is enabled, the `HazelcastInstance` is automatically wrapped in a `org.springframework.cache.CacheManager` implementation.
|
||||
|
||||
@@ -5,7 +5,7 @@ Spring Boot supports distributed JTA transactions across multiple XA resources b
|
||||
|
||||
When a JTA environment is detected, Spring's `JtaTransactionManager` is used to manage transactions.
|
||||
Auto-configured JMS, DataSource, and JPA beans are upgraded to support XA transactions.
|
||||
You can use standard Spring idioms, such as `@Transactional`, to participate in a distributed transaction.
|
||||
You can use standard Spring idioms, such as `@org.springframework.transaction.annotation.Transactional`, to participate in a distributed transaction.
|
||||
If you are within a JTA environment and still want to use local transactions, you can set the configprop:spring.jta.enabled[] property to `false` to disable the JTA auto-configuration.
|
||||
|
||||
|
||||
@@ -16,22 +16,22 @@ If you are within a JTA environment and still want to use local transactions, yo
|
||||
If you package your Spring Boot application as a `war` or `ear` file and deploy it to a Jakarta EE application server, you can use your application server's built-in transaction manager.
|
||||
Spring Boot tries to auto-configure a transaction manager by looking at common JNDI locations (`java:comp/UserTransaction`, `java:comp/TransactionManager`, and so on).
|
||||
When using a transaction service provided by your application server, you generally also want to ensure that all resources are managed by the server and exposed over JNDI.
|
||||
Spring Boot tries to auto-configure JMS by looking for a `ConnectionFactory` at the JNDI path (`java:/JmsXA` or `java:/XAConnectionFactory`), and you can use the xref:data/sql.adoc#data.sql.datasource.jndi[configprop:spring.datasource.jndi-name[] property] to configure your `DataSource`.
|
||||
Spring Boot tries to auto-configure JMS by looking for a `jakarta.jms.ConnectionFactory` at the JNDI path (`java:/JmsXA` or `java:/XAConnectionFactory`), and you can use the xref:data/sql.adoc#data.sql.datasource.jndi[configprop:spring.datasource.jndi-name[] property] to configure your `DataSource`.
|
||||
|
||||
|
||||
|
||||
[[io.jta.mixing-xa-and-non-xa-connections]]
|
||||
== Mixing XA and Non-XA JMS Connections
|
||||
|
||||
When using JTA, the primary JMS `ConnectionFactory` bean is XA-aware and participates in distributed transactions.
|
||||
You can inject into your bean without needing to use any `@Qualifier`:
|
||||
When using JTA, the primary JMS `jakarta.jms.ConnectionFactory` bean is XA-aware and participates in distributed transactions.
|
||||
You can inject into your bean without needing to use any `@org.springframework.beans.factory.annotation.Qualifier`:
|
||||
|
||||
include-code::primary/MyBean[]
|
||||
|
||||
In some situations, you might want to process certain JMS messages by using a non-XA `ConnectionFactory`.
|
||||
In some situations, you might want to process certain JMS messages by using a non-XA `jakarta.jms.ConnectionFactory`.
|
||||
For example, your JMS processing logic might take longer than the XA timeout.
|
||||
|
||||
If you want to use a non-XA `ConnectionFactory`, you can the `nonXaJmsConnectionFactory` bean:
|
||||
If you want to use a non-XA `jakarta.jms.ConnectionFactory`, you can the `nonXaJmsConnectionFactory` bean:
|
||||
|
||||
include-code::nonxa/MyBean[]
|
||||
|
||||
@@ -45,5 +45,5 @@ include-code::xa/MyBean[]
|
||||
== Supporting an Embedded Transaction Manager
|
||||
|
||||
The javadoc:org.springframework.boot.jms.XAConnectionFactoryWrapper[] and javadoc:org.springframework.boot.jdbc.XADataSourceWrapper[] interfaces can be used to support embedded transaction managers.
|
||||
The interfaces are responsible for wrapping `XAConnectionFactory` and `XADataSource` beans and exposing them as regular `ConnectionFactory` and `DataSource` beans, which transparently enroll in the distributed transaction.
|
||||
The interfaces are responsible for wrapping `jakarta.jms.XAConnectionFactory` and `javax.sql.XADataSource` beans and exposing them as regular `jakarta.jms.ConnectionFactory` and `DataSource` beans, which transparently enroll in the distributed transaction.
|
||||
DataSource and JMS auto-configuration use JTA variants, provided you have a `JtaTransactionManager` bean and appropriate XA wrapper beans registered within your `ApplicationContext`.
|
||||
|
||||
@@ -2,14 +2,14 @@
|
||||
= Quartz Scheduler
|
||||
|
||||
Spring Boot offers several conveniences for working with the https://www.quartz-scheduler.org/[Quartz scheduler], including the `spring-boot-starter-quartz` starter.
|
||||
If Quartz is available, a `Scheduler` is auto-configured (through the `SchedulerFactoryBean` abstraction).
|
||||
If Quartz is available, a `org.quartz.Scheduler` is auto-configured (through the `org.springframework.scheduling.quartz.SchedulerFactoryBean` abstraction).
|
||||
|
||||
Beans of the following types are automatically picked up and associated with the `Scheduler`:
|
||||
Beans of the following types are automatically picked up and associated with the `org.quartz.Scheduler`:
|
||||
|
||||
* `JobDetail`: defines a particular Job.
|
||||
`JobDetail` instances can be built with the `JobBuilder` API.
|
||||
* `Calendar`.
|
||||
* `Trigger`: defines when a particular job is triggered.
|
||||
* `org.quartz.JobDetail`: defines a particular Job.
|
||||
`org.quartz.JobDetail` instances can be built with the `org.quartz.JobBuilder` API.
|
||||
* `org.quartz.Calendar`.
|
||||
* `org.quartz.Trigger`: defines when a particular job is triggered.
|
||||
|
||||
By default, an in-memory `JobStore` is used.
|
||||
However, it is possible to configure a JDBC-based store if a `DataSource` bean is available in your application and if the configprop:spring.quartz.job-store-type[] property is configured accordingly, as shown in the following example:
|
||||
@@ -37,7 +37,7 @@ It is also possible to provide a custom script by setting the configprop:spring.
|
||||
|
||||
To have Quartz use a `DataSource` other than the application's main `DataSource`, declare a `DataSource` bean, annotating its `@Bean` method with `@QuartzDataSource`.
|
||||
Doing so ensures that the Quartz-specific `DataSource` is used by both the `SchedulerFactoryBean` and for schema initialization.
|
||||
Similarly, to have Quartz use a `TransactionManager` other than the application's main `TransactionManager` declare a `TransactionManager` bean, annotating its `@Bean` method with `@QuartzTransactionManager`.
|
||||
Similarly, to have Quartz use a `org.springframework.transaction.TransactionManager` other than the application's main `org.springframework.transaction.TransactionManager` declare a `org.springframework.transaction.TransactionManager` bean, annotating its `@Bean` method with `@QuartzTransactionManager`.
|
||||
|
||||
By default, jobs created by configuration will not overwrite already registered jobs that have been read from a persistent job store.
|
||||
To enable overwriting existing job definitions set the configprop:spring.quartz.overwrite-existing-jobs[] property.
|
||||
@@ -45,7 +45,7 @@ To enable overwriting existing job definitions set the configprop:spring.quartz.
|
||||
Quartz Scheduler configuration can be customized using `spring.quartz` properties and `SchedulerFactoryBeanCustomizer` beans, which allow programmatic `SchedulerFactoryBean` customization.
|
||||
Advanced Quartz configuration properties can be customized using `spring.quartz.properties.*`.
|
||||
|
||||
NOTE: In particular, an `Executor` bean is not associated with the scheduler as Quartz offers a way to configure the scheduler through `spring.quartz.properties`.
|
||||
NOTE: In particular, an `java.util.concurrent.Executor` bean is not associated with the scheduler as Quartz offers a way to configure the scheduler through `spring.quartz.properties`.
|
||||
If you need to customize the task executor, consider implementing `SchedulerFactoryBeanCustomizer`.
|
||||
|
||||
Jobs can define setters to inject data map properties.
|
||||
|
||||
@@ -3,15 +3,15 @@
|
||||
|
||||
The method validation feature supported by Bean Validation 1.1 is automatically enabled as long as a JSR-303 implementation (such as Hibernate validator) is on the classpath.
|
||||
This lets bean methods be annotated with `jakarta.validation` constraints on their parameters and/or on their return value.
|
||||
Target classes with such annotated methods need to be annotated with the `@Validated` annotation at the type level for their methods to be searched for inline constraint annotations.
|
||||
Target classes with such annotated methods need to be annotated with the `@org.springframework.validation.annotation.Validated` annotation at the type level for their methods to be searched for inline constraint annotations.
|
||||
|
||||
For instance, the following service triggers the validation of the first argument, making sure its size is between 8 and 10:
|
||||
|
||||
include-code::MyBean[]
|
||||
|
||||
The application's `MessageSource` is used when resolving `+{parameters}+` in constraint messages.
|
||||
The application's `org.springframework.context.MessageSource` is used when resolving `+{parameters}+` in constraint messages.
|
||||
This allows you to use xref:features/internationalization.adoc[your application's `messages.properties` files] for Bean Validation messages.
|
||||
Once the parameters have been resolved, message interpolation is completed using Bean Validation's default interpolator.
|
||||
|
||||
To customize the `Configuration` used to build the `ValidatorFactory`, define a `ValidationConfigurationCustomizer` bean.
|
||||
To customize the `jakarta.validation.Configuration` used to build the `ValidatorFactory`, define a `ValidationConfigurationCustomizer` bean.
|
||||
When multiple customizer beans are defined, they are called in order based on their `@Order` annotation or `Ordered` implementation.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
[[io.webservices]]
|
||||
= Web Services
|
||||
|
||||
Spring Boot provides Web Services auto-configuration so that all you must do is define your `Endpoints`.
|
||||
Spring Boot provides Web Services auto-configuration so that all you must do is define your `@org.springframework.ws.server.endpoint.annotation.Endpoint` beans.
|
||||
|
||||
The {url-spring-webservices-docs}[Spring Web Services features] can be easily accessed with the `spring-boot-starter-webservices` module.
|
||||
|
||||
|
||||
@@ -39,9 +39,9 @@ NOTE: When specifying addresses that way, the `host` and `port` properties are i
|
||||
If the address uses the `amqps` protocol, SSL support is enabled automatically.
|
||||
|
||||
See javadoc:org.springframework.boot.autoconfigure.amqp.RabbitProperties[] for more of the supported property-based configuration options.
|
||||
To configure lower-level details of the RabbitMQ `ConnectionFactory` that is used by Spring AMQP, define a `ConnectionFactoryCustomizer` bean.
|
||||
To configure lower-level details of the RabbitMQ `com.rabbitmq.client.ConnectionFactory` that is used by Spring AMQP, define a `ConnectionFactoryCustomizer` bean.
|
||||
|
||||
If a `ConnectionNameStrategy` bean exists in the context, it will be automatically used to name connections created by the auto-configured `CachingConnectionFactory`.
|
||||
If a `ConnectionNameStrategy` bean exists in the context, it will be automatically used to name connections created by the auto-configured `org.springframework.amqp.rabbit.connection.CachingConnectionFactory`.
|
||||
|
||||
To make an application-wide, additive customization to the `RabbitTemplate`, use a `RabbitTemplateCustomizer` bean.
|
||||
|
||||
@@ -57,7 +57,7 @@ Spring's `AmqpTemplate` and `AmqpAdmin` are auto-configured, and you can autowir
|
||||
include-code::MyBean[]
|
||||
|
||||
NOTE: javadoc:{url-spring-amqp-javadoc}/org.springframework.amqp.rabbit.core.RabbitMessagingTemplate[] can be injected in a similar manner.
|
||||
If a `MessageConverter` bean is defined, it is associated automatically to the auto-configured `AmqpTemplate`.
|
||||
If a `org.springframework.amqp.support.converter.MessageConverter` bean is defined, it is associated automatically to the auto-configured `AmqpTemplate`.
|
||||
|
||||
If necessary, any `org.springframework.amqp.core.Queue` that is defined as a bean is automatically used to declare a corresponding queue on the RabbitMQ instance.
|
||||
|
||||
@@ -93,7 +93,7 @@ spring:
|
||||
name: "my-stream"
|
||||
----
|
||||
|
||||
If a `MessageConverter`, `StreamMessageConverter`, or `ProducerCustomizer` bean is defined, it is associated automatically to the auto-configured `RabbitStreamTemplate`.
|
||||
If a `org.springframework.amqp.support.converter.MessageConverter`, `org.springframework.rabbit.stream.support.converter.StreamMessageConverter`, or `org.springframework.rabbit.stream.producer.ProducerCustomizer` bean is defined, it is associated automatically to the auto-configured `RabbitStreamTemplate`.
|
||||
|
||||
If you need to create more `RabbitStreamTemplate` instances or if you want to override the default, Spring Boot provides a `RabbitStreamTemplateConfigurer` bean that you can use to initialize a `RabbitStreamTemplate` with the same settings as the factories used by the auto-configuration.
|
||||
|
||||
@@ -104,7 +104,7 @@ If you need to create more `RabbitStreamTemplate` instances or if you want to ov
|
||||
|
||||
When the Rabbit infrastructure is present, any bean can be annotated with `@RabbitListener` to create a listener endpoint.
|
||||
If no `RabbitListenerContainerFactory` has been defined, a default `SimpleRabbitListenerContainerFactory` is automatically configured and you can switch to a direct container using the configprop:spring.rabbitmq.listener.type[] property.
|
||||
If a `MessageConverter` or a `MessageRecoverer` bean is defined, it is automatically associated with the default factory.
|
||||
If a `org.springframework.amqp.support.converter.MessageConverter` or a `org.springframework.amqp.rabbit.retry.MessageRecoverer` bean is defined, it is automatically associated with the default factory.
|
||||
|
||||
The following sample component creates a listener endpoint on the `someQueue` queue:
|
||||
|
||||
@@ -117,7 +117,7 @@ If you need to create more `RabbitListenerContainerFactory` instances or if you
|
||||
TIP: It does not matter which container type you chose.
|
||||
Those two beans are exposed by the auto-configuration.
|
||||
|
||||
For instance, the following configuration class exposes another factory that uses a specific `MessageConverter`:
|
||||
For instance, the following configuration class exposes another factory that uses a specific `org.springframework.amqp.support.converter.MessageConverter`:
|
||||
|
||||
include-code::custom/MyRabbitConfiguration[]
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
= JMS
|
||||
|
||||
The `jakarta.jms.ConnectionFactory` interface provides a standard method of creating a `jakarta.jms.Connection` for interacting with a JMS broker.
|
||||
Although Spring needs a `ConnectionFactory` to work with JMS, you generally need not use it directly yourself and can instead rely on higher level messaging abstractions.
|
||||
Although Spring needs a `jakarta.jms.ConnectionFactory` to work with JMS, you generally need not use it directly yourself and can instead rely on higher level messaging abstractions.
|
||||
(See the {url-spring-framework-docs}/integration/jms.html[relevant section] of the Spring Framework reference documentation for details.)
|
||||
Spring Boot also auto-configures the necessary infrastructure to send and receive messages.
|
||||
|
||||
@@ -11,7 +11,7 @@ Spring Boot also auto-configures the necessary infrastructure to send and receiv
|
||||
[[messaging.jms.activemq]]
|
||||
== ActiveMQ "Classic" Support
|
||||
|
||||
When https://activemq.apache.org/components/classic[ActiveMQ "Classic"] is available on the classpath, Spring Boot can configure a `ConnectionFactory`.
|
||||
When https://activemq.apache.org/components/classic[ActiveMQ "Classic"] is available on the classpath, Spring Boot can configure a `jakarta.jms.ConnectionFactory`.
|
||||
|
||||
NOTE: If you use `spring-boot-starter-activemq`, the necessary dependencies to connect to an ActiveMQ "Classic" instance are provided, as is the Spring infrastructure to integrate with JMS.
|
||||
|
||||
@@ -27,7 +27,7 @@ spring:
|
||||
password: "secret"
|
||||
----
|
||||
|
||||
By default, a `CachingConnectionFactory` wraps the native `ConnectionFactory` with sensible settings that you can control by external configuration properties in `+spring.jms.*+`:
|
||||
By default, a `org.springframework.jms.connection.CachingConnectionFactory` wraps the native `jakarta.jms.ConnectionFactory` with sensible settings that you can control by external configuration properties in `+spring.jms.*+`:
|
||||
|
||||
[configprops,yaml]
|
||||
----
|
||||
@@ -58,10 +58,10 @@ By default, ActiveMQ "Classic" creates a destination if it does not yet exist so
|
||||
[[messaging.jms.artemis]]
|
||||
== ActiveMQ Artemis Support
|
||||
|
||||
Spring Boot can auto-configure a `ConnectionFactory` when it detects that https://activemq.apache.org/components/artemis/[ActiveMQ Artemis] is available on the classpath.
|
||||
Spring Boot can auto-configure a `jakarta.jms.ConnectionFactory` when it detects that https://activemq.apache.org/components/artemis/[ActiveMQ Artemis] is available on the classpath.
|
||||
If the broker is present, an embedded broker is automatically started and configured (unless the mode property has been explicitly set).
|
||||
The supported modes are `embedded` (to make explicit that an embedded broker is required and that an error should occur if the broker is not available on the classpath) and `native` (to connect to a broker using the `netty` transport protocol).
|
||||
When the latter is configured, Spring Boot configures a `ConnectionFactory` that connects to a broker running on the local machine with the default settings.
|
||||
When the latter is configured, Spring Boot configures a `jakarta.jms.ConnectionFactory` that connects to a broker running on the local machine with the default settings.
|
||||
|
||||
NOTE: If you use `spring-boot-starter-artemis`, the necessary dependencies to connect to an existing ActiveMQ Artemis instance are provided, as well as the Spring infrastructure to integrate with JMS.
|
||||
Adding `org.apache.activemq:artemis-jakarta-server` to your application lets you use embedded mode.
|
||||
@@ -82,7 +82,7 @@ spring:
|
||||
When embedding the broker, you can choose if you want to enable persistence and list the destinations that should be made available.
|
||||
These can be specified as a comma-separated list to create them with the default options, or you can define bean(s) of type `org.apache.activemq.artemis.jms.server.config.JMSQueueConfiguration` or `org.apache.activemq.artemis.jms.server.config.TopicConfiguration`, for advanced queue and topic configurations, respectively.
|
||||
|
||||
By default, a `CachingConnectionFactory` wraps the native `ConnectionFactory` with sensible settings that you can control by external configuration properties in `+spring.jms.*+`:
|
||||
By default, a `org.springframework.jms.connection.CachingConnectionFactory` wraps the native `jakarta.jms.ConnectionFactory` with sensible settings that you can control by external configuration properties in `+spring.jms.*+`:
|
||||
|
||||
[configprops,yaml]
|
||||
----
|
||||
@@ -112,7 +112,7 @@ No JNDI lookup is involved, and destinations are resolved against their names, u
|
||||
[[messaging.jms.jndi]]
|
||||
== Using a JNDI ConnectionFactory
|
||||
|
||||
If you are running your application in an application server, Spring Boot tries to locate a JMS `ConnectionFactory` by using JNDI.
|
||||
If you are running your application in an application server, Spring Boot tries to locate a JMS `jakarta.jms.ConnectionFactory` by using JNDI.
|
||||
By default, the `java:/JmsXA` and `java:/XAConnectionFactory` location are checked.
|
||||
You can use the configprop:spring.jms.jndi-name[] property if you need to specify an alternative location, as shown in the following example:
|
||||
|
||||
@@ -133,7 +133,7 @@ Spring's `JmsTemplate` is auto-configured, and you can autowire it directly into
|
||||
include-code::MyBean[]
|
||||
|
||||
NOTE: javadoc:{url-spring-framework-javadoc}/org.springframework.jms.core.JmsMessagingTemplate[] can be injected in a similar manner.
|
||||
If a `DestinationResolver` or a `MessageConverter` bean is defined, it is associated automatically to the auto-configured `JmsTemplate`.
|
||||
If a `org.springframework.jms.support.destination.DestinationResolver` or a `org.springframework.jms.support.converter.MessageConverter` bean is defined, it is associated automatically to the auto-configured `JmsTemplate`.
|
||||
|
||||
|
||||
|
||||
@@ -142,12 +142,12 @@ If a `DestinationResolver` or a `MessageConverter` bean is defined, it is associ
|
||||
|
||||
When the JMS infrastructure is present, any bean can be annotated with `@JmsListener` to create a listener endpoint.
|
||||
If no `JmsListenerContainerFactory` has been defined, a default one is configured automatically.
|
||||
If a `DestinationResolver`, a `MessageConverter`, or a `jakarta.jms.ExceptionListener` beans are defined, they are associated automatically with the default factory.
|
||||
If a `org.springframework.jms.support.destination.DestinationResolver`, a `org.springframework.jms.support.converter.MessageConverter`, or a `jakarta.jms.ExceptionListener` beans are defined, they are associated automatically with the default factory.
|
||||
|
||||
By default, the default factory is transactional.
|
||||
If you run in an infrastructure where a `JtaTransactionManager` is present, it is associated to the listener container by default.
|
||||
If not, the `sessionTransacted` flag is enabled.
|
||||
In that latter scenario, you can associate your local data store transaction to the processing of an incoming message by adding `@Transactional` on your listener method (or a delegate thereof).
|
||||
In that latter scenario, you can associate your local data store transaction to the processing of an incoming message by adding `@org.springframework.transaction.annotation.Transactional` on your listener method (or a delegate thereof).
|
||||
This ensures that the incoming message is acknowledged, once the local transaction has completed.
|
||||
This also includes sending response messages that have been performed on the same JMS session.
|
||||
|
||||
@@ -159,7 +159,7 @@ TIP: See the javadoc:{url-spring-framework-javadoc}/org.springframework.jms.anno
|
||||
|
||||
If you need to create more `JmsListenerContainerFactory` instances or if you want to override the default, Spring Boot provides a `DefaultJmsListenerContainerFactoryConfigurer` that you can use to initialize a `DefaultJmsListenerContainerFactory` with the same settings as the one that is auto-configured.
|
||||
|
||||
For instance, the following example exposes another factory that uses a specific `MessageConverter`:
|
||||
For instance, the following example exposes another factory that uses a specific `org.springframework.jms.support.converter.MessageConverter`:
|
||||
|
||||
include-code::custom/MyJmsConfiguration[]
|
||||
|
||||
|
||||
@@ -114,7 +114,7 @@ spring:
|
||||
|
||||
This sets the common `prop.one` Kafka property to `first` (applies to producers, consumers, admins, and streams), the `prop.two` admin property to `second`, the `prop.three` consumer property to `third`, the `prop.four` producer property to `fourth` and the `prop.five` streams property to `fifth`.
|
||||
|
||||
You can also configure the Spring Kafka `JsonDeserializer` as follows:
|
||||
You can also configure the Spring Kafka `org.springframework.kafka.support.serializer.JsonDeserializer` as follows:
|
||||
|
||||
[configprops,yaml]
|
||||
----
|
||||
@@ -127,7 +127,7 @@ spring:
|
||||
"[spring.json.trusted.packages]": "com.example.main,com.example.another"
|
||||
----
|
||||
|
||||
Similarly, you can disable the `JsonSerializer` default behavior of sending type information in headers:
|
||||
Similarly, you can disable the `org.springframework.kafka.support.serializer.JsonSerializer` default behavior of sending type information in headers:
|
||||
|
||||
[configprops,yaml]
|
||||
----
|
||||
|
||||
@@ -174,7 +174,7 @@ But when you work with `WebClient`, `RestClient` or `RestTemplate` directly, you
|
||||
=== Testing Custom Hints
|
||||
|
||||
The `RuntimeHintsPredicates` API can be used to test your hints.
|
||||
The API provides methods that build a `Predicate` that can be used to test a `RuntimeHints` instance.
|
||||
The API provides methods that build a `java.util.function.Predicate` that can be used to test a `RuntimeHints` instance.
|
||||
|
||||
If you're using AssertJ, your test would look like this:
|
||||
|
||||
|
||||
@@ -25,7 +25,7 @@ Embedded servers are started and listen on a random port.
|
||||
Embedded servers are started and listen on a defined port (from your `application.properties`) or on the default port of `8080`.
|
||||
* `NONE`: Loads an `ApplicationContext` by using `SpringApplication` but does not provide _any_ web environment (mock or otherwise).
|
||||
|
||||
NOTE: If your test is `@Transactional`, it rolls back the transaction at the end of each test method by default.
|
||||
NOTE: If your test is `@org.springframework.transaction.annotation.Transactional`, it rolls back the transaction at the end of each test method by default.
|
||||
However, as using this arrangement with either `RANDOM_PORT` or `DEFINED_PORT` implicitly provides a real servlet environment, the HTTP client and server run in separate threads and, thus, in separate transactions.
|
||||
Any transaction initiated on the server does not roll back in this case.
|
||||
|
||||
@@ -228,7 +228,7 @@ If you need those components as part of an integration test, annotate the test w
|
||||
|
||||
If you have created your own reporting components (e.g. a custom `SpanExporter` or `+brave.handler.SpanHandler+`) and you don't want them to be active in tests, you can use the `@ConditionalOnEnabledTracing` annotation to disable them.
|
||||
|
||||
If you annotate xref:testing/spring-boot-applications.adoc#testing.spring-boot-applications.autoconfigured-tests[a sliced test] with `@AutoConfigureObservability`, it auto-configures a no-op `Tracer`.
|
||||
If you annotate xref:testing/spring-boot-applications.adoc#testing.spring-boot-applications.autoconfigured-tests[a sliced test] with `@AutoConfigureObservability`, it auto-configures a no-op `io.micrometer.tracing.Tracer`.
|
||||
Data exporting in sliced tests is not supported with the `@AutoConfigureObservability` annotation.
|
||||
|
||||
|
||||
@@ -267,7 +267,7 @@ See the javadoc:org.springframework.boot.test.mock.mockito.SpyBean[] API documen
|
||||
|
||||
NOTE: While Spring's test framework caches application contexts between tests and reuses a context for tests sharing the same configuration, the use of `@MockBean` or `@SpyBean` influences the cache key, which will most likely increase the number of contexts.
|
||||
|
||||
TIP: If you are using `@SpyBean` to spy on a bean with `@Cacheable` methods that refer to parameters by name, your application must be compiled with `-parameters`.
|
||||
TIP: If you are using `@SpyBean` to spy on a bean with `@org.springframework.cache.annotation.Cacheable` methods that refer to parameters by name, your application must be compiled with `-parameters`.
|
||||
This ensures that the parameter names are available to the caching infrastructure once the bean has been spied upon.
|
||||
|
||||
TIP: When you are using `@SpyBean` to spy on a bean that is proxied by Spring, you may need to remove Spring's proxy in some situations, for example when setting expectations using `given` or `when`.
|
||||
@@ -333,13 +333,13 @@ include-code::MyJsonAssertJTests[tag=*]
|
||||
== Auto-configured Spring MVC Tests
|
||||
|
||||
To test whether Spring MVC controllers are working as expected, use the `@WebMvcTest` annotation.
|
||||
`@WebMvcTest` auto-configures the Spring MVC infrastructure and limits scanned beans to `@Controller`, `@ControllerAdvice`, `@JsonComponent`, `Converter`, `GenericConverter`, `Filter`, `HandlerInterceptor`, `WebMvcConfigurer`, `WebMvcRegistrations`, and `HandlerMethodArgumentResolver`.
|
||||
`@WebMvcTest` auto-configures the Spring MVC infrastructure and limits scanned beans to `@Controller`, `@ControllerAdvice`, `@JsonComponent`, `org.springframework.core.convert.converter.Converter`, `org.springframework.core.convert.converter.GenericConverter`, `Filter`, `HandlerInterceptor`, `WebMvcConfigurer`, `WebMvcRegistrations`, and `org.springframework.web.method.support.HandlerMethodArgumentResolver`.
|
||||
Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@WebMvcTest` annotation is used.
|
||||
`@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans.
|
||||
|
||||
TIP: A list of the auto-configuration settings that are enabled by `@WebMvcTest` can be xref:appendix:test-auto-configuration/index.adoc[found in the appendix].
|
||||
|
||||
TIP: If you need to register extra components, such as the Jackson `Module`, you can import additional configuration classes by using `@Import` on your test.
|
||||
TIP: If you need to register extra components, such as the Jackson `com.fasterxml.jackson.databind.Module`, you can import additional configuration classes by using `@Import` on your test.
|
||||
|
||||
Often, `@WebMvcTest` is limited to a single controller and is used in combination with `@MockBean` to provide mock implementations for required collaborators.
|
||||
|
||||
@@ -376,13 +376,13 @@ TIP: Sometimes writing Spring MVC tests is not enough; Spring Boot can help you
|
||||
== Auto-configured Spring WebFlux Tests
|
||||
|
||||
To test that {url-spring-framework-docs}/web-reactive.html[Spring WebFlux] controllers are working as expected, you can use the `@WebFluxTest` annotation.
|
||||
`@WebFluxTest` auto-configures the Spring WebFlux infrastructure and limits scanned beans to `@Controller`, `@ControllerAdvice`, `@JsonComponent`, `Converter`, `GenericConverter`, `WebFilter`, and `WebFluxConfigurer`.
|
||||
`@WebFluxTest` auto-configures the Spring WebFlux infrastructure and limits scanned beans to `@Controller`, `@ControllerAdvice`, `@JsonComponent`, `org.springframework.core.convert.converter.Converter`, `org.springframework.core.convert.converter.GenericConverter` and `WebFluxConfigurer`.
|
||||
Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@WebFluxTest` annotation is used.
|
||||
`@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans.
|
||||
|
||||
TIP: A list of the auto-configurations that are enabled by `@WebFluxTest` can be xref:appendix:test-auto-configuration/index.adoc[found in the appendix].
|
||||
|
||||
TIP: If you need to register extra components, such as Jackson `Module`, you can import additional configuration classes using `@Import` on your test.
|
||||
TIP: If you need to register extra components, such as Jackson `com.fasterxml.jackson.databind.Module`, you can import additional configuration classes using `@Import` on your test.
|
||||
|
||||
Often, `@WebFluxTest` is limited to a single controller and used in combination with the `@MockBean` annotation to provide mock implementations for required collaborators.
|
||||
|
||||
@@ -396,7 +396,7 @@ include-code::MyControllerTests[]
|
||||
TIP: This setup is only supported by WebFlux applications as using `WebTestClient` in a mocked web application only works with WebFlux at the moment.
|
||||
|
||||
NOTE: `@WebFluxTest` cannot detect routes registered through the functional web framework.
|
||||
For testing `RouterFunction` beans in the context, consider importing your `RouterFunction` yourself by using `@Import` or by using `@SpringBootTest`.
|
||||
For testing `org.springframework.web.reactive.function.server.RouterFunction` beans in the context, consider importing your `org.springframework.web.reactive.function.server.RouterFunction` yourself by using `@Import` or by using `@SpringBootTest`.
|
||||
|
||||
NOTE: `@WebFluxTest` cannot detect custom security configuration registered as a `@Bean` of type `SecurityWebFilterChain`.
|
||||
To include that in your test, you will need to import the configuration that registers the bean by using `@Import` or by using `@SpringBootTest`.
|
||||
@@ -447,7 +447,7 @@ There are `GraphQlTester` variants and Spring Boot will auto-configure them depe
|
||||
|
||||
Spring Boot helps you to test your {url-spring-graphql-docs}/controllers.html[Spring GraphQL Controllers] with the `@GraphQlTest` annotation.
|
||||
`@GraphQlTest` auto-configures the Spring GraphQL infrastructure, without any transport nor server being involved.
|
||||
This limits scanned beans to `@Controller`, `RuntimeWiringConfigurer`, `JsonComponent`, `Converter`, `GenericConverter`, `DataFetcherExceptionResolver`, `Instrumentation` and `GraphQlSourceBuilderCustomizer`.
|
||||
This limits scanned beans to `@Controller`, `RuntimeWiringConfigurer`, `JsonComponent`, `org.springframework.core.convert.converter.Converter`, `org.springframework.core.convert.converter.GenericConverter`, `DataFetcherExceptionResolver`, `graphql.execution.instrumentation.Instrumentation` and `GraphQlSourceBuilderCustomizer`.
|
||||
Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@GraphQlTest` annotation is used.
|
||||
`@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans.
|
||||
|
||||
@@ -469,7 +469,7 @@ include-code::GraphQlIntegrationTests[]
|
||||
== Auto-configured Data Cassandra Tests
|
||||
|
||||
You can use `@DataCassandraTest` to test Cassandra applications.
|
||||
By default, it configures a `CassandraTemplate`, scans for `@Table` classes, and configures Spring Data Cassandra repositories.
|
||||
By default, it configures a `CassandraTemplate`, scans for `@org.springframework.data.cassandra.core.mapping.Table` classes, and configures Spring Data Cassandra repositories.
|
||||
Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@DataCassandraTest` annotation is used.
|
||||
`@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans.
|
||||
(For more about using Cassandra with Spring Boot, see xref:data/nosql.adoc#data.nosql.cassandra[].)
|
||||
@@ -486,7 +486,7 @@ include-code::MyDataCassandraTests[]
|
||||
== Auto-configured Data Couchbase Tests
|
||||
|
||||
You can use `@DataCouchbaseTest` to test Couchbase applications.
|
||||
By default, it configures a `CouchbaseTemplate` or `ReactiveCouchbaseTemplate`, scans for `@Document` classes, and configures Spring Data Couchbase repositories.
|
||||
By default, it configures a `CouchbaseTemplate` or `ReactiveCouchbaseTemplate`, scans for `@org.springframework.data.couchbase.core.mapping.Document` classes, and configures Spring Data Couchbase repositories.
|
||||
Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@DataCouchbaseTest` annotation is used.
|
||||
`@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans.
|
||||
(For more about using Couchbase with Spring Boot, see xref:data/nosql.adoc#data.nosql.couchbase[], earlier in this chapter.)
|
||||
@@ -503,7 +503,7 @@ include-code::MyDataCouchbaseTests[]
|
||||
== Auto-configured Data Elasticsearch Tests
|
||||
|
||||
You can use `@DataElasticsearchTest` to test Elasticsearch applications.
|
||||
By default, it configures an `ElasticsearchTemplate`, scans for `@Document` classes, and configures Spring Data Elasticsearch repositories.
|
||||
By default, it configures an `ElasticsearchTemplate`, scans for `@org.springframework.data.elasticsearch.annotations.Document` classes, and configures Spring Data Elasticsearch repositories.
|
||||
Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@DataElasticsearchTest` annotation is used.
|
||||
`@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans.
|
||||
(For more about using Elasticsearch with Spring Boot, see xref:data/nosql.adoc#data.nosql.elasticsearch[], earlier in this chapter.)
|
||||
@@ -539,7 +539,7 @@ include-code::MyNonTransactionalTests[]
|
||||
Data JPA tests may also inject a javadoc:org.springframework.boot.test.autoconfigure.orm.jpa.TestEntityManager[] bean, which provides an alternative to the standard JPA `EntityManager` that is specifically designed for tests.
|
||||
|
||||
TIP: `TestEntityManager` can also be auto-configured to any of your Spring-based test class by adding `@AutoConfigureTestEntityManager`.
|
||||
When doing so, make sure that your test is running in a transaction, for instance by adding `@Transactional` on your test class or method.
|
||||
When doing so, make sure that your test is running in a transaction, for instance by adding `@org.springframework.transaction.annotation.Transactional` on your test class or method.
|
||||
|
||||
A `JdbcTemplate` is also available if you need that.
|
||||
The following example shows the `@DataJpaTest` annotation in use:
|
||||
@@ -636,7 +636,7 @@ If that is not what you want, you can disable transaction management for a test
|
||||
== Auto-configured Data MongoDB Tests
|
||||
|
||||
You can use `@DataMongoTest` to test MongoDB applications.
|
||||
By default, it configures a `MongoTemplate`, scans for `@Document` classes, and configures Spring Data MongoDB repositories.
|
||||
By default, it configures a `MongoTemplate`, scans for `@org.springframework.data.mongodb.core.mapping.Document` classes, and configures Spring Data MongoDB repositories.
|
||||
Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@DataMongoTest` annotation is used.
|
||||
`@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans.
|
||||
(For more about using MongoDB with Spring Boot, see xref:data/nosql.adoc#data.nosql.mongodb[].)
|
||||
@@ -653,7 +653,7 @@ include-code::MyDataMongoDbTests[]
|
||||
== Auto-configured Data Neo4j Tests
|
||||
|
||||
You can use `@DataNeo4jTest` to test Neo4j applications.
|
||||
By default, it scans for `@Node` classes, and configures Spring Data Neo4j repositories.
|
||||
By default, it scans for `@org.springframework.data.neo4j.core.schema.Node` classes, and configures Spring Data Neo4j repositories.
|
||||
Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@DataNeo4jTest` annotation is used.
|
||||
`@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans.
|
||||
(For more about using Neo4J with Spring Boot, see xref:data/nosql.adoc#data.nosql.neo4j[].)
|
||||
|
||||
@@ -32,7 +32,7 @@ include-code::MyEnvironmentTests[]
|
||||
[[testing.utilities.output-capture]]
|
||||
== OutputCaptureExtension
|
||||
|
||||
`OutputCaptureExtension` is a JUnit `Extension` that you can use to capture javadoc:java.lang.System#out[] and javadoc:java.lang.System#err[] output.
|
||||
`OutputCaptureExtension` is a JUnit `org.junit.jupiter.api.extension.Extension` that you can use to capture javadoc:java.lang.System#out[] and javadoc:java.lang.System#err[] output.
|
||||
To use it, add `@ExtendWith(OutputCaptureExtension.class)` and inject `CapturedOutput` as an argument to your test class constructor or test method as follows:
|
||||
|
||||
include-code::MyOutputCaptureTests[]
|
||||
|
||||
@@ -31,7 +31,7 @@ This is done by automatically defining a `Neo4jConnectionDetails` bean which is
|
||||
NOTE: You'll need to add the `spring-boot-testcontainers` module as a test dependency in order to use service connections with Testcontainers.
|
||||
|
||||
Service connection annotations are processed by `ContainerConnectionDetailsFactory` classes registered with `spring.factories`.
|
||||
A `ContainerConnectionDetailsFactory` can create a `ConnectionDetails` bean based on a specific `Container` subclass, or the Docker image name.
|
||||
A `ContainerConnectionDetailsFactory` can create a `ConnectionDetails` bean based on a specific `org.testcontainers.containers.Container` subclass, or the Docker image name.
|
||||
|
||||
The following service connection factories are provided in the `spring-boot-testcontainers` jar:
|
||||
|
||||
@@ -95,7 +95,7 @@ The following service connection factories are provided in the `spring-boot-test
|
||||
|
||||
[TIP]
|
||||
====
|
||||
By default all applicable connection details beans will be created for a given `Container`.
|
||||
By default all applicable connection details beans will be created for a given `org.testcontainers.containers.Container`.
|
||||
For example, a `PostgreSQLContainer` will create both `JdbcConnectionDetails` and `R2dbcConnectionDetails`.
|
||||
|
||||
If you want to create only a subset of the applicable types, you can use the `type` attribute of `@ServiceConnection`.
|
||||
@@ -103,7 +103,7 @@ If you want to create only a subset of the applicable types, you can use the `ty
|
||||
|
||||
By default `Container.getDockerImageName().getRepository()` is used to obtain the name used to find connection details.
|
||||
The repository portion of the Docker image name ignores any registry and the version.
|
||||
This works as long as Spring Boot is able to get the instance of the `Container`, which is the case when using a `static` field like in the example above.
|
||||
This works as long as Spring Boot is able to get the instance of the `org.testcontainers.containers.Container`, which is the case when using a `static` field like in the example above.
|
||||
|
||||
If you're using a `@Bean` method, Spring Boot won't call the bean method to get the Docker image name, because this would cause eager initialization issues.
|
||||
Instead, the return type of the bean method is used to find out which connection detail should be used.
|
||||
|
||||
@@ -26,7 +26,7 @@ include-code::MyUserHandler[]
|
||||
|
||||
"`WebFlux.fn`" is part of the Spring Framework and detailed information is available in its {url-spring-framework-docs}/web/webflux-functional.html[reference documentation].
|
||||
|
||||
TIP: You can define as many `RouterFunction` beans as you like to modularize the definition of the router.
|
||||
TIP: You can define as many `org.springframework.web.reactive.function.server.RouterFunction` beans as you like to modularize the definition of the router.
|
||||
Beans can be ordered if you need to apply a precedence.
|
||||
|
||||
To get started, add the `spring-boot-starter-webflux` module to your application.
|
||||
@@ -49,7 +49,7 @@ The auto-configuration adds the following features on top of Spring's defaults:
|
||||
|
||||
If you want to keep Spring Boot WebFlux features and you want to add additional {url-spring-framework-docs}/web/webflux/config.html[WebFlux configuration], you can add your own `@Configuration` class of type `WebFluxConfigurer` but *without* `@EnableWebFlux`.
|
||||
|
||||
If you want to add additional customization to the auto-configured `HttpHandler`, you can define beans of type `WebHttpHandlerBuilderCustomizer` and use them to modify the `WebHttpHandlerBuilder`.
|
||||
If you want to add additional customization to the auto-configured `org.springframework.http.server.reactive.HttpHandler`, you can define beans of type `WebHttpHandlerBuilderCustomizer` and use them to modify the `WebHttpHandlerBuilder`.
|
||||
|
||||
If you want to take complete control of Spring WebFlux, you can add your own `@Configuration` annotated with `@EnableWebFlux`.
|
||||
|
||||
@@ -137,14 +137,14 @@ If one is not found, it then looks for an `index` template.
|
||||
If either is found, it is automatically used as the welcome page of the application.
|
||||
|
||||
This only acts as a fallback for actual index routes defined by the application.
|
||||
The ordering is defined by the order of `HandlerMapping` beans which is by default the following:
|
||||
The ordering is defined by the order of `org.springframework.web.reactive.HandlerMapping` beans which is by default the following:
|
||||
|
||||
[cols="1,1"]
|
||||
|===
|
||||
|`RouterFunctionMapping`
|
||||
|Endpoints declared with `RouterFunction` beans
|
||||
|`org.springframework.web.reactive.function.server.support.RouterFunctionMapping`
|
||||
|Endpoints declared with `org.springframework.web.reactive.function.server.RouterFunction` beans
|
||||
|
||||
|`RequestMappingHandlerMapping`
|
||||
|`org.springframework.web.reactive.result.method.annotation.RequestMappingHandlerMapping`
|
||||
|Endpoints declared in `@Controller` beans
|
||||
|
||||
|`RouterFunctionMapping` for the Welcome Page
|
||||
@@ -196,7 +196,7 @@ This support can be enabled by setting configprop:spring.webflux.problemdetails.
|
||||
|
||||
|
||||
The first step to customizing this feature often involves using the existing mechanism but replacing or augmenting the error contents.
|
||||
For that, you can add a bean of type `ErrorAttributes`.
|
||||
For that, you can add a bean of type `org.springframework.boot.web.reactive.error.ErrorAttributes`.
|
||||
|
||||
To change the error handling behavior, you can implement `ErrorWebExceptionHandler` and register a bean definition of that type.
|
||||
Because an `ErrorWebExceptionHandler` is quite low-level, Spring Boot also provides a convenient `AbstractErrorWebExceptionHandler` to let you handle errors in a WebFlux functional way, as shown in the following example:
|
||||
@@ -253,8 +253,8 @@ src/
|
||||
[[web.reactive.webflux.web-filters]]
|
||||
=== Web Filters
|
||||
|
||||
Spring WebFlux provides a `WebFilter` interface that can be implemented to filter HTTP request-response exchanges.
|
||||
`WebFilter` beans found in the application context will be automatically used to filter each exchange.
|
||||
Spring WebFlux provides a `org.springframework.web.server.WebFilter` interface that can be implemented to filter HTTP request-response exchanges.
|
||||
`org.springframework.web.server.WebFilter` beans found in the application context will be automatically used to filter each exchange.
|
||||
|
||||
Where the order of the filters is important they can implement `Ordered` or be annotated with `@Order`.
|
||||
Spring Boot auto-configuration may configure web filters for you.
|
||||
|
||||
@@ -25,7 +25,7 @@ include-code::MyUserHandler[]
|
||||
Spring MVC is part of the core Spring Framework, and detailed information is available in the {url-spring-framework-docs}/web/webmvc.html[reference documentation].
|
||||
There are also several guides that cover Spring MVC available at https://spring.io/guides.
|
||||
|
||||
TIP: You can define as many `RouterFunction` beans as you like to modularize the definition of the router.
|
||||
TIP: You can define as many `org.springframework.web.servlet.function.RouterFunction` beans as you like to modularize the definition of the router.
|
||||
Beans can be ordered if you need to apply a precedence.
|
||||
|
||||
|
||||
@@ -39,7 +39,7 @@ In addition to Spring MVC's defaults, the auto-configuration provides the follow
|
||||
|
||||
* Inclusion of `ContentNegotiatingViewResolver` and `BeanNameViewResolver` beans.
|
||||
* Support for serving static resources, including support for WebJars (covered xref:web/servlet.adoc#web.servlet.spring-mvc.static-content[later in this document]).
|
||||
* Automatic registration of `Converter`, `GenericConverter`, and `Formatter` beans.
|
||||
* Automatic registration of `org.springframework.core.convert.converter.Converter`, `org.springframework.core.convert.converter.GenericConverter`, and `org.springframework.format.Formatter` beans.
|
||||
* Support for `HttpMessageConverters` (covered xref:web/servlet.adoc#web.servlet.spring-mvc.message-converters[later in this document]).
|
||||
* Automatic registration of `MessageCodesResolver` (covered xref:web/servlet.adoc#web.servlet.spring-mvc.message-codes[later in this document]).
|
||||
* Static `index.html` support.
|
||||
@@ -47,7 +47,7 @@ In addition to Spring MVC's defaults, the auto-configuration provides the follow
|
||||
|
||||
If you want to keep those Spring Boot MVC customizations and make more {url-spring-framework-docs}/web/webmvc.html[MVC customizations] (interceptors, formatters, view controllers, and other features), you can add your own `@Configuration` class of type `WebMvcConfigurer` but *without* `@EnableWebMvc`.
|
||||
|
||||
If you want to provide custom instances of `RequestMappingHandlerMapping`, `RequestMappingHandlerAdapter`, or `ExceptionHandlerExceptionResolver`, and still keep the Spring Boot MVC customizations, you can declare a bean of type `WebMvcRegistrations` and use it to provide custom instances of those components.
|
||||
If you want to provide custom instances of `org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping`, `org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter`, or `ExceptionHandlerExceptionResolver`, and still keep the Spring Boot MVC customizations, you can declare a bean of type `WebMvcRegistrations` and use it to provide custom instances of those components.
|
||||
The custom instances will be subject to further initialization and configuration by Spring MVC.
|
||||
To participate in, and if desired, override that subsequent processing, a `WebMvcConfigurer` should be used.
|
||||
|
||||
@@ -60,7 +60,7 @@ Alternatively, add your own `@Configuration`-annotated `DelegatingWebMvcConfigur
|
||||
=== Spring MVC Conversion Service
|
||||
|
||||
Spring MVC uses a different `ConversionService` to the one used to convert values from your `application.properties` or `application.yaml` file.
|
||||
It means that `Period`, `Duration` and `DataSize` converters are not available and that `@DurationUnit` and `@DataSizeUnit` annotations will be ignored.
|
||||
It means that `java.time.Period`, `java.time.Duration` and `DataSize` converters are not available and that `@DurationUnit` and `@DataSizeUnit` annotations will be ignored.
|
||||
|
||||
If you want to customize the `ConversionService` used by Spring MVC, you can provide a `WebMvcConfigurer` bean with an `addFormatters` method.
|
||||
From this method you can register any converter that you like, or you can delegate to the static methods available on `ApplicationConversionService`.
|
||||
@@ -213,12 +213,12 @@ If one is not found, it then looks for an `index` template.
|
||||
If either is found, it is automatically used as the welcome page of the application.
|
||||
|
||||
This only acts as a fallback for actual index routes defined by the application.
|
||||
The ordering is defined by the order of `HandlerMapping` beans which is by default the following:
|
||||
The ordering is defined by the order of `org.springframework.web.servlet.HandlerMapping` beans which is by default the following:
|
||||
|
||||
[cols="1,1"]
|
||||
|===
|
||||
|`RouterFunctionMapping`
|
||||
|Endpoints declared with `RouterFunction` beans
|
||||
|Endpoints declared with `org.springframework.web.servlet.function.RouterFunction` beans
|
||||
|
||||
|`RequestMappingHandlerMapping`
|
||||
|Endpoints declared in `@Controller` beans
|
||||
@@ -298,7 +298,7 @@ spring:
|
||||
|
||||
Spring MVC will throw a `NoHandlerFoundException` if a handler is not found for a request.
|
||||
Note that, by default, the xref:web/servlet.adoc#web.servlet.spring-mvc.static-content[serving of static content] is mapped to `+/**+` and will, therefore, provide a handler for all requests.
|
||||
If no static content is available, `ResourceHttpRequestHandler` will throw a `NoResourceFoundException`.
|
||||
If no static content is available, `ResourceHttpRequestHandler` will throw a `org.springframework.web.servlet.resource.NoResourceFoundException`.
|
||||
For a `NoHandlerFoundException` to be thrown, set configprop:spring.mvc.static-path-pattern[] to a more specific value such as `/resources/**` or set configprop:spring.web.resources.add-mappings[] to `false` to disable serving of static content entirely.
|
||||
|
||||
|
||||
@@ -342,12 +342,12 @@ If you have this problem, you can reorder the classpath in the IDE to place the
|
||||
|
||||
By default, Spring Boot provides an `/error` mapping that handles all errors in a sensible way, and it is registered as a "`global`" error page in the servlet container.
|
||||
For machine clients, it produces a JSON response with details of the error, the HTTP status, and the exception message.
|
||||
For browser clients, there is a "`whitelabel`" error view that renders the same data in HTML format (to customize it, add a `View` that resolves to `error`).
|
||||
For browser clients, there is a "`whitelabel`" error view that renders the same data in HTML format (to customize it, add a `org.springframework.web.servlet.View` that resolves to `error`).
|
||||
|
||||
There are a number of `server.error` properties that can be set if you want to customize the default error handling behavior.
|
||||
See the xref:appendix:application-properties/index.adoc#appendix.application-properties.server[Server Properties] section of the Appendix.
|
||||
|
||||
To replace the default behavior completely, you can implement `ErrorController` and register a bean definition of that type or add a bean of type `ErrorAttributes` to use the existing mechanism but replace the contents.
|
||||
To replace the default behavior completely, you can implement `ErrorController` and register a bean definition of that type or add a bean of type `org.springframework.boot.web.servlet.error.ErrorAttributes` to use the existing mechanism but replace the contents.
|
||||
|
||||
TIP: The `BasicErrorController` can be used as a base class for a custom `ErrorController`.
|
||||
This is particularly useful if you want to add a handler for a new content type (the default is to handle `text/html` specifically and provide a fallback for everything else).
|
||||
@@ -373,7 +373,7 @@ You can also define a class annotated with `@ControllerAdvice` to customize the
|
||||
|
||||
include-code::MyControllerAdvice[]
|
||||
|
||||
In the preceding example, if `MyException` is thrown by a controller defined in the same package as `+SomeController+`, a JSON representation of the `MyErrorBody` POJO is used instead of the `ErrorAttributes` representation.
|
||||
In the preceding example, if `MyException` is thrown by a controller defined in the same package as `+SomeController+`, a JSON representation of the `MyErrorBody` POJO is used instead of the `org.springframework.boot.web.servlet.error.ErrorAttributes` representation.
|
||||
|
||||
In some cases, errors handled at the controller level are not recorded by web observations or the xref:actuator/metrics.adoc#actuator.metrics.supported.spring-mvc[metrics infrastructure].
|
||||
Applications can ensure that such exceptions are recorded with the observations by {url-spring-framework-docs}/integration/observability.html#observability.http-server.servlet[setting the handled exception on the observation context].
|
||||
@@ -429,12 +429,12 @@ The `ErrorController` then picks up any unhandled exceptions.
|
||||
[[web.servlet.spring-mvc.error-handling.error-pages-without-spring-mvc]]
|
||||
==== Mapping Error Pages Outside of Spring MVC
|
||||
|
||||
For applications that do not use Spring MVC, you can use the `ErrorPageRegistrar` interface to directly register `ErrorPages`.
|
||||
For applications that do not use Spring MVC, you can use the `ErrorPageRegistrar` interface to directly register `org.springframework.boot.web.server.ErrorPage` instances.
|
||||
This abstraction works directly with the underlying embedded servlet container and works even if you do not have a Spring MVC `DispatcherServlet`.
|
||||
|
||||
include-code::MyErrorPagesConfiguration[]
|
||||
|
||||
NOTE: If you register an `ErrorPage` with a path that ends up being handled by a `Filter` (as is common with some non-Spring web frameworks, like Jersey and Wicket), then the `Filter` has to be explicitly registered as an `ERROR` dispatcher, as shown in the following example:
|
||||
NOTE: If you register an `org.springframework.boot.web.server.ErrorPage` with a path that ends up being handled by a `Filter` (as is common with some non-Spring web frameworks, like Jersey and Wicket), then the `Filter` has to be explicitly registered as an `ERROR` dispatcher, as shown in the following example:
|
||||
|
||||
include-code::MyFilterConfiguration[]
|
||||
|
||||
@@ -476,7 +476,7 @@ https://jersey.github.io/[Jersey] and https://cxf.apache.org/[Apache CXF] work q
|
||||
CXF requires you to register its `Servlet` or `Filter` as a `@Bean` in your application context.
|
||||
Jersey has some native Spring support, so we also provide auto-configuration support for it in Spring Boot, together with a starter.
|
||||
|
||||
To get started with Jersey, include the `spring-boot-starter-jersey` as a dependency and then you need one `@Bean` of type `ResourceConfig` in which you register all the endpoints, as shown in the following example:
|
||||
To get started with Jersey, include the `spring-boot-starter-jersey` as a dependency and then you need one `@Bean` of type `org.glassfish.jersey.server.ResourceConfig` in which you register all the endpoints, as shown in the following example:
|
||||
|
||||
include-code::MyJerseyConfig[]
|
||||
|
||||
@@ -490,9 +490,9 @@ All the registered endpoints should be a `@Component` with HTTP resource annotat
|
||||
|
||||
include-code::MyEndpoint[]
|
||||
|
||||
Since the `Endpoint` is a Spring `@Component`, its lifecycle is managed by Spring and you can use the `@Autowired` annotation to inject dependencies and use the `@Value` annotation to inject external configuration.
|
||||
Since the `@Endpoint` is a Spring `@Component`, its lifecycle is managed by Spring and you can use the `@Autowired` annotation to inject dependencies and use the `@Value` annotation to inject external configuration.
|
||||
By default, the Jersey servlet is registered and mapped to `/*`.
|
||||
You can change the mapping by adding `@ApplicationPath` to your `ResourceConfig`.
|
||||
You can change the mapping by adding `@ApplicationPath` to your `org.glassfish.jersey.server.ResourceConfig`.
|
||||
|
||||
By default, Jersey is set up as a servlet in a `@Bean` of type `ServletRegistrationBean` named `jerseyServletRegistration`.
|
||||
By default, the servlet is initialized lazily, but you can customize that behavior by setting `spring.jersey.servlet.load-on-startup`.
|
||||
@@ -562,7 +562,7 @@ The single `onStartup` method provides access to the `ServletContext` and, if ne
|
||||
[[web.servlet.embedded-container.context-initializer.scanning]]
|
||||
==== Scanning for Servlets, Filters, and listeners
|
||||
|
||||
When using an embedded container, automatic registration of classes annotated with `@WebServlet`, `@WebFilter`, and `@WebListener` can be enabled by using `@ServletComponentScan`.
|
||||
When using an embedded container, automatic registration of classes annotated with `@jakarta.servlet.annotation.WebServlet`, `@jakarta.servlet.annotation.WebFilter`, and `@jakarta.servlet.annotation.WebListener` can be enabled by using `@ServletComponentScan`.
|
||||
|
||||
TIP: `@ServletComponentScan` has no effect in a standalone container, where the container's built-in discovery mechanisms are used instead.
|
||||
|
||||
@@ -632,7 +632,7 @@ server:
|
||||
----
|
||||
|
||||
If you want to change the `+SameSite+` attribute on other cookies added to your `HttpServletResponse`, you can use a `CookieSameSiteSupplier`.
|
||||
The `CookieSameSiteSupplier` is passed a `Cookie` and may return a `+SameSite+` value, or `null`.
|
||||
The `CookieSameSiteSupplier` is passed a `jakarta.servlet.http.Cookie` and may return a `+SameSite+` value, or `null`.
|
||||
|
||||
There are a number of convenience factory and filter methods that you can use to quickly match specific cookies.
|
||||
For example, adding the following bean will automatically apply a `+SameSite+` of `+Lax+` for all cookies with a name that matches the regular expression `myapp.*`.
|
||||
|
||||
@@ -38,7 +38,7 @@ The default security configuration is implemented in `SecurityAutoConfiguration`
|
||||
`SecurityAutoConfiguration` imports `+SpringBootWebSecurityConfiguration+` for web security and `UserDetailsServiceAutoConfiguration` configures authentication, which is also relevant in non-web applications.
|
||||
|
||||
To completely switch off the default web application security configuration, including Actuator security, or to combine multiple Spring Security components such as OAuth2 Client and Resource Server, add a bean of type `SecurityFilterChain` (doing so does not disable the `UserDetailsService` configuration).
|
||||
To also switch off the `UserDetailsService` configuration, add a bean of type `UserDetailsService`, `AuthenticationProvider`, or `AuthenticationManager`.
|
||||
To also switch off the `UserDetailsService` configuration, add a bean of type `UserDetailsService`, `org.springframework.security.authentication.AuthenticationProvider`, or `AuthenticationManager`.
|
||||
|
||||
The auto-configuration of a `UserDetailsService` will also back off any of the following Spring Security modules is on the classpath:
|
||||
|
||||
@@ -50,8 +50,8 @@ To use `UserDetailsService` in addition to one or more of these dependencies, de
|
||||
|
||||
Access rules can be overridden by adding a custom `SecurityFilterChain` bean.
|
||||
Spring Boot provides convenience methods that can be used to override access rules for actuator endpoints and static resources.
|
||||
`EndpointRequest` can be used to create a `RequestMatcher` that is based on the configprop:management.endpoints.web.base-path[] property.
|
||||
`PathRequest` can be used to create a `RequestMatcher` for resources in commonly used locations.
|
||||
`org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest` can be used to create a `org.springframework.security.web.util.matcher.RequestMatcher` that is based on the configprop:management.endpoints.web.base-path[] property.
|
||||
`org.springframework.boot.autoconfigure.security.servlet.PathRequest` can be used to create a `org.springframework.security.web.util.matcher.RequestMatcher` for resources in commonly used locations.
|
||||
|
||||
|
||||
|
||||
@@ -74,9 +74,9 @@ To use `ReactiveUserDetailsService` in addition to one or more of these dependen
|
||||
|
||||
Access rules and the use of multiple Spring Security components such as OAuth 2 Client and Resource Server can be configured by adding a custom `SecurityWebFilterChain` bean.
|
||||
Spring Boot provides convenience methods that can be used to override access rules for actuator endpoints and static resources.
|
||||
`EndpointRequest` can be used to create a `ServerWebExchangeMatcher` that is based on the configprop:management.endpoints.web.base-path[] property.
|
||||
`org.springframework.boot.actuate.autoconfigure.security.reactive.EndpointRequest` can be used to create a `ServerWebExchangeMatcher` that is based on the configprop:management.endpoints.web.base-path[] property.
|
||||
|
||||
`PathRequest` can be used to create a `ServerWebExchangeMatcher` for resources in commonly used locations.
|
||||
`org.springframework.boot.autoconfigure.security.reactive.PathRequest` can be used to create a `ServerWebExchangeMatcher` for resources in commonly used locations.
|
||||
|
||||
For example, you can customize your security configuration by adding something like:
|
||||
|
||||
@@ -248,7 +248,7 @@ spring:
|
||||
----
|
||||
|
||||
The same properties are applicable for both servlet and reactive applications.
|
||||
Alternatively, you can define your own `JwtDecoder` bean for servlet applications or a `ReactiveJwtDecoder` for reactive applications.
|
||||
Alternatively, you can define your own `org.springframework.security.oauth2.jwt.JwtDecoder` bean for servlet applications or a `org.springframework.security.oauth2.jwt.ReactiveJwtDecoder` for reactive applications.
|
||||
|
||||
In cases where opaque tokens are used instead of JWTs, you can configure the following properties to validate tokens through introspection:
|
||||
|
||||
@@ -329,7 +329,7 @@ The following components can be defined as beans to override auto-configuration
|
||||
* `AuthorizationServerSettings`
|
||||
* `SecurityFilterChain`
|
||||
* `com.nimbusds.jose.jwk.source.JWKSource<com.nimbusds.jose.proc.SecurityContext>`
|
||||
* `JwtDecoder`
|
||||
* `org.springframework.security.oauth2.jwt.JwtDecoder`
|
||||
|
||||
TIP: Spring Boot auto-configures an `InMemoryRegisteredClientRepository` which is used by Spring Authorization Server for the management of registered clients.
|
||||
The `InMemoryRegisteredClientRepository` has limited capabilities and we recommend using it only for development environments.
|
||||
|
||||
Reference in New Issue
Block a user