Polish Extract Doc Sections

docs/manual/src/docs/asciidoc/_includes/servlet/architecture/delegating-filter-proxy.adoc

@@ -0,0 +1,33 @@
+[[servlet-delegatingfilterproxy]]
+= DelegatingFilterProxy
+
+Spring provides a `Filter` implementation named `DelegatingFilterProxy` that allows bridging between the Servlet container's lifecycle and Spring's `ApplicationContext`.
+The Servlet container allows registering ``Filter``s using its own standards, but it is not aware of Spring defined Beans.
+`DelegatingFilterProxy` can be registered via standard Servlet container mechanisms, but delegate all the work to a Spring Bean that implements `Filter`.
+
+Here is a picture of how `DelegatingFilterProxy` fits into the <<servlet-filterchain-figure>>.
+
+.DelegatingFilterProxy
+[[servlet-delegatingfilterproxy-figure]]
+image::{figures}/delegatingfilterproxy.png[]
+
+`DelegatingFilterProxy` looks up __Bean Filter~0~__ from the `ApplicationContext` and then invokes __Bean Filter~0~__.
+The pseudo code of `DelegatingFilterProxy` can be seen below.
+
+.`DelegatingFilterProxy` Pseudo Code
+====
+[source,java,subs="+quotes,+macros"]
+----
+public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
+	// Lazily get Filter that was registered as a Spring Bean
+	// For the example in <<servlet-delegatingfilterproxy-figure>> `delegate` is an instance of __Bean Filter~0~__
+	Filter delegate = getFilterBean(someBeanName);
+	// delegate work to the Spring Bean
+	delegate.doFilter(request, response);
+}
+----
+====
+
+Another benefit of `DelegatingFilterProxy` is that it allows delaying looking `Filter` bean instances.
+This is important because the container needs to register the `Filter` instances before the container can startup.
+However, Spring typically uses a `ContextLoaderListener` to load the Spring Beans which will not be done until after the `Filter` instances need to be registered.

docs/manual/src/docs/asciidoc/_includes/servlet/architecture/filter-chain-proxy.adoc

@@ -0,0 +1,10 @@
+[[servlet-filterchainproxy]]
+= FilterChainProxy
+
+Spring Security's Servlet support is contained within `FilterChainProxy`.
+`FilterChainProxy` is a special `Filter` provided by Spring Security that allows delegating to many `Filter` instances through <<servlet-securityfilterchain,`SecurityFilterChain`>>.
+Since `FilterChainProxy` is a Bean, it is typically wrapped in a <<servlet-delegatingfilterproxy>>.
+
+.FilterChainProxy
+[[servlet-filterchainproxy-figure]]
+image::{figures}/filterchainproxy.png[]

docs/manual/src/docs/asciidoc/_includes/servlet/architecture/filters.adoc

@@ -0,0 +1,33 @@
+[[servlet-filters-review]]
+= A Review of ``Filter``s
+
+Spring Security's Servlet support is based on Servlet ``Filter``s, so it is helpful to look at the role of ``Filter``s generally first.
+The picture below shows the typical layering of the handlers for a single HTTP request.
+
+.FilterChain
+[[servlet-filterchain-figure]]
+image::{figures}/filterchain.png[]
+
+The client sends a request to the application, and the container creates a `FilterChain` which contains the ``Filter``s and `Servlet` that should process the `HttpServletRequest` based on the path of the request URI.
+At most one `Servlet` can handle a single `HttpServletRequest` and `HttpServletResponse`.
+However, more than one `Filter` can be used to:
+
+* Prevent downstream ``Filter``s or the `Servlet` from being invoked.
+In this instance the `Filter` will typically write the `HttpServletResponse`.
+* Modify the `HttpServletRequest` or `HttpServletResponse` used by the downstream ``Filter``s and `Servlet`
+
+The power of the `Filter` comes from the `FilterChain` that is passed into it.
+
+.`FilterChain` Usage Example
+===
+[source,java]
+----
+public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
+	// do something before the rest of the application
+    chain.doFilter(request, response); // invoke the rest of the application
+    // do something after the rest of the application
+}
+----
+===
+
+Since a `Filter` only impacts downstream ``Filter``s and the `Servlet`, the order each `Filter` is invoked is extremely important.

docs/manual/src/docs/asciidoc/_includes/servlet/architecture/index.adoc

@@ -7,168 +7,15 @@ This section discusses Spring Security's high level architecture within Servlet
 We build on this high level understanding within each section of the reference.
 // FIXME: Add links to other sections of architecture
 
-[[servlet-filters-review]]
-== A Review of ``Filter``s
+include::filters.adoc[leveloffset=+1]
 
-Spring Security's Servlet support is based on Servlet ``Filter``s, so it is helpful to look at the role of ``Filter``s generally first.
-The picture below shows the typical layering of the handlers for a single HTTP request.
+include::delegating-filter-proxy.adoc[leveloffset=+1]
 
