Edit the Web chapter of the reference documentation

I edited for spelling, punctuation, grammar, usage,
and corporate voice. I also added links and cross-references.

Author: Jay Bryant

src/docs/asciidoc/web-reactive.adoc

@@ -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,50 +29,46 @@ 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.
 
 
 
 [[webflux-reactive-libraries]]
 == 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.
-====

src/docs/asciidoc/web.adoc

@@ -7,10 +7,10 @@
 :tabsize: 4
 :docinfo1:
 
-This part of the documentation covers support for Servlet stack, web applications built on the
+This part of the documentation covers support for Servlet-stack web applications built on the
 Servlet API and deployed to Servlet containers. Individual chapters include <<mvc,Spring MVC>>,
 <<mvc-view,View Technologies>>, <<mvc-cors,CORS Support>>, and <<websocket,WebSocket Support>>.
-For reactive stack, web applications, go to <<web-reactive.adoc#spring-web-reactive,Web on Reactive Stack>>.
+For reactive-stack web applications, see <<web-reactive.adoc#spring-web-reactive,Web on Reactive Stack>>.
 
 include::web/webmvc.adoc[leveloffset=+1]
 
@@ -21,4 +21,3 @@ include::web/webmvc-test.adoc[leveloffset=+1]
 include::web/websocket.adoc[leveloffset=+1]
 
 include::web/integration.adoc[leveloffset=+1]
-

src/docs/asciidoc/web/integration.adoc

@@ -1,63 +1,59 @@
 [[web-integration]]
 = Other Web Frameworks
 
-
-
-
-[[intro]]
-== Introduction
-
 This chapter details Spring's integration with third party web frameworks.
 
 One of the core value propositions of the Spring Framework is that of enabling
-__choice__. In a general sense, Spring does not force one to use or buy into any
+_choice_. In a general sense, Spring does not force you to use or buy into any
 particular architecture, technology, or methodology (although it certainly recommends
 some over others). This freedom to pick and choose the architecture, technology, or
 methodology that is most relevant to a developer and their development team is
 arguably most evident in the web area, where Spring provides its own web framework
-(<<mvc,Spring MVC>>), while at the same time providing integration with a number of
+(<<mvc,Spring MVC>>) while, at the same time, providing integration with a number of
 popular third party web frameworks.
 
 
 
-
 [[web-integration-common]]
-== Common config
+== Common Configuration
 Before diving into the integration specifics of each supported web framework, let us
-first take a look at the Spring configuration that is __not__ specific to any one web
+first take a look at the Spring configuration that is not specific to any one web
 framework. (This section is equally applicable to Spring's own web framework, Spring
 MVC.)
 
