Provide distinct Web and Reactive Web sections

This change allows much more usable TOC for the reactive
stack and will make WebFlux documentation easier to
contribute thanks to a clearer split between both stacks.

Issue: SPR-15149

src/docs/asciidoc/index.adoc

@@ -13,7 +13,7 @@ IoC container, with any web framework on top, but you can also use only the
 transaction management, remote access to your logic through RMI or web services, and various
 options for persisting your data.
 It offers full-featured web frameworks such as <<web.adoc#mvc-introduction,Spring MVC>>
-and <<web.adoc#webflux, Spring WebFlux>>; and it enables you to
+and <<reactive-web.adoc#webflux, Spring WebFlux>>; and it enables you to
 integrate <<core.adoc#aop-introduction,AOP>> transparently into your software.
 
 This document is a reference guide to Spring Framework features. Questions on the
@@ -29,7 +29,9 @@ This reference document provides the following sections:
 
 * <<data-access.adoc#spring-data-tier,Data access and transaction management>>
 
-* <<web.adoc#spring-web,The Web>>
+* The Web with 2 flavors:
+ ** <<web.adoc#spring-web,Servlet-based stack with Spring MVC>>
+ ** <<reactive-web.adoc#spring-webflux, Reactive stack with Spring WebFlux>>
 
 * <<integration.adoc#spring-integration,Integration with other technologies>>
 

src/docs/asciidoc/integration.adoc

