SEC-1468: Doc and Javadoc updates.

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

@@ -254,9 +254,11 @@
                 <title><literal>authentication-success-handler-ref</literal></title>
                 <para>This can be used as an alternative to <literal>default-target-url</literal>
                     and <literal>always-use-default-target</literal>, giving you full control over
-                    the navigation flow after a successful authentication. The value should be he
+                    the navigation flow after a successful authentication. The value should be the
                     name of an <interfacename>AuthenticationSuccessHandler</interfacename> bean in
-                    the application context. </para>
+                    the application context. By default, an imlementation of
+                    <classname>SavedRequestAwareAuthenticationSuccessHandler</classname> is used and
+                    injected with the <literal>default-target-url</literal>.</para>
             </section>
             <section>
                 <title><literal>authentication-failure-handler-ref</literal></title>
@@ -431,10 +433,10 @@
             <para> Similar to <literal>&lt;form-login&gt;</literal> and has the same attributes. The
                 default value for <literal>login-processing-url</literal> is
                 "/j_spring_openid_security_check". An
-                    <classname>OpenIDAuthenticationFilter</classname> and
-                    <classname>OpenIDAuthenticationProvider</classname> will be registered. The
-                latter requires a reference to a <interfacename>UserDetailsService</interfacename>.
-                Again, this can be specified by Id, using the <literal>user-service-ref</literal>
+                <classname>OpenIDAuthenticationFilter</classname> and
+                <classname>OpenIDAuthenticationProvider</classname> will be registered. The latter
+                requires a reference to a <interfacename>UserDetailsService</interfacename>. Again,
+                this can be specified by Id, using the <literal>user-service-ref</literal>
                 attribute, or will be located automatically in the application context. </para>
             <section>
                 <title>The <literal>&lt;attribute-exchange></literal> Element</title>

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

@@ -292,7 +292,9 @@ class="org.springframework.security.web.context.SecurityContextPersistenceFilter
                 <classname>SavedRequestAwareAuthenticationSuccessHandler</classname>,
                 <classname>SimpleUrlAuthenticationFailureHandler</classname> and
                 <classname>ExceptionMappingAuthenticationFailureHandler</classname>. Have a look at
-                the Javadoc for these classes to see how they work. </para>
+                the Javadoc for these classes and also for <classname>AbstractAuthenticationProcessingFilter</classname>
+                to get an overview of how they work and the supported features.
+            </para>
             <para>If authentication is successful, the resulting
                 <interfacename>Authentication</interfacename> object will be placed into the
                 <classname>SecurityContextHolder</classname>. The configured

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

@@ -294,8 +294,8 @@
                     <title>Setting a Default Post-Login Destination</title>
                     <para> If a form login isn't prompted by an attempt to access a protected
                         resource, the <literal>default-target-url</literal> option comes into play.
-                        This is the URL the user will be taken to after logging in, and defaults to
-                        "/". You can also configure things so that they user
+                        This is the URL the user will be taken to after successfully logging in, and
+                        defaults to "/". You can also configure things so that the user
                         <emphasis>always</emphasis> ends up at this page (regardless of whether the
                         login was "on-demand" or they explicitly chose to log in) by setting the
                         <literal>always-use-default-target</literal> attribute to "true". This is
@@ -307,8 +307,15 @@
     <form-login login-page='/login.htm' default-target-url='/home.htm'
             always-use-default-target='true' />
   </http>
-  ]]>
-            </programlisting></para>
+  ]]>         </programlisting></para>
+                    <para>For even more control over the destination, you can use the
+                        <literal>authentication-success-handler-ref</literal> attribute as an
+                        alternative to <literal>default-target-url</literal>. The referenced bean
+                        should be an instance of
+                        <interfacename>AuthenticationSuccessHandler</interfacename>. You'll find
+                        more on this in the <link xlink:href="#form-login-flow-handling">Core
+                        Filters</link> chapter and also in the namespace appendix, as well as
+                        information on how to customize the flow when authentication fails. </para>
                 </section>
             </section>
         </section>
@@ -548,27 +555,26 @@
   </attribute-exchange>
  </openid-login>]]></programlisting>The <quote>type</quote> of each OpenID attribute is a URI,
                     determined by a particular schema, in this case <link
-                        xlink:href="http://axschema.org/">http://axschema.org/</link>. If an
-                    attribute must be retrieved for successful authentication, the
-                        <literal>required</literal> attribute can be set. The exact schema and
-                    attributes supported will depend on your OpenID provider. The attribute values
-                    are returned as part of the authentication process and can be accessed
-                    afterwards using the following code:
+                    xlink:href="http://axschema.org/">http://axschema.org/</link>. If an attribute
+                    must be retrieved for successful authentication, the <literal>required</literal>
+                    attribute can be set. The exact schema and attributes supported will depend on
+                    your OpenID provider. The attribute values are returned as part of the
+                    authentication process and can be accessed afterwards using the following code:
                     <programlisting language="java">
 OpenIDAuthenticationToken token = 
     (OpenIDAuthenticationToken)SecurityContextHolder.getContext().getAuthentication();
 List&lt;OpenIDAttribute> attributes = token.getAttributes();</programlisting>The
-                        <classname>OpenIDAttribute</classname> contains the attribute type and the
+                    <classname>OpenIDAttribute</classname> contains the attribute type and the
                     retrieved value (or values in the case of multi-valued attributes). We'll see
                     more about how the <classname>SecurityContextHolder</classname> class is used
                     when we look at core Spring Security components in the <link
-                        xlink:href="core-components">technical overview</link> chapter. Multiple
+                    xlink:href="core-components">technical overview</link> chapter. Multiple
                     attribute exchange configurations are also be supported, if you wish to use
                     multiple identity providers. You can supply multiple
-                        <literal>attribute-exchange</literal> elements, using an
-                        <literal>identifier-matcher</literal> attribute on each. This contains a
-                    regular expression which will be matched against the OpenID identifier supplied
-                    by the user. See the OpenID sample application in the codebase for an example
+                    <literal>attribute-exchange</literal> elements, using an
+                    <literal>identifier-matcher</literal> attribute on each. This contains a regular
+                    expression which will be matched against the OpenID identifier supplied by the
+                    user. See the OpenID sample application in the codebase for an example
                     configuration, providing different attribute lists for the Google, Yahoo and
                     MyOpenID providers.</para>
             </section>

web/src/main/java/org/springframework/security/web/authentication/AbstractAuthenticationTargetUrlRequestHandler.java

@@ -31,7 +31,7 @@ import org.springframework.util.StringUtils;
  * </li>
  * <li>
  * If a parameter matching the <tt>targetUrlParameter</tt> has been set on the request, the value will be used as
- * the destination.
+ * the destination. The default parameter name is {@code spring-security-redirect}.
  * </li>
  * <li>
  * If the <tt>useReferer</tt> property is set, the "Referer" HTTP header value will be used, if present.