OPEN - issue SEC-881: PreAuthenticatedFilter continues filter chain after unsuccessfulAuthentication(...)

http://jira.springframework.org/browse/SEC-881. Updated Javadoc.

core/src/main/java/org/springframework/security/ui/preauth/AbstractPreAuthenticatedProcessingFilter.java

@@ -25,6 +25,13 @@ import org.springframework.util.Assert;
 /**
  * Base class for processing filters that handle pre-authenticated authentication requests. Subclasses must implement
  * the getPreAuthenticatedPrincipal() and getPreAuthenticatedCredentials() methods.
+ * <p>
+ * By default, the filter chain will proceed when an authentication attempt fails in order to allow other 
+ * authentication mechanisms to process the request. To reject the credentials immediately, set the
+ * <tt>continueFilterChainOnUnsuccessfulAuthentication</tt> flag to false. The exception raised by the
+ * <tt>AuthenticationManager</tt> will the be re-thrown. Note that this will not affect cases where the principal
+ * returned by {@link #getPreAuthenticatedPrincipal} is null, when the chain will still proceed as normal.
+ * 
  *
  * @author Luke Taylor
  * @author Ruud Senden