From f8545f4dc26d87cdbb5131881a8ab3c671d2d198 Mon Sep 17 00:00:00 2001 From: Luke Taylor Date: Fri, 26 May 2006 22:48:21 +0000 Subject: [PATCH] Added extra commenting to Ldap classes --- .../ldap/DefaultInitialDirContextFactory.java | 11 +++++---- .../ldap/InitialDirContextFactory.java | 13 ++++++----- .../search/FilterBasedLdapUserSearch.java | 15 ++++++------ .../AbstractLdapAuthenticator.java | 3 ++- .../authenticator/LdapShaPasswordEncoder.java | 8 +++---- .../PasswordComparisonAuthenticator.java | 6 ++--- .../DefaultLdapAuthoritiesPopulator.java | 20 ++++++++++++---- .../userdetails/ldap/LdapUserDetails.java | 20 ++++++++-------- .../ldap/LdapUserDetailsMapper.java | 23 +++++++++++++++++++ 9 files changed, 79 insertions(+), 40 deletions(-) diff --git a/core/src/main/java/org/acegisecurity/ldap/DefaultInitialDirContextFactory.java b/core/src/main/java/org/acegisecurity/ldap/DefaultInitialDirContextFactory.java index 34401d81fe..430a845058 100644 --- a/core/src/main/java/org/acegisecurity/ldap/DefaultInitialDirContextFactory.java +++ b/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 getEnvironment 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 + * newInitialDirContext() 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. */ diff --git a/core/src/main/java/org/acegisecurity/ldap/InitialDirContextFactory.java b/core/src/main/java/org/acegisecurity/ldap/InitialDirContextFactory.java index 9556203b68..cb901768ff 100644 --- a/core/src/main/java/org/acegisecurity/ldap/InitialDirContextFactory.java +++ b/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); } diff --git a/core/src/main/java/org/acegisecurity/ldap/search/FilterBasedLdapUserSearch.java b/core/src/main/java/org/acegisecurity/ldap/search/FilterBasedLdapUserSearch.java index 294e4628fe..7c71d25ecf 100644 --- a/core/src/main/java/org/acegisecurity/ldap/search/FilterBasedLdapUserSearch.java +++ b/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); diff --git a/core/src/main/java/org/acegisecurity/providers/ldap/authenticator/AbstractLdapAuthenticator.java b/core/src/main/java/org/acegisecurity/providers/ldap/authenticator/AbstractLdapAuthenticator.java index 1a1e8bb98c..78d36df997 100644 --- a/core/src/main/java/org/acegisecurity/providers/ldap/authenticator/AbstractLdapAuthenticator.java +++ b/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"); diff --git a/core/src/main/java/org/acegisecurity/providers/ldap/authenticator/LdapShaPasswordEncoder.java b/core/src/main/java/org/acegisecurity/providers/ldap/authenticator/LdapShaPasswordEncoder.java index b3698cf0f1..396a036bb6 100644 --- a/core/src/main/java/org/acegisecurity/providers/ldap/authenticator/LdapShaPasswordEncoder.java +++ b/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; diff --git a/core/src/main/java/org/acegisecurity/providers/ldap/authenticator/PasswordComparisonAuthenticator.java b/core/src/main/java/org/acegisecurity/providers/ldap/authenticator/PasswordComparisonAuthenticator.java index 6599f82bb0..28403f2ee5 100644 --- a/core/src/main/java/org/acegisecurity/providers/ldap/authenticator/PasswordComparisonAuthenticator.java +++ b/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)) { diff --git a/core/src/main/java/org/acegisecurity/providers/ldap/populator/DefaultLdapAuthoritiesPopulator.java b/core/src/main/java/org/acegisecurity/providers/ldap/populator/DefaultLdapAuthoritiesPopulator.java index 1883988d2d..972340ba7d 100644 --- a/core/src/main/java/org/acegisecurity/providers/ldap/populator/DefaultLdapAuthoritiesPopulator.java +++ b/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. userRoleAttributes 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(); diff --git a/core/src/main/java/org/acegisecurity/userdetails/ldap/LdapUserDetails.java b/core/src/main/java/org/acegisecurity/userdetails/ldap/LdapUserDetails.java index 0124a21c8e..8d128b6938 100644 --- a/core/src/main/java/org/acegisecurity/userdetails/ldap/LdapUserDetails.java +++ b/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(); } diff --git a/core/src/main/java/org/acegisecurity/userdetails/ldap/LdapUserDetailsMapper.java b/core/src/main/java/org/acegisecurity/userdetails/ldap/LdapUserDetailsMapper.java index 2f0ec2d687..d61f0fd3df 100644 --- a/core/src/main/java/org/acegisecurity/userdetails/ldap/LdapUserDetailsMapper.java +++ b/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 GrantedAuthoritys 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; }