@@ -9120,3 +9120,4 @@ policies and different topologies which other solutions do not (take for example
 because there would no backing support. Such functionality should be controlled directly
 through the backing cache, when configuring it or through its native API.
 
+include::web/integration.adoc[leveloffset=+1]

src/docs/asciidoc/reactive-web.adoc

+[[spring-reactive-web]]
+= Reactive Web
+:doc-root: https://docs.spring.io
+:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework
+:toc: left
+:toclevels: 3
+
+This part of the documentation covers support for web applications designed to run on a
+reactive web stack (Reactive Streams API + non-blocking runtime) using <<webflux-module, Spring WebFlux>>,
+including its <<webflux-fn,functional programming model>>.
+
+[[spring-reactive-web-intro]]
+== Introduction
+
+
+[[spring-reactive-web-intro-reactive-programming]]
+=== What is Reactive Programming?
+
+In plain terms reactive programming is about non-blocking applications that are asynchronous
+and event-driven and require a small number of threads to scale vertically (i.e. within the
+JVM) rather than horizontally (i.e. through clustering).
+
+A key aspect of reactive applications is the concept of backpressure which is
+a mechanism to ensure producers don't overwhelm consumers. For example in a pipeline
+of reactive components extending from the database to the HTTP response when the
+HTTP connection is too slow the data repository can also slow down or stop completely
+until network capacity frees up.
+
+Reactive programming also leads to a major shift from imperative to declarative async
+composition of logic. It is comparable to writing blocking code vs using the
+`CompletableFuture` from Java 8 to compose follow-up actions via lambda expressions.
+
+For a longer introduction check the blog series
+https://spring.io/blog/2016/06/07/notes-on-reactive-programming-part-i-the-reactive-landscape["Notes on Reactive Programming"]
+by Dave Syer.
+
+
+[[spring-reactive-web-intro-reactive-api]]
+=== Reactive API and Building Blocks
+
+Spring Framework 5 embraces
+https://github.com/reactive-streams/reactive-streams-jvm#reactive-streams[Reactive Streams]
+as the contract for communicating backpressure across async components and
+libraries. Reactive Streams is a specification created through industry collaboration that
+has also been adopted in Java 9 as `java.util.concurrent.Flow`.
+
+The Spring Framework uses https://projectreactor.io/[Reactor] internally for its own
+reactive support. Reactor is a Reactive Streams implementation that further extends the
+basic Reactive Streams `Publisher` contract with the `Flux` and `Mono` composable API
+types to provide declarative operations on data sequences of `0..N` and `0..1`.
+
+The Spring Framework exposes `Flux` and `Mono` in many of its own reactive APIs.
+At the application level however, as always, Spring provides choice and fully supports
+the use of RxJava. For more on reactive types check the post
+https://spring.io/blog/2016/04/19/understanding-reactive-types["Understanding Reactive Types"]
+by Sebastien Deleuze.
+
+include::web/webflux.adoc[leveloffset=+1]
\ No newline at end of file

src/docs/asciidoc/web.adoc

 [[spring-web]]
-= The Web
+= Web
 :doc-root: https://docs.spring.io
 :api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework
 :toc: left
 :toclevels: 2
 
-This part of the documentation covers support for web applications. As of Spring Framework 5.0
-web applications can run on a traditional Servlet stack (Servlet API + Servlet container)
-or on a reactive stack (Reactive Streams API + non-blocking runtime).
-The first few chapters cover the Servlet-based <<mvc,Spring MVC>> web framework
-including <<view,Views>>, <<cors,CORS>>, and <<websocket,WebSocket>> support.
-Subsequent chapters cover the <<webflux,Spring WebFlux>> reactive web framework
-including its <<webflux-fn,functional programming model>>.
+This part of the documentation covers support for web applications designed to run on a
+traditional Servlet stack (Servlet API + Servlet container).
 
-include::web/web-mvc.adoc[leveloffset=+1]
+Chapters cover the Servlet-based <<mvc,Spring MVC>> web framework including <<mvc-view,Views>>,
+<<mvc-cors,CORS>>, and <<websocket,WebSocket>> support.
 
-include::web/web-view.adoc[leveloffset=+1]
+Note that as of Spring Framework 5.0 web applications can also run on a
+<<spring-web-reactive, reactive web stack>> (Reactive Streams API + non-blocking runtime).
 
-include::web/web-cors.adoc[leveloffset=+1]
+include::web/webmvc.adoc[leveloffset=+1]
 
-include::web/web-websocket.adoc[leveloffset=+1]
+include::web/webmvc-view.adoc[leveloffset=+1]
+
+include::web/webmvc-cors.adoc[leveloffset=+1]
+
+include::web/websocket.adoc[leveloffset=+1]
 
-include::web/web-flux.adoc[leveloffset=+1]
 
-include::web/web-integration.adoc[leveloffset=+1]

src/docs/asciidoc/web/web-flux.adoc → src/docs/asciidoc/web/webflux.adoc

 [[webflux]]
-= Spring WebFlux framework
-
-This section provides basic information on the reactive programming
-support for Web applications in Spring Framework 5.
-
-
-[[webflux-intro]]
-== Introduction
-
-
-[[webflux-intro-reactive-programming]]
-=== What is Reactive Programming?
-
-In plain terms reactive programming is about non-blocking applications that are asynchronous
-and event-driven and require a small number of threads to scale vertically (i.e. within the
-JVM) rather than horizontally (i.e. through clustering).
-
-A key aspect of reactive applications is the concept of backpressure which is
-a mechanism to ensure producers don't overwhelm consumers. For example in a pipeline
-of reactive components extending from the database to the HTTP response when the
-HTTP connection is too slow the data repository can also slow down or stop completely
-until network capacity frees up.
-
-Reactive programming also leads to a major shift from imperative to declarative async
-composition of logic. It is comparable to writing blocking code vs using the
-`CompletableFuture` from Java 8 to compose follow-up actions via lambda expressions.
-
-For a longer introduction check the blog series
-https://spring.io/blog/2016/06/07/notes-on-reactive-programming-part-i-the-reactive-landscape["Notes on Reactive Programming"]
-by Dave Syer.
-
-
-[[webflux-intro-reactive-api]]
-=== Reactive API and Building Blocks
-
-Spring Framework 5 embraces
-https://github.com/reactive-streams/reactive-streams-jvm#reactive-streams[Reactive Streams]
-as the contract for communicating backpressure across async components and
-libraries. Reactive Streams is a specification created through industry collaboration that
-has also been adopted in Java 9 as `java.util.concurrent.Flow`.
-
-The Spring Framework uses https://projectreactor.io/[Reactor] internally for its own
-reactive support. Reactor is a Reactive Streams implementation that further extends the
-basic Reactive Streams `Publisher` contract with the `Flux` and `Mono` composable API
-types to provide declarative operations on data sequences of `0..N` and `0..1`.
-
-The Spring Framework exposes `Flux` and `Mono` in many of its own reactive APIs.
-At the application level however, as always, Spring provides choice and fully supports
-the use of RxJava. For more on reactive types check the post
-https://spring.io/blog/2016/04/19/understanding-reactive-types["Understanding Reactive Types"]
-by Sebastien Deleuze.
-
-
-[[webflux-feature-overview]]
-== Spring WebFlux Module
+= Spring WebFlux
 
 Spring Framework 5 includes a new `spring-webflux` module. The module contains support
 for reactive HTTP and WebSocket clients as well as for reactive server web applications
 including REST, HTML browser, and WebSocket style interactions.
 
 [[webflux-server]]
-=== Server Side
+== Server Side
 
 On the server-side WebFlux supports 2 distinct programming models:
 
@@ -85,7 +31,7 @@ REST-style JSON and XML serialization and deserialization is supported on top
 as a `Flux<Object>`, and so is HTML view rendering and Server-Sent Events.
 
 [[webflux-server-annotation]]
-==== Annotation-based Programming Model
+=== Annotation-based Programming Model
 
 The same `@Controller` programming model and the same annotations used in Spring MVC
 are also supported in WebFlux. The main difference is that the underlying core,
@@ -123,11 +69,11 @@ public class PersonController {
 }
 ----
 
-include::web-flux-functional.adoc[leveloffset=+3]
+include::webflux-functional.adoc[leveloffset=+2]
 
 
 [[webflux-client]]
-=== Client Side
+== Client Side
 
 WebFlux includes a functional, reactive `WebClient` that offers a fully
 non-blocking and reactive alternative to the `RestTemplate`. It exposes network
@@ -161,7 +107,7 @@ still based and relies on `InputStream` and `OutputStream`.
 
 
 [[webflux-http-body]]
-=== Request and Response Body Conversion
+== Request and Response Body Conversion
 
 The `spring-core` module provides reactive `Encoder` and `Decoder` contracts
 that enable the serialization of a `Flux` of bytes to and from typed objects.
@@ -216,7 +162,7 @@ default as following:
 
 
 [[webflux-websocket-support]]
-=== Reactive WebSocket Support
+== Reactive WebSocket Support
 
 WebFlux includes reactive WebSocket client and server support.
 Both client and server are supported on the Java WebSocket API
@@ -257,7 +203,7 @@ client.execute("ws://localhost:8080/echo"), session -> {... }).blockMillis(5000)
 ----
 
 [[webflux-tests]]
