Added extra commenting to Ldap classes

core/src/main/java/org/acegisecurity/ldap/DefaultInitialDirContextFactory.java

@@ -160,7 +160,7 @@ public class DefaultInitialDirContextFactory implements InitialDirContextFactory
     }
 
     /**
-     * DOCUMENT ME!
+     * Sets up the environment parameters for creating a new context.
      *
      * @return the Hashtable describing the base DirContext that will be created, minus the username/password if any.
      */
@@ -230,7 +230,8 @@ public class DefaultInitialDirContextFactory implements InitialDirContextFactory
     }
 
     /**
-     * DOCUMENT ME!
+     * Sets any custom environment variables which will be added to the those returned
+     * by the <tt>getEnvironment</tt> method.
      *
      * @param extraEnvVars extra environment variables to be added at config time.
      */
@@ -245,7 +246,9 @@ public class DefaultInitialDirContextFactory implements InitialDirContextFactory
     }
 
     /**
-     * DOCUMENT ME!
+     * Sets the directory user to authenticate as when obtaining a context using the
+     * <tt>newInitialDirContext()</tt> method.
+     * If no name is supplied then the context will be obtained anonymously.
      *
      * @param managerDn The name of the "manager" user for default authentication.
      */
@@ -255,7 +258,7 @@ public class DefaultInitialDirContextFactory implements InitialDirContextFactory
     }
 
     /**
-     * DOCUMENT ME!
+     * Sets the password which will be used in combination with the manager DN.
      *
      * @param managerPassword The "manager" user's password.
      */

core/src/main/java/org/acegisecurity/ldap/InitialDirContextFactory.java

