Skip to content

S
spring-boot
Commit 7bbae21d authored by Brian Clozel's avatar Brian Clozel
Browse files
Options

Start documenting WebFlux support 

This commit adds new reference documentation sections about WebFlux
support in Spring Boot:

* Support for multiple HTTP servers (gh-8403)
* `CodecCustomizer` and JSON codecs (gh-8897, gh-9166)
* `WebClient.Builder` auto-configuration (gh-9522)
* Tests with `@WebFluxTest` (gh-8401)
* `WebTestClient` auto-configuration (gh-8399)
* Support for Thymeleafi and Mustache templating (gh-8124, gh-8648)
* Choose another HTTP server with WebFlux (closes gh-9690)
parent ef5c2afc
Hide whitespace changes
Inline Side-by-side
Showing with 393 additions and 135 deletions
spring-boot-docs/src/main/asciidoc/getting-started.adoc
View file @ 7bbae21d
......@@ -621,7 +621,7 @@ that any HTTP request with the path "`/`" should be mapped to the `home` method.
back to the caller.
TIP: The `@RestController` and `@RequestMapping` annotations are Spring MVC annotations
(they are not specific to Spring Boot). See the {spring-reference}#mvc[MVC section] in
(they are not specific to Spring Boot). See the {spring-reference}web.html#mvc[MVC section] in
the Spring Reference Documentation for more details.
......
spring-boot-docs/src/main/asciidoc/howto.adoc
View file @ 7bbae21d
......@@ -487,8 +487,78 @@ Spring Boot. The definitive list comes from searching the source code for
[[howto-embedded-servlet-containers]]
== Embedded servlet containers
[[howto-embedded-web-servers]]
== Embedded Web servers
[[howto-use-another-web-server]]
=== Use another Web server
The Spring Boot starters bring a default embedded container for you:
* `spring-boot-starter-web` brings Tomcat with `spring-boot-starter-tomcat`,
but `spring-boot-starter-jetty` and `spring-boot-starter-undertow` can be used instead.
* `spring-boot-starter-webflux` brings Reactor Netty with `spring-boot-starter-reactor-netty`,
but `spring-boot-starter-tomcat`, `spring-boot-starter-jetty` and
`spring-boot-starter-undertow` can be used instead.
NOTE: Many starters only support Spring MVC, so they transitively bring
`spring-boot-starter-web` into your application classpath
If you choose to use a different HTTP server, you need to exclude those dependencies
and include the one you chose instead. Spring Boot provides separate starters for
HTTP servers to help make this process as easy as possible.
Example in Maven, for Spring MVC:
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<exclusions>
<!-- Exclude the Tomcat dependency -->
<exclusion>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-tomcat</artifactId>
</exclusion>
</exclusions>
</dependency>
<!-- Use Jetty instead -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-jetty</artifactId>
</dependency>
----
Example in Gradle, for Spring WebFlux:
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
----
configurations {
// exclude Reactor Netty
compile.exclude module: 'spring-boot-starter-reactor-netty'
}
dependencies {
compile 'org.springframework.boot:spring-boot-starter-webflux'
// Use Undertow instead
compile 'org.springframework.boot:spring-boot-starter-undertow'
// ...
}
----
NOTE: `spring-boot-starter-reactor-netty` is required to use the `WebClient`,
so excluding it is not required if you wish to use a different HTTP server.
[[howto-configure-jetty]]
=== Configure Jetty
Generally you can follow the advice from
_<<howto-discover-build-in-options-for-external-properties>>_ about
`@ConfigurationProperties` (`ServerProperties` is the main one here), but also look at
`ServletWebServerFactoryCustomizer`. The Jetty APIs are quite rich so once you have
access to the `JettyServletWebServerFactory` you can modify it in a number
of ways. Or the nuclear option is to add your own `JettyServletWebServerFactory`.
......@@ -828,104 +898,6 @@ include::{code-examples}/context/embedded/TomcatLegacyCookieProcessorExample.jav
[[howto-use-jetty-instead-of-tomcat]]
=== Use Jetty instead of Tomcat
The Spring Boot starters (`spring-boot-starter-web` in particular) use Tomcat as an
embedded container by default. You need to exclude those dependencies and include the
Jetty one instead. Spring Boot provides Tomcat and Jetty dependencies bundled together
as separate starters to help make this process as easy as possible.
Example in Maven:
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<exclusions>
<exclusion>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-tomcat</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-jetty</artifactId>
</dependency>
----
Example in Gradle:
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
----
configurations {
compile.exclude module: 'spring-boot-starter-tomcat'
}
dependencies {
compile 'org.springframework.boot:spring-boot-starter-web'
compile 'org.springframework.boot:spring-boot-starter-jetty'
// ...
}
----
[[howto-configure-jetty]]
=== Configure Jetty
Generally you can follow the advice from
_<<howto-discover-build-in-options-for-external-properties>>_ about
`@ConfigurationProperties` (`ServerProperties` is the main one here), but also look at
`ServletWebServerFactoryCustomizer`. The Jetty APIs are quite rich so once you have
access to the `JettyServletWebServerFactory` you can modify it in a number
of ways. Or the nuclear option is to add your own `JettyServletWebServerFactory`.
[[howto-use-undertow-instead-of-tomcat]]
=== Use Undertow instead of Tomcat
Using Undertow instead of Tomcat is very similar to <<howto-use-jetty-instead-of-tomcat,
using Jetty instead of Tomcat>>. You need to exclude the Tomcat dependencies and include
the Undertow starter instead.
Example in Maven:
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<exclusions>
<exclusion>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-tomcat</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-undertow</artifactId>
</dependency>
----
Example in Gradle:
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
----
configurations {
compile.exclude module: 'spring-boot-starter-tomcat'
}
dependencies {
compile 'org.springframework.boot:spring-boot-starter-web'
compile 'org.springframework.boot:spring-boot-starter-undertow'
// ...
}
----
[[howto-configure-undertow]]
=== Configure Undertow
Generally you can follow the advice from
......@@ -1288,7 +1260,7 @@ Check out {sc-spring-boot-autoconfigure}/web/servlet/WebMvcAutoConfiguration.{sc
[[howto-http-clients-proxy-configuration]]
=== Configure RestTemplate to use a proxy
As described in <<spring-boot-features.adoc#boot-features-restclient-customization>>,
As described in <<spring-boot-features.adoc#boot-features-resttemplate-customization>>,
a `RestTemplateCustomizer` can be used with `RestTemplateBuilder` to build a customized
`RestTemplate`. This is the recommended approach for creating a `RestTemplate` configured
to use a proxy.
......
spring-boot-docs/src/main/asciidoc/index.adoc
View file @ 7bbae21d
......@@ -36,7 +36,7 @@ Phillip Webb; Dave Syer; Josh Long; Stéphane Nicoll; Rob Winch; Andy Wilkinson;
:dependency-management-plugin-documentation: {dependency-management-plugin}/blob/master/README.md
:spring-boot-maven-plugin-site: http://docs.spring.io/spring-boot/docs/{spring-boot-docs-version}/maven-plugin/
:spring-boot-gradle-plugin: http://docs.spring.io/spring-boot/docs/{spring-boot-docs-version}/gradle-plugin/
:spring-reference: http://docs.spring.io/spring/docs/{spring-docs-version}/spring-framework-reference/htmlsingle
:spring-reference: http://docs.spring.io/spring/docs/{spring-docs-version}/spring-framework-reference/
:spring-security-reference: http://docs.spring.io/spring-security/site/docs/{spring-security-docs-version}/reference/htmlsingle
:spring-security-oauth2-reference: http://projects.spring.io/spring-security-oauth/docs/oauth2.html
:spring-webservices-reference: http://docs.spring.io/spring-ws/docs/{spring-webservices-docs-version}/reference/htmlsingle
......@@ -52,8 +52,8 @@ Phillip Webb; Dave Syer; Josh Long; Stéphane Nicoll; Rob Winch; Andy Wilkinson;
:ant-manual: http://ant.apache.org/manual
:code-examples: ../java/org/springframework/boot
:gradle-user-guide: https://docs.gradle.org/3.4.1/userguide
:jetty-documentation: https://www.eclipse.org/jetty/documentation/9.3.x
:tomcat-documentation: https://tomcat.apache.org/tomcat-8.0-doc
:jetty-documentation: https://www.eclipse.org/jetty/documentation/9.4.x
:tomcat-documentation: https://tomcat.apache.org/tomcat-8.5-doc
// ======================================================================================
include::documentation-overview.adoc[]
......
spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc
View file @ 7bbae21d
......@@ -1657,8 +1657,10 @@ tried (`myPropertyName`, `MY_PROPERTY_NAME` etc).
[[boot-features-developing-web-applications]]
== Developing web applications
Spring Boot is well suited for web application development. You can easily create a
self-contained HTTP server using embedded Tomcat, Jetty, or Undertow. Most web
applications will use the `spring-boot-starter-web` module to get up and running quickly.
self-contained HTTP server using embedded Tomcat, Jetty, Undertow, or Netty.
Most web applications will use the `spring-boot-starter-web` module to get up
and running quickly. You can also choose to use to build reactive web applications
by using the `spring-boot-starter-webflux` module.
If you haven't yet developed a Spring Boot web application you can follow the
"Hello World!" example in the
......@@ -1700,7 +1702,7 @@ Here is a typical example `@RestController` to serve JSON data:
----
Spring MVC is part of the core Spring Framework and detailed information is available in
the {spring-reference}#mvc[reference documentation]. There are also several guides
the {spring-reference}web.html#mvc[reference documentation]. There are also several guides
available at http://spring.io/guides that cover Spring MVC.
......@@ -1722,9 +1724,9 @@ The auto-configuration adds the following features on top of Spring's defaults:
* Automatic use of a `ConfigurableWebBindingInitializer` bean (see below).
If you want to keep Spring Boot MVC features, and
you just want to add additional {spring-reference}#mvc[MVC configuration] (interceptors,
you just want to add additional {spring-reference}web.html#mvc[MVC configuration] (interceptors,
formatters, view controllers etc.) you can add your own `@Configuration` class of type
`WebMvcConfigurerAdapter`, but *without* `@EnableWebMvc`. If you wish to provide custom
`WebMvcConfigurer`, but *without* `@EnableWebMvc`. If you wish to provide custom
instances of `RequestMappingHandlerMapping`, `RequestMappingHandlerAdapter` or
`ExceptionHandlerExceptionResolver` you can declare a `WebMvcRegistrationsAdapter`
instance providing such components.
......@@ -1827,7 +1829,7 @@ you set the `spring.mvc.message-codes-resolver.format` property `PREFIX_ERROR_CO
By default Spring Boot will serve static content from a directory called `/static` (or
`/public` or `/resources` or `/META-INF/resources`) in the classpath or from the root
of the `ServletContext`. It uses the `ResourceHttpRequestHandler` from Spring MVC so you
can modify that behavior by adding your own `WebMvcConfigurerAdapter` and overriding the
can modify that behavior by adding your own `WebMvcConfigurer` and overriding the
`addResourceHandlers` method.
In a stand-alone web application the default servlet from the container is also
......@@ -1912,7 +1914,7 @@ for more of the supported options.
====
This feature has been thoroughly described in a dedicated
https://spring.io/blog/2014/07/24/spring-framework-4-1-handling-static-web-resources[blog post]
and in Spring Framework's {spring-reference}/#mvc-config-static-resources[reference documentation].
and in Spring Framework's {spring-reference}web.html#mvc-config-static-resources[reference documentation].
====
......@@ -2069,8 +2071,8 @@ interface.
You can also use regular Spring MVC features like
{spring-reference}/#mvc-exceptionhandlers[`@ExceptionHandler` methods] and
{spring-reference}/#mvc-ann-controller-advice[`@ControllerAdvice`]. The `ErrorController`
{spring-reference}web.html#mvc-exceptionhandlers[`@ExceptionHandler` methods] and
{spring-reference}web.html#mvc-ann-controller-advice[`@ControllerAdvice`]. The `ErrorController`
will then pick up any unhandled exceptions.
......@@ -2159,12 +2161,12 @@ http://caniuse.com/#feat=cors[most browsers] that allows you to specify in a fle
way what kind of cross domain requests are authorized, instead of using some less secure
and less powerful approaches like IFRAME or JSONP.
As of version 4.2, Spring MVC {spring-reference}/#cors[supports CORS] out of the box.
Using {spring-reference}/#_controller_method_cors_configuration[controller method CORS
As of version 4.2, Spring MVC {spring-reference}web.html#cors[supports CORS] out of the box.
Using {spring-reference}web.html#controller-method-cors-configuration[controller method CORS
configuration] with
{spring-javadoc}/web/bind/annotation/CrossOrigin.html[`@CrossOrigin`]
annotations in your Spring Boot application does not require any specific configuration.
{spring-reference}/#_global_cors_configuration[Global CORS configuration] can be defined
{spring-reference}web.html#global-cors-configuration[Global CORS configuration] can be defined
by registering a `WebMvcConfigurer` bean with a customized `addCorsMappings(CorsRegistry)`
method:
......@@ -2175,7 +2177,7 @@ method:
@Bean
public WebMvcConfigurer corsConfigurer() {
return new WebMvcConfigurerAdapter() {
return new WebMvcConfigurer() {
@Override
public void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/api/**");
......@@ -2185,6 +2187,184 @@ method:
}
----
[[boot-features-spring-webflux]]
=== The '`Spring WebFlux framework`'
Spring WebFlux is the new reactive web framework introduced in Spring Framework 5.0.
Unlike Spring MVC, it does not require the Servlet API, is fully asynchronous and
non-blocking, and implements the http://www.reactive-streams.org/[Reactive Streams]
specification through http://projectreactor.io/[the Reactor project].
Spring WebFlux comes in two flavours — the annotation-based one is quite close to
the Spring MVC model we know:
[source,java,indent=0]
----
@RestController
@RequestMapping("/users")
public class MyRestController {
@GetMapping("/{user}")
public Mono<User> getUser(@PathVariable Long user) {
// ...
}
@GetMapping("/{user}/customers")
Flux<Customer> getUserCustomers(@PathVariable Long user) {
// ...
}
@DeleteMapping("/{user}")
public Mono<User> deleteUser(@PathVariable Long user) {
// ...
}
}
----
'`WebFlux.fn`', the functional variant, separates the routing configuration from the actual handling
of the requests:
[source,java,indent=0]
----
@Configuration
public class RoutingConfiguration {
@Bean
public RouterFunction<ServerResponse> monoRouterFunction(UserHandler userHandler) {
return route(GET("/{user}").and(accept(APPLICATION_JSON)), userHandler::getUser)
.andRoute(GET("/{user}/customers").and(accept(APPLICATION_JSON)), userHandler::getUserCustomers)
.andRoute(DELETE("/{user}").and(accept(APPLICATION_JSON)), userHandler::deleteUser);
}
}
@Component
public class UserHandler {
public Mono<ServerResponse> getUser(ServerRequest request) {
// ...
}
public Mono<ServerResponse> getUserCustomers(ServerRequest request) {
// ...
}
public Mono<ServerResponse> deleteUser(ServerRequest request) {
// ...
}
}
----
WebFlux is part of the Spring Framework and detailed information is available in
the {spring-reference}web.html#web-reactive[reference documentation].
To get started, add the `spring-boot-starter-webflux` module to your application.
NOTE: Adding both `spring-boot-starter-web` and `spring-boot-starter-webflux`
modules in your application will result in Spring Boot auto-configuring Spring
MVC, not WebFlux. This behavior has been chosen because many Spring developers
will add `spring-boot-starter-webflux` to their Spring MVC application to use
the reactive `WebCLient`. You can still enforce your choice by setting the
chosen application type like
`SpringApplication.setWebApplicationType(WebApplicationType.REACTIVE)`.
[[boot-features-spring-webflux-auto-configuration]]
==== Spring WebFlux auto-configuration
Spring Boot provides auto-configuration for Spring WebFlux that works well with most
applications.
The auto-configuration adds the following features on top of Spring's defaults:
* Configuring codecs for `HttpMessageReader` and `HttpMessageWriter` instances (see below).
* Support for serving static resources, including support for WebJars (see below).
If you want to keep Spring Boot WebFlux features, and
you just want to add additional {spring-reference}web.html#web-reactive[WebFlux configuration]
you can add your own `@Configuration` class of type `WebFluxConfigurer`,
but *without* `@EnableWebFlux`.
If you want to take complete control of Spring WebFlux, you can add your own `@Configuration`
annotated with `@EnableWebFlux`.
[[boot-features-spring-webflux-httpcodecs]]
==== HTTP codecs with HttpMessageReaders and HttpMessageWriters
Spring WebFlux uses the `HttpMessageReader` and `HttpMessageWriter` interface to convert
HTTP requests and responses. They are configured with `CodecConfigurer` with sensible defaults,
by looking at the libraries available in your classpath.
Spring Boot will apply further customization using `CodecCustomizer` instances.
For example, `spring.jackson.*` configuration keys will be applied to the Jackson codec.
If you need to add or customize codecs you can create a custom `CodecCustomizer` component:
[source,java,indent=0]
----
import org.springframework.boot.web.codec.CodecCustomizer;
@Configuration
public class MyConfiguration {
@Bean
public CodecCustomizer myCodecCustomizer() {
return codecConfigurer -> {
// ...
}
}
}
----
You can also leverage <<boot-features-json-components,Boot's custom JSON serializers and deserializers>>.
[[boot-features-spring-webflux-static-content]]
==== Static Content
By default Spring Boot will serve static content from a directory called `/static` (or
`/public` or `/resources` or `/META-INF/resources`) in the classpath.
It uses the `ResourceWebHandler` from Spring WebFlux so you
can modify that behavior by adding your own `WebFluxConfigurer` and overriding the
`addResourceHandlers` method.
By default, resources are mapped on `+/**+` but you can tune that via
`spring.mvc.static-path-pattern`. For instance, relocating all resources to `/resources/**`
can be achieved as follows:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
----
spring.mvc.static-path-pattern=/resources/**
----
You can also customize the static resource locations using
`spring.resources.static-locations` (replacing the default values with a list of directory
locations). If you do this the default welcome page detection will switch to your custom
locations, so if there is an `index.html` in any of your locations on startup, it will be
the home page of the application.
In addition to the '`standard`' static resource locations above, a special case is made
for http://www.webjars.org/[Webjars content]. Any resources with a path in `+/webjars/**+`
will be served from jar files if they are packaged in the Webjars format.
TIP: Spring WebFlux applications don't strictly depend on the Servlet API, so they can't
be deployed as war and have no use of the `src/main/webapp` directory.
[[boot-features-spring-webflux-template-engines]]
==== Template engines
As well as REST web services, you can also use Spring WebFlux to serve dynamic HTML content.
Spring WebFlux supports a variety of templating technologies including Thymeleaf, FreeMarker
and Mustache.
Spring Boot includes auto-configuration support for the following templating engines:
* http://freemarker.org/docs/[FreeMarker]
* http://www.thymeleaf.org[Thymeleaf]
* http://mustache.github.io/[Mustache]
When you're using one of these templating engines with the default configuration, your
templates will be picked up automatically from `src/main/resources/templates`.
[[boot-features-jersey]]
......@@ -4050,7 +4230,7 @@ transparently, without any interference to the invoker. Spring Boot auto-config
cache infrastructure as long as the caching support is enabled via the `@EnableCaching`
annotation.
NOTE: Check the {spring-reference}/#cache[relevant section] of the Spring Framework
NOTE: Check the {spring-reference}integration.html#cache[relevant section] of the Spring Framework
reference for more details.
In a nutshell, adding caching to an operation of your service is as easy as adding the
......@@ -4092,8 +4272,8 @@ application uses. Practically all providers require you to explicitly configure
cache that you use in the application. Some offer a way to customize the default caches
defined by the `spring.cache.cache-names` property.
TIP: It is also possible to {spring-reference}/#cache-annotations-put[update] or
{spring-reference}/#cache-annotations-evict[evict] data from the cache transparently.
TIP: It is also possible to {spring-reference}integration.html#cache-annotations-put[update] or
{spring-reference}integration.html#cache-annotations-evict[evict] data from the cache transparently.
NOTE: If you are using the cache infrastructure with beans that are not interface-based,
make sure to enable the `proxyTargetClass` attribute of `@EnableCaching`.
......@@ -4395,7 +4575,7 @@ The `javax.jms.ConnectionFactory` interface provides a standard method of creati
`javax.jms.Connection` for interacting with a JMS broker. Although Spring needs a
`ConnectionFactory` to work with JMS, you generally won't need to use it directly yourself
and you can instead rely on higher level messaging abstractions (see the
{spring-reference}/#jms[relevant section] of the Spring Framework reference
{spring-reference}integration.html#jms[relevant section] of the Spring Framework reference
documentation for details). Spring Boot also auto-configures the necessary infrastructure
to send and receive messages.
......@@ -4880,8 +5060,8 @@ include::{code-examples}/kafka/KafkaSpecialProducerConsumerConfigExample.java[ta
[[boot-features-restclient]]
== Calling REST services
[[boot-features-resttemplate]]
== Calling REST services with '`RestTemplate`'
If you need to call remote REST services from your application, you can use Spring
Framework's `RestTemplate` class. Since `RestTemplate` instances often need to be
customized before being used, Spring Boot does not provide any single auto-configured
......@@ -4895,7 +5075,7 @@ Here's a typical example:
[source,java,indent=0]
----
@Service
public class MyBean {
public class MyService {
private final RestTemplate restTemplate;
......@@ -4914,7 +5094,7 @@ TIP: `RestTemplateBuilder` includes a number of useful methods that can be used
configure a `RestTemplate`. For example, to add BASIC auth support you can use
`builder.basicAuthorization("user", "password").build()`.
[[boot-features-restclient-customization]]
[[boot-features-resttemplate-customization]]
=== RestTemplate customization
There are three main approaches to `RestTemplate` customization, depending on how broadly
you want the customizations to apply.
......@@ -4941,6 +5121,60 @@ Lastly, the most extreme (and rarely used) option is to create your own
`RestTemplateBuilder` and will prevent any `RestTemplateCustomizer` beans from being used.
[[boot-features-webclient]]
== Calling REST services with '`WebClient`'
If you have Spring WebFlux on your classpath, you can also choose to use `WebClient`
to call remote REST services; compared to `RestTemplate`, this client has more a
functional feel to it and is fully reactive. You can create your own client
instance with the builder `WebClient.create()`, which already provides a good
out-of-the-box experience. See the
{spring-reference}web.html#web-reactive-client[relevant section on WebClient].
Spring Boot will create and pre-configure such a builder for you; for example,
client HTTP codecs will be configured just like the server ones
(see <<boot-features-spring-webflux-httpcodecs,WebFlux HTTP codecs auto-configuration>>).
Here's a typical example:
[source,java,indent=0]
----
@Service
public class MyService {
private final WebClient webClient;
public MyBean(WebClient.Builder webClientBuilder) {
this.webClient = webClientBuilder.baseUrl("http://example.org").build();
}
public Mono<Details> someRestCall(String name) {
return this.webClient.get().url("/{name}/details", name)
.retrieve().bodyToMono(Details.class);
}
}
----
[[boot-features-webclient-customization]]
=== WebClient customization
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
are stateful; any change on the builder will be reflected in all clients subsequently
created with it. If you'd like to create several clients with the same builder, you can
also consider cloning the builder with `WebClient.Builder other = builder.clone();`.
To make an application-wide, additive customization to all `WebClient.Builder` instances,
you can declare `WebClientCustomizer` beans and change the `WebClient.Builder` as you
would do locally at the point of injection.
Lastly, you can fall back to the original API and just use `WebClient.create()`. In that
case, no auto-configuration nor `WebClientCustomizer` will be applied.
[[boot-features-validation]]
== Validation
......@@ -4976,7 +5210,7 @@ The Spring Framework provides an easy abstraction for sending email using the
`JavaMailSender` interface and Spring Boot provides auto-configuration for it as well as
a starter module.
TIP: Check the {spring-reference}/#mail[reference documentation] for a detailed
TIP: Check the {spring-reference}integration.html#mail[reference documentation] for a detailed
explanation of how you can use `JavaMailSender`.
If `spring.mail.host` and the relevant libraries (as defined by
......@@ -5344,7 +5578,7 @@ If you use the
the following provided libraries:
* http://junit.org[JUnit] -- The de-facto standard for unit testing Java applications.
* {spring-reference}/#integration-testing[Spring Test] & Spring Boot Test --
* {spring-reference}testing.html#integration-testing[Spring Test] & Spring Boot Test --
Utilities and integration test support for Spring Boot applications.
* http://joel-costigliola.github.io/assertj/[AssertJ] -- A fluent assertion library.
* http://hamcrest.org/JavaHamcrest/[Hamcrest] -- A library of matcher objects (also known
......@@ -5374,7 +5608,7 @@ You can declare a dependency directly to `org.springframework:spring-test` or us
`spring-boot-starter-test` '`Starter`' to pull it in transitively.
If you have not used the `spring-test` module before you should start by reading the
{spring-reference}/#testing[relevant section] of the Spring Framework reference
{spring-reference}testing.html#testing[relevant section] of the Spring Framework reference
documentation.
......@@ -5713,7 +5947,7 @@ TIP: If you need to configure elements of the auto-configuration (for example wh
filters should be applied) you can use attributes in the `@AutoConfigureMockMvc`
annotation.
If you use HtmlUnit or Selenium, auto-configuration will also provide a `WebClient` bean
If you use HtmlUnit or Selenium, auto-configuration will also provide an HTMLUnit `WebClient` bean
and/or a `WebDriver` bean. Here is an example that uses HtmlUnit:
......@@ -5758,6 +5992,58 @@ definition.
A list of the auto-configuration that is enabled by `@WebMvcTest` can be
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.
[[boot-features-testing-spring-boot-applications-testing-autoconfigured-webflux-tests]]
==== Auto-configured Spring WebFlux tests
To test Spring WebFlux controllers are working as expected you can use the `@WebFluxTest`
annotation. `@WebFluxTest` will auto-configure the Spring WebFlux infrastructure and limit
scanned beans to `@Controller`, `@ControllerAdvice`, `@JsonComponent`,and `WebFluxConfigurer`.
Regular `@Component` beans will not be scanned when using this annotation.
Often `@WebFluxTest` will be limited to a single controller and used in combination with
`@MockBean` to provide mock implementations for required collaborators.
`@WebFluxTest` also auto-configures `WebTestClient`, which offers a powerful way to quickly
test WebFlux controllers without needing to start a full HTTP server.
TIP: You can also auto-configure `WebTestClient` in a non-`@WebFluxTest`
(e.g. `SpringBootTest`) by annotating it with `@AutoConfigureWebTestClient`.
[source,java,indent=0]
----
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.reactive.WebFluxTest;
import org.springframework.http.MediaType;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.test.web.reactive.server.WebTestClient;
@RunWith(SpringRunner.class)
@WebFluxTest(UserVehicleController.class)
public class MyControllerTests {
@Autowired
private WebTestClient webClient;
@MockBean
private UserVehicleService userVehicleService;
@Test
public void testExample() throws Exception {
given(this.userVehicleService.getVehicleDetails("sboot"))
.willReturn(new VehicleDetails("Honda", "Civic"));
this.webClient.get().uri("/sboot/vehicle").accept(MediaType.TEXT_PLAIN)
.exchange()
.expectStatus().isOk()
.expectBody(String.class).isEqualTo("Honda Civic");
}
}
----
A list of the auto-configuration that is enabled by `@WebFluxTest` can be
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.
[[boot-features-testing-spring-boot-applications-testing-autoconfigured-jpa-test]]
......@@ -5768,7 +6054,7 @@ Data JPA repositories. Regular `@Component` beans will not be loaded into the
`ApplicationContext`.
Data JPA tests are transactional and rollback at the end of each test by default,
see the {spring-reference}#testcontext-tx-enabling-transactions[relevant section] in the
see the {spring-reference}testing.html#testcontext-tx-enabling-transactions[relevant section] in the
Spring Reference Documentation for more details. If that's not what you want, you can
disable transaction management for a test or for the whole class as follows:
......@@ -5853,7 +6139,7 @@ will also configure an in-memory embedded database and a `JdbcTemplate`. Regular
`@Component` beans will not be loaded into the `ApplicationContext`.
JDBC tests are transactional and rollback at the end of each test by default,
see the {spring-reference}#testcontext-tx-enabling-transactions[relevant section] in the
see the {spring-reference}testing.html#testcontext-tx-enabling-transactions[relevant section] in the
Spring Reference Documentation for more details. If that's not what you want, you can
disable transaction management for a test or for the whole class as follows:
......@@ -5994,7 +6280,7 @@ beans will not be loaded into the `ApplicationContext`:
----
Data Neo4j tests are transactional and rollback at the end of each test by default,
see the {spring-reference}#testcontext-tx-enabling-transactions[relevant section] in the
see the {spring-reference}testing.html#testcontext-tx-enabling-transactions[relevant section] in the
Spring Reference Documentation for more details. If that's not what you want, you can
disable transaction management for a test or for the whole class as follows:
......@@ -6371,7 +6657,7 @@ and Undertow. If you're deploying a war file to a standalone container, Spring B
assumes that the container will be responsible for the configuration of its WebSocket
support.
Spring Framework provides {spring-reference}/#websocket[rich WebSocket support] that can
Spring Framework provides {spring-reference}web.html#websocket[rich WebSocket support] that can
be easily accessed via the `spring-boot-starter-websocket` module.
......@@ -6550,7 +6836,7 @@ application'. A web application is any application that is using a Spring
[[boot-features-spel-conditions]]
==== SpEL expression conditions
The `@ConditionalOnExpression` annotation allows configuration to be included based on the
result of a {spring-reference}/#expressions[SpEL expression].
result of a {spring-reference}core.html#expressions[SpEL expression].
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment