Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Edit the Web chapter of the reference documentation

Browse Source 
I edited for spelling, punctuation, grammar, usage,
and corporate voice. I also added links and cross-references.
This commit is contained in:
Jay Bryant
2018-09-17 09:36:43 -05:00
committed by Brian Clozel
parent b29a278b2a
commit 00a3afcda8
17 changed files with 4882 additions and 4061 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
src/docs/asciidoc/web-reactive.adoc
View File

@@ -7,12 +7,12 @@
:tabsize: 4
:docinfo1:
This part of the documentation covers support for reactive stack, web applications built on a
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 non-blocking
servers such as Netty, Undertow, and Servlet 3.1+ containers. Individual chapters cover
servers, such as Netty, Undertow, and Servlet 3.1+ containers. Individual chapters cover
the <<webflux,Spring WebFlux>> framework,
the reactive <<webflux-client,WebClient>>, support for <<webflux-test>>,
and <<webflux-reactive-libraries>>. For Servlet stack, web applications, please see
the reactive <<webflux-client,`WebClient`>>, support for <<webflux-test, testing>>,
and <<webflux-reactive-libraries, reactive libraries>>. For Servlet-stack web applications, see
<<web.adoc#spring-web,Web on Servlet Stack>>.
include::web/webflux.adoc[leveloffset=+1]
@@ -29,19 +29,18 @@ include::web/webflux-websocket.adoc[leveloffset=+1]
The `spring-test` module provides mock implementations of `ServerHttpRequest`,
`ServerHttpResponse`, and `ServerWebExchange`.
See <<testing.adoc#mock-objects-web-reactive,Spring Web Reactive>> mock objects.
See <<testing.adoc#mock-objects-web-reactive,Spring Web Reactive>> for a discussion of mock objects.
The <<testing.adoc#webtestclient,WebTestClient>> 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.
<<testing.adoc#webtestclient,`WebTestClient`>> builds on these mock request and
response objects to provide support for testing WebFlux applications without an HTTP
server. You can use the `WebTestClient` for end-to-end integration tests, too.
[[webflux-threading-model]]
=== Threading model
//[[webflux-threading-model]]
//=== Threading model
// TODO Once we have content for this heading, we should un-comment the heading and
// anchor. Until then, we should leave it commented.
@@ -49,30 +48,27 @@ server. The `WebTestClient` can be used for end-to-end integration tests too.
== Reactive Libraries
`spring-webflux` depends on `reactor-core` and uses it internally to compose asynchronous
logic and to provide Reactive Streams support. Generally WebFlux APIs return `Flux` or
`Mono` -- since that's what's used internally, and leniently accept any Reactive Streams
`Publisher` implementation as input. The use of `Flux` vs `Mono` is important because it
helps to express cardinality -- e.g. whether a single or multiple async values are
expected, and that can be essential for making decisions, for example when encoding or
decoding HTTP messages.
logic and to provide Reactive Streams support. Generally, WebFlux APIs return `Flux` or
`Mono` (since those are used internally) and leniently accept any Reactive Streams
`Publisher` implementation as input. The use of `Flux` versus `Mono` is important, because it
helps to express cardinality -- for example, whether a single or multiple asynchronous values are
expected, and that can be essential for making decisions (for example, when encoding or
decoding HTTP messages).
For annotated controllers, WebFlux transparently adapts to the reactive library chosen by
the application. This is done with the help of the
{api-spring-framework}/core/ReactiveAdapterRegistry.html[ReactiveAdapterRegistry] which
{api-spring-framework}/core/ReactiveAdapterRegistry.html[`ReactiveAdapterRegistry`], which
provides pluggable support for reactive library and other asynchronous types. The registry
has built-in support for RxJava and `CompletableFuture`, but others can be registered too.
has built-in support for RxJava and `CompletableFuture`, but you can register others, too.
For functional APIs such as <<webflux-fn>>, the `WebClient`, and others, the general rules
for WebFlux APIs apply -- `Flux` and `Mono` as return values, and Reactive Streams
For functional APIs (such as <<webflux-fn>>, the `WebClient`, and others), the general rules
for WebFlux APIs apply -- `Flux` and `Mono` as return values and a Reactive Streams
`Publisher` as input. When a `Publisher`, whether custom or from another reactive library,
is provided, it can only be treated as a stream with unknown semantics (0..N). If however
is provided, it can be treated only as a stream with unknown semantics (0..N). If, however,
the semantics are known, you can wrap it with `Flux` or `Mono.from(Publisher)` instead
of passing 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
expects multiple values. If the media type implies an infinite stream (for example,
`application/json+stream`), values are written and flushed individually. Otherwise,
values are buffered into a list and rendered as a JSON array.
====