Added Javadoc to all classes

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.
  * <br>
  *
  * @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);
 }

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.
+ * <p/>
+ * 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.
+ * </p>
  * <br>
  *
  * @author Ray Krueger
  * @version $Id$
+ * @see JAASNameCallbackHandler
+ * @see JAASPasswordCallbackHandler
+ * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/callback/Callback.html">Callback</a>
+ * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/callback/CallbackHandler.html">CallbackHandler</a>
  */
 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 <a href="http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/callback/Callback.html">Callback</a>.
+     * 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;
 
 }

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.
  * <br>
  *
  * @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);

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.
  * <br>
  *
  * @author Ray Krueger
  * @version $Id$
+ * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/callback/Callback.html">Callback</a>
+ * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/callback/NameCallback.html">NameCallback</a>
  */
 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;

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.
  * <br>
  *
  * @author Ray Krueger
  * @version $Id$
+ * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/callback/Callback.html">Callback</a>
+ * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/callback/PasswordCallback.html">PasswordCallback</a>
  */
 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;

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...
- * <br>
+ * 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;
     }

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.
  * <br>
  *
  * @author Ray Krueger

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.
  * <br>
  *
  * @author Ray Krueger