LDAP-47: Code example in section 4.1 of the documentation is incorrect

spring-ldap/docs/reference/src/executors.xml

@@ -9,13 +9,16 @@
     versions of the most common operations in <literal>DirContext</literal>,
     we have not provided an alternative for each and every method signature,
     mostly because there are so many of them. We have, however, provided a
-    means to call whichever overloaded method you want. Let's say, for
-    example, that you want to use the following method:</para>
+    means to call whichever <literal>DirContext</literal> method you want
+    and still get the benefits that LdapTemplate provides.</para>
+    
+    <para>Let's say that you want to call the following <literal>DirContext</literal>
+    method:</para>
 
     <programlisting>NamingEnumeration search(Name name, String filterExpr, Object[] filterArgs, SearchControls ctls)</programlisting>
 
-    <para>The way to do this is to use a custom
-    <literal>SearchExecutor</literal> implementation:</para>
+    <para>There is no corresponding overloaded method in LdapTemplate. The way to solve
+    this is to use a custom <literal>SearchExecutor</literal> implementation:</para>
 
     <informalexample>
       <programlisting>public interface SearchExecutor {
@@ -23,6 +26,16 @@
 }</programlisting>
     </informalexample>
 
+    <para>In your custom executor, you have access to a <literal>DirContext</literal>
+    object, which you use to call the method you want. You then provide a handler
+    that is responsible for mapping attributes and collecting the results. You can
+    for example use one of the available implementations of
+    <literal>CollectingNameClassPairCallbackHandler</literal>, which will collect
+    the mapped results in an internal list. In order to
+    actually execute the search, you call the <literal>search</literal> 
+    method in LdapTemplate that takes an executor and a handler as arguments. Finally,
+    you return whatever your handler has collected.</para>
+
     <example>
       <title>A custom search method using SearchExecutor and
       AttributesMapper</title>
@@ -39,10 +52,11 @@ public class PersonDaoImpl implements PersonDao {
          }
       }</emphasis>;
 
-      NameClassPairCallbackHandler handler =
+      CollectingNameClassPairCallbackHandler handler =
          new AttributesMapperCallbackHandler(new PersonAttributesMapper());
 
-      return ldapTemplate.search(<emphasis role="bold">executor</emphasis>, handler);
+      ldapTemplate.search(<emphasis role="bold">executor</emphasis>, handler);
+      return handler.getList();
    }
 }</programlisting>
     </example>
@@ -67,17 +81,18 @@ public class PersonDaoImpl implements PersonDao {
          }
       };
 
-      NameClassPairCallbackHandler handler =
+      CollectingNameClassPairCallbackHandler handler =
          <emphasis role="bold">new ContextMapperCallbackHandler(new PersonContextMapper())</emphasis>;
 
-      return ldapTemplate.search(executor, handler);
+      ldapTemplate.search(executor, handler);
+      return handler.getList();
    }
 }</programlisting>
     </example>
 
     <note>
       <para>When using the
-      <literal>LdapTemplate.ContextMapperCallbackHandler</literal> you must
+      <literal>ContextMapperCallbackHandler</literal> you must
       make sure that you have called
       <literal>setReturningObjFlag(true)</literal> on your
       <literal>SearchControls</literal> instance.</para>