Skip to content

Commit 7bbae21

Browse files
bclozelbclozel
committed
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)
1 parent ef5c2af commit 7bbae21

File tree

4 files changed

+393
-135
lines changed

4 files changed

+393
-135
lines changed

‎spring-boot-docs/src/main/asciidoc/getting-started.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -621,7 +621,7 @@ that any HTTP request with the path "`/`" should be mapped to the `home` method.
621621
back to the caller.
622622

623623
TIP: The `@RestController` and `@RequestMapping` annotations are Spring MVC annotations
624-
(they are not specific to Spring Boot). See the {spring-reference}#mvc[MVC section] in
624+
(they are not specific to Spring Boot). See the {spring-reference}web.html#mvc[MVC section] in
625625
the Spring Reference Documentation for more details.
626626

627627

‎spring-boot-docs/src/main/asciidoc/howto.adoc

Lines changed: 73 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -487,8 +487,78 @@ Spring Boot. The definitive list comes from searching the source code for
487487

488488

489489

490-
[[howto-embedded-servlet-containers]]
491-
== Embedded servlet containers
490+
[[howto-embedded-web-servers]]
491+
== Embedded Web servers
492+
493+
494+
495+
[[howto-use-another-web-server]]
496+
=== Use another Web server
497+
The Spring Boot starters bring a default embedded container for you:
498+
499+
* `spring-boot-starter-web` brings Tomcat with `spring-boot-starter-tomcat`,
500+
but `spring-boot-starter-jetty` and `spring-boot-starter-undertow` can be used instead.
501+
* `spring-boot-starter-webflux` brings Reactor Netty with `spring-boot-starter-reactor-netty`,
502+
but `spring-boot-starter-tomcat`, `spring-boot-starter-jetty` and
503+
`spring-boot-starter-undertow` can be used instead.
504+
505+
NOTE: Many starters only support Spring MVC, so they transitively bring
506+
`spring-boot-starter-web` into your application classpath
507+
508+
If you choose to use a different HTTP server, you need to exclude those dependencies
509+
and include the one you chose instead. Spring Boot provides separate starters for
510+
HTTP servers to help make this process as easy as possible.
511+
512+
Example in Maven, for Spring MVC:
513+
514+
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
515+
----
516+
<dependency>
517+
<groupId>org.springframework.boot</groupId>
518+
<artifactId>spring-boot-starter-web</artifactId>
519+
<exclusions>
520+
<!-- Exclude the Tomcat dependency -->
521+
<exclusion>
522+
<groupId>org.springframework.boot</groupId>
523+
<artifactId>spring-boot-starter-tomcat</artifactId>
524+
</exclusion>
525+
</exclusions>
526+
</dependency>
527+
<!-- Use Jetty instead -->
528+
<dependency>
529+
<groupId>org.springframework.boot</groupId>
530+
<artifactId>spring-boot-starter-jetty</artifactId>
531+
</dependency>
532+
----
533+
534+
Example in Gradle, for Spring WebFlux:
535+
536+
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
537+
----
538+
configurations {
539+
// exclude Reactor Netty
540+
compile.exclude module: 'spring-boot-starter-reactor-netty'
541+
}
542+
543+
dependencies {
544+
compile 'org.springframework.boot:spring-boot-starter-webflux'
545+
// Use Undertow instead
546+
compile 'org.springframework.boot:spring-boot-starter-undertow'
547+
// ...
548+
}
549+
----
550+
551+
NOTE: `spring-boot-starter-reactor-netty` is required to use the `WebClient`,
552+
so excluding it is not required if you wish to use a different HTTP server.
553+
554+
[[howto-configure-jetty]]
555+
=== Configure Jetty
556+
Generally you can follow the advice from
557+
_<<howto-discover-build-in-options-for-external-properties>>_ about
558+
`@ConfigurationProperties` (`ServerProperties` is the main one here), but also look at
559+
`ServletWebServerFactoryCustomizer`. The Jetty APIs are quite rich so once you have
560+
access to the `JettyServletWebServerFactory` you can modify it in a number
561+
of ways. Or the nuclear option is to add your own `JettyServletWebServerFactory`.
492562

493563

494564

@@ -828,104 +898,6 @@ include::{code-examples}/context/embedded/TomcatLegacyCookieProcessorExample.jav
828898

829899

830900

