Improvements to Javadoc.

core/src/main/java/org/springframework/security/Authentication.java

@@ -20,18 +20,26 @@ import java.io.Serializable;
 import java.security.Principal;
 import java.util.List;
 
+import org.springframework.security.context.SecurityContextHolder;
+
 
 /**
- * Represents an authentication request.
+ * Represents the token for an authentication request or for an authenticated principal once the request has been
- *
+ * processed by the {@link AuthenticationManager#authenticate(Authentication)} method.
  * <p>
- * An <code>Authentication</code> object is not considered authenticated until
+ * Once the request has been authenticated, the <tt>Authentication</tt> will usually be stored in a thread-local
- * it is processed by an {@link AuthenticationManager}.
+ * <tt>SecurityContext</tt> managed by the {@link SecurityContextHolder} by the authentication mechanism which is
- * </p>
+ * being used. An explicit authentication can be achieved, without using one of Spring Security's authentication 
+ * mechanisms,  by creating an <tt>Authentication</tt> instance and using the code:
  *
- * <p>
+ * <pre>
- * Stored in a request {@link org.springframework.security.context.SecurityContext}.
+ * SecurityContextHolder.getContext().setAuthentication(anAuthentication);
- * </p>
+ * </pre>
+ * Note that unless the <tt>Authentication</tt> has the <tt>authenticated</tt> property set to <tt>true</tt>, it will
+ * still be authenticated by any security interceptor (for method or web invocations) which encounters it.
+ *
+ * In most cases, the framework transparently takes care of managing the security context and authentication objects
+ * for you.
  *
  * @author Ben Alex
  * @version $Id$
@@ -66,10 +74,15 @@ public interface Authentication extends Principal, Serializable {
     Object getDetails();
 
     /**
-     * The identity of the principal being authenticated. This is usually a username. Callers are expected to
+     * The identity of the principal being authenticated. In the case of an authentication request with username and
-     * populate the principal.
+     * password, this would be the username. Callers are expected to populate the principal for an authentication
+     * request.
+     * <p>
+     * The <tt>AuthenticationManager</tt> implementation will often return an <tt>Authentication</tt> containing
+     * richer information as the principal for use by the application. Many of the authentication providers will
+     * create a {@link UserDetails} object as the principal.
      *
-     * @return the <code>Principal</code> being authenticated
+     * @return the <code>Principal</code> being authenticated or the authenticated principal after authentication.
      */
     Object getPrincipal();
 
@@ -79,21 +92,25 @@ public interface Authentication extends Principal, Serializable {
      * (or, more often, one of its <code>AuthenticationProvider</code>s) will return an immutable authentication token
      * after successful authentication, in which case that token can safely return <code>true</code> to this method.
      * Returning <code>true</code> will improve performance, as calling the <code>AuthenticationManager</code> for
-     * every request will no longer be necessary.<p>For security reasons, implementations of this interface
+     * every request will no longer be necessary.
-     * should be very careful about returning <code>true</code> to this method unless they are either immutable, or
+     * <p>
-     * have some way of ensuring the properties have not been changed since original creation.</p>
+     * For security reasons, implementations of this interface should be very careful about returning
+     * <code>true</code> from this method unless they are either immutable, or have some way of ensuring the properties
+     * have not been changed since original creation.
      *
      * @return true if the token has been authenticated and the <code>AbstractSecurityInterceptor</code> does not need
-     *         to represent the token for re-authentication to the <code>AuthenticationManager</code>
+     *         to present the token to the <code>AuthenticationManager</code> again for re-authentication.
      */
     boolean isAuthenticated();
 
     /**
-     * See {@link #isAuthenticated()} for a full description.<p>Implementations should <b>always</b> allow this
+     * See {@link #isAuthenticated()} for a full description.
-     * method to be called with a <code>false</code> parameter, as this is used by various classes to specify the
+     * <p>
-     * authentication token should not be trusted. If an implementation wishes to reject an invocation with a
+     * Implementations should <b>always</b> allow this method to be called with a <code>false</code> parameter,
-     * <code>true</code> parameter (which would indicate the authentication token is trusted - a potential security
+     * as this is used by various classes to specify the authentication token should not be trusted.
-     * risk) the implementation should throw an {@link IllegalArgumentException}.</p>
+     * If an implementation wishes to reject an invocation with a <code>true</code> parameter (which would indicate
+     * the authentication token is trusted - a potential security risk) the implementation should throw an
+     * {@link IllegalArgumentException}.
      *
      * @param isAuthenticated <code>true</code> if the token should be trusted (which may result in an exception) or
      *        <code>false</code> if the token should not be trusted
@@ -102,6 +119,5 @@ public interface Authentication extends Principal, Serializable {
      *         <code>true</code> as the argument) is rejected due to the implementation being immutable or
      *         implementing its own alternative approach to {@link #isAuthenticated()}
      */
-    void setAuthenticated(boolean isAuthenticated)
+    void setAuthenticated(boolean isAuthenticated) throws IllegalArgumentException;
-        throws IllegalArgumentException;
 }