Break down Core and Web chapters in reference doc

Core and Web chapters are important chapters in the Spring Framework
reference documentation, and splitting them in multiple files will
help to evolve the documentation while not creating too many files.

Issue: SPR-12309

build.gradle

@@ -1106,7 +1106,7 @@ configure(rootProject) {
 	asciidoctor {
 		sourceDir project.file('src/asciidoc')
 		separateOutputDirs = false
-		backends = ['docbook5']
+		backends = ['docbook']
 		options doctype: 'book', eruby: 'erubis'
 		attributes 'spring-version': project.version,
 					revnumber : project.version,

src/asciidoc/core-aop.adoc

@@ -36,11 +36,11 @@ AOP is used in the Spring Framework to...
 * ... allow users to implement custom aspects, complementing their use of OOP with AOP.
 
 [NOTE]
-===
+====
 If you are interested only in generic declarative services or other pre-packaged
 declarative middleware services such as pooling, you do not need to work directly with
 Spring AOP, and can skip most of this chapter.
-===
+====
 
 
 

src/asciidoc/testing.adoc

@@ -386,11 +386,11 @@ loader since the default loader supports either resource `locations` or annotate
 +
 
 [NOTE]
-===
+====
 `@ContextConfiguration` provides support for __inheriting__ resource locations or
 configuration classes as well as context initializers declared by superclasses by
 default.
-===
+====
 
 +
 
@@ -530,13 +530,13 @@ should be active when loading an `ApplicationContext` for test classes.
 +
 
 [NOTE]
-===
+====
 `@ActiveProfiles` provides support for __inheriting__ active bean definition profiles
 declared by superclasses by default. It is also possible to resolve active bean
 definition profiles programmatically by implementing a custom
 <<testcontext-ctx-management-env-profiles-ActiveProfilesResolver,`ActiveProfilesResolver`>>
 and registering it via the `resolver` attribute of `@ActiveProfiles`.
-===
+====
 
 +
 
@@ -757,7 +757,7 @@ conjunction with `@ContextConfiguration`.
 +
 
 [NOTE]
-===
+====
 If the default conventions are sufficient for your test configuration, you can avoid
 using `@TransactionConfiguration` altogether. In other words, if you have only one
 transaction manager -- or if you have multiple transaction managers but the transaction
@@ -765,7 +765,7 @@ manager for tests is named "transactionManager" or specified via a
 `TransactionManagementConfigurer` -- and if you want transactions to roll back
 automatically, then there is no need to annotate your test class with
 `@TransactionConfiguration`.
-===
+====
 
 +
 
@@ -916,7 +916,7 @@ tests and can be used anywhere in the Spring Framework.
 
 .JSR-250 Lifecycle Annotations
 [NOTE]
-===
+====
 In the Spring TestContext Framework `@PostConstruct` and `@PreDestroy` may be used with
 standard semantics on any application components configured in the `ApplicationContext`;
 however, these lifecycle annotations have limited usage within an actual test class.
@@ -928,7 +928,7 @@ class. On the other hand, if a method within a test class is annotated with
 `@PreDestroy`, that method will __never__ be executed. Within a test class it is
 therefore recommended to use test lifecycle callbacks from the underlying test framework
 instead of `@PostConstruct` and `@PreDestroy`.
-===
+====
 
 
 [[integration-testing-annotations-junit]]
@@ -1819,11 +1819,11 @@ annotation and supplying a list of profiles that should be activated when loadin
 `ApplicationContext` for the test.
 
 [NOTE]
-===
+====
 `@ActiveProfiles` may be used with any implementation of the new `SmartContextLoader`
 SPI, but `@ActiveProfiles` is not supported with implementations of the older
 `ContextLoader` SPI.
-===
+====
 
 Let's take a look at some examples with XML configuration and `@Configuration` classes.
 
@@ -2149,7 +2149,7 @@ the `Environment`'s set of `PropertySources` for the `ApplicationContext` loaded
 annotated integration test.
 
 [NOTE]
-===
+====
 `@TestPropertySource` may be used with any implementation of the `SmartContextLoader`
 SPI, but `@TestPropertySource` is not supported with implementations of the older
 `ContextLoader` SPI.
@@ -2157,7 +2157,7 @@ SPI, but `@TestPropertySource` is not supported with implementations of the olde
 Implementations of `SmartContextLoader` gain access to merged test property source values
 via the `getPropertySourceLocations()` and `getPropertySourceProperties()` methods in
 `MergedContextConfiguration`.
-===
+====
 
 *Declaring test property sources*
 
@@ -2494,7 +2494,7 @@ is much faster.
 
 .Test suites and forked processes
 [NOTE]
-===
+====
 The Spring TestContext framework stores application contexts in a __static__ cache. This
 means that the context is literally stored in a `static` variable. In other words, if
 tests execute in separate processes the static cache will be cleared between each test
@@ -2509,7 +2509,7 @@ http://maven.apache.org/plugins/maven-surefire-plugin/test-mojo.html#forkMode[fo
 for the Maven Surefire plug-in is set to `always` or `pertest`, the TestContext
 framework will not be able to cache application contexts between test classes and the
 build process will run significantly slower as a result.
-===
+====
 
 Since having a large number of application contexts loaded within a given test suite can
 cause the suite to take an unnecessarily long time to execute, it is often beneficial to
@@ -2678,13 +2678,13 @@ application context for `ExtendedTests` will be loaded only from
 
 .Dirtying a context within a context hierarchy
 [NOTE]
-===
+====
 If `@DirtiesContext` is used in a test whose context is configured as part of a context
 hierarchy, the `hierarchyMode` flag can be used to control how the context cache is
 cleared. For further details consult the discussion of `@DirtiesContext` in
 <<integration-testing-annotations-spring,Spring Testing Annotations>> and the
 `@DirtiesContext` javadocs.
-===
+====
 --
 
 
@@ -2726,7 +2726,7 @@ use of `@Autowired` on fields and setter methods. The application context config
 is presented after all sample code listings.
 
 [NOTE]
-===
+====
 The dependency injection behavior in the following code listings is not specific to
 JUnit. The same DI techniques can be used in conjunction with any testing framework.
 
@@ -2734,7 +2734,7 @@ The following examples make calls to static assertion methods such as `assertNot
 but without prepending the call with `Assert`. In such cases, assume that the method was
 properly imported through an `import static` declaration that is not shown in the
 example.
-===
+====
 
 The first code listing shows a JUnit-based implementation of the test class that uses
 `@Autowired` for field injection.

src/asciidoc/web-integration.adoc

+
+[[web-integration]]
+= Integrating with other web frameworks
+
+
+[[intro]]
+== Introduction
+
+.Spring Web Flow
+****
+Spring Web Flow (SWF) aims to be the best solution for the management of web application
+page flow.
+
+SWF integrates with existing frameworks like Spring MVC and JSF, in both Servlet and
+Portlet environments. If you have a business process (or processes) that would benefit
+from a conversational model as opposed to a purely request model, then SWF may be the
+solution.
+
+SWF allows you to capture logical page flows as self-contained modules that are reusable
+in different situations, and as such is ideal for building web application modules that
+guide the user through controlled navigations that drive business processes.
+
+For more information about SWF, consult the
+http://projects.spring.io/spring-webflow/[Spring Web Flow website].
+****
+
+This chapter details Spring's integration with third party web frameworks, such as
+http://www.oracle.com/technetwork/java/javaee/javaserverfaces-139869.html[JSF].
+
+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
+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
+popular third party web frameworks. This allows one to continue to leverage any and all
+of the skills one may have acquired in a particular web framework such as JSF, while
+at the same time being able to enjoy the benefits afforded by Spring in other areas such
+as data access, declarative transaction management, and flexible configuration and
+application assembly.
+
+Having dispensed with the woolly sales patter (c.f. the previous paragraph), the
+remainder of this chapter will concentrate upon the meaty details of integrating your
+favorite web framework with Spring. One thing that is often commented upon by developers
+coming to Java from other languages is the seeming super-abundance of web frameworks
+available in Java. There are indeed a great number of web frameworks in the Java space;
+in fact there are far too many to cover with any semblance of detail in a single
+chapter. This chapter thus picks four of the more popular web frameworks in Java,
+starting with the Spring configuration that is common to all of the supported web
+frameworks, and then detailing the specific integration options for each supported web
+framework.
+
+[NOTE]
+====
+Please note that this chapter does not attempt to explain how to use any of the
+supported web frameworks. For example, if you want to use JSF for the presentation
+layer of your web application, the assumption is that you are already familiar with
+JSF itself. If you need further details about any of the supported web frameworks
+themselves, please do consult <<web-integration-resources>> at the end of this chapter.
+====
+
+
+
+
+[[web-integration-common]]
+== 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
+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
+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.
+
+On to specifics: all that one need do is to declare a
+{javadoc-baseurl}/org/springframework/web/context/ContextLoaderListener.html[`ContextLoaderListener`]
+in the standard Java EE servlet `web.xml` file of one's 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:
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<listener>
+		<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
+	</listener>
+----
+
+Find below the <context-param/> configuration:
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<context-param>
+		<param-name>contextConfigLocation</param-name>
+		<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
+load. Once the context files are loaded, Spring creates a
+{javadoc-baseurl}/org/springframework/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`
+created by the `ContextLoaderListener`.
+
+[source,java,indent=0]
+[subs="verbatim,quotes"]
+----
+	WebApplicationContext ctx = WebApplicationContextUtils.getWebApplicationContext(servletContext);
+----
+
+The
+{javadoc-baseurl}/org/springframework/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
+to use the `getRequiredWebApplicationContext()` method. This method throws an exception
+when the `ApplicationContext` is missing.
+
+Once you have a reference to the `WebApplicationContext`, you can retrieve beans by
+their name or type. Most developers retrieve beans by name and then cast them to one of
+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
+has more detail on its specific integration strategies.
+
+
+
+
+[[jsf]]
+== JavaServer Faces 1.2
+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.
+
+[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!
+====
+
+The key element in Spring's JSF integration is the JSF `ELResolver` mechanism.
+
+[[jsf-springbeanfaceselresolver]]
+=== SpringBeanFacesELResolver (JSF 1.2+)
+`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
+implementation.
+
+Configuration-wise, simply define `SpringBeanFacesELResolver` in your JSF 1.2
+__faces-context.xml__ file:
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<faces-config>
+		<application>
+			<el-resolver>org.springframework.web.jsf.el.SpringBeanFacesELResolver</el-resolver>
+			...
+		</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
+{javadoc-baseurl}/org/springframework/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.
+
+[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
+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
+among Java web developers.
+
+Check out the Struts
+https://struts.apache.org/release/2.3.x/docs/spring-plugin.html[Spring Plugin] for the
+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.__"
+
+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
+for the web user interface and the Spring container for the lower layers.
+
+For more information, check out 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
+chapter.
+
+* The http://www.oracle.com/technetwork/java/javaee/javaserverfaces-139869.html[JSF] homepage
+* The http://struts.apache.org/[Struts] homepage
+* The http://tapestry.apache.org/[Tapestry] homepage
+

src/asciidoc/web-view.adoc

@@ -21,7 +21,7 @@ or JSTL is done using a normal view resolver defined in the `WebApplicationConte
 Furthermore, of course you need to write some JSPs that will actually render the view.
 
 [NOTE]
-===
+====
 Setting up your application to use JSTL is a common source of error, mainly caused by
 confusion over the different servlet spec., JSP and JSTL version numbers, what they mean
 and how to declare the taglibs correctly. The article
@@ -30,7 +30,7 @@ to Reference and Use JSTL in your Web Application] provides a useful guide to th
 pitfalls and how to avoid them. Note that as of Spring 3.0, the minimum supported
 servlet version is 2.4 (JSP 2.0 and JSTL 1.1), which reduces the scope for confusion
 somewhat.
-===
+====
 
 
 
@@ -857,10 +857,10 @@ applications using Spring. The following describes in a broad way how to do this
 
 
 [NOTE]
-===
+====
 This section focuses on Spring's support for Tiles v3 in the
 `org.springframework.web.servlet.view.tiles3` package.
-===
+====
 
 
 [[view-tiles-dependencies]]
@@ -921,10 +921,10 @@ With this configuration, `tiles_fr_FR.xml` will be used for requests with the `f
 and `tiles.xml` will be used by default.
 
 [NOTE]
-===
+====
 Since underscores are used to indicate locales, it is recommended to avoid using
 them otherwise in the file names for Tiles definitions.
-===
+====
 
 
 [[view-tiles-url]]
@@ -1094,10 +1094,10 @@ definition to your `'{asterisk}-servlet.xml'` as shown below:
 ----
 
 [NOTE]
-===
+====
 For non web-apps add a `VelocityConfigurationFactoryBean` or a
 `FreeMarkerConfigurationFactoryBean` to your application context definition file.
-===
+====