831-
[[howto-use-jetty-instead-of-tomcat]]
832-
=== Use Jetty instead of Tomcat
833-
The Spring Boot starters (`spring-boot-starter-web` in particular) use Tomcat as an
834-
embedded container by default. You need to exclude those dependencies and include the
835-
Jetty one instead. Spring Boot provides Tomcat and Jetty dependencies bundled together
836-
as separate starters to help make this process as easy as possible.
837-
838-
Example in Maven:
839-
840-
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
841-
----
842-
<dependency>
843-
<groupId>org.springframework.boot</groupId>
844-
<artifactId>spring-boot-starter-web</artifactId>
845-
<exclusions>
846-
<exclusion>
847-
<groupId>org.springframework.boot</groupId>
848-
<artifactId>spring-boot-starter-tomcat</artifactId>
849-
</exclusion>
850-
</exclusions>
851-
</dependency>
852-
<dependency>
853-
<groupId>org.springframework.boot</groupId>
854-
<artifactId>spring-boot-starter-jetty</artifactId>
855-
</dependency>
856-
----
857-
858-
Example in Gradle:
859-
860-
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
861-
----
862-
configurations {
863-
compile.exclude module: 'spring-boot-starter-tomcat'
864-
}
865-
866-
dependencies {
867-
compile 'org.springframework.boot:spring-boot-starter-web'
868-
compile 'org.springframework.boot:spring-boot-starter-jetty'
869-
// ...
870-
}
871-
----
872-
873-
874-
875-
[[howto-configure-jetty]]
876-
=== Configure Jetty
877-
Generally you can follow the advice from
878-
_<<howto-discover-build-in-options-for-external-properties>>_ about
879-
`@ConfigurationProperties` (`ServerProperties` is the main one here), but also look at
880-
`ServletWebServerFactoryCustomizer`. The Jetty APIs are quite rich so once you have
881-
access to the `JettyServletWebServerFactory` you can modify it in a number
882-
of ways. Or the nuclear option is to add your own `JettyServletWebServerFactory`.
883-
884-
885-
886-
[[howto-use-undertow-instead-of-tomcat]]
887-
=== Use Undertow instead of Tomcat
888-
Using Undertow instead of Tomcat is very similar to <<howto-use-jetty-instead-of-tomcat,
889-
using Jetty instead of Tomcat>>. You need to exclude the Tomcat dependencies and include
890-
the Undertow starter instead.
891-
892-
Example in Maven:
893-
894-
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
895-
----
896-
<dependency>
897-
<groupId>org.springframework.boot</groupId>
898-
<artifactId>spring-boot-starter-web</artifactId>
899-
<exclusions>
900-
<exclusion>
901-
<groupId>org.springframework.boot</groupId>
902-
<artifactId>spring-boot-starter-tomcat</artifactId>
903-
</exclusion>
904-
</exclusions>
905-
</dependency>
906-
<dependency>
907-
<groupId>org.springframework.boot</groupId>
908-
<artifactId>spring-boot-starter-undertow</artifactId>
909-
</dependency>
910-
----
911-
912-
Example in Gradle:
913-
914-
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
915-
----
916-
configurations {
917-
compile.exclude module: 'spring-boot-starter-tomcat'
918-
}
919-
920-
dependencies {
921-
compile 'org.springframework.boot:spring-boot-starter-web'
922-
compile 'org.springframework.boot:spring-boot-starter-undertow'
923-
// ...
924-
}
925-
----
926-
927-
928-
929901
[[howto-configure-undertow]]
930902
=== Configure Undertow
931903
Generally you can follow the advice from
@@ -1288,7 +1260,7 @@ Check out {sc-spring-boot-autoconfigure}/web/servlet/WebMvcAutoConfiguration.{sc
12881260

12891261
[[howto-http-clients-proxy-configuration]]
12901262
=== Configure RestTemplate to use a proxy
1291-
As described in <<spring-boot-features.adoc#boot-features-restclient-customization>>,
1263+
As described in <<spring-boot-features.adoc#boot-features-resttemplate-customization>>,
12921264
a `RestTemplateCustomizer` can be used with `RestTemplateBuilder` to build a customized
12931265
`RestTemplate`. This is the recommended approach for creating a `RestTemplate` configured
12941266
to use a proxy.

‎spring-boot-docs/src/main/asciidoc/index.adoc

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ Phillip Webb; Dave Syer; Josh Long; Stéphane Nicoll; Rob Winch; Andy Wilkinson;
3636
:dependency-management-plugin-documentation: {dependency-management-plugin}/blob/master/README.md
3737
:spring-boot-maven-plugin-site: http://docs.spring.io/spring-boot/docs/{spring-boot-docs-version}/maven-plugin/
3838
:spring-boot-gradle-plugin: http://docs.spring.io/spring-boot/docs/{spring-boot-docs-version}/gradle-plugin/
39-
:spring-reference: http://docs.spring.io/spring/docs/{spring-docs-version}/spring-framework-reference/htmlsingle
39+
:spring-reference: http://docs.spring.io/spring/docs/{spring-docs-version}/spring-framework-reference/
4040
:spring-security-reference: http://docs.spring.io/spring-security/site/docs/{spring-security-docs-version}/reference/htmlsingle
4141
:spring-security-oauth2-reference: http://projects.spring.io/spring-security-oauth/docs/oauth2.html
4242
: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;
5252
:ant-manual: http://ant.apache.org/manual
5353
:code-examples: ../java/org/springframework/boot
5454
:gradle-user-guide: https://docs.gradle.org/3.4.1/userguide
55-
:jetty-documentation: https://www.eclipse.org/jetty/documentation/9.3.x
56-
:tomcat-documentation: https://tomcat.apache.org/tomcat-8.0-doc
55+
:jetty-documentation: https://www.eclipse.org/jetty/documentation/9.4.x
56+
:tomcat-documentation: https://tomcat.apache.org/tomcat-8.5-doc
5757
// ======================================================================================
5858

5959
include::documentation-overview.adoc[]

0 commit comments

Comments
 (0)