Ref manual content and docbook improvements

docs/manual/src/docbook/anon-auth-provider.xml

@@ -1,4 +1,4 @@
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="anonymous">
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="anonymous" xmlns:xlink="http://www.w3.org/1999/xlink">
     <info>
         <title>Anonymous Authentication</title>
     </info>
@@ -37,7 +37,7 @@
             <title>Configuration</title>
         </info>
         <para>Anonymous authentication support is provided automatically when using the HTTP
-            configurain Spring Security 3.0 and can be customized (or disabled) using the
+            configuration Spring Security 3.0 and can be customized (or disabled) using the
                 <literal>&lt;anonymous></literal> element. You don't need to configure the beans
             described here unless you are using traditional bean configuration.</para>
         <para>Three classes that together provide the anonymous authentication feature.
@@ -69,10 +69,10 @@
     </programlisting>
         </para>
         <para>The <literal>key</literal> is shared between the filter and authentication provider,
-            so that tokens created by the former are accepted by the latter<footnote><para>The use
-                    of the <literal>key</literal> property should not be regarded as providing any
-                    real security here. It is merely a book-keeping exercise. If you are sharing a
-                        <classname>ProviderManager</classname> which contains an
+            so that tokens created by the former are accepted by the latter<footnote>
+                <para>The use of the <literal>key</literal> property should not be regarded as
+                    providing any real security here. It is merely a book-keeping exercise. If you
+                    are sharing a <classname>ProviderManager</classname> which contains an
                         <classname>AnonymousAuthenticationProvider</classname> in a scenario where
                     it is possible for an authenticating client to construct the
                         <interfacename>Authentication</interfacename> object (such as with RMI
@@ -83,8 +83,8 @@
                     anonymous provider. This isn't a problem with normal usage but if you are using
                     RMI you would be best to use a customized <classname>ProviderManager</classname>
                     which omits the anonymous provider rather than sharing the one you use for your
-                    HTTP authentication mechanisms.</para></footnote>. The
-                <literal>userAttribute</literal> is expressed in the form of
+                    HTTP authentication mechanisms.</para>
+            </footnote>. The <literal>userAttribute</literal> is expressed in the form of
                 <literal>usernameInTheAuthenticationToken,grantedAuthority[,grantedAuthority]</literal>.
             This is the same syntax as used after the equals sign for
                 <literal>InMemoryDaoImpl</literal>'s <literal>userMap</literal> property.</para>
@@ -128,8 +128,9 @@
         <para> You will often see the <literal>ROLE_ANONYMOUS</literal> attribute in the above
             interceptor configuration replaced with <literal>IS_AUTHENTICATED_ANONYMOUSLY</literal>.
             This is an example of the use of the <classname>AuthenticatedVoter</classname> which
-            will see in ???. It uses an <interfacename>AuthenticationTrustResolver</interfacename>
-            to process this particular configuration attribute and grant access to aonymous users.
-        </para>
+            will see in the <link xlink:href="#authz-authenticated-voter">authorization
+                chapter</link>. It uses an
+                <interfacename>AuthenticationTrustResolver</interfacename> to process this
+            particular configuration attribute and grant access to aonymous users. </para>
     </section>
 </chapter>

docs/manual/src/docbook/appendix-namespace.xml

@@ -22,15 +22,16 @@
     <para> The <literal>&lt;http&gt;</literal> element encapsulates the security configuration for
       the web layer of your application. It creates a <classname>FilterChainProxy</classname> bean
       named "springSecurityFilterChain" which maintains the stack of security filters which make up
-      the web security configuration <footnote><para>See the <link xlink:href="#ns-web-xml">
-            introductory chapter</link> for how to set up the mapping from your
-            <literal>web.xml</literal></para></footnote>. Some core filters are always created and
-      others will be added to the stack depending on the attributes child elements which are
-      present. The positions of the standard filters are fixed (see <link xlink:href="#filter-stack"
-        >the filter order table</link> in the namespace introduction), removing a common source of
-      errors with previous versions of the framework when users had to configure the filter chain
-      explicitly in the<classname>FilterChainProxy</classname> bean. You can, of course, still do
-      this if you need full control of the configuration. </para>
+      the web security configuration <footnote>
+        <para>See the <link xlink:href="#ns-web-xml"> introductory chapter</link> for how to set up
+          the mapping from your <literal>web.xml</literal></para>
+      </footnote>. Some core filters are always created and others will be added to the stack
+      depending on the attributes child elements which are present. The positions of the standard
+      filters are fixed (see <link xlink:href="#filter-stack">the filter order table</link> in the
+      namespace introduction), removing a common source of errors with previous versions of the
+      framework when users had to configure the filter chain explicitly in
+        the<classname>FilterChainProxy</classname> bean. You can, of course, still do this if you
+      need full control of the configuration. </para>
     <para> All filters which require a reference to the
         <interfacename>AuthenticationManager</interfacename> will be automatically injected with the
       internal instance created by the namespace configuration (see the <link
@@ -112,7 +113,7 @@
       </section>
     </section>
     <section xml:id="nsa-access-denied-handler">
-      <title><literal>access-denied-handler</literal></title>
+      <title><literal>&lt;access-denied-handler></literal></title>
       <para> This element allows you to set the <literal>errorPage</literal> property for the
         default <interfacename>AccessDeniedHandler</interfacename> used by the
           <classname>ExceptionTranslationFilter</classname>, (using the
@@ -129,7 +130,10 @@
           <classname>FilterSecurityInterceptor</classname> and to exclude particular patterns from
         the filter chain entirely (by setting the attribute <literal>filters="none"</literal>). It
         is also responsible for configuring a <classname>ChannelAuthenticationFilter</classname> if
-        particular URLs need to be accessed by HTTPS, for example. </para>
+        particular URLs need to be accessed by HTTPS, for example. When matching the specified
+        patterns against an incoming request, the matching is done in the order in which the
+        elements are declared. So the most specific matches patterns should come first and the most
+        general should come last.</para>
       <section xml:id="nsa-pattern">
         <title><literal>pattern</literal></title>
         <para> The pattern which defines the URL path. The content will depend on the
@@ -139,24 +143,25 @@
       <section xml:id="nsa-method">
         <title><literal>method</literal></title>
         <para> The HTTP Method which will be used in combination with the pattern to match an
-          incoming request. If omitted, any method will match. </para>
+          incoming request. If omitted, any method will match. If an identical pattern is specified
+          with and without a method, the method-specific match will take precedence.</para>
       </section>
       <section xml:id="nsa-access">
         <title><literal>access</literal></title>
         <para> Lists the access attributes which will be stored in the
             <interfacename>FilterInvocationDefinitionSource</interfacename> for the defined URL
-          pattern/method combination. This should be a comma-separated list of the attributes (such
-          as role names). </para>
+          pattern/method combination. This should be a comma-separated list of the security
+          configuration attributes (such as role names). </para>
       </section>
       <section xml:id="nsa-requires-channel">
         <title><literal>requires-channel</literal></title>
-        <para> Can be "http" or "https" depending on whether a particular URL pattern should be
-          accessed over HTTP or HTTPS respectively. Alternatively the value "any" can be used when
-          there is no preference. If this attribute is present on any
-            <literal>&lt;intercept-url&gt;</literal> element, then a
+        <para> Can be <quote>http</quote> or <quote>https</quote> depending on whether a particular
+          URL pattern should be accessed over HTTP or HTTPS respectively. Alternatively the value
+            <quote>any</quote> can be used when there is no preference. If this attribute is present
+          on any <literal>&lt;intercept-url&gt;</literal> element, then a
             <classname>ChannelAuthenticationFilter</classname> will be added to the filter stack and
-          its additional dependencies added to the application context.
-          <!--See the chapter on <link
+          its additional dependencies added to the application
+          context.<!--See the chapter on <link
             xlink:href="#channel-security-config">channel security</link> for an example
           configuration using traditional beans. --></para>
         <para> If a <literal>&lt;port-mappings&gt;</literal> configuration is added, this will be
@@ -164,6 +169,14 @@
             <classname>InsecureChannelProcessor</classname> beans to determine the ports used for
           redirecting to HTTP/HTTPS. </para>
       </section>
+      <section>
+        <title><literal>filters</literal></title>
+        <para>Can only take the value <quote>none</quote>. This will cause any matching request to
+          bypass the Spring Security filter chain entirely. None of the rest of the
+            <literal>&lt;http></literal> configuration will have any effect on the request and there
+          will be no security context available for its duration. Access to secured methods during
+          the request will fail.</para>
+      </section>
     </section>
     <section>
       <title>The <literal>&lt;port-mappings&gt;</literal> Element</title>
@@ -180,13 +193,14 @@
         filter stack and an <classname>LoginUrlAuthenticationEntryPoint</classname> to the
         application context to provide authentication on demand. This will always take precedence
         over other namespace-created entry points. If no attributes are supplied, a login page will
-        be generated automatically at the URL "/spring-security-login" <footnote><para>This feature
-            is really just provided for convenience and is not intended for production (where a view
-            technology will have been chosen and can be used to render a customized login page). The
-            class <classname>DefaultLoginPageGeneratingFilter</classname> is responsible for
-            rendering the login page and will provide login forms for both normal form login and/or
-            OpenID if required.</para></footnote> The behaviour can be customized using the
-        following attributes. </para>
+        be generated automatically at the URL "/spring-security-login" <footnote>
+          <para>This feature is really just provided for convenience and is not intended for
+            production (where a view technology will have been chosen and can be used to render a
+            customized login page). The class
+              <classname>DefaultLoginPageGeneratingFilter</classname> is responsible for rendering
+            the login page and will provide login forms for both normal form login and/or OpenID if
+            required.</para>
+        </footnote> The behaviour can be customized using the following attributes. </para>
       <section>
         <title><literal>login-page</literal></title>
         <para> The URL that should be used to render the login page. Maps to the
@@ -279,9 +293,11 @@
         <title>The <literal>key</literal> Attribute</title>
         <para>Maps to the "key" property of <classname>AbstractRememberMeServices</classname>.
           Should be set to a unique value to ensure that remember-me cookies are only valid within
-          the one application <footnote><para>This doesn't affect the use of
+          the one application <footnote>
+            <para>This doesn't affect the use of
                 <classname>PersistentTokenBasedRememberMeServices</classname>, where the tokens are
-              stored on the server side.</para></footnote>. </para>
+              stored on the server side.</para>
+          </footnote>. </para>
       </section>
       <section>
         <title><literal>token-validity-seconds</literal></title>
@@ -507,11 +523,15 @@
         <para> Rather than defining security attributes on an individual method or class basis using
           the <literal>@Secured</literal> annotation, you can define cross-cutting security
           constraints across whole sets of methods and interfaces in your service layer using the
-            <literal>&lt;protect-pointcut&gt;</literal> element. This has two attributes:
-                  <itemizedlist><listitem><para><literal>expression</literal> - the pointcut
-                expression</para></listitem><listitem><para><literal>access</literal> - the security
-                attributes which apply</para></listitem></itemizedlist> You can find an example in
-          the <link xlink:href="#ns-protect-pointcut">namespace introduction</link>. </para>
+            <literal>&lt;protect-pointcut&gt;</literal> element. This has two attributes: <itemizedlist>
+            <listitem>
+              <para><literal>expression</literal> - the pointcut expression</para>
+            </listitem>
+            <listitem>
+              <para><literal>access</literal> - the security attributes which apply</para>
+            </listitem>
+          </itemizedlist> You can find an example in the <link xlink:href="#ns-protect-pointcut"
+            >namespace introduction</link>. </para>
       </section>
       <section xml:id="nsa-custom-after-invocation">
         <title>The <literal>&lt;after-invocation-provider&gt;</literal> Element</title>

docs/manual/src/docbook/authorization-common.xml

@@ -1,9 +1,9 @@
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="authorization-common"
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="authz-arch"
   xmlns:xlink="http://www.w3.org/1999/xlink">
   <info>
-    <title>Common Authorization Concepts</title>
+    <title>Authorization Architecture</title>
   </info>
-  <section xml:id="authorities">
+  <section xml:id="authz-authorities">
     <info>
       <title>Authorities</title>
     </info>
@@ -45,7 +45,7 @@
         <literal>GrantedAuthorityImpl</literal> to populate the
         <interfacename>Authentication</interfacename> object.</para>
   </section>
-  <section xml:id="pre-invocation">
+  <section xml:id="authz-pre-invocation">
     <info>
       <title>Pre-Invocation Handling</title>
     </info>
@@ -53,7 +53,7 @@
       chapter, Spring Security provides interceptors which control access to secure objects such as
       method invocations or web requests. A pre-invocation decision on whether the invocation is
       allowed to proceed is made by the <interfacename>AccessDecisionManager</interfacename>. </para>
-    <section>
+    <section xml:id="authz-access-decision-manager">
       <title>The AccessDecisionManager</title>
       <para>The <interfacename>AccessDecisionManager</interfacename> is called by the
           <classname>AbstractSecurityInterceptor</classname> and is responsible for making final
@@ -82,102 +82,110 @@
         called by a security interceptor implementation to ensure the configured
           <interfacename>AccessDecisionManager</interfacename> supports the type of secure object
         that the security interceptor will present.</para>
-      <section>
-        <title>Voting-Based AccessDecisionManager Implementations</title>
-        <para>Whilst users can implement their own
-            <interfacename>AccessDecisionManager</interfacename> to control all aspects of
-          authorization, Spring Security includes several
-            <interfacename>AccessDecisionManager</interfacename> implementations that are based on
-          voting. <xref linkend="authz-access-voting"/> illustrates the relevant classes.</para>
-        <figure xml:id="authz-access-voting">
-          <title>Voting Decision Manager</title>
-          <mediaobject>
-            <!--        
-        <imageobject role="fo">
-          <imagedata align="center" fileref="resources/images/AccessDecisionVoting.gif" format="GIF"/>
-        </imageobject>
+    </section>
+    <section xml:id="authz-voting-based">
+      <title>Voting-Based AccessDecisionManager Implementations</title>
+      <para>Whilst users can implement their own
+          <interfacename>AccessDecisionManager</interfacename> to control all aspects of
+        authorization, Spring Security includes several
+          <interfacename>AccessDecisionManager</interfacename> implementations that are based on
+        voting. <xref linkend="authz-access-voting"/> illustrates the relevant classes.</para>
+      <figure xml:id="authz-access-voting">
+        <title>Voting Decision Manager</title>
+        <mediaobject>
+          <!--        
+      <imageobject role="fo">
+        <imagedata align="center" fileref="resources/images/AccessDecisionVoting.gif" format="GIF"/>
+      </imageobject>
 -->
-            <imageobject>
-              <imagedata align="center" scalefit="1" fileref="images/AccessDecisionVoting.gif"
-                format="GIF"/>
-            </imageobject>
-          </mediaobject>
-        </figure>
-        <para>Using this approach, a series of <interfacename>AccessDecisionVoter</interfacename>
-          implementations are polled on an authorization decision. The
-            <interfacename>AccessDecisionManager</interfacename> then decides whether or not to
-          throw an <literal>AccessDeniedException</literal> based on its assessment of the
-          votes.</para>
-        <para>The <interfacename>AccessDecisionVoter</interfacename> interface has three methods:
-          <programlisting>
+          <imageobject>
+            <imagedata align="center" scalefit="1" fileref="images/AccessDecisionVoting.gif"
+              format="GIF" />
+          </imageobject>
+        </mediaobject>
+      </figure>
+      <para>Using this approach, a series of <interfacename>AccessDecisionVoter</interfacename>
+        implementations are polled on an authorization decision. The
+          <interfacename>AccessDecisionManager</interfacename> then decides whether or not to throw
+        an <literal>AccessDeniedException</literal> based on its assessment of the votes.</para>
+      <para>The <interfacename>AccessDecisionVoter</interfacename> interface has three methods:
+        <programlisting>
 int vote(Authentication authentication, Object object, List&lt;ConfigAttribute&gt; config);
 boolean supports(ConfigAttribute attribute);
 boolean supports(Class clazz);
 </programlisting>
-          Concrete implementations return an <literal>int</literal>, with possible values being
-          reflected in the <interfacename>AccessDecisionVoter</interfacename> static fields
-            <literal>ACCESS_ABSTAIN</literal>, <literal>ACCESS_DENIED</literal> and
-            <literal>ACCESS_GRANTED</literal>. A voting implementation will return
-            <literal>ACCESS_ABSTAIN</literal> if it has no opinion on an authorization decision. If
-          it does have an opinion, it must return either <literal>ACCESS_DENIED</literal> or
-            <literal>ACCESS_GRANTED</literal>.</para>
-        <para>There are three concrete <interfacename>AccessDecisionManager</interfacename>s
-          provided with Spring Security that tally the votes. The <literal>ConsensusBased</literal>
-          implementation will grant or deny access based on the consensus of non-abstain votes.
-          Properties are provided to control behavior in the event of an equality of votes or if all
-          votes are abstain. The <literal>AffirmativeBased</literal> implementation will grant
-          access if one or more <literal>ACCESS_GRANTED</literal> votes were received (i.e. a deny
-          vote will be ignored, provided there was at least one grant vote). Like the
-            <literal>ConsensusBased</literal> implementation, there is a parameter that controls the
-          behavior if all voters abstain. The <literal>UnanimousBased</literal> provider expects
-          unanimous <literal>ACCESS_GRANTED</literal> votes in order to grant access, ignoring
-          abstains. It will deny access if there is any <literal>ACCESS_DENIED</literal> vote. Like
-          the other implementations, there is a parameter that controls the behaviour if all voters
+        Concrete implementations return an <literal>int</literal>, with possible values being
+        reflected in the <interfacename>AccessDecisionVoter</interfacename> static fields
+          <literal>ACCESS_ABSTAIN</literal>, <literal>ACCESS_DENIED</literal> and
+          <literal>ACCESS_GRANTED</literal>. A voting implementation will return
+          <literal>ACCESS_ABSTAIN</literal> if it has no opinion on an authorization decision. If it
+        does have an opinion, it must return either <literal>ACCESS_DENIED</literal> or
+          <literal>ACCESS_GRANTED</literal>.</para>
+      <para>There are three concrete <interfacename>AccessDecisionManager</interfacename>s provided
+        with Spring Security that tally the votes. The <literal>ConsensusBased</literal>
+        implementation will grant or deny access based on the consensus of non-abstain votes.
+        Properties are provided to control behavior in the event of an equality of votes or if all
+        votes are abstain. The <literal>AffirmativeBased</literal> implementation will grant access
+        if one or more <literal>ACCESS_GRANTED</literal> votes were received (i.e. a deny vote will
+        be ignored, provided there was at least one grant vote). Like the
+          <literal>ConsensusBased</literal> implementation, there is a parameter that controls the
+        behavior if all voters abstain. The <literal>UnanimousBased</literal> provider expects
+        unanimous <literal>ACCESS_GRANTED</literal> votes in order to grant access, ignoring
+        abstains. It will deny access if there is any <literal>ACCESS_DENIED</literal> vote. Like
+        the other implementations, there is a parameter that controls the behaviour if all voters
+        abstain.</para>
+      <para>It is possible to implement a custom
+          <interfacename>AccessDecisionManager</interfacename> that tallies votes differently. For
+        example, votes from a particular <interfacename>AccessDecisionVoter</interfacename> might
+        receive additional weighting, whilst a deny vote from a particular voter may have a veto
+        effect.</para>
+      <section xml:id="authz-role-voter">
+        <title><classname>RoleVoter</classname></title>
+        <para> The most commonly used <interfacename>AccessDecisionVoter</interfacename> provided
+          with Spring Security is the simple <classname>RoleVoter</classname>, which treats
+          configuration attributes as simple role names and votes to grant access if the user has
+          been assigned that role.</para>
+        <para>It will vote if any <interfacename>ConfigAttribute</interfacename> begins with the
+          prefix <literal>ROLE_</literal>. It will vote to grant access if there is a
+            <interfacename>GrantedAuthority</interfacename> which returns a
+            <literal>String</literal> representation (via the <literal>getAuthority()</literal>
+          method) exactly equal to one or more <literal>ConfigAttributes</literal> starting with
+            <literal>ROLE_</literal>. If there is no exact match of any
+            <literal>ConfigAttribute</literal> starting with <literal>ROLE_</literal>, the
+            <literal>RoleVoter</literal> will vote to deny access. If no
+            <literal>ConfigAttribute</literal> begins with <literal>ROLE_</literal>, the voter will
           abstain.</para>
-        <para>It is possible to implement a custom
-            <interfacename>AccessDecisionManager</interfacename> that tallies votes differently. For
-          example, votes from a particular <interfacename>AccessDecisionVoter</interfacename> might
-          receive additional weighting, whilst a deny vote from a particular voter may have a veto
-          effect.</para>
-        <section>
-          <title><classname>RoleVoter</classname></title>
-          <para> The most commonly used <interfacename>AccessDecisionVoter</interfacename> provided
-            with Spring Security is the simple <classname>RoleVoter</classname>, which treats
-            configuration attributes as simple role names and votes to grant access if the user has
-            been assigned that role.</para>
-          <para>It will vote if any ConfigAttribute begins with the prefix <literal>ROLE_</literal>.
-            It will vote to grant access if there is a
-              <interfacename>GrantedAuthority</interfacename> which returns a
-              <literal>String</literal> representation (via the <literal>getAuthority()</literal>
-            method) exactly equal to one or more <literal>ConfigAttributes</literal> starting with
-              <literal>ROLE_</literal>. If there is no exact match of any
-              <literal>ConfigAttribute</literal> starting with <literal>ROLE_</literal>, the
-              <literal>RoleVoter</literal> will vote to deny access. If no
-              <literal>ConfigAttribute</literal> begins with <literal>ROLE_</literal>, the voter
-            will abstain. The comparisons of attributes and</para>
-        </section>
-        <section>
-          <title>Custom Voters</title>
-          <para>It is also possible to implement a custom
-              <interfacename>AccessDecisionVoter</interfacename>. Several examples are provided in
-            Spring Security unit tests, including <literal>ContactSecurityVoter</literal> and
-              <literal>DenyVoter</literal>. The <literal>ContactSecurityVoter</literal> abstains
-            from voting decisions where a <literal>CONTACT_OWNED_BY_CURRENT_USER</literal>
-            <literal>ConfigAttribute</literal> is not found. If voting, it queries the
-              <classname>MethodInvocation</classname> to extract the owner of the
-              <literal>Contact</literal> object that is subject of the method call. It votes to
-            grant access if the <literal>Contact</literal> owner matches the principal presented in
-            the <interfacename>Authentication</interfacename> object. It could have just as easily
-            compared the <literal>Contact</literal> owner with some
-              <interfacename>GrantedAuthority</interfacename> the
-              <interfacename>Authentication</interfacename> object presented. All of this is
-            achieved with relatively few lines of code and demonstrates the flexibility of the
-            authorization model.</para>
-        </section>
+      </section>
+      <section xml:id="authz-authenticated-voter">
+        <title><classname>AuthenticatedVoter</classname></title>
+        <para> Another voter which we've implicitly seen is the
+            <classname>AuthenticatedVoter</classname>, which can be used to differentiate between
+          anonymous, fully-authenticated and remember-me authenticated users. When we've used the
+          attribute <literal>IS_AUTHENTICATED_ANONYMOUSLY</literal> to grant anonymous access, this
+          attribute was being processed by the <classname>AuthenticatedVoter</classname>. See the
+          Javadoc for this class for more information. </para>
+      </section>
+      <section>
+        <title>Custom Voters</title>
+        <para>It is also possible to implement a custom
+            <interfacename>AccessDecisionVoter</interfacename>. Several examples are provided in
+          Spring Security unit tests, including <literal>ContactSecurityVoter</literal> and
+            <literal>DenyVoter</literal>. The <literal>ContactSecurityVoter</literal> abstains from
+          voting decisions where a <literal>CONTACT_OWNED_BY_CURRENT_USER</literal>
+          <literal>ConfigAttribute</literal> is not found. If voting, it queries the
+            <classname>MethodInvocation</classname> to extract the owner of the
+            <literal>Contact</literal> object that is subject of the method call. It votes to grant
+          access if the <literal>Contact</literal> owner matches the principal presented in the
+            <interfacename>Authentication</interfacename> object. It could have just as easily
+          compared the <literal>Contact</literal> owner with some
+            <interfacename>GrantedAuthority</interfacename> the
+            <interfacename>Authentication</interfacename> object presented. All of this is achieved
+          with relatively few lines of code and demonstrates the flexibility of the authorization
+          model.</para>
       </section>
     </section>
   </section>
-  <section xml:id="after-invocation">
+  <section xml:id="authz-after-invocation-handling">
     <info>
       <title>After Invocation Handling</title>
     </info>
@@ -189,11 +197,15 @@ boolean supports(Class clazz);
       that integrate with its ACL capabilities.</para>
     <para><xref linkend="authz-after-invocation"/> illustrates Spring Security's
         <literal>AfterInvocationManager</literal> and its concrete implementations. <figure
-        xml:id="authz-after-invocation"><title>After Invocation
-            Implementation</title><mediaobject><imageobject>
+        xml:id="authz-after-invocation">
+        <title>After Invocation Implementation</title>
+        <mediaobject>
+          <imageobject>
             <imagedata align="center" scalefit="1" fileref="images/AfterInvocation.gif" format="GIF"
             />
-          </imageobject></mediaobject></figure></para>
+          </imageobject>
+        </mediaobject>
+      </figure></para>
     <para>Like many other parts of Spring Security, <literal>AfterInvocationManager</literal> has a
       single concrete implementation, <literal>AfterInvocationProviderManager</literal>, which polls
       a list of <literal>AfterInvocationProvider</literal>s. Each

docs/manual/src/docbook/namespace-config.xml

@@ -9,8 +9,8 @@
     <para> Namespace configuration has been available since version 2.0 of the Spring framework. It
       allows you to supplement the traditional Spring beans application context syntax with elements
       from additional XML schema. You can find more information in the Spring <link
-        xlink:href="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/apc.html">
-        Reference Documentation</link>. A namespace element can be used simply to allow a more
+        xlink:href="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/apc.html"
+        > Reference Documentation</link>. A namespace element can be used simply to allow a more
       concise way of configuring an individual bean or, more powerfully, to define an alternative
       configuration syntax which more closely matches the problem domain and hides the underlying
       complexity from the user. A simple element may conceal the fact that multiple beans and
@@ -21,13 +21,13 @@
 ]]></programlisting> This is much simpler than wiring up the equivalent Apache Directory Server
       beans. The most common alternative configuration requirements are supported by attributes on
       the <literal>ldap-server</literal> element and the user is isolated from worrying about which
-      beans they need to create and what the bean property names are. <footnote><para>You can find out
-          more about the use of the <literal>ldap-server</literal> element in the chapter on <link
-            xlink:href="#ldap">LDAP</link>.</para></footnote>. Use of a good XML editor while
-      editing the application context file should provide information on the attributes and elements
-      that are available. We would recommend that you try out the <link
-        xlink:href="http://www.springsource.com/products/sts">SpringSource Tool Suite</link> as it
-      has special features for working with standard Spring namespaces. </para>
+      beans they need to create and what the bean property names are. <footnote>
+        <para>You can find out more about the use of the <literal>ldap-server</literal> element in
+          the chapter on <link xlink:href="#ldap">LDAP</link>.</para>
+      </footnote>. Use of a good XML editor while editing the application context file should
+      provide information on the attributes and elements that are available. We would recommend that
+      you try out the <link xlink:href="http://www.springsource.com/products/sts">SpringSource Tool
+        Suite</link> as it has special features for working with standard Spring namespaces. </para>
     <para> To start using the security namespace in your application context, all you need to do is
       add the schema declaration to your application context file: <programlisting language="xml">
   <![CDATA[
@@ -61,28 +61,44 @@
       <para> The namespace is designed to capture the most common uses of the framework and provide
         a simplified and concise syntax for enabling them within an application. The design is based
         around the large-scale dependencies within the framework, and can be divided up into the
-        following areas: <itemizedlist><listitem><para>
+        following areas: <itemizedlist>
+          <listitem>
+            <para>
               <emphasis>Web/HTTP Security</emphasis> - the most complex part. Sets up the filters
               and related service beans used to apply the framework authentication mechanisms, to
-              secure URLs, render login and error pages and much
-              more.</para></listitem><listitem><para>
+              secure URLs, render login and error pages and much more.</para>
+          </listitem>
+          <listitem>
+            <para>
               <emphasis>Business Object (Method) Security</emphasis> - options for securing the
-              service layer.</para></listitem><listitem><para>
+              service layer.</para>
+          </listitem>
+          <listitem>
+            <para>
               <emphasis>AuthenticationManager</emphasis> - handles authentication requests from
-              other parts of the framework.</para></listitem><listitem><para>
+              other parts of the framework.</para>
+          </listitem>
+          <listitem>
+            <para>
               <emphasis>AccessDecisionManager</emphasis> - provides access decisions for web and
               method security. A default one will be registered, but you can also choose to use a
-              custom one, declared using normal Spring bean
-              syntax.</para></listitem><listitem><para>
+              custom one, declared using normal Spring bean syntax.</para>
+          </listitem>
+          <listitem>
+            <para>
               <emphasis>AuthenticationProvider</emphasis>s - mechanisms against which the
               authentication manager authenticates users. The namespace provides supports for
               several standard options and also a means of adding custom beans declared using a
-              traditional syntax. </para></listitem><listitem><para>
+              traditional syntax. </para>
+          </listitem>
+          <listitem>
+            <para>
               <emphasis>UserDetailsService</emphasis> - closely related to authentication providers,
-              but often also required by other beans.</para></listitem>
+              but often also required by other beans.</para>
+          </listitem>
           <!-- todo: diagram and link to other sections which describe the interfaces -->
         </itemizedlist></para>
-      <para>We'll see how these work together in the following sections.</para>
+      <para>We'll see how to configure these in the following sections.</para>
     </section>
   </section>
   <section xml:id="ns-getting-started">
@@ -91,8 +107,8 @@
       of the main features of the framework. Let's assume you initially want to get up and running
       as quickly as possible and add authentication support and access control to an existing web
       application, with a few test logins. Then we'll look at how to change over to authenticating
-      against a database or other security information repository. In later sections we'll introduce
-      more advanced namespace configuration options. </para>
+      against a database or other security repository. In later sections we'll introduce more
+      advanced namespace configuration options. </para>
     <section xml:id="ns-web-xml">
       <title><literal>web.xml</literal> Configuration</title>
       <para> The first thing you need to do is add the following filter declaration to your
@@ -124,12 +140,28 @@
   </http>
   ]]>
 </programlisting> Which says that we want all URLs within our application to be secured,
-        requiring the role <literal>ROLE_USER</literal> to access them.</para>
+        requiring the role <literal>ROLE_USER</literal> to access them. The
+          <literal>&lt;http></literal> element is the parent for all web-related namespace
+        functionality. The <literal>&lt;intercept-url></literal> element defines a
+          <literal>pattern</literal> which is matched against the URLs of incoming requests using an
+        ant path style syntax. The <literal>access</literal> attribute defines the access
+        requirements for requests matching the given pattern. With the default configuration, this
+        is typically a comma-separated list of roles, one of which a user must have to be allowed to
+        make the request. Access-control in Spring Security is not limited to the use of simple
+        roles, however, and we'll see later how the interpretation can vary<footnote>
+          <para>The interpretation of the comma-separated values in the <literal>access</literal>
+            attribute depends on the implementation of the <link xlink:href="#ns-access-manager"
+              >AccessDecisionManager</link> which is used. In Spring Security 3.0, the attribute can
+            also be populated with an <link xlink:href="#el-access">EL expression</link>.</para>
+        </footnote>.</para>
       <note>
         <para>You can use multiple <literal>&lt;intercept-url&gt;</literal> elements to define
           different access requirements for different sets of URLs, but they will be evaluated in
           the order listed and the first match will be used. So you must put the most specific
-          matches at the top.</para>
+          matches at the top. You can also add a <literal>method</literal> attribute to limit the
+          match to a particular HTTP method (<literal>GET</literal>, <literal>POST</literal>,
+            <literal>PUT</literal> etc.). For a pattern defined both with and without a method, the
+          method-specific match will take precedence regardless of ordering. </para>
       </note>
       <para> To add some users, you can define a set of test data directly in the namespace: <programlisting language="xml"><![CDATA[
   <authentication-manager>
@@ -144,10 +176,10 @@
         </programlisting></para>
       <sidebar>
         <para>If you are familiar with pre-namespace versions of the framework, you can probably
-          already guess roughly what's going on here. The &lt;http&gt; element is responsible for
-          creating a <classname>FilterChainProxy</classname> and the filter beans which it uses.
-          Common issues like incorrect filter ordering are no longer an issue as the filter
-          positions are predefined.</para>
+          already guess roughly what's going on here. The <literal>&lt;http&gt;</literal> element is
+          responsible for creating a <classname>FilterChainProxy</classname> and the filter beans
+          which it uses. Common problems like incorrect filter ordering are no longer an issue as
+          the filter positions are predefined.</para>
         <para>The <literal>&lt;authentication-provider&gt;</literal> element creates a
             <classname>DaoAuthenticationProvider</classname> bean and the
             <literal>&lt;user-service&gt;</literal> element creates an
@@ -185,14 +217,15 @@
     <logout />
   </http>
   ]]></programlisting> These other elements are responsible for setting up form-login, basic
-          authentication and logout handling services respectively <footnote><para>In versions prior
-              to 3.0, this list also included remember-me functionality. This could cause some
-              confusing errors with some configurations and was removed in 3.0. In 3.0, the addition
-              of an <classname>AnonymousAuthenticationFilter</classname> is part of the default
-                <literal>&lt;http></literal> configuration, so the <literal>&lt;anonymous
-                /></literal> element is added regardless of whether <literal>auto-config</literal>
-              is enabled.</para></footnote> . They each have attributes which can be used to alter
-          their behaviour. </para>
+          authentication and logout handling services respectively <footnote>
+            <para>In versions prior to 3.0, this list also included remember-me functionality. This
+              could cause some confusing errors with some configurations and was removed in 3.0. In
+              3.0, the addition of an <classname>AnonymousAuthenticationFilter</classname> is part
+              of the default <literal>&lt;http></literal> configuration, so the
+                <literal>&lt;anonymous /></literal> element is added regardless of whether
+                <literal>auto-config</literal> is enabled.</para>
+          </footnote> . They each have attributes which can be used to alter their behaviour.
+        </para>
       </section>
       <section xml:id="ns-form-and-basic">
         <title>Form and Basic Login Options</title>
@@ -213,13 +246,16 @@
         </programlisting> Note that you can still use <literal>auto-config</literal>. The
             <literal>form-login</literal> element just overrides the default settings. Also note
           that we've added an extra <literal>intercept-url</literal> element to say that any
-          requests for the login page should be available to anonymous users <footnote><para>See the
-              chapter on <link xlink:href="#anonymous">anonymous authentication</link> for more
-              details.</para></footnote>. Otherwise the request would be matched by the pattern
-            <literal>/**</literal> and it wouldn't be possible to access the login page itself! This
-          is a common configuration error and will result in an infinite loop in the application.
-          Spring Security will emit a warning in the log if your login page appears to be secured.
-          It is also possible to have all requests matching a particular pattern bypass the security
+          requests for the login page should be available to anonymous users <footnote>
+            <para>See the chapter on <link xlink:href="#anonymous">anonymous authentication</link>
+              and also the <link xlink:href="#authz-authenticated-voter">AuthenticatedVoter</link>
+              class for more details on how the value
+                <literal>IS_AUTHENTICATED_ANONYMOUSLY</literal> is processed.</para>
+          </footnote>. Otherwise the request would be matched by the pattern <literal>/**</literal>
+          and it wouldn't be possible to access the login page itself! This is a common
+          configuration error and will result in an infinite loop in the application. Spring
+          Security will emit a warning in the log if your login page appears to be secured. It is
+          also possible to have all requests matching a particular pattern bypass the security
           filter chain completely: <programlisting language="xml"><![CDATA[
   <http auto-config='true'>
     <intercept-url pattern="/css/**" filters="none"/>  
@@ -228,9 +264,12 @@
     <form-login login-page='/login.jsp'/>
   </http>
   ]]>
-          </programlisting> Note that these requests will be completely oblivious to Spring
-          Security, so you will not be able to access information on the current user or call
-          secured methods during the request. </para>
+          </programlisting>It's important to realise that these requests will be completely
+          oblivious to any further Spring Security web-related configuration or additional
+          attributes such as <literal>requires-channel</literal>, so you will not be able to access
+          information on the current user or call secured methods during the request. Use
+            <literal>access='IS_AUTHENTICATED_ANONYMOUSLY'</literal> as an alternative if you still
+          want the security filter chain to be applied.</para>
         <para>If you want to use basic authentication instead of form login, then change the
           configuration to <programlisting language="xml"><![CDATA[
   <http auto-config='true'>
@@ -282,7 +321,7 @@
     </authentication-provider>
   </authentication-manager>
   ]]>
-        </programlisting> Where "securityDataSource" is the name of a
+        </programlisting> Where <quote>securityDataSource</quote> is the name of a
           <classname>DataSource</classname> bean in the application context, pointing at a database
         containing the standard Spring Security <link xlink:href="#db_schema_users_authorities">user
           data tables</link>. Alternatively, you could configure a Spring Security
@@ -437,14 +476,20 @@
           logs in. If you don't require this protection, or it conflicts with some other
           requirement, you can control the behaviour using the
             <literal>session-fixation-protection</literal> attribute on
-            <literal>&lt;session-management&gt;</literal>, which has three options
-                  <itemizedlist><listitem><para><literal>migrateSession</literal> - creates a new
-                session and copies the existing session attributes to the new session. This is the
-                default.</para></listitem><listitem><para><literal>none</literal> - Don't do
-                anything. The original session will be
-                  retained.</para></listitem><listitem><para><literal>newSession</literal> - Create
-                a new "clean" session, without copying the existing session
-            data.</para></listitem></itemizedlist></para>
+            <literal>&lt;session-management&gt;</literal>, which has three options <itemizedlist>
+            <listitem>
+              <para><literal>migrateSession</literal> - creates a new session and copies the
+                existing session attributes to the new session. This is the default.</para>
+            </listitem>
+            <listitem>
+              <para><literal>none</literal> - Don't do anything. The original session will be
+                retained.</para>
+            </listitem>
+            <listitem>
+              <para><literal>newSession</literal> - Create a new "clean" session, without copying
+                the existing session data.</para>
+            </listitem>
+          </itemizedlist></para>
       </section>
     </section>
     <section xml:id="ns-openid">
@@ -481,48 +526,112 @@
       <para>The order of the filters is always strictly enforced when using the namespace. When the
         application context is being created, the filter beans are sorted by the namespace handling
         code and the standard Spring Security filters each have an alias in the namespace and a
-        well-known position.<note><para>In previous versions, the sorting took place after the
-            filter instances had been created, during post-processing of the application context. In
-            version 3.0+ the sorting is now done at the bean metadata level, before the classes have
-            been instantiated. This has implications for how you add your own filters to the stack
-            as the entire filter list must be known during the parsing of the
-              <literal>&lt;http></literal> element, so the syntax has changed slightly in
-            3.0.</para></note>The filters, aliases and namespace elements/attributes which create
-        the filters are shown in <xref linkend="filter-stack"/>. The filters are listed in the order
-        in which they occur in the filter chain. <table xml:id="filter-stack"><title>Standard Filter
-            Aliases and Ordering</title><tgroup cols="3" align="left"><thead><row><entry
-                  align="center">Alias</entry><entry align="center">Filter Class</entry><entry
-                  align="center">Namespace Element or
-                  Attribute</entry></row></thead><tbody><row><entry>
-                    CHANNEL_FILTER</entry><entry><literal>ChannelProcessingFilter</literal></entry><entry><literal>http/intercept-url@requires-channel</literal></entry></row><row><entry>
-                  CONCURRENT_SESSION_FILTER</entry><entry><literal>ConcurrentSessionFilter</literal>
-                </entry><entry><literal>session-management/concurrency-control</literal></entry></row><row><entry>
-                  SECURITY_CONTEXT_FILTER</entry><entry><classname>SecurityContextPersistenceFilter</classname></entry><entry><literal>http</literal></entry></row><row><entry>
-                  LOGOUT_FILTER
-                    </entry><entry><literal>LogoutFilter</literal></entry><entry><literal>http/logout</literal></entry></row><row><entry>
-                  X509_FILTER
-                    </entry><entry><literal>X509AuthenticationFilter</literal></entry><entry><literal>http/x509</literal></entry></row><row><entry>
-                  PRE_AUTH_FILTER
-                    </entry><entry><literal>AstractPreAuthenticatedProcessingFilter</literal>
-                  Subclasses</entry><entry>N/A</entry></row><row><entry> CAS_FILTER
-                    </entry><entry><literal>CasAuthenticationFilter</literal></entry><entry>N/A</entry></row><row><entry>
-                  FORM_LOGIN_FILTER
-                    </entry><entry><literal>UsernamePasswordAuthenticationFilter</literal></entry><entry><literal>http/form-login</literal></entry></row><row><entry>
-                  BASIC_AUTH_FILTER
-                  </entry><entry><literal>BasicAuthenticationFilter</literal></entry><entry><literal>http/http-basic</literal></entry></row><row><entry>
-                  SERVLET_API_SUPPORT_FILTER</entry><entry><literal>SecurityContextHolderAwareFilter</literal></entry><entry><literal>http/@servlet-api-provision</literal></entry></row><row><entry>
-                  REMEMBER_ME_FILTER
-                    </entry><entry><classname>RememberMeAuthenticationFilter</classname></entry><entry><literal>http/remember-me</literal></entry></row><row><entry>
-                  ANONYMOUS_FILTER
-                  </entry><entry><literal>AnonymousAuthenticationFilter</literal></entry><entry><literal>http/anonymous</literal></entry></row><row><entry>
-                  SESSION_MANAGEMENT_FILTER</entry><entry><literal>SessionManagementFilter</literal></entry><entry><literal>session-management</literal></entry></row><row><entry>EXCEPTION_TRANSLATION_FILTER
-                    </entry><entry><classname>ExceptionTranslationFilter</classname></entry><entry><literal>http</literal></entry></row><row><entry>
-                  FILTER_SECURITY_INTERCEPTOR
-                    </entry><entry><classname>FilterSecurityInterceptor</classname></entry><entry><literal>http</literal></entry></row><row><entry>
-                  SWITCH_USER_FILTER
-                  </entry><entry><literal>SwitchUserFilter</literal></entry><entry>N/A</entry></row></tbody></tgroup></table>
-        You can add your own filter to the stack, using the <literal>custom-filter</literal> element
-        and one of these names to specify the position your filter should appear at: <programlisting language="xml"><![CDATA[
+        well-known position.<note>
+          <para>In previous versions, the sorting took place after the filter instances had been
+            created, during post-processing of the application context. In version 3.0+ the sorting
+            is now done at the bean metadata level, before the classes have been instantiated. This
+            has implications for how you add your own filters to the stack as the entire filter list
+            must be known during the parsing of the <literal>&lt;http></literal> element, so the
+            syntax has changed slightly in 3.0.</para>
+        </note>The filters, aliases and namespace elements/attributes which create the filters are
+        shown in <xref linkend="filter-stack"/>. The filters are listed in the order in which they
+        occur in the filter chain. <table xml:id="filter-stack">
+          <title>Standard Filter Aliases and Ordering</title>
+          <tgroup cols="3" align="left">
+            <thead>
+              <row>
+                <entry align="center">Alias</entry>
+                <entry align="center">Filter Class</entry>
+                <entry align="center">Namespace Element or Attribute</entry>
+              </row>
+            </thead>
+            <tbody>
+              <row>
+                <entry> CHANNEL_FILTER</entry>
+                <entry><literal>ChannelProcessingFilter</literal></entry>
+                <entry><literal>http/intercept-url@requires-channel</literal></entry>
+              </row>
+              <row>
+                <entry> CONCURRENT_SESSION_FILTER</entry>
+                <entry><literal>ConcurrentSessionFilter</literal>
+                </entry>
+                <entry><literal>session-management/concurrency-control</literal></entry>
+              </row>
+              <row>
+                <entry> SECURITY_CONTEXT_FILTER</entry>
+                <entry><classname>SecurityContextPersistenceFilter</classname></entry>
+                <entry><literal>http</literal></entry>
+              </row>
+              <row>
+                <entry> LOGOUT_FILTER </entry>
+                <entry><literal>LogoutFilter</literal></entry>
+                <entry><literal>http/logout</literal></entry>
+              </row>
+              <row>
+                <entry> X509_FILTER </entry>
+                <entry><literal>X509AuthenticationFilter</literal></entry>
+                <entry><literal>http/x509</literal></entry>
+              </row>
+              <row>
+                <entry> PRE_AUTH_FILTER </entry>
+                <entry><literal>AstractPreAuthenticatedProcessingFilter</literal> Subclasses</entry>
+                <entry>N/A</entry>
+              </row>
+              <row>
+                <entry> CAS_FILTER </entry>
+                <entry><literal>CasAuthenticationFilter</literal></entry>
+                <entry>N/A</entry>
+              </row>
+              <row>
+                <entry> FORM_LOGIN_FILTER </entry>
+                <entry><literal>UsernamePasswordAuthenticationFilter</literal></entry>
+                <entry><literal>http/form-login</literal></entry>
+              </row>
+              <row>
+                <entry> BASIC_AUTH_FILTER </entry>
+                <entry><literal>BasicAuthenticationFilter</literal></entry>
+                <entry><literal>http/http-basic</literal></entry>
+              </row>
+              <row>
+                <entry> SERVLET_API_SUPPORT_FILTER</entry>
+                <entry><literal>SecurityContextHolderAwareFilter</literal></entry>
+                <entry><literal>http/@servlet-api-provision</literal></entry>
+              </row>
+              <row>
+                <entry> REMEMBER_ME_FILTER </entry>
+                <entry><classname>RememberMeAuthenticationFilter</classname></entry>
+                <entry><literal>http/remember-me</literal></entry>
+              </row>
+              <row>
+                <entry> ANONYMOUS_FILTER </entry>
+                <entry><literal>AnonymousAuthenticationFilter</literal></entry>
+                <entry><literal>http/anonymous</literal></entry>
+              </row>
+              <row>
+                <entry> SESSION_MANAGEMENT_FILTER</entry>
+                <entry><literal>SessionManagementFilter</literal></entry>
+                <entry><literal>session-management</literal></entry>
+              </row>
+              <row>
+                <entry>EXCEPTION_TRANSLATION_FILTER </entry>
+                <entry><classname>ExceptionTranslationFilter</classname></entry>
+                <entry><literal>http</literal></entry>
+              </row>
+              <row>
+                <entry> FILTER_SECURITY_INTERCEPTOR </entry>
+                <entry><classname>FilterSecurityInterceptor</classname></entry>
+                <entry><literal>http</literal></entry>
+              </row>
+              <row>
+                <entry> SWITCH_USER_FILTER </entry>
+                <entry><literal>SwitchUserFilter</literal></entry>
+                <entry>N/A</entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </table> You can add your own filter to the stack, using the
+          <literal>custom-filter</literal> element and one of these names to specify the position
+        your filter should appear at: <programlisting language="xml"><![CDATA[
   <http>
      <custom-filter position="FORM_LOGIN_FILTER" ref="myFilter" />
   </http>
@@ -569,10 +678,10 @@
     <para>From version 2.0 onwards Spring Security has improved support substantially for adding
       security to your service layer methods. It provides support for JSR-250 security as well as
       the framework's original <literal>@Secured</literal> annotation. From 3.0 you can also make
-      use of new <link xlink:href="el-access">expression-based annotations</link>. 
-      You can apply security to a single bean, using the
-        <literal>intercept-methods</literal> element to decorate the bean declaration, or you can
-      secure multiple beans across the entire service layer using the AspectJ style pointcuts. </para>
+      use of new <link xlink:href="el-access">expression-based annotations</link>. You can apply
+      security to a single bean, using the <literal>intercept-methods</literal> element to decorate
+      the bean declaration, or you can secure multiple beans across the entire service layer using
+      the AspectJ style pointcuts. </para>
     <section xml:id="ns-global-method">
       <title>The <literal>&lt;global-method-security&gt;</literal> Element</title>
       <para> This element is used to enable annotation-based security in your application (by
@@ -639,7 +748,7 @@
     <para> This section assumes you have some knowledge of the underlying architecture for
       access-control within Spring Security. If you don't you can skip it and come back to it later,
       as this section is only really relevant for people who need to do some customization in order
-      to use more than simple role based security. </para>
+      to use more than simple role-based security. </para>
     <para> When you use a namespace configuration, a default instance of
         <interfacename>AccessDecisionManager</interfacename> is automatically registered for you and
       will be used for making access decisions for method invocations and web URL access, based on
@@ -648,7 +757,8 @@
       annotation secured methods). </para>
     <para> The default strategy is to use an <classname>AffirmativeBased</classname>
       <interfacename>AccessDecisionManager</interfacename> with a <classname>RoleVoter</classname>
-      and an <classname>AuthenticatedVoter</classname>. </para>
+      and an <classname>AuthenticatedVoter</classname>. You can find out more about these in the
+      chapter on <link xlink:href="authorization">authorization</link>.</para>
     <section xml:id="ns-custom-access-mgr">
       <title>Customizing the AccessDecisionManager</title>
       <para> If you need to use a more complicated access control strategy then it is easy to set an
@@ -694,9 +804,9 @@
   </bean>
   ]]></programlisting></para>
     <para> Another common requirement is that another bean in the context may require a reference to
-      the <interfacename>AuthenticationManager</interfacename>. You can easily
-      register an alias for the <interfacename>AuthenticationManager</interfacename> and
-      use this name elsewhere in your application context. <programlisting language="xml"><![CDATA[        
+      the <interfacename>AuthenticationManager</interfacename>. You can easily register an alias for
+      the <interfacename>AuthenticationManager</interfacename> and use this name elsewhere in your
+      application context. <programlisting language="xml"><![CDATA[        
   <security:authentication-manager alias="authenticationManager"> 
      ...
   </security:authentication-manager>

docs/manual/src/docbook/remember-me-authentication.xml

@@ -46,7 +46,7 @@
             more significant security is needed you should use the approach described in the next
             section. Alternatively remember-me services should simply not be used at all.</para>
         <para>If you are familiar with the topics discussed in the chapter on <link
-                xlink:href="ns-config">namespace configuration</link>, you can enable remember-me
+                xlink:href="#ns-config">namespace configuration</link>, you can enable remember-me
             authentication just by adding the <literal>&lt;remember-me&gt;</literal> element: <programlisting><![CDATA[
   <http>
     ...
@@ -64,11 +64,12 @@
         <para>This approach is based on the article <link
                 xlink:href="http://jaspan.com/improved_persistent_login_cookie_best_practice"
                 >http://jaspan.com/improved_persistent_login_cookie_best_practice</link> with some
-            minor modifications <footnote><para>Essentially, the username is not included in the
-                    cookie, to prevent exposing a valid login name unecessarily. There is a
-                    discussion on this in the comments section of this article.</para></footnote>.
-            To use the this approach with namespace configuration, you would supply a datasource
-            reference: <programlisting><![CDATA[
+            minor modifications <footnote>
+                <para>Essentially, the username is not included in the cookie, to prevent exposing a
+                    valid login name unecessarily. There is a discussion on this in the comments
+                    section of this article.</para>
+            </footnote>. To use the this approach with namespace configuration, you would supply a
+            datasource reference: <programlisting><![CDATA[
   <http>
     ...
     <remember-me data-source-ref="someDataSource"/>
@@ -161,12 +162,16 @@
             <para> This class can be used in the same way as
                     <classname>TokenBasedRememberMeServices</classname>, but it additionally needs
                 to be configured with a <interfacename>PersistentTokenRepository</interfacename> to
-                store the tokens. There are two standard implementations.
-                                <itemizedlist><listitem><para><classname>InMemoryTokenRepositoryImpl</classname>
-                            which is intended for testing
-                                only.</para></listitem><listitem><para><classname>JdbcTokenRepositoryImpl</classname>
-                            which stores the tokens in a database. </para></listitem></itemizedlist>
-                The database schema is described above in <xref
+                store the tokens. There are two standard implementations. <itemizedlist>
+                    <listitem>
+                        <para><classname>InMemoryTokenRepositoryImpl</classname> which is intended
+                            for testing only.</para>
+                    </listitem>
+                    <listitem>
+                        <para><classname>JdbcTokenRepositoryImpl</classname> which stores the tokens
+                            in a database. </para>
+                    </listitem>
+                </itemizedlist> The database schema is described above in <xref
                     linkend="remember-me-persistent-token"/>. </para>
         </section>
     </section>

docs/manual/src/docbook/springsecurity.xml

@@ -1,12 +1,14 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <book version="5.0" xml:id="spring-security-reference-guide" xmlns="http://docbook.org/ns/docbook"
   xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
-  <info><title>Spring Security</title><subtitle>Reference
-        Documentation</subtitle><authorgroup><author>
+  <info><title>Spring Security</title><subtitle>Reference Documentation</subtitle><authorgroup>
+      <author>
         <personname>Ben Alex</personname>
-      </author><author>
+      </author>
+      <author>
         <personname>Luke Taylor</personname>
-      </author></authorgroup>
+      </author>
+    </authorgroup>
     <productname>Spring Security</productname>
     <releaseinfo>3.0.0.RC2</releaseinfo>
   </info>
@@ -77,9 +79,9 @@
       <para> We'll also take a look at the sample applications that are available. It's worth trying
         to run these and experimenting with them a bit even before you read the later sections - you
         can dip back into them as your understanding of the framework increases. Please also check
-        out the <link xlink:href="http://static.springsource.org/spring-security/site/index.html">project website</link> as
-        it has useful information on building the project, plus links to articles, videos and tutorials.
-      </para>
+        out the <link xlink:href="http://static.springsource.org/spring-security/site/index.html"
+          >project website</link> as it has useful information on building the project, plus links
+        to articles, videos and tutorials. </para>
     </partintro>
     <xi:include href="introduction.xml"/>
     <xi:include href="namespace-config.xml"/>

docs/manual/src/docbook/technical-overview.xml

@@ -189,31 +189,50 @@ if (principal instanceof UserDetails) {
       own proprietary authentication system. </para>
     <section>
       <title>What is authentication in Spring Security?</title>
-      <para> Let's consider a standard authentication scenario that everyone is familiar with.
-              <orderedlist><listitem><para>A user is prompted to log in with a username and
-              password.</para></listitem><listitem><para>The system (successfully) verifies that the
-              password is correct for the username.</para></listitem><listitem><para>The context
-              information for that user is obtained (their list of roles and so
-            on).</para></listitem><listitem><para>A security context is established for the
-              user</para></listitem><listitem><para>The user proceeds, potentially to perform some
-              operation which is potentially protected by an access control mechanism which checks
-              the required permissions for the operation against the current security context
-              information. </para></listitem></orderedlist> The first three items constitute the
-        authentication process so we'll take a look at how these take place within Spring
-              Security.<orderedlist><listitem><para>The username and password are obtained and
-              combined into an instance of
+      <para> Let's consider a standard authentication scenario that everyone is familiar with. <orderedlist>
+          <listitem>
+            <para>A user is prompted to log in with a username and password.</para>
+          </listitem>
+          <listitem>
+            <para>The system (successfully) verifies that the password is correct for the
+              username.</para>
+          </listitem>
+          <listitem>
+            <para>The context information for that user is obtained (their list of roles and so
+              on).</para>
+          </listitem>
+          <listitem>
+            <para>A security context is established for the user</para>
+          </listitem>
+          <listitem>
+            <para>The user proceeds, potentially to perform some operation which is potentially
+              protected by an access control mechanism which checks the required permissions for the
+              operation against the current security context information. </para>
+          </listitem>
+        </orderedlist> The first three items constitute the authentication process so we'll take a
+        look at how these take place within Spring Security.<orderedlist>
+          <listitem>
+            <para>The username and password are obtained and combined into an instance of
                 <classname>UsernamePasswordAuthenticationToken</classname> (an instance of the
                 <interfacename>Authentication</interfacename> interface, which we saw
-              earlier).</para></listitem><listitem><para>The token is passed to an instance of
-                <interfacename>AuthenticationManager</interfacename> for
-            validation.</para></listitem><listitem><para>The
-                <interfacename>AuthenticationManager</interfacename> returns a fully populated
+              earlier).</para>
+          </listitem>
+          <listitem>
+            <para>The token is passed to an instance of
+                <interfacename>AuthenticationManager</interfacename> for validation.</para>
+          </listitem>
+          <listitem>
+            <para>The <interfacename>AuthenticationManager</interfacename> returns a fully populated
                 <interfacename>Authentication</interfacename> instance on successful
-              authentication.</para></listitem><listitem><para>The security context is established
-              by calling <code>SecurityContextHolder.getContext().setAuthentication(...)</code>,
-              passing in the returned authentication object.</para></listitem></orderedlist>From
-        that point on, the user is considered to be authenticated. Let's look at some code as an
-        example.
+              authentication.</para>
+          </listitem>
+          <listitem>
+            <para>The security context is established by calling
+                <code>SecurityContextHolder.getContext().setAuthentication(...)</code>, passing in
+              the returned authentication object.</para>
+          </listitem>
+        </orderedlist>From that point on, the user is considered to be authenticated. Let's look at
+        some code as an example.
         <programlisting language="java">import org.springframework.security.authentication.*;
 import org.springframework.security.core.*;
 import org.springframework.security.core.authority.GrantedAuthorityImpl;
@@ -484,17 +503,29 @@ Successfully authenticated. Security context contains: \
           <interfacename>Authentication</interfacename> if the principal has been
         authenticated.</para>
       <para><classname>AbstractSecurityInterceptor</classname> provides a consistent workflow for
-        handling secure object requests, typically: <orderedlist><listitem><para>Look up the
-                <quote>configuration attributes</quote> associated with the present
-            request</para></listitem><listitem><para>Submitting the secure object, current
+        handling secure object requests, typically: <orderedlist>
+          <listitem>
+            <para>Look up the <quote>configuration attributes</quote> associated with the present
+              request</para>
+          </listitem>
+          <listitem>
+            <para>Submitting the secure object, current
                 <interfacename>Authentication</interfacename> and configuration attributes to the
                 <interfacename>AccessDecisionManager</interfacename> for an authorization
-              decision</para></listitem><listitem><para>Optionally change the
-                <interfacename>Authentication</interfacename> under which the invocation takes
-              place</para></listitem><listitem><para>Allow the secure object invocation to proceed
-              (assuming access was granted)</para></listitem><listitem><para>Call the
-                <interfacename>AfterInvocationManager</interfacename> if configured, once the
-              invocation has returned.</para></listitem></orderedlist></para>
+              decision</para>
+          </listitem>
+          <listitem>
+            <para>Optionally change the <interfacename>Authentication</interfacename> under which
+              the invocation takes place</para>
+          </listitem>
+          <listitem>
+            <para>Allow the secure object invocation to proceed (assuming access was granted)</para>
+          </listitem>
+          <listitem>
+            <para>Call the <interfacename>AfterInvocationManager</interfacename> if configured, once
+              the invocation has returned.</para>
+          </listitem>
+        </orderedlist></para>
       <section xml:id="tech-intro-config-attributes">
         <title>What are Configuration Attributes?</title>
         <para> A <quote>configuration attribute</quote> can be thought of as a String that has
@@ -507,8 +538,16 @@ Successfully authenticated. Security context contains: \
             <interfacename>SecurityMetadataSource</interfacename> which it uses to look up the
           attributes for a secure object. Usually this configuration will be hidden from the user.
           Configuration attributes will be entered as annotations on secured methods or as access
-          attributes on secured URLs (using the namespace <literal>&lt;intercept-url&gt;</literal>
-          syntax).</para>
+          attributes on secured URLs. For example, when we saw something like
+            <literal>&lt;intercept-url pattern='/secure/**' access='ROLE_A,ROLE_B'/></literal> in
+          the namespace introduction, this is saying that the configuration attributes
+            <literal>ROLE_A</literal> and <literal>ROLE_B</literal> apply to web requests matching
+          the given pattern. In practice, with the default
+            <interfacename>AccessDecisionManager</interfacename> configuration, this means that
+          anyone who has a <interfacename>GrantedAuthority</interfacename> matching either of these
+          two attributes will be allowed access. Strictly speaking though, they are just attributes
+          and the interpretation is dependent on the
+            <interfacename>AccessDecisionManager</interfacename> implementation.</para>
       </section>
       <section>
         <title>RunAsManager</title>
@@ -539,10 +578,14 @@ Successfully authenticated. Security context contains: \
           or not change it in any way as it chooses.</para>
         <para><classname>AbstractSecurityInterceptor</classname> and its related objects are shown
           in <xref linkend="abstract-security-interceptor"/>. <figure
-            xml:id="abstract-security-interceptor"><title>Security interceptors and the
-                <quote>secure object</quote> model</title><mediaobject><imageobject>
+            xml:id="abstract-security-interceptor">
+            <title>Security interceptors and the <quote>secure object</quote> model</title>
+            <mediaobject>
+              <imageobject>
                 <imagedata align="center" fileref="images/security-interception.png" format="PNG"/>
-              </imageobject></mediaobject></figure></para>
+              </imageobject>
+            </mediaobject>
+          </figure></para>
       </section>
       <section>
         <title>Extending the Secure Object Model</title>

docs/manual/src/xsl/html-custom.xsl

@@ -41,11 +41,11 @@
 <!-- Activate Graphics -->
 	<xsl:param name="admon.graphics" select="1"/>
 	<xsl:param name="admon.graphics.path">images/</xsl:param>
-	<xsl:param name="admon.graphics.extension">.gif</xsl:param>
+	<xsl:param name="admon.graphics.extension">.png</xsl:param>
 	<xsl:param name="callout.graphics" select="1" />
 	<xsl:param name="callout.defaultcolumn">120</xsl:param>
 	<xsl:param name="callout.graphics.path">images/callouts/</xsl:param>
-	<xsl:param name="callout.graphics.extension">.gif</xsl:param>
+	<xsl:param name="callout.graphics.extension">.png</xsl:param>
 
 	<xsl:param name="table.borders.with.css" select="1"/>
 	<xsl:param name="html.stylesheet">css/manual.css</xsl:param>

docs/manual/src/xsl/pdf-custom.xsl

@@ -28,8 +28,8 @@
 	<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/fo/highlight.xsl"/>
 
 	<xsl:param name="admon.graphics">'1'</xsl:param>
-	<xsl:param name="admon.graphics.path">images/</xsl:param>
-	<xsl:param name="draft.watermark.image" select="'images/draft.png'"/>
+	<xsl:param name="admon.graphics.path">src/docbook/images/</xsl:param>
+	<!-- xsl:param name="draft.watermark.image" select="'images/draft.png'"/ -->
 	<xsl:param name="paper.type" select="'A4'"/>
 
 	<xsl:param name="page.margin.top" select="'1cm'"/>