@@ -30,8 +30,9 @@ public interface InitialDirContextFactory {
     //~ Methods ========================================================================================================
 
     /**
-     * 
-    DOCUMENT ME!
+     * Returns the root DN of the contexts supplied by this factory.
+     * The names for searches etc. which are performed against contexts
+     * returned by this factory should be relative to the root DN.
      *
      * @return The DN of the contexts returned by this factory.
      */
@@ -40,17 +41,17 @@ public interface InitialDirContextFactory {
     /**
      * Provides an initial context without specific user information.
      *
-     * @return DOCUMENT ME!
+     * @return An initial context for the LDAP directory
      */
     DirContext newInitialDirContext();
 
     /**
      * Provides an initial context by binding as a specific user.
      *
-     * @param userDn DOCUMENT ME!
-     * @param password DOCUMENT ME!
+     * @param userDn the user to authenticate as when obtaining the context.
+     * @param password the user's password.
      *
-     * @return DOCUMENT ME!
+     * @return An initial context for the LDAP directory
      */
     DirContext newInitialDirContext(String userDn, String password);
 }

core/src/main/java/org/acegisecurity/ldap/search/FilterBasedLdapUserSearch.java

@@ -97,11 +97,11 @@ public class FilterBasedLdapUserSearch implements LdapUserSearch {
     //~ Methods ========================================================================================================
 
     /**
-     * Return the LdapUserDetailsImpl containing the user's information
+     * Return the LdapUserDetails containing the user's information
      *
      * @param username the username to search for.
      *
-     * @return DOCUMENT ME!
+     * @return An LdapUserDetails object containing the details of the located user's directory entry
      *
      * @throws UsernameNotFoundException if no matching entry is found.
      */
@@ -129,9 +129,9 @@ public class FilterBasedLdapUserSearch implements LdapUserSearch {
     }
 
     /**
-     * Sets the corresponding property on the SearchControls instance used in the search.
+     * Sets the corresponding property on the {@link SearchControls} instance used in the search.
      *
-     * @param deref DOCUMENT ME!
+     * @param deref the derefLinkFlag value as defined in SearchControls..
      */
     public void setDerefLinkFlag(boolean deref) {
         searchControls.setDerefLinkFlag(deref);
@@ -141,16 +141,17 @@ public class FilterBasedLdapUserSearch implements LdapUserSearch {
      * If true then searches the entire subtree as identified by context, if false (the default) then only
      * searches the level identified by the context.
      *
-     * @param searchSubtree DOCUMENT ME!
+     * @param searchSubtree true the underlying search controls should be set to SearchControls.SUBTREE_SCOPE
+     * rather than SearchControls.ONELEVEL_SCOPE.
      */
     public void setSearchSubtree(boolean searchSubtree) {
         searchControls.setSearchScope(searchSubtree ? SearchControls.SUBTREE_SCOPE : SearchControls.ONELEVEL_SCOPE);
     }
 
     /**
-     * The time (in milliseconds) which to wait before the search fails; the default is zero, meaning forever.
+     * The time to wait before the search fails; the default is zero, meaning forever.
      *
-     * @param searchTimeLimit DOCUMENT ME!
+     * @param searchTimeLimit the time limit for the search (in milliseconds).
      */
     public void setSearchTimeLimit(int searchTimeLimit) {
         searchControls.setTimeLimit(searchTimeLimit);

core/src/main/java/org/acegisecurity/providers/ldap/authenticator/AbstractLdapAuthenticator.java

@@ -154,7 +154,8 @@ public abstract class AbstractLdapAuthenticator implements LdapAuthenticator, In
      * Sets the pattern which will be used to supply a DN for the user. The pattern should be the name relative
      * to the root DN. The pattern argument {0} will contain the username. An example would be "cn={0},ou=people".
      *
-     * @param dnPattern DOCUMENT ME!
+     * @param dnPattern the array of patterns which will be tried when obtaining a username
+     * to a DN.
      */
     public void setUserDnPatterns(String[] dnPattern) {
         Assert.notNull(dnPattern, "The array of DN patterns cannot be set to null");

core/src/main/java/org/acegisecurity/providers/ldap/authenticator/LdapShaPasswordEncoder.java

@@ -61,16 +61,14 @@ public class LdapShaPasswordEncoder implements PasswordEncoder {
     }
 
     /**
-     * 
-    DOCUMENT ME!
+     * Calculates the hash of password (and salt bytes, if supplied) and returns a base64 encoded concatenation
+     * of the hash and salt, prefixed with {SHA} (or {SSHA} if salt was used).
      *
      * @param rawPass the password to be encoded.
      * @param salt the salt. Must be a byte array or null.
      *
-     * @return base64 encoded concatenation of password hash and salt, prefixed with {SHA} or {SSHA} depending on
-     *         whether salt bytes were supplied.
+     * @return the encoded password in the specified format
      *
-     * @throws LdapDataAccessException DOCUMENT ME!
      */
     public String encodePassword(String rawPass, Object salt) {
         MessageDigest sha;

core/src/main/java/org/acegisecurity/providers/ldap/authenticator/PasswordComparisonAuthenticator.java

@@ -133,10 +133,10 @@ public final class PasswordComparisonAuthenticator extends AbstractLdapAuthentic
     /**
      * Allows the use of both simple and hashed passwords in the directory.
      *
-     * @param password DOCUMENT ME!
-     * @param ldapPassword DOCUMENT ME!
+     * @param password the password supplied by the user
+     * @param ldapPassword the (possibly hashed) password (from the directory)
      *
-     * @return DOCUMENT ME!
+     * @return true if they match
      */
     private boolean verifyPassword(String password, String ldapPassword) {
         if (ldapPassword.equals(password)) {

core/src/main/java/org/acegisecurity/providers/ldap/populator/DefaultLdapAuthoritiesPopulator.java

@@ -114,7 +114,7 @@ public class DefaultLdapAuthoritiesPopulator implements LdapAuthoritiesPopulator
 
     //~ Constructors ===================================================================================================
 
-/**
+    /**
      * Constructor for group search scenarios. <tt>userRoleAttributes</tt> may still be
      * set as a property.
      *
@@ -139,15 +139,25 @@ public class DefaultLdapAuthoritiesPopulator implements LdapAuthoritiesPopulator
 
     //~ Methods ========================================================================================================
 
+    /**
+     * This method should be overridden if required to obtain any additional
+     * roles for the given user (on top of those obtained from the standard
+     * search implemented by this class).
+     *
+     *
+     * @param ldapUser the user who's roles are required
+     * @return the extra roles which will be merged with those returned by the group search
+     */
+
     protected Set getAdditionalRoles(LdapUserDetails ldapUser) {
         return null;
     }
 
     /**
-     * 
-    DOCUMENT ME!
+     * Obtains the authorities for the user who's directory entry is represented by
+     * the supplied LdapUserDetails object.
      *
-     * @param userDetails DOCUMENT ME!
+     * @param userDetails the user who's authorities are required
      *
      * @return the set of roles granted to the user.
      */
@@ -191,6 +201,8 @@ public class DefaultLdapAuthoritiesPopulator implements LdapAuthoritiesPopulator
 //
 //        return userRoles;
 //    }
+
+
     public final Set getGroupMembershipRoles(String userDn, String username) {
         Set authorities = new HashSet();
 

core/src/main/java/org/acegisecurity/userdetails/ldap/LdapUserDetails.java

@@ -21,19 +21,20 @@ import javax.naming.directory.Attributes;
 import javax.naming.ldap.Control;
 
 
-/**
- * @author Luke Taylor
- * @version $Id$
+/**
+ * Captures the information for a user's LDAP entry.
+ *
+ * @author Luke Taylor
+ * @version $Id$
  */
 public interface LdapUserDetails extends UserDetails {
     //~ Methods ========================================================================================================
 
     /**
-     * 
-    DOCUMENT ME!
+     * The attributes for the user's entry in the directory (or a subset of them, depending on what was
+     * retrieved from the directory)
      *
-     * @return the attributes for the user's entry in the directory (or a subset of them, depending on what was
-     *         retrieved).
+     * @return the user's attributes, or an empty array if none were obtained, never null.
      */
     Attributes getAttributes();
 
@@ -45,10 +46,9 @@ public interface LdapUserDetails extends UserDetails {
     Control[] getControls();
 
     /**
-     * 
-    DOCUMENT ME!
+     * The DN of the entry for this user's account.
      *
-     * @return the DN of the entry for this user's account.
+     * @return the user's DN
      */
     String getDn();
 }

core/src/main/java/org/acegisecurity/userdetails/ldap/LdapUserDetailsMapper.java

@@ -92,19 +92,42 @@ public class LdapUserDetailsMapper implements LdapEntryMapper {
         return essence;
     }
 
+    /**
+     * Determines whether role field values will be converted to upper case when loaded.
+     * The default is true.
+     *
+     * @param convertToUpperCase true if the roles should be converted to upper case.
+     */
     public void setConvertToUpperCase(boolean convertToUpperCase) {
         this.convertToUpperCase = convertToUpperCase;
     }
 
+    /**
+     * The name of the attribute which contains the user's password.
+     * Defaults to "userPassword".
+     *
+     * @param passwordAttributeName the name of the attribute
+     */
     public void setPasswordAttributeName(String passwordAttributeName) {
         this.passwordAttributeName = passwordAttributeName;
     }
 
+    /**
+     * The names of any attributes in the user's  entry which represent application
+     * roles. These will be converted to <tt>GrantedAuthority</tt>s and added to the
+     * list in the returned LdapUserDetails object.
+     *
+     * @param roleAttributes the names of the role attributes.
+     */
     public void setRoleAttributes(String[] roleAttributes) {
         Assert.notNull(roleAttributes, "roleAttributes array cannot be null");
         this.roleAttributes = roleAttributes;
     }
 
+    /**
+     * The prefix that should be applied to the role names
+     * @param rolePrefix the prefix (defaults to "ROLE_").
+     */
     public void setRolePrefix(String rolePrefix) {
         this.rolePrefix = rolePrefix;
     }