-=== Testing
+== Testing
 
 The `spring-test` module includes a `WebTestClient` that can be used to test
 WebFlux server endpoints with or without a running server.
@@ -274,11 +220,11 @@ in the framework.
 
 
 [[webflux-getting-started]]
-== Getting Started
+= Getting Started
 
 
 [[webflux-getting-started-boot]]
-=== Spring Boot Starter
+== Spring Boot Starter
 
 The
 Spring Boot WebFlux starter available via http://start.spring.io is the fastest way to get started.
@@ -290,7 +236,7 @@ with Spring Boot to switch to a different runtime.
 See the Spring Boot reference documentation page for more details and instruction.
 
 [[webflux-getting-started-manual]]
-=== Manual Bootstrapping
+== Manual Bootstrapping
 
 This section outlines the steps to get up and running manually.
 
@@ -365,7 +311,7 @@ Spring configuration.
 ====
 
 [[webflux-getting-started-examples]]
-=== Examples
+== Examples
 
 You will find code examples useful to build reactive Web application in the following projects:
 

src/docs/asciidoc/web/web-cors.adoc → src/docs/asciidoc/web/webmvc-cors.adoc

-[[cors]]
-= Spring MVC CORS Support
+[[mvc-cors]]
+= CORS Support
 
 == Introduction
 

src/docs/asciidoc/web/web-mvc.adoc → src/docs/asciidoc/web/webmvc.adoc

@@ -2689,7 +2689,7 @@ directly on `RequestMappingHandlerAdapter`.
 All MVC frameworks for web applications provide a way to address views. Spring provides
 view resolvers, which enable you to render models in a browser without tying you to a
 specific view technology. Out of the box, Spring enables you to use JSPs, FreeMarker
-templates and XSLT views, for example. See <<view>> for a discussion of how to integrate
+templates and XSLT views, for example. See <<mvc-view>> for a discussion of how to integrate
 and use a number of disparate view technologies.
 
 The two interfaces that are important to the way Spring handles views are `ViewResolver`

src/docs/asciidoc/web/web-websocket.adoc → src/docs/asciidoc/web/websocket.adoc

 [[websocket]]
-= Servlet Stack WebSocket Support
+= Servlet-based WebSocket Support
 :doc-spring-security: {doc-root}/spring-security/site/docs/current/reference