You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by lu...@apache.org on 2014/05/17 17:06:35 UTC
svn commit: r1595495 -
/directory/site/trunk/content/api/user-guide/2.10-ldap-connection-template.mdtext
Author: lucastheisen
Date: Sat May 17 15:06:34 2014
New Revision: 1595495
URL: http://svn.apache.org/r1595495
Log:
testing
Modified:
directory/site/trunk/content/api/user-guide/2.10-ldap-connection-template.mdtext
Modified: directory/site/trunk/content/api/user-guide/2.10-ldap-connection-template.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/2.10-ldap-connection-template.mdtext?rev=1595495&r1=1595494&r2=1595495&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/2.10-ldap-connection-template.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/2.10-ldap-connection-template.mdtext Sat May 17 15:06:34 2014
@@ -32,6 +32,7 @@ The LdapConnectionTemplate provides simp
* [Providing CRUD Methods](#providing-crud-methods)
* [Handling Search Result Iteration](#handling-search-result-iteration)
* [Providing Simplified, Password Policy Aware, Authentication/Password Modification Methods](#providing-simplified-password-policy-aware-authenticationpassword-modification-methods)
+* [Other Useful Methods](#other-useful-methods)
The concept is basically that of the Template Method design pattern in that it does all the boiler plate work for you and hands back control as necessary.
@@ -84,7 +85,7 @@ The connection template implements an in
Providing CRUD Methods
----------------------
-The standard CRUD methods are provided (*though in this case Add, Lookup, Modify, Delete*) with a couple useful overloads. Add, Delete, and Modify all provide at least 2 approaches. The first is creating your own XxxRequest objects and supplying that the the method. This can be done by using the ModelFactory methods provided by LdapConnectionTemplate. The second, more elegant solution, is to use the DN and RequestBuilder approach. This approach will generate the request for you from the internal ModelFactory and provide it to a callback for you to fill in the details. This has the added benefit of translating any LdapException's that may occur (usually due to model implementation setter methods) to LdapRuntimeException, to remove the *****need***** for try/catch blocks. Now for some examples:
+The standard CRUD methods are provided (*though in this case Add, Lookup, Modify, Delete*) with a couple useful overloads. Add, Delete, and Modify all provide at least 2 approaches. The first is creating your own XxxRequest objects and supplying that to the method. These request objects can be created using the ModelFactory methods provided by LdapConnectionTemplate. The second, more elegant solution, is to use the DN and RequestBuilder approach. This approach will generate the request for you from the internal ModelFactory and provide it to a callback for you to fill in the details. This has the added benefit of translating any LdapException's that may occur (usually due to model implementation setter methods) to LdapRuntimeException, to remove the ***need*** for try/catch blocks. Now for some examples:
Add provides the standard approaches of supplying your own AddRequest and using RequestBuilder, as well as a third shortcut approach where you supply all the attributes instead of a RequestBuilder:
@@ -138,11 +139,36 @@ Delete provides the 2 standard approache
DeleteResponse response = ldapConnectionTemplate.delete(
ldapConnectionTemplate.newDn( "uid=misspiggy,ou=muppets,dc=muppets,dc=org" ) );
-Lookup is a different story in that it is an accessor (instead of mutator) so its interface must provide a way of handling the expected response data. To that end, we introduce the EntryMapper. EntryMapper defines how a returned ldap entry should be interpreted. This is typically used to construct a domain object:
+Lookup is a different story in that it is an accessor (instead of mutator) so its interface must provide a way of handling the expected response data. To that end, we supply an EntryMapper. EntryMapper defines how a returned ldap entry should be interpreted. This is typically used to construct a domain object:
+
+ :::Java
+ // using a previously defined EntryMapper
+ Muppet kermit = ldapConnectionTemplate.lookup(
+ ldapConnectionTemplate.newDn( "uid=kermitthefrog,ou=muppets,dc=muppets,dc=org" ),
+ muppetEntryMapper );
+
+ // using an inline defined EntityMapper
+ String email = ldapConnectionTemplate.lookup(
+ ldapConnectionTemplate.newDn( "uid=kermitthefrog,ou=muppets,dc=muppets,dc=org" ),
+ new String[] { "mail" }, // attribute list
+ new EntryMapper<String>() {
+ @Override
+ public String map( Entry entry ) throws LdapException {
+ return entry.get( "mail" ).getString();
+ }
+ } );
+
+More information on EntryMapper can be found in the [Handling Search Result Iteration](#handling-search-result-iteration) section.
+
+
+Handling Search Result Iteration
+--------------------------------
+
+Searching usually contains a lot of boiler plate code for build requests and iterating through responses. This template does the work for you. It iterates over the entire result set, feeds each entry through an EntryMapper, and collects the results into the list returned to the caller. All you have to do is provide the EntryMapper for mapping a single entry to a domain object. EntryMapper itself is a very simple interface with one method. As you saw before in the lookup documentation, they are typically defined as static members of your service classes:
:::Java
// Typically mappers are reused, so define a static member
- private static final EntryMapper muppetEntryMapper =
+ private static final EntryMapper muppetEntryMapper =
new EntryMapper<Muppet>() {
@Override
public String map( Entry entry ) throws LdapException {
@@ -155,17 +181,36 @@ Lookup is a different story in that it i
}
};
- // A domain service method for retrieving a Muppet
- public Muppet getMuppet( String id ) {
- return ldapConnectionTemplate.lookup(
- ldapConnectionTemplate.newDn( id ),
- muppetEntryMapper );
- }
+And now your searches become much simpler:
+ :::Java
+ List<Muppet> allTheMuppets = ldapConnectionTemplate.search(
+ "ou=muppets,dc=muppets,dc=org",
+ "(objectClass=inetOrgPerson)",
+ SearchScope.ONELEVEL,
+ muppetEntryMapper );
+
+Now that is just plain ***SIMPLE***. The search method has many overloads to simplify use as it is the most common LDAP operation. There is also a searchFirst method which provides all the same overloads and is designed to return the first matching result:
+
+ :::Java
+ Muppet kermit = ldapConnectionTemplate.searchFirst(
+ "ou=muppets,dc=muppets,dc=org",
+ "(mail=kermitthefrog@muppets.org)",
+ SearchScope.ONELEVEL,
+ muppetEntryMapper );
-Handling Search Result Iteration
---------------------------------
Providing Simplified, Password Policy Aware, Authentication/Password Modification Methods
-----------------------------------------------------------------------------------------
+Other Useful Methods
+--------------------
+
+The template provides a method that will check the response and throw an exception if the request was not successful. It was designed to be chained:
+
+ :::Java
+ // using DN only
+ DeleteResponse response = ldapConnectionTemplate.responseOrException(
+ ldapConnectionTemplate.delete(
+ ldapConnectionTemplate.newDn( "uid=misspiggy,ou=muppets,dc=muppets,dc=org" ) ) );
+