From bf409b5b25701db08e7b0c4336a77e5fe72aa026 Mon Sep 17 00:00:00 2001 From: Luke Taylor Date: Tue, 16 Dec 2008 02:06:26 +0000 Subject: [PATCH] Improvements to Javadoc. --- .../security/Authentication.java | 60 ++++++++++++------- 1 file changed, 38 insertions(+), 22 deletions(-) diff --git a/core/src/main/java/org/springframework/security/Authentication.java b/core/src/main/java/org/springframework/security/Authentication.java index 54ce5101a6..c691e3d025 100644 --- a/core/src/main/java/org/springframework/security/Authentication.java +++ b/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. *

- * An Authentication object is not considered authenticated until - * it is processed by an {@link AuthenticationManager}. - *

+ * Once the request has been authenticated, the Authentication will usually be stored in a thread-local + * SecurityContext managed by the {@link SecurityContextHolder} by the authentication mechanism which is + * being used. An explicit authentication can be achieved, without using one of Spring Security's authentication + * mechanisms, by creating an Authentication instance and using the code: * - *

- * Stored in a request {@link org.springframework.security.context.SecurityContext}. - *

+ * 
+ * SecurityContextHolder.getContext().setAuthentication(anAuthentication);
+ *
+ * Note that unless the Authentication has the authenticated property set to true, 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 - * populate the principal. + * The identity of the principal being authenticated. In the case of an authentication request with username and + * password, this would be the username. Callers are expected to populate the principal for an authentication + * request. + *

+ * The AuthenticationManager implementation will often return an Authentication 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 Principal being authenticated + * @return the Principal 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 AuthenticationProviders) will return an immutable authentication token * after successful authentication, in which case that token can safely return true to this method. * Returning true will improve performance, as calling the AuthenticationManager for - * every request will no longer be necessary.

For security reasons, implementations of this interface - * should be very careful about returning true to this method unless they are either immutable, or - * have some way of ensuring the properties have not been changed since original creation.

+ * every request will no longer be necessary. + *

+ * For security reasons, implementations of this interface should be very careful about returning + * true 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 AbstractSecurityInterceptor does not need - * to represent the token for re-authentication to the AuthenticationManager + * to present the token to the AuthenticationManager again for re-authentication. */ boolean isAuthenticated(); /** - * See {@link #isAuthenticated()} for a full description.

Implementations should always allow this - * method to be called with a false parameter, as this is used by various classes to specify the - * authentication token should not be trusted. If an implementation wishes to reject an invocation with a - * true parameter (which would indicate the authentication token is trusted - a potential security - * risk) the implementation should throw an {@link IllegalArgumentException}.

+ * See {@link #isAuthenticated()} for a full description. + *

+ * Implementations should always allow this method to be called with a false parameter, + * as this is used by various classes to specify the authentication token should not be trusted. + * If an implementation wishes to reject an invocation with a true parameter (which would indicate + * the authentication token is trusted - a potential security risk) the implementation should throw an + * {@link IllegalArgumentException}. * * @param isAuthenticated true if the token should be trusted (which may result in an exception) or * false if the token should not be trusted @@ -102,6 +119,5 @@ public interface Authentication extends Principal, Serializable { * true as the argument) is rejected due to the implementation being immutable or * implementing its own alternative approach to {@link #isAuthenticated()} */ - void setAuthenticated(boolean isAuthenticated) - throws IllegalArgumentException; + void setAuthenticated(boolean isAuthenticated) throws IllegalArgumentException; }