diff --git a/src/docs/asciidoc/web-reactive.adoc b/src/docs/asciidoc/web-reactive.adoc index e32c78ee45..88de041887 100644 --- a/src/docs/asciidoc/web-reactive.adoc +++ b/src/docs/asciidoc/web-reactive.adoc @@ -7,9 +7,62 @@ :docinfo1: This part of the documentation covers support for reactive stack, web applications built on a -http://www.reactive-streams.org/[Reactive Streams] API to run on top of non-blocking +http://www.reactive-streams.org/[Reactive Streams] API to run on non-blocking servers such as Netty, Undertow, and Servlet 3.1+ containers. Individual chapters cover -<> and its <>. -For Servlet stack, web applications, to go <>. +the <> framework, +the reactive <>, support for <>, +and <>. For Servlet stack, web applications, please see +<>. -include::web/webflux.adoc[leveloffset=+1] \ No newline at end of file +include::web/webflux.adoc[leveloffset=+1] + +include::web/webflux-webclient.adoc[leveloffset=+1] + + +[[webflux-test]] +== Testing + +The `spring-test` module provides mock implementations of `ServerHttpRequest`, +`ServerHttpResponse`, and `ServerWebExchange`. +See <> mock objects. + +The <> builds on these mock request and +response objects to provide support for testing WebFlux applications without and HTTP +server. The `WebTestClient` can be used for end-to-end integration tests too. + + +[[webflux-reactive-libraries]] +== Reactive Libraries + +Reactor is a required dependency for the `spring-webflux` module and is used internally +for composing logic and for Reactive Streams support. An easy rule to remember is that +WebFlux APIs return `Flux` or `Mono` -- since that's what's used internally, and +leniently accept any Reactive Streams `Publisher` implementation. + +The use of `Flux` and `Mono` helps to express cardinality -- e.g. +whether a single or multiple async values are expected. This is important for API design +but also essential in some cases, e.g. when encoding an HTTP message. + +For annotated controllers, WebFlux adapts transparently to the reactive library in use +with proper translation of cardinality. This is done with the help of the +{api-spring-framework}/core/ReactiveAdapterRegistry.html[ReactiveAdapterRegistry] from +`spring-core` which provides pluggable support for reactive and async types. The registry +has built-in support for RxJava and `CompletableFuture` but others can be registered. + +For functional endpoints, the `WebClient`, and other functional APIs, the general rule +of thumb for WebFlux APIs applies: + +* `Flux` or `Mono` as return values -- use them to compose logic or pass to any Reactive +Streams library (both are `Publisher` implementations). +* Reactive Streams `Publisher` for input -- if a `Publisher` from another reactive library +is provided it can only be treated as a stream with unknown semantics (0..N). If the +semantics are known -- e.g. `io.reactivex.Single`, you can use `Mono.from(Publisher)` and +pass that in instead of the raw `Publisher`. + +[NOTE] +==== +For example, given a `Publisher` that is not a `Mono`, the Jackson JSON message writer +expects multiple values. If the media type implies an infinite stream -- e.g. +`"application/json+stream"`, values are written and flushed individually; otherwise +values are buffered into a list and rendered as a JSON array. +==== diff --git a/src/docs/asciidoc/web/webflux.adoc b/src/docs/asciidoc/web/webflux.adoc index 7fd0fdc0fb..76708c1c18 100644 --- a/src/docs/asciidoc/web/webflux.adoc +++ b/src/docs/asciidoc/web/webflux.adoc @@ -16,11 +16,6 @@ and co-exist side by side in the Spring Framework. Each module is optional. Applications may use one or the other module, or in some cases both -- e.g. Spring MVC controllers with the reactive `WebClient`. -The `spring-webflux` module also provides a reactive <> for -performing HTTP requests, along with client and server, reactive WebSocket support. -The `spring-test` module provides test support for WebFlux applications, see -<> for more details. - [[webflux-new-framework]] === Why a new web framework? @@ -1387,55 +1382,3 @@ from the base class and you can still have any number of other ``WebMvcConfigure the classpath. -include::webflux-webclient.adoc[leveloffset=+1] - - -[[webflux-test]] -== Testing - -The `spring-test` module provides mock implementations of `ServerHttpRequest`, -`ServerHttpResponse`, and `ServerWebExchange`. -See <> mock objects. - -The <> builds on these mock request and -response objects to provide support for testing WebFlux applications without and HTTP -server. The `WebTestClient` can be used for end-to-end integration tests too. - - - -[[webflux-reactive-libraries]] -== Reactive Libraries - -Reactor is a required dependency for the `spring-webflux` module and is used internally -for composing logic and for Reactive Streams support. An easy rule to remember is that -WebFlux APIs return `Flux` or `Mono` -- since that's what's used internally, and -leniently accept any Reactive Streams `Publisher` implementation. - -The use of `Flux` and `Mono` helps to express cardinality -- e.g. -whether a single or multiple async values are expected. This is important for API design -but also essential in some cases, e.g. when encoding an HTTP message. - -For annotated controllers, WebFlux adapts transparently to the reactive library in use -with proper translation of cardinality. This is done with the help of the -{api-spring-framework}/core/ReactiveAdapterRegistry.html[ReactiveAdapterRegistry] from -`spring-core` which provides pluggable support for reactive and async types. The registry -has built-in support for RxJava and `CompletableFuture` but others can be registered. - -For functional endpoints, the `WebClient`, and other functional APIs, the general rule -of thumb for WebFlux APIs applies: - -* `Flux` or `Mono` as return values -- use them to compose logic or pass to any Reactive -Streams library (both are `Publisher` implementations). -* Reactive Streams `Publisher` for input -- if a `Publisher` from another reactive library -is provided it can only be treated as a stream with unknown semantics (0..N). If the -semantics are known -- e.g. `io.reactivex.Single`, you can use `Mono.from(Publisher)` and -pass that in instead of the raw `Publisher`. - -[NOTE] -==== -For example, given a `Publisher` that is not a `Mono`, the Jackson JSON message writer -expects multiple values. If the media type implies an infinite stream -- e.g. -`"application/json+stream"`, values are written and flushed individually; otherwise -values are buffered into a list and rendered as a JSON array. -==== -