From 657a69b90661f6f673760e48d8234724d58eac33 Mon Sep 17 00:00:00 2001
From: Luke Taylor <luke.taylor@springsource.com>
Date: Sun, 4 Jul 2010 15:10:08 +0100
Subject: [PATCH] Minor doc/javadoc updates to clarify use of
 UserDetailsContextapper.

---
 .../manual/src/docbook/ldap-auth-provider.xml | 20 ++++++++++---------
 .../userdetails/UserDetailsContextMapper.java |  3 ++-
 2 files changed, 13 insertions(+), 10 deletions(-)

diff --git a/docs/manual/src/docbook/ldap-auth-provider.xml b/docs/manual/src/docbook/ldap-auth-provider.xml
index dd0d7e690b..b25b591047 100644
--- a/docs/manual/src/docbook/ldap-auth-provider.xml
+++ b/docs/manual/src/docbook/ldap-auth-provider.xml
@@ -364,16 +364,18 @@ public interface UserDetailsContextMapper {
 
   void mapUserToContext(UserDetails user, DirContextAdapter ctx);
 }]]>
-                </programlisting> Only the first method is relevant for
-                authentication. If you provide an implementation of this interface, you can control
-                exactly how the UserDetails object is created. The first parameter is an instance of
-                Spring LDAP's <interfacename>DirContextOperations</interfacename> which gives you
-                access to the LDAP attributes which were loaded. The <literal>username</literal>
-                parameter is the name used to authenticate and the final parameter is the collection
-                of authorities loaded for the user. </para>
+                </programlisting> Only the first method is relevant for authentication. If you
+                provide an implementation of this interface and inject it into the
+                <classname>LdapAuthenticationProvider</classname>, you have control over exactly how
+                the UserDetails object is created. The first parameter is an instance of Spring
+                LDAP's <interfacename>DirContextOperations</interfacename> which gives you access to
+                the LDAP attributes which were loaded during authentication. The
+                <literal>username</literal> parameter is the name used to authenticate and the final
+                parameter is the collection of authorities loaded for the user by the configured
+                <interfacename>LdapAuthoritiesPopulator</interfacename>. </para>
             <para> The way the context data is loaded varies slightly depending on the type of
-                authentication you are using. With the <classname>BindAuthenticator</classname>,
-                the context returned from the bind operation will be used to read the attributes,
+                authentication you are using. With the <classname>BindAuthenticator</classname>, the
+                context returned from the bind operation will be used to read the attributes,
                 otherwise the data will be read using the standard context obtained from the
                 configured <interfacename>ContextSource</interfacename> (when a search is configured
                 to locate the user, this will be the data returned by the search object). </para>
diff --git a/ldap/src/main/java/org/springframework/security/ldap/userdetails/UserDetailsContextMapper.java b/ldap/src/main/java/org/springframework/security/ldap/userdetails/UserDetailsContextMapper.java
index 2992f569dd..3ff020fd5c 100644
--- a/ldap/src/main/java/org/springframework/security/ldap/userdetails/UserDetailsContextMapper.java
+++ b/ldap/src/main/java/org/springframework/security/ldap/userdetails/UserDetailsContextMapper.java
@@ -23,7 +23,8 @@ import org.springframework.ldap.core.DirContextAdapter;
 
 /**
  * Operations to map a UserDetails object to and from a Spring LDAP <tt>DirContextOperations</tt> implementation.
- * Used by LdapUserDetailsManager when loading and saving/creating user information.
+ * Used by {@code LdapUserDetailsManager} when loading and saving/creating user information, and also by the
+ * {@code LdapAuthenticationProvider} to allow customization of the user data loaded during authentication.
  *
  * @author Luke Taylor
  * @since 2.0