Javadoc updates.

core/src/main/java/org/springframework/security/authentication/dao/AbstractUserDetailsAuthenticationProvider.java

@@ -59,10 +59,13 @@ import org.springframework.util.Assert;
  * is returned. To override this
  * default, set the {@link #setForcePrincipalAsString} to <code>true</code>.
  * <p>
- * Caching is handled via the <code>UserDetails</code> object being placed in the {@link UserCache}. This
+ * Caching is handled by storing the <code>UserDetails</code> object being placed in the {@link UserCache}. This
  * ensures that subsequent requests with the same username can be validated without needing to query the {@link
  * UserDetailsService}. It should be noted that if a user appears to present an incorrect password, the {@link
- * UserDetailsService} will be queried to confirm the most up-to-date password was used for comparison.</p>
+ * UserDetailsService} will be queried to confirm the most up-to-date password was used for comparison.
+ * Caching is only likely to be required for stateless applications. In a normal web application, for example,
+ * the <tt>SecurityContext</tt> is stored in the user's session and the user isn't reauthenticated on
+ * each request. The default cache implementation is therefore {@link NullUserCache}.
  *
  * @author Ben Alex
  * @version $Id$
@@ -133,7 +136,7 @@ public abstract class AbstractUserDetailsAuthenticationProvider implements Authe
         }
 
         preAuthenticationChecks.check(user);
-        
+
         try {
             additionalAuthenticationChecks(user, (UsernamePasswordAuthenticationToken) authentication);
         } catch (AuthenticationException exception) {
@@ -272,7 +275,7 @@ public abstract class AbstractUserDetailsAuthenticationProvider implements Authe
      * Sets the policy will be used to verify the status of the loaded <tt>UserDetails</tt> <em>before</em>
      * validation of the credentials takes place.
      *
-     * @param preAuthenticationChecks strategy to be invoked prior to authentication. 
+     * @param preAuthenticationChecks strategy to be invoked prior to authentication.
      */
     public void setPreAuthenticationChecks(UserDetailsChecker preAuthenticationChecks) {
         this.preAuthenticationChecks = preAuthenticationChecks;

core/src/main/java/org/springframework/security/core/userdetails/UserCache.java

@@ -16,17 +16,21 @@
 package org.springframework.security.core.userdetails;
 
 
-
 /**
  * Provides a cache of {@link UserDetails} objects.
  *
  * <p>
- * Implementations should provide appropriate methods to set their cache
- * parameters (e.g. time-to-live) and/or force removal of entities before their
- * normal expiration. These are not part of the <code>UserCache</code>
+ * Implementations should provide appropriate methods to set their cache parameters (e.g. time-to-live) and/or force
+ * removal of entities before their normal expiration. These are not part of the <code>UserCache</code>
  * interface contract because they vary depending on the type of caching
  * system used (e.g. in-memory vs disk vs cluster vs hybrid).
- * </p>
+ * <p>
+ * Caching is generally only required in applications which do not maintain server-side state, such as remote clients
+ * or web services. The authentication credentials are then presented on each invocation and the overhead of accessing
+ * a database or other persistent storage mechanism to validate would be excessive. In this case, you would configure
+ * a cache to store the <tt>UserDetails</tt> information rather than loading it each time.
+ *
+ * @see {@link org.springframework.security.authentication.dao.AbstractUserDetailsAuthenticationProvider}
  *
  * @author Ben Alex
  * @version $Id$
@@ -54,9 +58,10 @@ public interface UserCache {
 
     /**
      * Removes the specified user from the cache. The <code>username</code> is the key used to remove the user.
-     * If the user is not found, the method should simply return (not thrown an exception).<P>Some cache
-     * implementations may not support eviction from the cache,  in which case they should provide appropriate
-     * behaviour to alter the user in either its documentation, via an exception, or through a log message.</p>
+     * If the user is not found, the method should simply return (not thrown an exception).
+     * <p>
+     * Some cache implementations may not support eviction from the cache, in which case they should provide appropriate
+     * behaviour to alter the user in either its documentation, via an exception, or through a log message.
      *
      * @param username to be evicted from the cache
      */