SEC-1327: Minor doc update

docs/manual/src/docbook/core-filters.xml

@@ -157,14 +157,14 @@
                     <classname>AccessDeniedHandlerImpl</classname> is used, which just sends a 403
                 (Forbidden) response to the client. Alternatively you can configure an instance
                 explicitly (as in the above example) and set an error page URL which it will
-                forwards the request to <footnote><para>We use a forward so that the
-                        SecurityContextHolder still contains details of the principal, which may be
-                        useful for displaying to the user. In old releases of Spring Security we
-                        relied upon the servlet container to handle a 403 error message, which
-                        lacked this useful contextual information.</para></footnote>. This can be a
-                simple <quote>access denied</quote> page, such as a JSP, or it could be a more
-                complex handler such as an MVC controller. And of course, you can implement the
-                interface yourself and use your own implementation. </para>
+                forwards the request to <footnote>
+                    <para>We use a forward so that the SecurityContextHolder still contains details
+                        of the principal, which may be useful for displaying to the user. In old
+                        releases of Spring Security we relied upon the servlet container to handle a
+                        403 error message, which lacked this useful contextual information.</para>
+                </footnote>. This can be a simple <quote>access denied</quote> page, such as a JSP,
+                or it could be a more complex handler such as an MVC controller. And of course, you
+                can implement the interface yourself and use your own implementation. </para>
             <para>It's also possible to supply a custom
                     <interfacename>AccessDeniedHandler</interfacename> when you're using the
                 namespace to configure your application. See <link
@@ -175,9 +175,9 @@
     <section xml:id="security-context-persistence-filter">
         <title><classname>SecurityContextPersistenceFilter</classname></title>
         <para> We covered the purpose of this all-important filter in the <link
