From 3e37b74e3f1c4b5afa78c7eab9dbe9bd5c04deae Mon Sep 17 00:00:00 2001 From: Ray Krueger Date: Mon, 19 Jul 2004 19:42:14 +0000 Subject: [PATCH] Added Javadoc to all classes --- .../providers/jaas/AuthorityGranter.java | 13 ++++++++- .../JAASAuthenticationCallbackHandler.java | 28 ++++++++++++++++++- .../providers/jaas/JAASGrantedAuthority.java | 5 ++-- .../jaas/JAASNameCallbackHandler.java | 14 +++++++++- .../jaas/JAASPasswordCallbackHandler.java | 14 +++++++++- .../jaas/event/JAASAuthenticationEvent.java | 13 +++++++-- .../event/JAASAuthenticationFailedEvent.java | 2 +- .../event/JAASAuthenticationSuccessEvent.java | 3 +- 8 files changed, 82 insertions(+), 10 deletions(-) diff --git a/core/src/main/java/org/acegisecurity/providers/jaas/AuthorityGranter.java b/core/src/main/java/org/acegisecurity/providers/jaas/AuthorityGranter.java index c0e18f3cb7..1b2dfa99cc 100644 --- a/core/src/main/java/org/acegisecurity/providers/jaas/AuthorityGranter.java +++ b/core/src/main/java/org/acegisecurity/providers/jaas/AuthorityGranter.java @@ -3,12 +3,23 @@ package net.sf.acegisecurity.providers.jaas; import java.security.Principal; /** - * Insert comments here... + * The AuthorityGranter interface is used to map a given principal to a role name. + * If a Windows NT login module were to be used from JAAS, an AuthrityGranter implementation could be created + * to map a NT Group Principal to a ROLE_USER role for instance. *
* * @author Ray Krueger * @version $Id$ */ public interface AuthorityGranter { + + /** + * The grant method is called for each principal returned from the LoginContext subject. + * If the AuthorityGranter wishes to grant authority, it should return the role name, such as ROLE_USER. + * If the AuthrityGranter does not wish to grant any authority it should return null. + * + * @param principal One of the principal from the LoginContext.getSubect().getPrincipals() method. + * @return The name of a role to grant, or null meaning no role should be granted. + */ public String grant(Principal principal); } diff --git a/core/src/main/java/org/acegisecurity/providers/jaas/JAASAuthenticationCallbackHandler.java b/core/src/main/java/org/acegisecurity/providers/jaas/JAASAuthenticationCallbackHandler.java index f8da0609e7..47cb294c86 100644 --- a/core/src/main/java/org/acegisecurity/providers/jaas/JAASAuthenticationCallbackHandler.java +++ b/core/src/main/java/org/acegisecurity/providers/jaas/JAASAuthenticationCallbackHandler.java @@ -7,15 +7,41 @@ import javax.security.auth.callback.UnsupportedCallbackException; import java.io.IOException; /** - * Insert comments here... + * The JAASAuthenticationCallbackHandler is similar to the javax.security.auth.callback.CallbackHandler interface + * in that it defines a handle method. The JAASAuthenticationCallbackHandler is only asked to handle one Callback instance at at time + * rather than an array of all Callbacks, as the javax... CallbackHandler defines. + *

+ * Before a JAASAuthenticationCallbackHandler is asked to 'handle' any callbacks, it is first passed the Authentication + * object that the login attempt is for. NOTE: The Authentication object has not been 'authenticated' yet. + *

*
* * @author Ray Krueger * @version $Id$ + * @see JAASNameCallbackHandler + * @see JAASPasswordCallbackHandler + * @see Callback + * @see CallbackHandler */ public interface JAASAuthenticationCallbackHandler { + + /** + * Called by the JAASAuthenticationProvider before calling the handle method for any Callbacks. + * + * @param auth The Authentication object currently being authenticated. + */ void setAuthentication(Authentication auth); + /** + * Handle the Callback. + * The handle method will be called for every callback instance sent from the LoginContext. Meaning that The handle + * method may be called multiple times for a given JAASAuthenticationCallbackHandler, after a single call + * to the {@link #setAuthentication(net.sf.acegisecurity.Authentication) setAuthentication} method. + * + * @param callback + * @throws IOException + * @throws UnsupportedCallbackException + */ void handle(Callback callback) throws IOException, UnsupportedCallbackException; } diff --git a/core/src/main/java/org/acegisecurity/providers/jaas/JAASGrantedAuthority.java b/core/src/main/java/org/acegisecurity/providers/jaas/JAASGrantedAuthority.java index 16ffb178b2..ae851e89e5 100644 --- a/core/src/main/java/org/acegisecurity/providers/jaas/JAASGrantedAuthority.java +++ b/core/src/main/java/org/acegisecurity/providers/jaas/JAASGrantedAuthority.java @@ -5,15 +5,16 @@ import net.sf.acegisecurity.GrantedAuthorityImpl; import java.security.Principal; /** - * Insert comments here... + * Extends GrantedAuthorityImpl to hold the principal that an AuthorityGranter justified as a reason to grant this Authority. *
* * @author Ray Krueger * @version $Id$ + * @see AuthorityGranter */ public class JAASGrantedAuthority extends GrantedAuthorityImpl { - Principal principal; + private Principal principal; public JAASGrantedAuthority(String role, Principal principal) { super(role); diff --git a/core/src/main/java/org/acegisecurity/providers/jaas/JAASNameCallbackHandler.java b/core/src/main/java/org/acegisecurity/providers/jaas/JAASNameCallbackHandler.java index a5488fce9d..2d508f2097 100644 --- a/core/src/main/java/org/acegisecurity/providers/jaas/JAASNameCallbackHandler.java +++ b/core/src/main/java/org/acegisecurity/providers/jaas/JAASNameCallbackHandler.java @@ -8,11 +8,14 @@ import javax.security.auth.callback.UnsupportedCallbackException; import java.io.IOException; /** - * Insert comments here... + * The most basic Callbacks to be handled when using a LoginContext from JAAS, are the NameCallback and PasswordCallback. + * The acegi security framework provides the JAASNameCallbackHandler specifically tailored to handling the NameCallback. *
* * @author Ray Krueger * @version $Id$ + * @see Callback + * @see NameCallback */ public class JAASNameCallbackHandler implements JAASAuthenticationCallbackHandler { @@ -22,6 +25,15 @@ public class JAASNameCallbackHandler implements JAASAuthenticationCallbackHandle this.authentication = authentication; } + /** + * If the callback passed to the 'handle' method is an instance of NameCallback, the JAASNameCallbackHandler will call, + * callback.setName(authentication.getPrincipal().toString()). Where 'authentication' is the {@link Authentication} + * object used in the {@link #setAuthentication(net.sf.acegisecurity.Authentication) setAuthentication} method. + * + * @param callback + * @throws IOException + * @throws UnsupportedCallbackException + */ public void handle(Callback callback) throws IOException, UnsupportedCallbackException { if (callback instanceof NameCallback) { NameCallback ncb = (NameCallback) callback; diff --git a/core/src/main/java/org/acegisecurity/providers/jaas/JAASPasswordCallbackHandler.java b/core/src/main/java/org/acegisecurity/providers/jaas/JAASPasswordCallbackHandler.java index 0ff89124ec..84675b15f0 100644 --- a/core/src/main/java/org/acegisecurity/providers/jaas/JAASPasswordCallbackHandler.java +++ b/core/src/main/java/org/acegisecurity/providers/jaas/JAASPasswordCallbackHandler.java @@ -8,11 +8,14 @@ import javax.security.auth.callback.UnsupportedCallbackException; import java.io.IOException; /** - * Insert comments here... + * The most basic Callbacks to be handled when using a LoginContext from JAAS, are the NameCallback and PasswordCallback. + * The acegi security framework provides the JAASPasswordCallbackHandler specifically tailored to handling the PasswordCallback. *
* * @author Ray Krueger * @version $Id$ + * @see Callback + * @see PasswordCallback */ public class JAASPasswordCallbackHandler implements JAASAuthenticationCallbackHandler { @@ -22,6 +25,15 @@ public class JAASPasswordCallbackHandler implements JAASAuthenticationCallbackHa this.auth = auth; } + /** + * If the callback passed to the 'handle' method is an instance of PasswordCallback, the JAASPasswordCallbackHandler will call, + * callback.setPassword(authentication.getCredentials().toString()). Where 'authentication' is the {@link Authentication} + * object used in the {@link JAASAuthenticationCallbackHandler#setAuthentication(net.sf.acegisecurity.Authentication) setAuthentication} method. + * + * @param callback + * @throws IOException + * @throws UnsupportedCallbackException + */ public void handle(Callback callback) throws IOException, UnsupportedCallbackException { if (callback instanceof PasswordCallback) { PasswordCallback pc = (PasswordCallback) callback; diff --git a/core/src/main/java/org/acegisecurity/providers/jaas/event/JAASAuthenticationEvent.java b/core/src/main/java/org/acegisecurity/providers/jaas/event/JAASAuthenticationEvent.java index 257d499a8a..149d5aed94 100644 --- a/core/src/main/java/org/acegisecurity/providers/jaas/event/JAASAuthenticationEvent.java +++ b/core/src/main/java/org/acegisecurity/providers/jaas/event/JAASAuthenticationEvent.java @@ -4,18 +4,27 @@ import net.sf.acegisecurity.Authentication; import org.springframework.context.ApplicationEvent; /** - * Insert comments here... - *
+ * Parent class for events fired by the {@link net.sf.acegisecurity.providers.jaas.JAASAuthenticationProvider JAASAuthenticationProvider}. * * @author Ray Krueger * @version $Id$ */ public abstract class JAASAuthenticationEvent extends ApplicationEvent { + /** + * The Authentication object is stored as the ApplicationEvent 'source'. + * + * @param auth + */ public JAASAuthenticationEvent(Authentication auth) { super(auth); } + /** + * Pre-casted method that returns the 'source' of the event. + * + * @return + */ public Authentication getAuthentication() { return (Authentication) source; } diff --git a/core/src/main/java/org/acegisecurity/providers/jaas/event/JAASAuthenticationFailedEvent.java b/core/src/main/java/org/acegisecurity/providers/jaas/event/JAASAuthenticationFailedEvent.java index 857c48d596..ba1aa6ee58 100644 --- a/core/src/main/java/org/acegisecurity/providers/jaas/event/JAASAuthenticationFailedEvent.java +++ b/core/src/main/java/org/acegisecurity/providers/jaas/event/JAASAuthenticationFailedEvent.java @@ -3,7 +3,7 @@ package net.sf.acegisecurity.providers.jaas.event; import net.sf.acegisecurity.Authentication; /** - * Insert comments here... + * Fired when LoginContext.login throws a LoginException, or if any other exception is thrown during that time. *
* * @author Ray Krueger diff --git a/core/src/main/java/org/acegisecurity/providers/jaas/event/JAASAuthenticationSuccessEvent.java b/core/src/main/java/org/acegisecurity/providers/jaas/event/JAASAuthenticationSuccessEvent.java index 0f4a85f315..6345ac4e8c 100644 --- a/core/src/main/java/org/acegisecurity/providers/jaas/event/JAASAuthenticationSuccessEvent.java +++ b/core/src/main/java/org/acegisecurity/providers/jaas/event/JAASAuthenticationSuccessEvent.java @@ -3,7 +3,8 @@ package net.sf.acegisecurity.providers.jaas.event; import net.sf.acegisecurity.Authentication; /** - * Insert comments here... + * Fired by the {@link net.sf.acegisecurity.providers.jaas.JAASAuthenticationProvider JAASAuthenticationProvider} after + * successfully logging the user into the LoginContext, handling all callbacks, and calling all AuthorityGranters. *
* * @author Ray Krueger