diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc index 4e84952128..6b5942dffa 100644 --- a/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc +++ b/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc @@ -334,8 +334,8 @@ discussed earlier. ---- You can additionally implement the `org.springframework.core.Ordered` interface or use -the `org.springframework.core.annotation.Order` annotation if several `CommandLineRunner` or -`ApplicationRunner` beans are defined that must be called in a specific order. +the `org.springframework.core.annotation.Order` annotation if several `CommandLineRunner` +or `ApplicationRunner` beans are defined that must be called in a specific order. @@ -2848,11 +2848,12 @@ that you can see how to set things up. [[boot-features-security]] == Security -If Spring Security is on the classpath, then web applications are secure by default. Spring Boot -relies on Spring Security’s content-negotiation strategy to determine whether to use `httpBasic` -or `formLogin`. To add method-level security to a web application, you can also add `@EnableGlobalMethodSecurity` -with your desired settings. Additional information can be found in the {spring-security-reference}#jc-method[Spring -Security Reference]. +If Spring Security is on the classpath, then web applications are secure by default. +Spring Boot relies on Spring Security’s content-negotiation strategy to determine whether +to use `httpBasic` +or `formLogin`. To add method-level security to a web application, you can also add +`@EnableGlobalMethodSecurity` with your desired settings. Additional information can be +found in the {spring-security-reference}#jc-method[Spring Security Reference]. The default `AuthenticationManager` has a single user (the user name is '`user`', and the password is random and is printed at INFO level when the application starts), as shown in @@ -2871,8 +2872,8 @@ The default security configuration is implemented in `SecurityAutoConfiguration` the classes imported from there (`SpringBootWebSecurityConfiguration` for web security and `AuthenticationManagerConfiguration` for authentication configuration, which is also relevant in non-web applications). To switch off the default web application security -configuration completely, you can add a bean of type `WebSecurityConfigurerAdapter` (this does not -disable the authentication manager configuration or Actuator's security). +configuration completely, you can add a bean of type `WebSecurityConfigurerAdapter` (this +does not disable the authentication manager configuration or Actuator's security). To also switch off the authentication manager configuration, you can add a bean of type `UserDetailsService`, `AuthenticationProvider` or `AuthenticationManager`. @@ -2881,15 +2882,17 @@ Boot samples] to get you started with common use cases. The basic features you get by default in a web application are: -* A `UserDetailsService` bean with in-memory store and a single user with a generated password. -* Form-based login or HTTP Basic security (depending on Content-Type) for the entire application (including -actuator endpoints if actuator is on the classpath). +* A `UserDetailsService` bean with in-memory store and a single user with a generated + password. +* Form-based login or HTTP Basic security (depending on Content-Type) for the entire + application (including actuator endpoints if actuator is on the classpath). -Access rules can be overriden by adding a custom `WebSecurityConfigurerAdapter`. 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 -`management.endpoints.web.base-path` property. `StaticResourceRequest` can be used to -create a `RequestMatcher` for static resources in commonly used locations. +Access rules can be overriden by adding a custom `WebSecurityConfigurerAdapter`. 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 `management.endpoints.web.base-path` property. +`StaticResourceRequest` can be used to create a `RequestMatcher` for static resources in +commonly used locations. [[boot-features-security-oauth2]] === OAuth2 @@ -4644,12 +4647,12 @@ infrastructure to send and receive messages. [[boot-features-activemq]] ==== ActiveMQ Support When ActiveMQ is available on the classpath, Spring Boot can also configure a -`ConnectionFactory`. If the broker is present, an embedded broker is automatically -started and configured (provided no broker URL is specified through configuration). +`ConnectionFactory`. If the broker is present, an embedded broker is automatically started +and configured (provided no broker URL is specified through configuration). NOTE: If you use `spring-boot-starter-activemq`, the necessary dependencies to connect or -embed an ActiveMQ instance are provided, as is the Spring infrastructure to integrate -with JMS. +embed an ActiveMQ instance are provided, as is the Spring infrastructure to integrate with +JMS. ActiveMQ configuration is controlled by external configuration properties in `+spring.activemq.*+`. For example, you might declare the following section in @@ -4784,12 +4787,12 @@ default one is configured automatically. If a `DestinationResolver` or a 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). 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. +`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). 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. The following component creates a listener endpoint on the `someQueue` destination: @@ -4857,9 +4860,9 @@ Then you can use the factory in any `@JmsListener`-annotated method as follows: === AMQP The Advanced Message Queuing Protocol (AMQP) is a platform-neutral, wire-level protocol for message-oriented middleware. The Spring AMQP project applies core Spring concepts to -the development of AMQP-based messaging solutions. Spring Boot offers several -conveniences for working with AMQP through RabbitMQ, including the -`spring-boot-starter-amqp` '`Starter`'. +the development of AMQP-based messaging solutions. Spring Boot offers several conveniences +for working with AMQP through RabbitMQ, including the `spring-boot-starter-amqp` +'`Starter`'. @@ -4936,9 +4939,8 @@ 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 -`spring.rabbitmq.listener.type` property. If a `MessageConverter` or a -`MessageRecoverer` bean is defined, it is automatically associated with the default -factory. +`spring.rabbitmq.listener.type` property. If a `MessageConverter` or a `MessageRecoverer` +bean is defined, it is automatically associated with the default factory. The following sample component creates a listener endpoint on the `someQueue` queue: @@ -5098,18 +5100,18 @@ The following component creates a listener endpoint on the `someTopic` topic: ==== Additional Kafka Properties The properties supported by auto configuration are shown in <>. Note that, for the most part, these properties -(hyphenated or camelCase) map directly to the Apache Kafka dotted properties. Refer to -the Apache Kafka documentation for details. +(hyphenated or camelCase) map directly to the Apache Kafka dotted properties. Refer to the +Apache Kafka documentation for details. The first few of these properties apply to both producers and consumers but can be specified at the producer or consumer level if you wish to use different values for each. -Apache Kafka designates properties with an importance of HIGH, MEDIUM, or LOW. Spring -Boot auto-configuration supports all HIGH importance properties, some selected MEDIUM and -LOW properties, and any properties that do not have a default value. +Apache Kafka designates properties with an importance of HIGH, MEDIUM, or LOW. Spring Boot +auto-configuration supports all HIGH importance properties, some selected MEDIUM and LOW +properties, and any properties that do not have a default value. Only a subset of the properties supported by Kafka are available through the -`KafkaProperties` class. If you wish to configure the producer or consumer with -additional properties that are not directly supported, use the following properties: +`KafkaProperties` class. If you wish to configure the producer or consumer with additional +properties that are not directly supported, use the following properties: [source,properties,indent=0] ---- @@ -5172,8 +5174,8 @@ new `RestTemplateBuilder` instance, so the customizations only affect this use o builder. To make an application-wide, additive customization, use a `RestTemplateCustomizer` bean. -All such beans are automatically registered with the auto-configured -`RestTemplateBuilder` and are applied to any templates that are built with it. +All such beans are automatically registered with the auto-configured `RestTemplateBuilder` +and are applied to any templates that are built with it. The following example shows a customizer that configures the use of a proxy for all hosts except `192.168.0.5`: @@ -5226,8 +5228,8 @@ The following code shows a typical example: [[boot-features-webclient-customization]] === WebClient Customization -There are three main approaches to `WebClient` customization, depending on how broadly -you want the customizations to apply. +There are three main approaches to `WebClient` customization, depending on how broadly you +want the customizations to apply. To make the scope of any customizations as narrow as possible, inject the auto-configured `WebClient.Builder` and then call its methods as required. `WebClient.Builder` instances @@ -5239,8 +5241,8 @@ To make an application-wide, additive customization to all `WebClient.Builder` i you can declare `WebClientCustomizer` beans and change the `WebClient.Builder` locally at the point of injection. -Finally, you can fall back to the original API and use `WebClient.create()`. In that -case, no auto-configuration or `WebClientCustomizer` is applied. +Finally, you can fall back to the original API and use `WebClient.create()`. In that case, +no auto-configuration or `WebClientCustomizer` is applied. @@ -5308,12 +5310,12 @@ either an http://www.atomikos.com/[Atomikos] or https://github.com/bitronix/btm[ embedded transaction manager. JTA transactions are also supported when deploying to a suitable Java EE Application Server. -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. If you are within a JTA environment and still -want to use local transactions, you can set the `spring.jta.enabled` property to `false` -to disable the JTA auto-configuration. +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. If you are within a JTA environment and still want to use +local transactions, you can set the `spring.jta.enabled` property to `false` to disable +the JTA auto-configuration. @@ -5335,8 +5337,8 @@ your `application.properties` file. Properties starting with for complete details. NOTE: To ensure that multiple transaction managers can safely coordinate the same -resource managers, each Atomikos instance must be configured with a unique ID. By -default, this ID is the IP address of the machine on which Atomikos is running. To ensure +resource managers, each Atomikos instance must be configured with a unique ID. By default, +this ID is the IP address of the machine on which Atomikos is running. To ensure uniqueness in production, you should configure the `spring.jta.transaction-manager-id` property with a different value for each instance of your application. @@ -5358,8 +5360,8 @@ https://github.com/bitronix/btm/wiki/Transaction-manager-configuration[Bitronix documentation] for details. NOTE: To ensure that multiple transaction managers can safely coordinate the same -resource managers, each Bitronix instance must be configured with a unique ID. By -default, this ID is the IP address of the machine on which Bitronix is running. To ensure +resource managers, each Bitronix instance must be configured with a unique ID. By default, +this ID is the IP address of the machine on which Bitronix is running. To ensure uniqueness in production, you should configure the `spring.jta.transaction-manager-id` property with a different value for each instance of your application. @@ -5465,8 +5467,8 @@ If you define a `com.hazelcast.config.Config` bean, Spring Boot uses that. If yo configuration defines an instance name, Spring Boot tries to locate an existing instance rather than creating a new one. -You could also specify the `hazelcast.xml` configuration file to use via configuration, -as shown in the following example: +You could also specify the `hazelcast.xml` configuration file to use via configuration, as +shown in the following example: [source,properties,indent=0] ---- @@ -5503,8 +5505,8 @@ auto-configured (via the `SchedulerFactoryBean` abstraction). Beans of the following types are automatically picked up and associated with the the `Scheduler`: -* `JobDetail`: defines a particular Job. `JobDetail` instances can be built with -the `JobBuilder` API. +* `JobDetail`: defines a particular Job. `JobDetail` instances can be built with the + `JobBuilder` API. * `Calendar`. * `Trigger`: defines when a particular job is triggered. @@ -5569,11 +5571,11 @@ abstractions over messaging and also other transports such as HTTP, TCP, and oth Spring Integration is available on your classpath, it is initialized through the `@EnableIntegration` annotation. -Spring Boot also configures some features that are triggered by the presence of -additional Spring Integration modules. If `'spring-integration-jmx'` is also on the -classpath, message processing statistics are published over JMX . If -`'spring-integration-jdbc'` is available, the default database schema can be created on -startup, as shown in the following line: +Spring Boot also configures some features that are triggered by the presence of additional +Spring Integration modules. If `'spring-integration-jmx'` is also on the classpath, +message processing statistics are published over JMX . If `'spring-integration-jdbc'` is +available, the default database schema can be created on startup, as shown in the +following line: [source,properties,indent=0] ---- @@ -6239,11 +6241,10 @@ A list of the auto-configuration settings that are enabled by `@DataJpaTest` can also configures an in-memory embedded database and a `JdbcTemplate`. Regular `@Component` beans are not loaded into the `ApplicationContext`. -By default, JDBC tests are transactional and roll back at the end of each test. -See the {spring-reference}testing.html#testcontext-tx-enabling-transactions[relevant -section] in the Spring Framework Reference Documentation for more details. If that is not -what you want, you can disable transaction management for a test or for the whole class -as follows: +By default, JDBC tests are transactional and roll back at the end of each test. See the +{spring-reference}testing.html#testcontext-tx-enabling-transactions[relevant section] in +the Spring Framework Reference Documentation for more details. If that is not what you +want, you can disable transaction management for a test or for the whole class as follows: [source,java,indent=0] ---- @@ -6362,10 +6363,10 @@ A list of the auto-configuration settings that are enabled by `@DataMongoTest` c [[boot-features-testing-spring-boot-applications-testing-autoconfigured-neo4j-test]] ==== Auto-configured Data Neo4j Tests -You can use `@DataNeo4jTest` to test Neo4j applications. By default, it -uses an in-memory embedded Neo4j (if the embedded driver is available), scans for -`@NodeEntity` classes, and configures Spring Data Neo4j repositories. Regular -`@Component` beans are not loaded into the `ApplicationContext`: +You can use `@DataNeo4jTest` to test Neo4j applications. By default, it uses an in-memory +embedded Neo4j (if the embedded driver is available), scans for `@NodeEntity` classes, and +configures Spring Data Neo4j repositories. Regular `@Component` beans are not loaded into +the `ApplicationContext`: [source,java,indent=0] ---- @@ -6536,8 +6537,7 @@ A list of the auto-configuration settings that are enabled by `@RestClientTest` [[boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-docs]] ==== Auto-configured Spring REST Docs Tests You can use the `@AutoConfigureRestDocs` annotation to use Spring REST Docs in your tests -with Mock MVC or REST Assured. It removes the need for the JUnit rule in Spring REST -Docs. +with Mock MVC or REST Assured. It removes the need for the JUnit rule in Spring REST Docs. `@AutoConfigureRestDocs` can be used to override the default output directory (`target/generated-snippets` if you are using Maven or `build/generated-snippets` if you @@ -6680,9 +6680,9 @@ at the same level as your application, as shown in the following example: ---- NOTE: Depending on the complexity of your application, you may either have a single -`ApplicationConfiguration` class for your customizations or one class per domain area -when it makes sense. The latter approach lets you enable it in one of your tests, if -necessary, with the `@Import` annotation. +`ApplicationConfiguration` class for your customizations or one class per domain area when +it makes sense. The latter approach lets you enable it in one of your tests, if necessary, +with the `@Import` annotation. Another source of confusion is classpath scanning. Assume that, while you structured your code in a sensible way, you need to scan an additional package. Your application may @@ -6860,7 +6860,7 @@ following example: [[boot-features-websockets]] == WebSockets -Spring Boot provides WebSockets auto-configuration for embedded Tomcat (8 and 7), Jetty +Spring Boot provides WebSockets auto-configuration for embedded Tomcat 8.5, Jetty 9, and Undertow. If you deploy a war file to a standalone container, Spring Boot assumes that the container is responsible for the configuration of its WebSocket support. @@ -6977,18 +6977,18 @@ annotations include: [[boot-features-class-conditions]] ==== Class Conditions -The `@ConditionalOnClass` and `@ConditionalOnMissingClass` annotations let -configuration be included based on the presence or absence of specific classes. Due to -the fact that annotation metadata is parsed by using http://asm.ow2.org/[ASM], you can -use the `value` attribute to refer to the real class, even though that class might not -actually appear on the running application classpath. You can also use the `name` -attribute if you prefer to specify the class name by using a `String` value. +The `@ConditionalOnClass` and `@ConditionalOnMissingClass` annotations let configuration +be included based on the presence or absence of specific classes. Due to the fact that +annotation metadata is parsed by using http://asm.ow2.org/[ASM], you can use the `value` +attribute to refer to the real class, even though that class might not actually appear on +the running application classpath. You can also use the `name` attribute if you prefer to +specify the class name by using a `String` value. [TIP] ==== If you use `@ConditionalOnClass` or `@ConditionalOnMissingClass` as a part of a -meta-annotation to compose your own composed annotations, you must use `name` as -referring to the class in such a case is not handled. +meta-annotation to compose your own composed annotations, you must use `name` as referring +to the class in such a case is not handled. ==== @@ -7025,9 +7025,9 @@ recommend only using `@ConditionalOnBean` and `@ConditionalOnMissingBean` annota auto-configuration classes (since these are guaranteed to load after any user-defined bean definitions have been added). -NOTE: `@ConditionalOnBean` and `@ConditionalOnMissingBean` do not prevent -`@Configuration` classes from being created. Using these conditions at the class level is -equivalent to marking each contained `@Bean` method with the annotation. +NOTE: `@ConditionalOnBean` and `@ConditionalOnMissingBean` do not prevent `@Configuration` +classes from being created. Using these conditions at the class level is equivalent to +marking each contained `@Bean` method with the annotation. @@ -7051,10 +7051,10 @@ conventions, as shown in the following example: `file:/home/user/test.dat`. [[boot-features-web-application-conditions]] ==== Web Application Conditions -The `@ConditionalOnWebApplication` and `@ConditionalOnNotWebApplication` annotations -let configuration be included depending on whether the application is a 'web -application'. A web application is any application that is using a Spring -`WebApplicationContext`, defines a `session` scope, or has a `StandardServletEnvironment`. +The `@ConditionalOnWebApplication` and `@ConditionalOnNotWebApplication` annotations let +configuration be included depending on whether the application is a 'web application'. +A web application is any application that is using a Spring `WebApplicationContext`, +defines a `session` scope, or has a `StandardServletEnvironment`. @@ -7082,8 +7082,8 @@ single module if you do not need to separate those two concerns. [[boot-features-custom-starter-naming]] ==== Naming You should make sure to provide a proper namespace for your starter. Do not start your -module names with `spring-boot`, even if you are using a different Maven `groupId`. We -may offer an official support for the thing you auto-configure in the future. +module names with `spring-boot`, even if you are using a different Maven `groupId`. We may +offer official support for the thing you auto-configure in the future. As a rule of thumb, you should name a combined module after the starter. For example, assume that you are creating a starter for "acme" and that you name the auto-configure