-.FilterChain
-[[servlet-filterchain-figure]]
-image::{figures}/filterchain.png[]
+include::filter-chain-proxy.adoc[leveloffset=+1]
 
-The client sends a request to the application, and the container creates a `FilterChain` which contains the ``Filter``s and `Servlet` that should process the `HttpServletRequest` based on the path of the request URI.
-At most one `Servlet` can handle a single `HttpServletRequest` and `HttpServletResponse`.
-However, more than one `Filter` can be used to:
+include::security-filter-chain.adoc[leveloffset=+1]
 
-* Prevent downstream ``Filter``s or the `Servlet` from being invoked.
-In this instance the `Filter` will typically write the `HttpServletResponse`.
-* Modify the `HttpServletRequest` or `HttpServletResponse` used by the downstream ``Filter``s and `Servlet`
-
-The power of the `Filter` comes from the `FilterChain` that is passed into it.
-
-.`FilterChain` Usage Example
-====
-[source,java]
-----
-public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
-	// do something before the rest of the application
-    chain.doFilter(request, response); // invoke the rest of the application
-    // do something after the rest of the application
-}
-----
-====
-
-Since a `Filter` only impacts downstream ``Filter``s and the `Servlet`, the order each `Filter` is invoked is extremely important.
-
-[[servlet-delegatingfilterproxy]]
-== DelegatingFilterProxy
-
-Spring provides a `Filter` implementation named `DelegatingFilterProxy` that allows bridging between the Servlet container's lifecycle and Spring's `ApplicationContext`.
-The Servlet container allows registering ``Filter``s using its own standards, but it is not aware of Spring defined Beans.
-`DelegatingFilterProxy` can be registered via standard Servlet container mechanisms, but delegate all the work to a Spring Bean that implements `Filter`.
-
-Here is a picture of how `DelegatingFilterProxy` fits into the <<servlet-filterchain-figure>>.
-
-.DelegatingFilterProxy
-[[servlet-delegatingfilterproxy-figure]]
-image::{figures}/delegatingfilterproxy.png[]
-
-`DelegatingFilterProxy` looks up __Bean Filter~0~__ from the `ApplicationContext` and then invokes __Bean Filter~0~__.
-The pseudo code of `DelegatingFilterProxy` can be seen below.
-
-.`DelegatingFilterProxy` Pseudo Code
-====
-[source,java,subs="+quotes,+macros"]
-----
-public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
-	// Lazily get Filter that was registered as a Spring Bean
-	// For the example in <<servlet-delegatingfilterproxy-figure>> `delegate` is an instance of __Bean Filter~0~__
-	Filter delegate = getFilterBean(someBeanName);
-	// delegate work to the Spring Bean
-	delegate.doFilter(request, response);
-}
-----
-====
-
-Another benefit of `DelegatingFilterProxy` is that it allows delaying looking `Filter` bean instances.
-This is important because the container needs to register the `Filter` instances before the container can startup.
-However, Spring typically uses a `ContextLoaderListener` to load the Spring Beans which will not be done until after the `Filter` instances need to be registered.
-
-[[servlet-filterchainproxy]]
-== FilterChainProxy
-
-Spring Security's Servlet support is contained within `FilterChainProxy`.
-`FilterChainProxy` is a special `Filter` provided by Spring Security that allows delegating to many `Filter` instances through <<servlet-securityfilterchain,`SecurityFilterChain`>>.
-Since `FilterChainProxy` is a Bean, it is typically wrapped in a <<servlet-delegatingfilterproxy>>.
-
-.FilterChainProxy
-[[servlet-filterchainproxy-figure]]
-image::{figures}/filterchainproxy.png[]
-
-[[servlet-securityfilterchain]]
-== SecurityFilterChain
-
-{security-api-url}org/springframework/security/web/SecurityFilterChain.html[`SecurityFilterChain`] is used by <<servlet-filterchainproxy>> to determine which Spring Security ``Filter``s should be invoked for this request.
-
-The <<servlet-security-filters,Security Filters>> in `SecurityFilterChain` are typically Beans, but they are registered with `FilterChainProxy` instead of <<servlet-delegatingfilterproxy>>.
-`FilterChainProxy` provides a number of advantages to registering directly with the Servlet container or <<servlet-delegatingfilterproxy>>.
-First, it provides a starting point for all of Spring Security's Servlet support.
-For that reason, if you are attempting to troubleshoot Spring Security's Servlet support, adding a debug point in `FilterChainProxy` is a great place to start.
-
-Second, since `FilterChainProxy` is central to Spring Security usage it can perform tasks that are not viewed as optional.
-// FIXME: Add a link to SecurityContext
-For example, it clears out the `SecurityContext` to avoid memory leaks.
-It also applies Spring Security's <<servlet-httpfirewall,`HttpFirewall`>> to protect applications against certain types of attacks.
-
-In addition, it provides more flexibility in determining when a `SecurityFilterChain` should be invoked.
-In a Servlet container, ``Filter``s are invoked based upon the URL alone.
-// FIXME: Link to RequestMatcher
-However, `FilterChainProxy` can determine invocation based upon anything in the `HttpServletRequest` by leveraging the `RequestMatcher` interface.
-
-In fact, `FilterChainProxy` can be used to determine which `SecurityFilterChain` should be used.
-This allows providing a totally separate configuration for different _slices_ if your application.
-
-.Multiple SecurityFilterChain
-[[servlet-multi-securityfilterchain-figure]]
-image::{figures}/multi-securityfilterchain.png[]
-
-In the <<servlet-multi-securityfilterchain-figure>> Figure `FilterChainProxy` decides which `SecurityFilterChain` should be used.
-Only the first `SecurityFilterChain` that matches will be invoked.
-If a URL of `/api/messages/` is requested, it will first match on ``SecurityFilterChain~0~``'s pattern of `+/api/**+`, so only `SecurityFilterChain~0~` will be invoked even though it also matches on ``SecurityFilterChain~n~``.
-If a URL of `/messages/` is requested, it will not match on ``SecurityFilterChain~0~``'s pattern of `+/api/**+`, so `FilterChainProxy` will continue trying each `SecurityFilterChain`.
-Assuming that no other, `SecurityFilterChain` instances match `SecurityFilterChain~n~` will be invoked.
-// FIXME add link to pattern matching
-
-Notice that `SecurityFilterChain~0~` has only three security ``Filter``s instances configured.
-However, `SecurityFilterChain~n~` has four security ``Filter``s configured.
-It is important to note that each `SecurityFilterChain` can be unique and configured in isolation.
-In fact, a `SecurityFilterChain` might have zero security ``Filter``s if the application wants Spring Security to ignore certain requests.
-// FIXME: add link to configuring multiple `SecurityFilterChain` instances
-
-[[servlet-security-filters]]
-== Security Filters
-
-The Security Filters are inserted into the <<servlet-filterchainproxy>> with the <<servlet-securityfilterchain>> API.
-The <<servlet-filters-review,order of ``Filter``>>s matters.
-It is typically not necessary to know the ordering of Spring Security's ``Filter``s.
-However, there are times that it is beneficial to know the ordering
-
-Below is a comprehensive list of Spring Security Filter ordering:
-
-* ChannelProcessingFilter
-* ConcurrentSessionFilter
-* WebAsyncManagerIntegrationFilter
-* SecurityContextPersistenceFilter
-* HeaderWriterFilter
-* CorsFilter
-* CsrfFilter
-* LogoutFilter
-* OAuth2AuthorizationRequestRedirectFilter
-* Saml2WebSsoAuthenticationRequestFilter
-* X509AuthenticationFilter
-* AbstractPreAuthenticatedProcessingFilter
-* CasAuthenticationFilter
-* OAuth2LoginAuthenticationFilter
-* Saml2WebSsoAuthenticationFilter
-* UsernamePasswordAuthenticationFilter
-* ConcurrentSessionFilter
-* OpenIDAuthenticationFilter
-* DefaultLoginPageGeneratingFilter
-* DefaultLogoutPageGeneratingFilter
-* DigestAuthenticationFilter
-* BearerTokenAuthenticationFilter
-* BasicAuthenticationFilter
-* RequestCacheAwareFilter
-* SecurityContextHolderAwareRequestFilter
-* JaasApiIntegrationFilter
-* RememberMeAuthenticationFilter
-* AnonymousAuthenticationFilter
-* OAuth2AuthorizationCodeGrantFilter
-* SessionManagementFilter
-* <<servlet-exceptiontranslationfilter,`ExceptionTranslationFilter`>>
-* <<servlet-authorization-filtersecurityinterceptor,`FilterSecurityInterceptor`>>
-* SwitchUserFilter
+include::security-filters.adoc[leveloffset=+1]
 
 include::exception-translation-filter.adoc[leveloffset=+1]
 

