| Title: 2.10 - The LdapConnectionTemplate |
| NavPrev: 2.9-exception-management.html |
| NavPrevText: 2.9 - Exception management |
| NavUp: 2-basic-ldap-api-usage.html |
| NavUpText: 2 - Basic LDAP API usage |
| NavNext: 2.11-filter-builder.html |
| NavNextText: 2.11 - The FilterBuilder |
| Notice: Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| . |
| http://www.apache.org/licenses/LICENSE-2.0 |
| . |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| |
| 2.10 - Why use the LdapConnectionTemplate? |
| ========================================== |
| |
| The LdapConnectionTemplate provides simplified access to the API functions. It does so by |
| |
| * [Managing Connections](#managing-connections) |
| * [Providing Factory Methods For Model Objects](#providing-factory-methods-for-model-objects) |
| * [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) |
| |
| Conceptually it uses the Template Method design pattern to do all of the boiler plate work for you. It can give control back as needed for special cases. |
| |
| Managing Connections |
| -------------------- |
| |
| The connection template manages connections through a connection pool. The connection pool must be supplied to the constructor: |
| |
| :::Java |
| LdapConnectionConfig config = new LdapConnectionConfig(); |
| config.setLdapHost( hostname ); |
| config.setLdapPort( port ); |
| config.setName( adminDn ); |
| config.setCredentials( adminPassword ); |
| |
| DefaultLdapConnectionFactory factory = new DefaultLdapConnectionFactory( config ); |
| factory.setTimeOut( connectionTimeout ); |
| |
| // optional, values below are defaults |
| GenericObjectPool.Config poolConfig = new GenericObjectPool.Config(); |
| poolConfig.lifo = true; |
| poolConfig.maxActive = 8; |
| poolConfig.maxIdle = 8; |
| poolConfig.maxWait = -1L; |
| poolConfig.minEvictableIdleTimeMillis = 1000L * 60L * 30L; |
| poolConfig.minIdle = 0; |
| poolConfig.numTestsPerEvictionRun = 3; |
| poolConfig.softMinEvictableIdleTimeMillis = -1L; |
| poolConfig.testOnBorrow = false; |
| poolConfig.testOnReturn = false; |
| poolConfig.testWhileIdle = false; |
| poolConfig.timeBetweenEvictionRunsMillis = -1L; |
| poolConfig.whenExhaustedAction = GenericObjectPool.WHEN_EXHAUSTED_BLOCK; |
| |
| // could use DefaultPoolableLdapConnectionFactory instead |
| // see javadoc for ValidatingPoolableLdapConnectionFactory |
| // for an explanation |
| LdapConnectionTemplate ldapConnectionTemplate = |
| new LdapConnectionTemplate( new LdapConnectionPool( |
| new ValidatingPoolableLdapConnectionFactory( factory ), poolConfig ) ); |
| |
| This may look complicated, but most of the parameters are optional and it's an easy way for you to manage connections in a safe and efficient manner. |
| |
| Providing Factory Methods For Model Objects |
| ------------------------------------------- |
| |
| The connection template implements an interface called the ModelFactory. Any implementation of this factory can be injected into the template once it is constructed. By default, it uses ModelFactoryImpl which in turn constructs the standard Apache LDAP API model objects. This abstraction frees you from having to be concerned with implementation details while still giving you the power to override the default behavior as you see fit. |
| |
| :::Java |
| ModelFactory modelFactory = new MyCustomModelFactory(); |
| ldapConnectionTemplate.setModelFactory( modelFactory ); |
| |
| 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 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: |
| |
| :::Java |
| // using RequestBuilder |
| AddResponse response = ldapConnectionTemplate.add( |
| ldapConnectionTemplate.newDn( "uid=kermitthefrog,ou=muppets,dc=muppets,dc=org" ), |
| new RequestBuilder<AddRequest>() { |
| @Override |
| public void buildRequest( AddRequest request ) throws LdapException { |
| request.getEntry() |
| .add( "objectClass", "top", "person", "organizationalPerson", "inetOrgPerson" ) |
| .add( "cn", "Kermit The Frog" ) |
| .add( "givenName", "Kermit" ) |
| .add( "sn", "The Frog" ) |
| .add( "mail", "kermitthefrog@muppets.org" ) |
| .add( "uid", "kermitthefrog" ); |
| } |
| } ); |
| |
| // using Attributes list |
| AddResponse response = ldapConnectionTemplate.add( |
| ldapConnectionTemplate.newDn( "uid=misspiggy,ou=muppets,dc=muppets,dc=org" ), |
| ldapConnectionTemplate.newAttribute( "objectClass", |
| "top", "person", "organizationalPerson", "inetOrgPerson" ), |
| ldapConnectionTemplate.newAttribute( "cn", "Miss Piggy" ), |
| ldapConnectionTemplate.newAttribute( "givenName", "Miss" ), |
| ldapConnectionTemplate.newAttribute( "sn", "Piggy" ), |
| ldapConnectionTemplate.newAttribute( "mail", "misspiggy@muppets.org" ), |
| ldapConnectionTemplate.newAttribute( "uid", "misspiggy" ) ); |
| |
| Modify simply supplies the 2 standard approaches: |
| |
| :::Java |
| // using RequestBuilder |
| ModifyResponse response = ldapConnectionTemplate.modify( |
| ldapConnectionTemplate.newDn( "uid=misspiggy,ou=muppets,dc=muppets,dc=org" ), |
| new RequestBuilder<ModifyRequest>() { |
| @Override |
| public void buildRequest( ModifyRequest request ) throws LdapException { |
| request.replace( "sn", "The Frog" ) |
| .replace( "cn", "Miss The Frog" ) |
| .replace( "mail", "missthefrog@muppets.org" ); |
| } |
| } ); |
| |
| Delete provides the 2 standard approaches plus an additional DN-only option as that is most likely enough: |
| |
| :::Java |
| // using DN only |
| 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 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 boilerplate code for building requests and iterating through its responses. This template does the work for you. It iterates over the entire result set, feeds each entry through an EntryMapper, and assembles the results into a list tht is 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<Muppet> muppetEntryMapper = |
| new EntryMapper<Muppet>() { |
| @Override |
| public Muppet map( Entry entry ) throws LdapException { |
| return new Muppet.Builder() |
| .setId( entry.getDn() ) |
| .setFirstName( entry.get( "givenName" ).getString() ) |
| .setLastName( entry.get( "sn" ).getString() ) |
| .setEmailAddress( entry.get( "mail" ).getString() ) |
| .build(); |
| } |
| }; |
| |
| 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 usages for the most common LDAP operations. 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 ); |
| |
| It is also natural to pair the search function with the FilterBuilder: |
| |
| :::Java |
| import static org.apache.directory.ldap.client.api.search.FilterBuilder.equal; |
| import static org.apache.directory.ldap.client.api.search.FilterBuilder.or; |
| |
| ... |
| |
| Muppet kermit = ldapConnectionTemplate.search( |
| "ou=muppets,dc=muppets,dc=org", |
| or( |
| equal( "mail", "kermitthefrog@muppets.org" ), |
| equal( "mail", "misspiggy@muppets.org" ) ), |
| SearchScope.ONELEVEL, |
| muppetEntryMapper ); |
| |
| This has the added benefit of ensuring that your search filter has been property encoded per [RFC4515 section 3](https://tools.ietf.org/html/rfc4515.html#section-3). For more information, see [Filter Builder](/api/user-guide/2.11-filter-builder.html). |
| |
| |
| Providing Simplified, Password Policy Aware, Authentication/Password Modification Methods |
| ----------------------------------------------------------------------------------------- |
| |
| One of the most common usages of LDAP is as an identity provider. As such, the most common operation is authentication, and password management. If your LDAP server supports the [password policy control](http://tools.ietf.org/html/draft-behera-ldap-password-policy-10) then the authenticate method is very handy: |
| |
| :::Java |
| // throws PasswordException if authentication fails |
| PasswordWarning warning = ldapConnectionTemplate.authenticate( |
| ldapConnectionTemplate.newDn( "uid=" + uid + ", ou=people, dc=example, dc=com" ), |
| password ); |
| |
| // or if you authenticate using an attribute not in the dn |
| PasswordWarning warning = ldapConnectionTemplate.authenticate( |
| "ou=people,dc=example,dc=com", |
| "(mail=kermitthefrog@muppets.com)", |
| SearchScope.ONELEVEL, |
| "set4now".toCharArray() ); |
| |
| In this case, if authentication failed, a PasswordException is thrown. If authentication was successful, any warnings will be returned in the PasswordWarning object, or null will be returned if there are no warnings. |
| |
| Modifying a password is simple as well: |
| |
| :::Java |
| // using administrator account to modify a users password |
| ldapConnectionTemplate.modifyPassword( userDn, password ); |
| |
| // or user account modifying their own password |
| ldapConnectionTemplate.modifyPassword( userDn, oldPassword, newPassword ); |
| |
| // or if you want want more control |
| ldapConnectionTemplate.modifyPassword( userDn, oldPassword, newPassword, asAdmin ); |
| |
| If you modify the password as an administrator, then the oldPassword is not required, and if your password policy is set to, the password reset flag will be set causing a PasswordWarning to be returned the next time authenticate was called for that user. |
| |
| |
| Other Useful Methods |
| -------------------- |
| |
| The template provides a method that checks the response and throws an exception if the request was unsuccessful. 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" ) ) ); |
| |
