SEC-1327: Javadoc additions to clarify some behaviour

web/src/main/java/org/springframework/security/web/authentication/preauth/AbstractPreAuthenticatedProcessingFilter.java

@@ -26,7 +26,12 @@ import org.springframework.web.filter.GenericFilterBean;
 
 /**
  * Base class for processing filters that handle pre-authenticated authentication requests. Subclasses must implement
- * the getPreAuthenticatedPrincipal() and getPreAuthenticatedCredentials() methods.
+ * the {@code getPreAuthenticatedPrincipal()} and {@code getPreAuthenticatedCredentials()} methods.
+ * <p>
+ * If the security context already contains an {@code Authentication} object (either from a invocation of the
+ * filter or because of some other authentication mechanism), the filter will do nothing by default. You can force
+ * it to check for a change in the principal by setting the {@link #setCheckForPrincipalChanges(boolean)
+ * checkForPrincipalChanges} property.
  * <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
@@ -34,7 +39,6 @@ import org.springframework.web.filter.GenericFilterBean;
  * <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
  * @since 2.0

web/src/main/java/org/springframework/security/web/context/HttpSessionSecurityContextRepository.java

@@ -257,8 +257,12 @@ public class HttpSessionSecurityContextRepository implements SecurityContextRepo
     }
 
     /**
-     * If set to true (the default), a new session will be created to store the security context if it is determined
-     * that it's contents are different from the default.
+     * If set to true (the default), a session will be created (if required) to store the security context if it is
+     * determined that its contents are different from the default empty context value.
+     * <p>
+     * Note that setting this flag to false does not prevent this class from storing the security context. If your
+     * application (or another filter) creates a session, then the security context will still be stored for an
+     * authenticated user.
      *
      * @param allowSessionCreation
      */