docs/manual/src/docs/asciidoc/_includes/servlet/architecture/security-filter-chain.adoc

@@ -0,0 +1,39 @@
+[[servlet-securityfilterchain]]
+= SecurityFilterChain
+
+{security-api-url}org/springframework/security/web/SecurityFilterChain.html[`SecurityFilterChain`] is used by <<servlet-filterchainproxy>> to determine which Spring Security ``Filter``s should be invoked for this request.
+
+The <<servlet-security-filters,Security Filters>> in `SecurityFilterChain` are typically Beans, but they are registered with `FilterChainProxy` instead of <<servlet-delegatingfilterproxy>>.
+`FilterChainProxy` provides a number of advantages to registering directly with the Servlet container or <<servlet-delegatingfilterproxy>>.
+First, it provides a starting point for all of Spring Security's Servlet support.
+For that reason, if you are attempting to troubleshoot Spring Security's Servlet support, adding a debug point in `FilterChainProxy` is a great place to start.
+
+Second, since `FilterChainProxy` is central to Spring Security usage it can perform tasks that are not viewed as optional.
+// FIXME: Add a link to SecurityContext
+For example, it clears out the `SecurityContext` to avoid memory leaks.
+It also applies Spring Security's <<servlet-httpfirewall,`HttpFirewall`>> to protect applications against certain types of attacks.
+
+In addition, it provides more flexibility in determining when a `SecurityFilterChain` should be invoked.
+In a Servlet container, ``Filter``s are invoked based upon the URL alone.
+// FIXME: Link to RequestMatcher
+However, `FilterChainProxy` can determine invocation based upon anything in the `HttpServletRequest` by leveraging the `RequestMatcher` interface.
+
+In fact, `FilterChainProxy` can be used to determine which `SecurityFilterChain` should be used.
+This allows providing a totally separate configuration for different _slices_ if your application.
+
+.Multiple SecurityFilterChain
+[[servlet-multi-securityfilterchain-figure]]
+image::{figures}/multi-securityfilterchain.png[]
+
+In the <<servlet-multi-securityfilterchain-figure>> Figure `FilterChainProxy` decides which `SecurityFilterChain` should be used.
+Only the first `SecurityFilterChain` that matches will be invoked.
+If a URL of `/api/messages/` is requested, it will first match on ``SecurityFilterChain~0~``'s pattern of `+/api/**+`, so only `SecurityFilterChain~0~` will be invoked even though it also matches on ``SecurityFilterChain~n~``.
+If a URL of `/messages/` is requested, it will not match on ``SecurityFilterChain~0~``'s pattern of `+/api/**+`, so `FilterChainProxy` will continue trying each `SecurityFilterChain`.
+Assuming that no other, `SecurityFilterChain` instances match `SecurityFilterChain~n~` will be invoked.
+// FIXME add link to pattern matching
+
+Notice that `SecurityFilterChain~0~` has only three security ``Filter``s instances configured.
+However, `SecurityFilterChain~n~` has four security ``Filter``s configured.
+It is important to note that each `SecurityFilterChain` can be unique and configured in isolation.
+In fact, a `SecurityFilterChain` might have zero security ``Filter``s if the application wants Spring Security to ignore certain requests.
+// FIXME: add link to configuring multiple `SecurityFilterChain` instances