-One of the concepts (for want of a better word) espoused by (Spring's) lightweight
-application model is that of a layered architecture. Remember that in a 'classic'
-layered architecture, the web layer is but one of many layers; it serves as one of the
-entry points into a server side application and it delegates to service objects
-(facades) defined in a service layer to satisfy business specific (and
+One of the concepts (for want of a better word) espoused by Spring's lightweight
+application model is that of a layered architecture. Remember that in a "`classic`"
+layered architecture, the web layer is but one of many layers. It serves as one of the
+entry points into a server-side application, and it delegates to service objects
+(facades) that are defined in a service layer to satisfy business-specific (and
 presentation-technology agnostic) use cases. In Spring, these service objects, any other
-business-specific objects, data access objects, etc. exist in a distinct 'business
-context', which contains __no__ web or presentation layer objects (presentation objects
-such as Spring MVC controllers are typically configured in a distinct 'presentation
-context'). This section details how one configures a Spring container (a
-`WebApplicationContext`) that contains all of the 'business beans' in one's application.
+business-specific objects, data-access objects, and others exist in a distinct "`business
+context`", which contains no web or presentation layer objects (presentation objects
+,such as Spring MVC controllers, are typically configured in a distinct "`presentation
+context`"). This section details how you can configure a Spring container (a
+`WebApplicationContext`) that contains all of the 'business beans' in your application.
 
-On to specifics: all that one need do is to declare a
+Moving on to specifics, all you one need to do is declare a
 {api-spring-framework}/web/context/ContextLoaderListener.html[`ContextLoaderListener`]
-in the standard Java EE servlet `web.xml` file of one's web application, and add a
+in the standard Java EE servlet `web.xml` file of your web application and add a
 `contextConfigLocation`<context-param/> section (in the same file) that defines which
 set of Spring XML configuration files to load.
 
-Find below the <listener/> configuration:
+Consider the following `<listener/>` configuration:
 
+====
 [source,xml,indent=0]
 [subs="verbatim,quotes"]
 ----
 	<listener>
 		<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
 	</listener>
 ----
+====
 
-Find below the <context-param/> configuration:
+Further consider the following `<context-param/>` configuration:
 
+====
 [source,xml,indent=0]
 [subs="verbatim,quotes"]
 ----
@@ -66,30 +62,35 @@ Find below the <context-param/> configuration:
 		<param-value>/WEB-INF/applicationContext*.xml</param-value>
 	</context-param>
 ----
+====
 
-If you don't specify the `contextConfigLocation` context parameter, the
-`ContextLoaderListener` will look for a file called `/WEB-INF/applicationContext.xml` to
+If you do not specify the `contextConfigLocation` context parameter, the
+`ContextLoaderListener` looks for a file called `/WEB-INF/applicationContext.xml` to
 load. Once the context files are loaded, Spring creates a
 {api-spring-framework}/web/context/WebApplicationContext.html[`WebApplicationContext`]
 object based on the bean definitions and stores it in the `ServletContext` of the web
 application.
 
-All Java web frameworks are built on top of the Servlet API, and so one can use the
-following code snippet to get access to this 'business context' `ApplicationContext`
+All Java web frameworks are built on top of the Servlet API, so you can use the
+following code snippet to get access to this "`business context`" `ApplicationContext`
 created by the `ContextLoaderListener`.
 
+The following example shows how to get the `WebApplicationContext`:
+
+====
 [source,java,indent=0]
 [subs="verbatim,quotes"]
 ----
 	WebApplicationContext ctx = WebApplicationContextUtils.getWebApplicationContext(servletContext);
 ----
+====
 
 The
 {api-spring-framework}/web/context/support/WebApplicationContextUtils.html[`WebApplicationContextUtils`]
-class is for convenience, so you don't have to remember the name of the `ServletContext`
-attribute. Its __getWebApplicationContext()__ method will return `null` if an object
-doesn't exist under the `WebApplicationContext.ROOT_WEB_APPLICATION_CONTEXT_ATTRIBUTE`
-key. Rather than risk getting `NullPointerExceptions` in your application, it's better
+class is for convenience, so you need not remember the name of the `ServletContext`
+attribute. Its `getWebApplicationContext()` method returns `null` if an object
+does not exist under the `WebApplicationContext.ROOT_WEB_APPLICATION_CONTEXT_ATTRIBUTE`
+key. Rather than risk getting `NullPointerExceptions` in your application, it is better
 to use the `getRequiredWebApplicationContext()` method. This method throws an exception
 when the `ApplicationContext` is missing.
 
@@ -99,45 +100,44 @@ their implemented interfaces.
 
 Fortunately, most of the frameworks in this section have simpler ways of looking up
 beans. Not only do they make it easy to get beans from a Spring container, but they also
-allow you to use dependency injection on their controllers. Each web framework section
+let you use dependency injection on their controllers. Each web framework section
 has more detail on its specific integration strategies.
 
 
 
-
 [[jsf]]
 == JSF
+
 JavaServer Faces (JSF) is the JCP's standard component-based, event-driven web user
 interface framework. As of Java EE 5, it is an official part of the Java EE umbrella.
 
 For a popular JSF runtime as well as for popular JSF component libraries, check out the
 http://myfaces.apache.org/[Apache MyFaces project]. The MyFaces project also provides
-common JSF extensions such as http://myfaces.apache.org/orchestra/[MyFaces Orchestra]:
-a Spring-based JSF extension that provides rich conversation scope support.
+common JSF extensions, such as http://myfaces.apache.org/orchestra/[MyFaces Orchestra]
+(a Spring-based JSF extension that provides rich conversation scope support).
 
-[NOTE]
-====
-Spring Web Flow 2.0 provides rich JSF support through its newly established Spring Faces
+NOTE: Spring Web Flow 2.0 provides rich JSF support through its newly established Spring Faces
 module, both for JSF-centric usage (as described in this section) and for Spring-centric
-usage (using JSF views within a Spring MVC dispatcher). Check out the
-http://projects.spring.io/spring-webflow[Spring Web Flow website] for details!
-====
+usage (using JSF views within a Spring MVC dispatcher). See the
+http://projects.spring.io/spring-webflow[Spring Web Flow website] for details.
 
 The key element in Spring's JSF integration is the JSF `ELResolver` mechanism.
 
 
 
 [[jsf-springbeanfaceselresolver]]
 === Spring Bean Resolver
+
 `SpringBeanFacesELResolver` is a JSF 1.2+ compliant `ELResolver` implementation,
-integrating with the standard Unified EL as used by JSF 1.2 and JSP 2.1. Like
-`SpringBeanVariableResolver`, it delegates to the Spring's 'business context'
-`WebApplicationContext` __first__, then to the default resolver of the underlying JSF
+integrating with the standard Unified EL as used by JSF 1.2 and JSP 2.1. As
+`SpringBeanVariableResolver`, it delegates to Spring's "`business context`"
+`WebApplicationContext` first and then to the default resolver of the underlying JSF
 implementation.
 
-Configuration-wise, simply define `SpringBeanFacesELResolver` in your JSF
-__faces-context.xml__ file:
+Configuration-wise, you can define `SpringBeanFacesELResolver` in your JSF
+`faces-context.xml` file, as the following example shows:
 
+====
 [source,xml,indent=0]
 [subs="verbatim,quotes"]
 ----
@@ -148,33 +148,39 @@ __faces-context.xml__ file:
 		</application>
 	</faces-config>
 ----
+====
 
 
 
 [[jsf-facescontextutils]]
-=== FacesContextUtils
-A custom `VariableResolver` works well when mapping one's properties to beans
-in __faces-config.xml__, but at times one may need to grab a bean explicitly. The
+=== Using `FacesContextUtils`
+
+A custom `VariableResolver` works well when mapping your properties to beans
+in `faces-config.xml`, but, at times, you may need to explicitly grab a bean. The
 {api-spring-framework}/web/jsf/FacesContextUtils.html[`FacesContextUtils`]
 class makes this easy. It is similar to `WebApplicationContextUtils`, except that it
 takes a `FacesContext` parameter rather than a `ServletContext` parameter.
 
+The following example shows how to use `FacesContextUtils`:
+
+====
 [source,java,indent=0]
 [subs="verbatim,quotes"]
 ----
 	ApplicationContext ctx = FacesContextUtils.getWebApplicationContext(FacesContext.getCurrentInstance());
 ----
-
+====
 
 
 
 [[struts]]
 == Apache Struts 2.x
-Invented by Craig McClanahan, http://struts.apache.org[Struts] is an open source project
+
+Invented by Craig McClanahan, http://struts.apache.org[Struts] is an open-source project
 hosted by the Apache Software Foundation. At the time, it greatly simplified the
 JSP/Servlet programming paradigm and won over many developers who were using proprietary
-frameworks. It simplified the programming model, it was open source (and thus free as in
-beer), and it had a large community, which allowed the project to grow and become popular
+frameworks. It simplified the programming model, it was open source (and thus free, as in
+beer), and it had a large community, which let the project grow and become popular
 among Java web developers.
 
 Check out the Struts
@@ -183,28 +189,25 @@ built-in Spring integration shipped with Struts.
 
 
 
-
 [[tapestry]]
 == Tapestry 5.x
-From the http://tapestry.apache.org/[Tapestry homepage]:
 
-Tapestry is a "__Component oriented framework for creating dynamic, robust,
-highly scalable web applications in Java.__"
+http://tapestry.apache.org/[Tapestry] is a ""Component oriented framework for creating dynamic, robust,
+highly scalable web applications in Java.""
 
 While Spring has its own <<mvc,powerful web layer>>, there are a number of unique
-advantages to building an enterprise Java application using a combination of Tapestry
+advantages to building an enterprise Java application by using a combination of Tapestry
 for the web user interface and the Spring container for the lower layers.
 
-For more information, check out Tapestry's dedicated
+For more information, see Tapestry's dedicated
 https://tapestry.apache.org/integrating-with-spring-framework.html[integration module for
 Spring].
 
 
 
-
 [[web-integration-resources]]
 == Further Resources
-Find below links to further resources about the various web frameworks described in this
+The following links go to further resources about the various web frameworks described in this
 chapter.
 
 * The http://www.oracle.com/technetwork/java/javaee/javaserverfaces-139869.html[JSF] homepage