-                xlink:href="#tech-intro-sec-context-persistence">Technical Overview</link> chapter 
-            so you might want to re-read that section at this point. Let's first take a look at how 
-            you would configure it for use with a <classname>FilterChainProxy</classname>. A basic 
+                xlink:href="#tech-intro-sec-context-persistence">Technical Overview</link> chapter
+            so you might want to re-read that section at this point. Let's first take a look at how
+            you would configure it for use with a <classname>FilterChainProxy</classname>. A basic
             configuration only requires the bean itself <programlisting><![CDATA[
 <bean id="securityContextPersistenceFilter"
 class="org.springframework.security.web.context.SecurityContextPersistenceFilter"/>
@@ -205,20 +205,20 @@ public interface SecurityContextRepository {
                 with wrapper classes. The returned contents will be passed to the filter chain. </para>
             <para> The default implementation is
                     <classname>HttpSessionSecurityContextRepository</classname>, which stores the
-                security context as an <interfacename>HttpSession</interfacename> attribute
-                        <footnote><para>In Spring Security 2.0 and earlier, this filter was called
+                security context as an <interfacename>HttpSession</interfacename> attribute <footnote>
+                    <para>In Spring Security 2.0 and earlier, this filter was called
                             <classname>HttpSessionContextIntegrationFilter</classname> and performed
                         all the work of storing the context was performed by the filter itself. If
                         you were familiar with this class, then most of the configuration options
                         which were available can now be found on
-                            <classname>HttpSessionSecurityContextRepository</classname>.
-                    </para></footnote>. The most important configuration parameter for this
-                implementation is the <literal>allowSessionCreation</literal> property, which
-                defaults to <literal>true</literal>, thus allowing the class to create a session if
-                it needs one to store the security context for an authenticated user (it won't
-                create one unless authentication has taken place and the contents of the security
-                context have changed). If you don't want a session to be created, then you can set
-                this property to <literal>false</literal>: <programlisting language="xml"><![CDATA[
+                            <classname>HttpSessionSecurityContextRepository</classname>. </para>
+                </footnote>. The most important configuration parameter for this implementation is
+                the <literal>allowSessionCreation</literal> property, which defaults to
+                    <literal>true</literal>, thus allowing the class to create a session if it needs
+                one to store the security context for an authenticated user (it won't create one
+                unless authentication has taken place and the contents of the security context have
+                changed). If you don't want a session to be created, then you can set this property
+                to <literal>false</literal>: <programlisting language="xml"><![CDATA[
 <bean id="securityContextPersistenceFilter"
 class="org.springframework.security.web.context.SecurityContextPersistenceFilter">
 <property name='securityContextRepository'>
@@ -228,7 +228,9 @@ class="org.springframework.security.web.context.SecurityContextPersistenceFilter
 </property>
 </bean>
 ]]></programlisting> Alternatively you could provide a null implementation of the
-                    <interfacename>SecurityContextRepository</interfacename> interface. </para>
+                    <interfacename>SecurityContextRepository</interfacename> interface, which will
+                prevent the security context from being stored, even if a session has already been
+                created during the request. </para>
         </section>
     </section>
     <section xml:id="form-login-filter">
@@ -238,27 +240,35 @@ class="org.springframework.security.web.context.SecurityContextPersistenceFilter
             namespace <literal>&lt;http&gt;</literal> element and cannot be substituted with
             alternatives. The only thing that's missing now is an actual authentication mechanism,
             something that will allow a user to authenticate. This filter is the most commonly used
-            authentication filter and the one that is most often customized <footnote><para>For
-                    historical reasons, prior to Spring Security 3.0, this filter was called
+            authentication filter and the one that is most often customized <footnote>
+                <para>For historical reasons, prior to Spring Security 3.0, this filter was called
                         <classname>AuthenticationProcessingFilter</classname> and the entry point
                     was called <classname>AuthenticationProcessingFilterEntryPoint</classname>.
                     Since the framework now supports many different forms of authentication, they
-                    have both been given more specific names in 3.0.</para></footnote>. It also
-            provides the implementation used by the &lt;form-login&gt; element from the namespace.
-            There are three stages required to configure it. <orderedlist><listitem><para>Configure
-                        a <classname>LoginUrlAuthenticationEntryPoint</classname> with the URL of
-                        the login page, just as we did above, and set it on the
-                            <classname>ExceptionTranslationFilter</classname>.
-                        </para></listitem><listitem><para>Implement the login page (using a JSP or
-                        MVC controller).</para></listitem><listitem><para>Configure an instance of
+                    have both been given more specific names in 3.0.</para>
+            </footnote>. It also provides the implementation used by the &lt;form-login&gt; element
+            from the namespace. There are three stages required to configure it. <orderedlist>
+                <listitem>
+                    <para>Configure a <classname>LoginUrlAuthenticationEntryPoint</classname> with
+                        the URL of the login page, just as we did above, and set it on the
+                            <classname>ExceptionTranslationFilter</classname>. </para>
+                </listitem>
+                <listitem>
+                    <para>Implement the login page (using a JSP or MVC controller).</para>
+                </listitem>
+                <listitem>
+                    <para>Configure an instance of
                             <classname>UsernamePasswordAuthenticationFilter</classname> in the
-                        application context</para></listitem><listitem><para>Add the filter bean to
-                        your filter chain proxy (making sure you pay attention to the order).
-                        <!-- TODO: link --></para></listitem></orderedlist> The login form simply
-            contains <literal>j_username</literal> and <literal>j_password</literal> input fields,
-            and posts to the URL that is monitored by the filter (by default this is
-                <literal>/j_spring_security_check</literal>). The basic filter configuration looks
-            something like this: <programlisting><![CDATA[    
+                        application context</para>
+                </listitem>
+                <listitem>
+                    <para>Add the filter bean to your filter chain proxy (making sure you pay
+                        attention to the order). <!-- TODO: link --></para>
+                </listitem>
+            </orderedlist> The login form simply contains <literal>j_username</literal> and
+                <literal>j_password</literal> input fields, and posts to the URL that is monitored
+            by the filter (by default this is <literal>/j_spring_security_check</literal>). The
+            basic filter configuration looks something like this: <programlisting><![CDATA[    
 <bean id="authenticationFilter" class=
 "org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter">
   <property name="authenticationManager" ref="authenticationManager"/>
@@ -274,12 +284,13 @@ class="org.springframework.security.web.context.SecurityContextPersistenceFilter
                     <interfacename>AuthenticationSuccessHandler</interfacename> and
                     <interfacename>AuthenticationFailureHandler</interfacename> strategy interfaces,
                 respectively. The filter has properties which allow you to set these so you can
-                customize the behaviour completely <footnote><para>In versions prior to 3.0, the
-                        application flow at this point had evolved to a stage was controlled by a
-                        mix of properties on this class and strategy plugins. The decision was made
-                        for 3.0 to refactor the code to make these two strategies entirely
-                        responsible. </para></footnote>. Some standard implementations are supplied
-                such as <classname>SimpleUrlAuthenticationSuccessHandler</classname>,
+                customize the behaviour completely <footnote>
+                    <para>In versions prior to 3.0, the application flow at this point had evolved
+                        to a stage was controlled by a mix of properties on this class and strategy
+                        plugins. The decision was made for 3.0 to refactor the code to make these
+                        two strategies entirely responsible. </para>
+                </footnote>. Some standard implementations are supplied such as
+                    <classname>SimpleUrlAuthenticationSuccessHandler</classname>,
                     <classname>SavedRequestAwareAuthenticationSuccessHandler</classname>,
                     <classname>SimpleUrlAuthenticationFailureHandler</classname> and
                     <classname>ExceptionMappingAuthenticationFailureHandler</classname>. Have a look
@@ -291,12 +302,12 @@ class="org.springframework.security.web.context.SecurityContextPersistenceFilter
                 user to the approprate destination. By default a
                     <classname>SavedRequestAwareAuthenticationSuccessHandler</classname> is used,
                 which means that the user will be redirected to the original destination they
-                requested before they were asked to login. <note><para> The
-                            <classname>ExceptionTranslationFilter</classname> caches the original
+                requested before they were asked to login. <note>
+                    <para> The <classname>ExceptionTranslationFilter</classname> caches the original
                         request a user makes. When the user authenticates, the request handler makes
                         use of this cached request to obtain the original URL and redirect to it.
-                        The original request is then rebuilt and used as an alternative.
-                    </para></note> If authentication fails, the configured
+                        The original request is then rebuilt and used as an alternative. </para>
+                </note> If authentication fails, the configured
                     <interfacename>AuthenticationFailureHandler</interfacename> will be invoked.
             </para>
         </section>