docs/manual/src/docs/asciidoc/_includes/servlet/architecture/security-filters.adoc

@@ -0,0 +1,43 @@
+[[servlet-security-filters]]
+= Security Filters
+
+The Security Filters are inserted into the <<servlet-filterchainproxy>> with the <<servlet-securityfilterchain>> API.
+The <<servlet-filters-review,order of ``Filter``>>s matters.
+It is typically not necessary to know the ordering of Spring Security's ``Filter``s.
+However, there are times that it is beneficial to know the ordering
+
+Below is a comprehensive list of Spring Security Filter ordering:
+
+* ChannelProcessingFilter
+* ConcurrentSessionFilter
+* WebAsyncManagerIntegrationFilter
+* SecurityContextPersistenceFilter
+* HeaderWriterFilter
+* CorsFilter
+* CsrfFilter
+* LogoutFilter
+* OAuth2AuthorizationRequestRedirectFilter
+* Saml2WebSsoAuthenticationRequestFilter
+* X509AuthenticationFilter
+* AbstractPreAuthenticatedProcessingFilter
+* CasAuthenticationFilter
+* OAuth2LoginAuthenticationFilter
+* Saml2WebSsoAuthenticationFilter
+* UsernamePasswordAuthenticationFilter
+* ConcurrentSessionFilter
+* OpenIDAuthenticationFilter
+* DefaultLoginPageGeneratingFilter
+* DefaultLogoutPageGeneratingFilter
+* DigestAuthenticationFilter
+* BearerTokenAuthenticationFilter
+* BasicAuthenticationFilter
+* RequestCacheAwareFilter
+* SecurityContextHolderAwareRequestFilter
+* JaasApiIntegrationFilter
+* RememberMeAuthenticationFilter
+* AnonymousAuthenticationFilter
+* OAuth2AuthorizationCodeGrantFilter
+* SessionManagementFilter
+* <<servlet-exceptiontranslationfilter,`ExceptionTranslationFilter`>>
+* <<servlet-authorization-filtersecurityinterceptor,`FilterSecurityInterceptor`>>
+* SwitchUserFilter