org.springframework.ldap.core

## Interface LdapOperations

- All Known Implementing Classes:
    LdapTemplate

      public interface LdapOperations

  Interface that specifies a basic set of LDAP operations. Implemented by LdapTemplate, but it might be a useful option to use this interface in order to enhance testability.
  Author:
    Mattias Hellborg Arthursson, Ulrik Sandberg

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `authenticate(LdapQuery query, String password)` Utility method to perform a simple LDAP 'bind' authentication.
    `<T> T` | `authenticate(LdapQuery query, String password, AuthenticatedLdapEntryContextMapper<T> mapper)` Utility method to perform a simple LDAP 'bind' authentication.
    `boolean` | `authenticate(Name base, String filter, String password)` Deprecated. use `authenticate(org.springframework.ldap.query.LdapQuery, String)` or `authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)`
    `boolean` | `authenticate(Name base, String filter, String password, AuthenticatedLdapEntryContextCallback callback)` Deprecated. use `authenticate(org.springframework.ldap.query.LdapQuery, String)` or `authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)`
    `boolean` | `authenticate(Name base, String filter, String password, AuthenticatedLdapEntryContextCallback callback, AuthenticationErrorCallback errorCallback)` Deprecated. use `authenticate(org.springframework.ldap.query.LdapQuery, String)` or `authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)`
    `boolean` | `authenticate(Name base, String filter, String password, AuthenticationErrorCallback errorCallback)` Deprecated. use `authenticate(org.springframework.ldap.query.LdapQuery, String)` or `authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)`
    `boolean` | `authenticate(String base, String filter, String password)` Deprecated. use `authenticate(org.springframework.ldap.query.LdapQuery, String)` or `authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)`
    `boolean` | `authenticate(String base, String filter, String password, AuthenticatedLdapEntryContextCallback callback)` Deprecated. use `authenticate(org.springframework.ldap.query.LdapQuery, String)` or `authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)`
    `boolean` | `authenticate(String base, String filter, String password, AuthenticatedLdapEntryContextCallback callback, AuthenticationErrorCallback errorCallback)` Deprecated. use `authenticate(org.springframework.ldap.query.LdapQuery, String)` or `authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)`
    `boolean` | `authenticate(String base, String filter, String password, AuthenticationErrorCallback errorCallback)` Deprecated. use `authenticate(org.springframework.ldap.query.LdapQuery, String)` or `authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)`
    `void` | `bind(DirContextOperations ctx)` Bind the data in the supplied context in the tree.
    `void` | `bind(Name dn, Object obj, Attributes attributes)` Create an entry in the LDAP tree.
    `void` | `bind(String dn, Object obj, Attributes attributes)` Create an entry in the LDAP tree.
    `void` | `create(Object entry)` Create the given entry in the LDAP directory.
    `void` | `delete(Object entry)` Delete an entry from the LDAP directory.
    `<T> T` | `executeReadOnly(ContextExecutor<T> ce)` Perform an operation (or series of operations) on a read-only context.
    `<T> T` | `executeReadWrite(ContextExecutor<T> ce)` Perform an operation (or series of operations) on a read-write context.
    `<T> List<T>` | `find(LdapQuery query, Class<T> clazz)` Search for entries in the LDAP directory.
    `<T> List<T>` | `find(Name base, Filter filter, SearchControls searchControls, Class<T> clazz)` Find all entries in the LDAP directory of a given type that matches the specified filter.
    `<T> List<T>` | `findAll(Class<T> clazz)` Find all entries in the LDAP directory of a given type.
    `<T> List<T>` | `findAll(Name base, SearchControls searchControls, Class<T> clazz)` Find all entries in the LDAP directory of a given type.
    `<T> T` | `findByDn(Name dn, Class<T> clazz)` Read a named entry from the LDAP directory.
    `<T> T` | `findOne(LdapQuery query, Class<T> clazz)` Search for objects in the directory tree matching the specified LdapQuery, expecting to find exactly one match.
    `ObjectDirectoryMapper` | `getObjectDirectoryMapper()` Get the configured ObjectDirectoryMapper.
    `List<String>` | `list(Name base)` Perform a non-recursive listing of the children of the given `base`.
    `void` | `list(Name base, NameClassPairCallbackHandler handler)` Perform a non-recursive listing of the children of the given `base`.
    `<T> List<T>` | `list(Name base, NameClassPairMapper<T> mapper)` Perform a non-recursive listing of the children of the given `base`.
    `List<String>` | `list(String base)` Perform a non-recursive listing of the children of the given `base`.
    `void` | `list(String base, NameClassPairCallbackHandler handler)` Perform a non-recursive listing of the children of the given `base`.
    `<T> List<T>` | `list(String base, NameClassPairMapper<T> mapper)` Perform a non-recursive listing of the children of the given `base`.
    `List<String>` | `listBindings(Name base)` Perform a non-recursive listing of children of the given `base`.
    `<T> List<T>` | `listBindings(Name base, ContextMapper<T> mapper)` Perform a non-recursive listing of the children of the given `base`.
    `void` | `listBindings(Name base, NameClassPairCallbackHandler handler)` Perform a non-recursive listing of the children of the given `base`.
    `<T> List<T>` | `listBindings(Name base, NameClassPairMapper<T> mapper)` Perform a non-recursive listing of the children of the given `base`.
    `List<String>` | `listBindings(String base)` Perform a non-recursive listing of children of the given `base`.
    `<T> List<T>` | `listBindings(String base, ContextMapper<T> mapper)` Perform a non-recursive listing of the children of the given `base`.
    `void` | `listBindings(String base, NameClassPairCallbackHandler handler)` Perform a non-recursive listing of the children of the given `base`.
    `<T> List<T>` | `listBindings(String base, NameClassPairMapper<T> mapper)` Perform a non-recursive listing of the children of the given `base`.
    `Object` | `lookup(Name dn)` Lookup the supplied DN and return the found object.
    `<T> T` | `lookup(Name dn, AttributesMapper<T> mapper)` Convenience method to get the attributes of a specified DN and automatically pass them to an `AttributesMapper`.
    `<T> T` | `lookup(Name dn, ContextMapper<T> mapper)` Convenience method to lookup a specified DN and automatically pass the found object to a `ContextMapper`.
    `<T> T` | `lookup(Name dn, String[] attributes, AttributesMapper<T> mapper)` Convenience method to get the specified attributes of a specified DN and automatically pass them to an `AttributesMapper`.
    `<T> T` | `lookup(Name dn, String[] attributes, ContextMapper<T> mapper)` Convenience method to get the specified attributes of a specified DN and automatically pass them to a `ContextMapper`.
    `Object` | `lookup(String dn)` Lookup the supplied DN and return the found object.
    `<T> T` | `lookup(String dn, AttributesMapper<T> mapper)` Convenience method to get the attributes of a specified DN and automatically pass them to an `AttributesMapper`.
    `<T> T` | `lookup(String dn, ContextMapper<T> mapper)` Convenience method to lookup a specified DN and automatically pass the found object to a `ContextMapper`.
    `<T> T` | `lookup(String dn, String[] attributes, AttributesMapper<T> mapper)` Convenience method to get the specified attributes of a specified DN and automatically pass them to an `AttributesMapper`.
    `<T> T` | `lookup(String dn, String[] attributes, ContextMapper<T> mapper)` Convenience method to get the specified attributes of a specified DN and automatically pass them to a `ContextMapper`.
    `DirContextOperations` | `lookupContext(Name dn)` Convenience method to lookup the supplied DN and automatically cast it to `DirContextOperations`.
    `DirContextOperations` | `lookupContext(String dn)` Convenience method to lookup the supplied DN and automatically cast it to `DirContextOperations`.
    `void` | `modifyAttributes(DirContextOperations ctx)` Modify the attributes of the entry referenced by the supplied `DirContextOperations` instance.
    `void` | `modifyAttributes(Name dn, ModificationItem[] mods)` Modify an entry in the LDAP tree using the supplied `ModificationItems`.
    `void` | `modifyAttributes(String dn, ModificationItem[] mods)` Modify an entry in the LDAP tree using the supplied `ModificationItems`.
    `void` | `rebind(DirContextOperations ctx)` Remove an entry and replace it with a new one.
    `void` | `rebind(Name dn, Object obj, Attributes attributes)` Remove an entry and replace it with a new one.
    `void` | `rebind(String dn, Object obj, Attributes attributes)` Remove an entry and replace it with a new one.
    `void` | `rename(Name oldDn, Name newDn)` Move an entry in the LDAP tree to a new location.
    `void` | `rename(String oldDn, String newDn)` Move an entry in the LDAP tree to a new location.
    `<T> List<T>` | `search(LdapQuery query, AttributesMapper<T> mapper)` Perform a search with parameters from the specified LdapQuery.
    `<T> List<T>` | `search(LdapQuery query, ContextMapper<T> mapper)` Perform a search with parameters from the specified LdapQuery.
    `void` | `search(LdapQuery query, NameClassPairCallbackHandler callbackHandler)` Perform a search with parameters from the specified LdapQuery.
    `<T> List<T>` | `search(Name base, String filter, AttributesMapper<T> mapper)` Search for all objects matching the supplied filter.
    `<T> List<T>` | `search(Name base, String filter, ContextMapper<T> mapper)` Search for all objects matching the supplied filter.
    `<T> List<T>` | `search(Name base, String filter, int searchScope, AttributesMapper<T> mapper)` Search for all objects matching the supplied filter.
    `void` | `search(Name base, String filter, int searchScope, boolean returningObjFlag, NameClassPairCallbackHandler handler)` Search for all objects matching the supplied filter.
    `<T> List<T>` | `search(Name base, String filter, int searchScope, ContextMapper<T> mapper)` Search for all objects matching the supplied filter.
    `<T> List<T>` | `search(Name base, String filter, int searchScope, String[] attrs, AttributesMapper<T> mapper)` Search for all objects matching the supplied filter.
    `<T> List<T>` | `search(Name base, String filter, int searchScope, String[] attrs, ContextMapper<T> mapper)` Search for all objects matching the supplied filter.
    `void` | `search(Name base, String filter, NameClassPairCallbackHandler handler)` Search for all objects matching the supplied filter.
    `<T> List<T>` | `search(Name base, String filter, SearchControls controls, AttributesMapper<T> mapper)` Search for all objects matching the supplied filter.
    `<T> List<T>` | `search(Name base, String filter, SearchControls controls, AttributesMapper<T> mapper, DirContextProcessor processor)` Search for all objects matching the supplied filter.
    `<T> List<T>` | `search(Name base, String filter, SearchControls controls, ContextMapper<T> mapper)` Search for all objects matching the supplied filter.
    `<T> List<T>` | `search(Name base, String filter, SearchControls controls, ContextMapper<T> mapper, DirContextProcessor processor)` Search for all objects matching the supplied filter.
    `void` | `search(Name base, String filter, SearchControls controls, NameClassPairCallbackHandler handler)` Search for all objects matching the supplied filter.
    `void` | `search(Name base, String filter, SearchControls controls, NameClassPairCallbackHandler handler, DirContextProcessor processor)` Search for all objects matching the supplied filter.
    `void` | `search(SearchExecutor se, NameClassPairCallbackHandler handler)` Perform a search using a particular `SearchExecutor`.
    `void` | `search(SearchExecutor se, NameClassPairCallbackHandler handler, DirContextProcessor processor)` Perform a search using a particular `SearchExecutor` and context processor.
    `<T> List<T>` | `search(String base, String filter, AttributesMapper<T> mapper)` Search for all objects matching the supplied filter.
    `<T> List<T>` | `search(String base, String filter, ContextMapper<T> mapper)` Search for all objects matching the supplied filter.
    `<T> List<T>` | `search(String base, String filter, int searchScope, AttributesMapper<T> mapper)` Search for all objects matching the supplied filter.
    `void` | `search(String base, String filter, int searchScope, boolean returningObjFlag, NameClassPairCallbackHandler handler)` Search for all objects matching the supplied filter.
    `<T> List<T>` | `search(String base, String filter, int searchScope, ContextMapper<T> mapper)` Search for all objects matching the supplied filter.
    `<T> List<T>` | `search(String base, String filter, int searchScope, String[] attrs, AttributesMapper<T> mapper)` Search for all objects matching the supplied filter.
    `<T> List<T>` | `search(String base, String filter, int searchScope, String[] attrs, ContextMapper<T> mapper)` Search for all objects matching the supplied filter.
    `void` | `search(String base, String filter, NameClassPairCallbackHandler handler)` Search for all objects matching the supplied filter.
    `<T> List<T>` | `search(String base, String filter, SearchControls controls, AttributesMapper<T> mapper)` Search for all objects matching the supplied filter.
    `<T> List<T>` | `search(String base, String filter, SearchControls controls, AttributesMapper<T> mapper, DirContextProcessor processor)` Search for all objects matching the supplied filter.
    `<T> List<T>` | `search(String base, String filter, SearchControls controls, ContextMapper<T> mapper)` Search for all objects matching the supplied filter.
    `<T> List<T>` | `search(String base, String filter, SearchControls controls, ContextMapper<T> mapper, DirContextProcessor processor)` Search for all objects matching the supplied filter.
    `void` | `search(String base, String filter, SearchControls controls, NameClassPairCallbackHandler handler)` Search for all objects matching the supplied filter.
    `void` | `search(String base, String filter, SearchControls controls, NameClassPairCallbackHandler handler, DirContextProcessor processor)` Search for all objects matching the supplied filter.
    `DirContextOperations` | `searchForContext(LdapQuery query)` Perform a search for a unique entry matching the specified LDAP query and return the found entry as a DirContextOperation instance.
    `<T> T` | `searchForObject(LdapQuery query, ContextMapper<T> mapper)` Perform a search for a unique entry matching the specified LDAP query and return the found object.
    `<T> T` | `searchForObject(Name base, String filter, ContextMapper<T> mapper)` Perform a search for a unique entry matching the specified search criteria and return the found object.
    `<T> T` | `searchForObject(Name base, String filter, SearchControls searchControls, ContextMapper<T> mapper)` Perform a search for a unique entry matching the specified search criteria and return the found object.
    `<T> T` | `searchForObject(String base, String filter, ContextMapper<T> mapper)` Perform a search for a unique entry matching the specified search criteria and return the found object.
    `<T> T` | `searchForObject(String base, String filter, SearchControls searchControls, ContextMapper<T> mapper)` Perform a search for a unique entry matching the specified search criteria and return the found object.
    `void` | `unbind(Name dn)` Remove an entry from the LDAP tree.
    `void` | `unbind(Name dn, boolean recursive)` Remove an entry from the LDAP tree, optionally removing all descendants in the process.
    `void` | `unbind(String dn)` Remove an entry from the LDAP tree.
    `void` | `unbind(String dn, boolean recursive)` Remove an entry from the LDAP tree, optionally removing all descendants in the process.
    `void` | `update(Object entry)` Update the given entry in the LDAP directory.

- - ### Method Detail

    - #### search

          void search(SearchExecutor se,
                      NameClassPairCallbackHandler handler,
                      DirContextProcessor processor)
               throws NamingException

      Perform a search using a particular `SearchExecutor` and context processor. Use this method only if especially needed - for the most cases there is an overloaded convenience method which calls this one with suitable argments. This method handles all the plumbing; getting a readonly context; looping through the `NamingEnumeration` and closing the context and enumeration. The actual search is delegated to the SearchExecutor and each found `NameClassPair` is passed to the `CallbackHandler`. Any encountered `NamingException` will be translated using `LdapUtils.convertLdapException(javax.naming.NamingException)`.
      Parameters:
        `se` - The `SearchExecutor` to use for performing the actual search.
        `handler` - The `NameClassPairCallbackHandler` to which each found entry will be passed.
        `processor` - `DirContextProcessor` for custom pre- and post-processing.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted as no entries being found.

    - #### search

          void search(SearchExecutor se,
                      NameClassPairCallbackHandler handler)
               throws NamingException

      Perform a search using a particular `SearchExecutor`. Use this method only if especially needed - for the most cases there is an overloaded convenience method which calls this one with suitable argments. This method handles all the plumbing; getting a readonly context; looping through the `NamingEnumeration` and closing the context and enumeration. The actual search is delegated to the `SearchExecutor` and each found `NameClassPair` is passed to the `CallbackHandler`. Any encountered `NamingException` will be translated using the `LdapUtils.convertLdapException(javax.naming.NamingException)`.
      Parameters:
        `se` - The `SearchExecutor` to use for performing the actual search.
        `handler` - The `NameClassPairCallbackHandler` to which each found entry will be passed.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted as no entries being found.
      See Also:
        `search(Name, String, AttributesMapper)`, `search(Name, String, ContextMapper)`

    - #### executeReadOnly

          <T> T executeReadOnly(ContextExecutor<T> ce)
                         throws NamingException

      Perform an operation (or series of operations) on a read-only context. This method handles the plumbing - getting a `DirContext`, translating any Exceptions and closing the context afterwards. This method is not intended for searches; use `search(SearchExecutor, NameClassPairCallbackHandler)` or any of the overloaded search methods for this.
      Parameters:
        `ce` - The `ContextExecutor` to which the actual operation on the `DirContext` will be delegated.
      Returns:
        the result from the ContextExecutor's operation.
      Throws:
        `NamingException` - if the operation resulted in a `NamingException`.
      See Also:
        `search(SearchExecutor, NameClassPairCallbackHandler)`, `search(Name, String, AttributesMapper)`, `search(Name, String, ContextMapper)`

    - #### executeReadWrite

          <T> T executeReadWrite(ContextExecutor<T> ce)
                          throws NamingException

      Perform an operation (or series of operations) on a read-write context. This method handles the plumbing - getting a `DirContext`, translating any exceptions and closing the context afterwards. This method is intended only for very particular cases, where there is no suitable method in this interface to use.
      Parameters:
        `ce` - The `ContextExecutor` to which the actual operation on the `DirContext` will be delegated.
      Returns:
        the result from the ContextExecutor's operation.
      Throws:
        `NamingException` - if the operation resulted in a `NamingException`.
      See Also:
        `bind(Name, Object, Attributes)`, `unbind(Name)`, `rebind(Name, Object, Attributes)`, `rename(Name, Name)`, `modifyAttributes(Name, ModificationItem[])`

    - #### search

          void search(Name base,
                      String filter,
                      SearchControls controls,
                      NameClassPairCallbackHandler handler)
               throws NamingException

      Search for all objects matching the supplied filter. Each `SearchResult` is supplied to the specified `NameClassPairCallbackHandler`. The `SearchScope` specified in the supplied `SearchControls` will be used in the search. Note that if you are using a `ContextMapper`, the returningObjFlag needs to be set to true in the `SearchControls`.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `controls` - The `SearchControls` to use in the search.
        `handler` - The `NameClassPairCallbackHandler` to supply the `SearchResult` to.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          void search(String base,
                      String filter,
                      SearchControls controls,
                      NameClassPairCallbackHandler handler)
               throws NamingException

      Search for all objects matching the supplied filter. See `search(Name, String, SearchControls, NameClassPairCallbackHandler)` for details.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `controls` - The `SearchControls` to use in the search.
        `handler` - The `NameClassPairCallbackHandler` to supply the `SearchResult` to.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          void search(Name base,
                      String filter,
                      SearchControls controls,
                      NameClassPairCallbackHandler handler,
                      DirContextProcessor processor)
               throws NamingException

      Search for all objects matching the supplied filter. Each `SearchResult` is supplied to the specified `NameClassPairCallbackHandler`. The `SearchScope` specified in the supplied `SearchControls` will be used in the search. Note that if you are using a `ContextMapper`, the returningObjFlag needs to be set to true in the `SearchControls`. The given `DirContextProcessor` will be called before and after the search.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `controls` - The `SearchControls` to use in the search.
        `handler` - The `NameClassPairCallbackHandler` to supply the `SearchResult` to.
        `processor` - The `DirContextProcessor` to use before and after the search.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          <T> List<T> search(String base,
                             String filter,
                             SearchControls controls,
                             AttributesMapper<T> mapper,
                             DirContextProcessor processor)
                      throws NamingException

      Search for all objects matching the supplied filter. The Attributes in each `SearchResult` is supplied to the specified `AttributesMapper`. The `SearchScope` specified in the supplied `SearchControls` will be used in the search. The given `DirContextProcessor` will be called before and after the search.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `controls` - The `SearchControls` to use in the search.
        `mapper` - The `AttributesMapper` to use for translating each entry.
        `processor` - The `DirContextProcessor` to use before and after the search.
      Returns:
        a `List` containing all entries received from the `AttributesMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          <T> List<T> search(Name base,
                             String filter,
                             SearchControls controls,
                             AttributesMapper<T> mapper,
                             DirContextProcessor processor)
                      throws NamingException

      Search for all objects matching the supplied filter. The Attributes in each `SearchResult` is supplied to the specified `AttributesMapper`. The `SearchScope` specified in the supplied `SearchControls` will be used in the search. The given `DirContextProcessor` will be called before and after the search.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `controls` - The `SearchControls` to use in the search.
        `mapper` - The `AttributesMapper` to use for translating each entry.
        `processor` - The `DirContextProcessor` to use before and after the search.
      Returns:
        a `List` containing all entries received from the `AttributesMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          <T> List<T> search(String base,
                             String filter,
                             SearchControls controls,
                             ContextMapper<T> mapper,
                             DirContextProcessor processor)
                      throws NamingException

      Search for all objects matching the supplied filter. The Object returned in each `SearchResult` is supplied to the specified `ContextMapper`. The `SearchScope` specified in the supplied `SearchControls` will be used in the search. The given `DirContextProcessor` will be called before and after the search.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `controls` - The `SearchControls` to use in the search. If the returnObjFlag is not set in the `SearchControls`, this method will set it automatically, as this is required for the `ContextMapper` to work.
        `mapper` - The `ContextMapper` to use for translating each entry.
        `processor` - The `DirContextProcessor` to use before and after the search.
      Returns:
        a `List` containing all entries received from the `ContextMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          <T> List<T> search(Name base,
                             String filter,
                             SearchControls controls,
                             ContextMapper<T> mapper,
                             DirContextProcessor processor)
                      throws NamingException

      Search for all objects matching the supplied filter. The Object returned in each `SearchResult` is supplied to the specified `ContextMapper`. The `SearchScope` specified in the supplied `SearchControls` will be used in the search. The given `DirContextProcessor` will be called before and after the search.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `controls` - The `SearchControls` to use in the search. If the returnObjFlag is not set in the `SearchControls`, this method will set it automatically, as this is required for the `ContextMapper` to work.
        `mapper` - The `ContextMapper` to use for translating each entry.
        `processor` - The `DirContextProcessor` to use before and after the search.
      Returns:
        a `List` containing all entries received from the `ContextMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          void search(String base,
                      String filter,
                      SearchControls controls,
                      NameClassPairCallbackHandler handler,
                      DirContextProcessor processor)
               throws NamingException

      Search for all objects matching the supplied filter. See `search(Name, String, SearchControls, NameClassPairCallbackHandler, DirContextProcessor)` for details.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `controls` - The `SearchControls` to use in the search.
        `handler` - The `NameClassPairCallbackHandler` to supply the `SearchResults` to.
        `processor` - The `DirContextProcessor` to use before and after the search.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          void search(Name base,
                      String filter,
                      int searchScope,
                      boolean returningObjFlag,
                      NameClassPairCallbackHandler handler)
               throws NamingException

      Search for all objects matching the supplied filter. Each `SearchResult` is supplied to the specified `NameClassPairCallbackHandler`. Use the specified values for search scope and return objects flag.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `searchScope` - The search scope to set in `SearchControls` .
        `returningObjFlag` - Whether the bound object should be returned in search results. Must be set to `true` if a `ContextMapper` is used.
        `handler` - The `NameClassPairCallbackHandler` to supply the `SearchResults` to.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          void search(String base,
                      String filter,
                      int searchScope,
                      boolean returningObjFlag,
                      NameClassPairCallbackHandler handler)
               throws NamingException

      Search for all objects matching the supplied filter. Each `SearchResult` is supplied to the specified `NameClassPairCallbackHandler`. Use the specified values for search scope and return objects flag.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `searchScope` - The search scope to set in `SearchControls` .
        `returningObjFlag` - Whether the bound object should be returned in search results. Must be set to `true` if a `ContextMapper` is used.
        `handler` - The `NameClassPairCallbackHandler` to supply the `SearchResults` to.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          void search(Name base,
                      String filter,
                      NameClassPairCallbackHandler handler)
               throws NamingException

      Search for all objects matching the supplied filter. Each `SearchResult` is supplied to the specified `NameClassPairCallbackHandler`. The default Search scope ( `SearchControls.SUBTREE_SCOPE`) will be used and the returnObjects flag will be set to `false`.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `handler` - The `NameClassPairCallbackHandler` to supply the `SearchResults` to.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          void search(String base,
                      String filter,
                      NameClassPairCallbackHandler handler)
               throws NamingException

      Search for all objects matching the supplied filter. Each `SearchResult` is supplied to the specified `NameClassPairCallbackHandler`. The default Search scope ( `SearchControls.SUBTREE_SCOPE`) will be used and the returnObjects flag will be set to `false`.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `handler` - The `NameClassPairCallbackHandler` to supply the `SearchResults` to.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          <T> List<T> search(Name base,
                             String filter,
                             int searchScope,
                             String[] attrs,
                             AttributesMapper<T> mapper)
                      throws NamingException

      Search for all objects matching the supplied filter. Only return any attributes mathing the specified attribute names. The Attributes in each `SearchResult` is supplied to the specified `AttributesMapper`.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `searchScope` - The search scope to set in `SearchControls` .
        `attrs` - The attributes to return, `null` means returning all attributes.
        `mapper` - The `AttributesMapper` to use for translating each entry.
      Returns:
        a `List` containing all entries received from the `AttributesMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          <T> List<T> search(String base,
                             String filter,
                             int searchScope,
                             String[] attrs,
                             AttributesMapper<T> mapper)
                      throws NamingException

      Search for all objects matching the supplied filter. Only return any attributes mathing the specified attribute names. The Attributes in each `SearchResult` is supplied to the specified `AttributesMapper`.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `searchScope` - The search scope to set in `SearchControls` .
        `attrs` - The attributes to return, `null` means returning all attributes.
        `mapper` - The `AttributesMapper` to use for translating each entry.
      Returns:
        a `List` containing all entries received from the `AttributesMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          <T> List<T> search(Name base,
                             String filter,
                             int searchScope,
                             AttributesMapper<T> mapper)
                      throws NamingException

      Search for all objects matching the supplied filter. The Attributes in each `SearchResult` is supplied to the specified `AttributesMapper`.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `searchScope` - The search scope to set in `SearchControls` .
        `mapper` - The `AttributesMapper` to use for translating each entry.
      Returns:
        a `List` containing all entries received from the `AttributesMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          <T> List<T> search(String base,
                             String filter,
                             int searchScope,
                             AttributesMapper<T> mapper)
                      throws NamingException

      Search for all objects matching the supplied filter. The Attributes in each `SearchResult` is supplied to the specified `AttributesMapper`.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `searchScope` - The search scope to set in `SearchControls` .
        `mapper` - The `AttributesMapper` to use for translating each entry.
      Returns:
        a `List` containing all entries received from the `AttributesMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          <T> List<T> search(Name base,
                             String filter,
                             AttributesMapper<T> mapper)
                      throws NamingException

      Search for all objects matching the supplied filter. The Attributes in each `SearchResult` is supplied to the specified `AttributesMapper`. The default search scope will be used.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `mapper` - The `AttributesMapper` to use for translating each entry.
      Returns:
        a `List` containing all entries received from the `AttributesMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          <T> List<T> search(String base,
                             String filter,
                             AttributesMapper<T> mapper)
                      throws NamingException

      Search for all objects matching the supplied filter. The Attributes in each `SearchResult` is supplied to the specified `AttributesMapper`. The default search scope will be used.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `mapper` - The `AttributesMapper` to use for translating each entry.
      Returns:
        a `List` containing all entries received from the `AttributesMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          <T> List<T> search(Name base,
                             String filter,
                             int searchScope,
                             String[] attrs,
                             ContextMapper<T> mapper)
                      throws NamingException

      Search for all objects matching the supplied filter. The `Object` returned in each `SearchResult` is supplied to the specified `ContextMapper`. Only return the supplied attributes.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `searchScope` - The search scope to set in `SearchControls` .
        `attrs` - The attributes to return, `null` means all attributes.
        `mapper` - The `ContextMapper` to use for translating each entry.
      Returns:
        a `List` containing all entries received from the `ContextMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          <T> List<T> search(String base,
                             String filter,
                             int searchScope,
                             String[] attrs,
                             ContextMapper<T> mapper)
                      throws NamingException

      Search for all objects matching the supplied filter. The `Object` returned in each `SearchResult` is supplied to the specified `ContextMapper`. Only return the supplied attributes.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `searchScope` - The search scope to set in `SearchControls` .
        `attrs` - The attributes to return, `null` means all attributes.
        `mapper` - The `ContextMapper` to use for translating each entry.
      Returns:
        a `List` containing all entries received from the `ContextMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          <T> List<T> search(Name base,
                             String filter,
                             int searchScope,
                             ContextMapper<T> mapper)
                      throws NamingException

      Search for all objects matching the supplied filter. The `Object` returned in each `SearchResult` is supplied to the specified `ContextMapper`.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `searchScope` - The search scope to set in `SearchControls` .
        `mapper` - The `ContextMapper` to use for translating each entry.
      Returns:
        a `List` containing all entries received from the `ContextMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          <T> List<T> search(String base,
                             String filter,
                             int searchScope,
                             ContextMapper<T> mapper)
                      throws NamingException

      Search for all objects matching the supplied filter. The `Object` returned in each `SearchResult` is supplied to the specified `ContextMapper`.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `searchScope` - The search scope to set in `SearchControls` .
        `mapper` - The `ContextMapper` to use for translating each entry.
      Returns:
        a `List` containing all entries received from the `ContextMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          <T> List<T> search(Name base,
                             String filter,
                             ContextMapper<T> mapper)
                      throws NamingException

      Search for all objects matching the supplied filter. The `Object` returned in each `SearchResult` is supplied to the specified `ContextMapper`. The default search scope (`SearchControls.SUBTREE_SCOPE`) will be used.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `mapper` - The `ContextMapper` to use for translating each entry.
      Returns:
        a `List` containing all entries received from the `ContextMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          <T> List<T> search(String base,
                             String filter,
                             ContextMapper<T> mapper)
                      throws NamingException

      Search for all objects matching the supplied filter. The `Object` returned in each `SearchResult` is supplied to the specified `ContextMapper`. The default search scope (`SearchControls.SUBTREE_SCOPE`) will be used.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `mapper` - The `ContextMapper` to use for translating each entry.
      Returns:
        a `List` containing all entries received from the `ContextMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          <T> List<T> search(String base,
                             String filter,
                             SearchControls controls,
                             ContextMapper<T> mapper)
                      throws NamingException

      Search for all objects matching the supplied filter. The `Object` returned in each `SearchResult` is supplied to the specified `ContextMapper`. The default search scope (`SearchControls.SUBTREE_SCOPE`) will be used.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `mapper` - The `ContextMapper` to use for translating each entry.
      Returns:
        a `List` containing all entries received from the `ContextMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          <T> List<T> search(Name base,
                             String filter,
                             SearchControls controls,
                             ContextMapper<T> mapper)
                      throws NamingException

      Search for all objects matching the supplied filter. The Object returned in each `SearchResult` is supplied to the specified `ContextMapper`.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `controls` - The `SearchControls` to use in the search. If the returnObjFlag is not set in the `SearchControls`, this method will set it automatically, as this is required for the `ContextMapper` to work.
        `mapper` - The `ContextMapper` to use for translating each entry.
      Returns:
        a `List` containing all entries received from the `ContextMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          <T> List<T> search(String base,
                             String filter,
                             SearchControls controls,
                             AttributesMapper<T> mapper)
                      throws NamingException

      Search for all objects matching the supplied filter. The Attributes returned in each `SearchResult` is supplied to the specified `AttributesMapper`.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `controls` - The `SearchControls` to use in the search.
        `mapper` - The `AttributesMapper` to use for translating each entry.
      Returns:
        a `List` containing all entries received from the `ContextMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### search

          <T> List<T> search(Name base,
                             String filter,
                             SearchControls controls,
                             AttributesMapper<T> mapper)
                      throws NamingException

      Search for all objects matching the supplied filter. The Attributes returned in each `SearchResult` is supplied to the specified `AttributesMapper`.
      Parameters:
        `base` - The base DN where the search should begin.
        `filter` - The filter to use in the search.
        `controls` - The `SearchControls` to use in the search.
        `mapper` - The `AttributesMapper` to use for translating each entry.
      Returns:
        a `List` containing all entries received from the `ContextMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### list

          void list(String base,
                    NameClassPairCallbackHandler handler)
             throws NamingException

      Perform a non-recursive listing of the children of the given `base`. Each resulting `NameClassPair` is supplied to the specified `NameClassPairCallbackHandler`.
      Parameters:
        `base` - The base DN where the list should be performed.
        `handler` - The `NameClassPairCallbackHandler` to supply each `NameClassPair` to.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### list

          void list(Name base,
                    NameClassPairCallbackHandler handler)
             throws NamingException

      Perform a non-recursive listing of the children of the given `base`. Each resulting `NameClassPair` is supplied to the specified `NameClassPairCallbackHandler`.
      Parameters:
        `base` - The base DN where the list should be performed.
        `handler` - The `NameClassPairCallbackHandler` to supply each `NameClassPair` to.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### list

          <T> List<T> list(String base,
                           NameClassPairMapper<T> mapper)
                    throws NamingException

      Perform a non-recursive listing of the children of the given `base`. Pass all the found `NameClassPair` objects to the supplied `NameClassPairMapper` and return all the returned values as a `List`.
      Parameters:
        `base` - The base DN where the list should be performed.
        `mapper` - The `NameClassPairMapper` to supply each `NameClassPair` to.
      Returns:
        a `List` containing the Objects returned from the Mapper.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### list

          <T> List<T> list(Name base,
                           NameClassPairMapper<T> mapper)
                    throws NamingException

      Perform a non-recursive listing of the children of the given `base`. Pass all the found `NameClassPair` objects to the supplied `NameClassPairMapper` and return all the returned values as a `List`.
      Parameters:
        `base` - The base DN where the list should be performed.
        `mapper` - The `NameClassPairMapper` to supply each `NameClassPair` to.
      Returns:
        a `List` containing the Objects returned from the Mapper.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### list

          List<String> list(String base)
                     throws NamingException

      Perform a non-recursive listing of the children of the given `base`.
      Parameters:
        `base` - The base DN where the list should be performed.
      Returns:
        a List containing the names of all the contexts bound to `base`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### list

          List<String> list(Name base)
                     throws NamingException

      Perform a non-recursive listing of the children of the given `base`.
      Parameters:
        `base` - The base DN where the list should be performed.
      Returns:
        a List containing the names of all the contexts bound to `base`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### listBindings

          void listBindings(String base,
                            NameClassPairCallbackHandler handler)
                     throws NamingException

      Perform a non-recursive listing of the children of the given `base`. Each resulting `Binding` is supplied to the specified `NameClassPairCallbackHandler`.
      Parameters:
        `base` - The base DN where the list should be performed.
        `handler` - The `NameClassPairCallbackHandler` to supply each `Binding` to.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### listBindings

          void listBindings(Name base,
                            NameClassPairCallbackHandler handler)
                     throws NamingException

      Perform a non-recursive listing of the children of the given `base`. Each resulting `Binding` is supplied to the specified `NameClassPairCallbackHandler`.
      Parameters:
        `base` - The base DN where the list should be performed.
        `handler` - The `NameClassPairCallbackHandler` to supply each `Binding` to.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### listBindings

          <T> List<T> listBindings(String base,
                                   NameClassPairMapper<T> mapper)
                            throws NamingException

      Perform a non-recursive listing of the children of the given `base`. Pass all the found `Binding` objects to the supplied `NameClassPairMapper` and return all the returned values as a `List`.
      Parameters:
        `base` - The base DN where the list should be performed.
        `mapper` - The `NameClassPairMapper` to supply each `Binding` to.
      Returns:
        a `List` containing the Objects returned from the Mapper.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### listBindings

          <T> List<T> listBindings(Name base,
                                   NameClassPairMapper<T> mapper)
                            throws NamingException

      Perform a non-recursive listing of the children of the given `base`. Pass all the found `Binding` objects to the supplied `NameClassPairMapper` and return all the returned values as a `List`.
      Parameters:
        `base` - The base DN where the list should be performed.
        `mapper` - The `NameClassPairMapper` to supply each `Binding` to.
      Returns:
        a `List` containing the Objects returned from the Mapper.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### listBindings

          List<String> listBindings(String base)
                             throws NamingException

      Perform a non-recursive listing of children of the given `base`.
      Parameters:
        `base` - The base DN where the list should be performed.
      Returns:
        a `List` containing the names of all the contexts bound to `base`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### listBindings

          List<String> listBindings(Name base)
                             throws NamingException

      Perform a non-recursive listing of children of the given `base`.
      Parameters:
        `base` - The base DN where the list should be performed.
      Returns:
        a `List` containing the names of all the contexts bound to `base`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### listBindings

          <T> List<T> listBindings(String base,
                                   ContextMapper<T> mapper)
                            throws NamingException

      Perform a non-recursive listing of the children of the given `base`. The Object returned in each `Binding` is supplied to the specified `ContextMapper`.
      Parameters:
        `base` - The base DN where the list should be performed.
        `mapper` - The `ContextMapper` to use for mapping the found object.
      Returns:
        a `List` containing all entries received from the `ContextMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### listBindings

          <T> List<T> listBindings(Name base,
                                   ContextMapper<T> mapper)
                            throws NamingException

      Perform a non-recursive listing of the children of the given `base`. The Object returned in each `Binding` is supplied to the specified `ContextMapper`.
      Parameters:
        `base` - The base DN where the list should be performed.
        `mapper` - The `ContextMapper` to use for mapping the found object.
      Returns:
        a `List` containing all entries received from the `ContextMapper`.
      Throws:
        `NamingException` - if any error occurs. Note that a `NameNotFoundException` will be ignored. Instead this is interpreted that no entries were found.

    - #### lookup

          Object lookup(Name dn)
                 throws NamingException

      Lookup the supplied DN and return the found object. This will typically be a `DirContextAdapter`, unless the `DirObjectFactory` has been modified in the `ContextSource`.
      Parameters:
        `dn` - The distinguished name of the object to find.
      Returns:
        the found object, typically a `DirContextAdapter` instance.
      Throws:
        `NamingException` - if any error occurs.
      See Also:
        `lookupContext(Name)`, `AbstractContextSource.setDirObjectFactory(Class)`

    - #### lookup

          Object lookup(String dn)
                 throws NamingException

      Lookup the supplied DN and return the found object. This will typically be a `DirContextAdapter`, unless the `DirObjectFactory` has been modified in the `ContextSource`.
      Parameters:
        `dn` - The distinguished name of the object to find.
      Returns:
        the found object, typically a `DirContextAdapter` instance.
      Throws:
        `NamingException` - if any error occurs.
      See Also:
        `lookupContext(String)`, `AbstractContextSource.setDirObjectFactory(Class)`

    - #### lookup

          <T> T lookup(Name dn,
                       AttributesMapper<T> mapper)
                throws NamingException

      Convenience method to get the attributes of a specified DN and automatically pass them to an `AttributesMapper`.
      Parameters:
        `dn` - The distinguished name to find.
        `mapper` - The `AttributesMapper` to use for mapping the found object.
      Returns:
        the object returned from the mapper.
      Throws:
        `NamingException` - if any error occurs.

    - #### lookup

          <T> T lookup(String dn,
                       AttributesMapper<T> mapper)
                throws NamingException

      Convenience method to get the attributes of a specified DN and automatically pass them to an `AttributesMapper`.
      Parameters:
        `dn` - The distinguished name to find.
        `mapper` - The `AttributesMapper` to use for mapping the found object.
      Returns:
        the object returned from the mapper.
      Throws:
        `NamingException` - if any error occurs.

    - #### lookup

          <T> T lookup(Name dn,
                       ContextMapper<T> mapper)
                throws NamingException

      Convenience method to lookup a specified DN and automatically pass the found object to a `ContextMapper`.
      Parameters:
        `dn` - The distinguished name to find.
        `mapper` - The `ContextMapper` to use for mapping the found object.
      Returns:
        the object returned from the mapper.
      Throws:
        `NamingException` - if any error occurs.

    - #### lookup

          <T> T lookup(String dn,
                       ContextMapper<T> mapper)
                throws NamingException

      Convenience method to lookup a specified DN and automatically pass the found object to a `ContextMapper`.
      Parameters:
        `dn` - The distinguished name to find.
        `mapper` - The `ContextMapper` to use for mapping the found object.
      Returns:
        the object returned from the mapper.
      Throws:
        `NamingException` - if any error occurs.

    - #### lookup

          <T> T lookup(Name dn,
                       String[] attributes,
                       AttributesMapper<T> mapper)
                throws NamingException

      Convenience method to get the specified attributes of a specified DN and automatically pass them to an `AttributesMapper`.
      Parameters:
        `dn` - The distinguished name to find.
        `attributes` - The names of the attributes to pass to the mapper.
        `mapper` - The `AttributesMapper` to use for mapping the found object.
      Returns:
        the object returned from the mapper.
      Throws:
        `NamingException` - if any error occurs.

    - #### lookup

          <T> T lookup(String dn,
                       String[] attributes,
                       AttributesMapper<T> mapper)
                throws NamingException

      Convenience method to get the specified attributes of a specified DN and automatically pass them to an `AttributesMapper`.
      Parameters:
        `dn` - The distinguished name to find.
        `attributes` - The names of the attributes to pass to the mapper.
        `mapper` - The `AttributesMapper` to use for mapping the found object.
      Returns:
        the object returned from the mapper.
      Throws:
        `NamingException` - if any error occurs.

    - #### lookup

          <T> T lookup(Name dn,
                       String[] attributes,
                       ContextMapper<T> mapper)
                throws NamingException

      Convenience method to get the specified attributes of a specified DN and automatically pass them to a `ContextMapper`.
      Parameters:
        `dn` - The distinguished name to find.
        `attributes` - The names of the attributes to pass to the mapper.
        `mapper` - The `ContextMapper` to use for mapping the found object.
      Returns:
        the object returned from the mapper.
      Throws:
        `NamingException` - if any error occurs.

    - #### lookup

          <T> T lookup(String dn,
                       String[] attributes,
                       ContextMapper<T> mapper)
                throws NamingException

      Convenience method to get the specified attributes of a specified DN and automatically pass them to a `ContextMapper`.
      Parameters:
        `dn` - The distinguished name to find.
        `attributes` - The names of the attributes to pass to the mapper.
        `mapper` - The `ContextMapper` to use for mapping the found object.
      Returns:
        the object returned from the mapper.
      Throws:
        `NamingException` - if any error occurs.

    - #### modifyAttributes

          void modifyAttributes(Name dn,
                                ModificationItem[] mods)
                         throws NamingException

      Modify an entry in the LDAP tree using the supplied `ModificationItems`.
      Parameters:
        `dn` - The distinguished name of the node to modify.
        `mods` - The modifications to perform.
      Throws:
        `NamingException` - if any error occurs.
      See Also:
        `modifyAttributes(DirContextOperations)`

    - #### modifyAttributes

          void modifyAttributes(String dn,
                                ModificationItem[] mods)
                         throws NamingException

      Modify an entry in the LDAP tree using the supplied `ModificationItems`.
      Parameters:
        `dn` - The distinguished name of the node to modify.
        `mods` - The modifications to perform.
      Throws:
        `NamingException` - if any error occurs.
      See Also:
        `modifyAttributes(DirContextOperations)`

    - #### bind

          void bind(Name dn,
                    Object obj,
                    Attributes attributes)
             throws NamingException

      Create an entry in the LDAP tree. The attributes used to create the entry are either retrieved from the `obj` parameter or the `attributes` parameter (or both). One of these parameters may be `null` but not both.
      Parameters:
        `dn` - The distinguished name to bind the object and attributes to.
        `obj` - The object to bind, may be `null`. Typically a `DirContext` implementation.
        `attributes` - The attributes to bind, may be `null`.
      Throws:
        `NamingException` - if any error occurs.
      See Also:
        `DirContextAdapter`

    - #### bind

          void bind(String dn,
                    Object obj,
                    Attributes attributes)
             throws NamingException

      Create an entry in the LDAP tree. The attributes used to create the entry are either retrieved from the `obj` parameter or the `attributes` parameter (or both). One of these parameters may be `null` but not both.
      Parameters:
        `dn` - The distinguished name to bind the object and attributes to.
        `obj` - The object to bind, may be `null`. Typically a `DirContext` implementation.
        `attributes` - The attributes to bind, may be `null`.
      Throws:
        `NamingException` - if any error occurs.
      See Also:
        `DirContextAdapter`

    - #### unbind

          void unbind(Name dn)
               throws NamingException

      Remove an entry from the LDAP tree. The entry must not have any children - if you suspect that the entry might have descendants, use `unbind(Name, boolean)` in stead.
      Parameters:
        `dn` - The distinguished name of the entry to remove.
      Throws:
        `NamingException` - if any error occurs.

    - #### unbind

          void unbind(String dn)
               throws NamingException

      Remove an entry from the LDAP tree. The entry must not have any children - if you suspect that the entry might have descendants, use `unbind(Name, boolean)` in stead.
      Parameters:
        `dn` - The distinguished name to unbind.
      Throws:
        `NamingException` - if any error occurs.

    - #### unbind

          void unbind(Name dn,
                      boolean recursive)
               throws NamingException

      Remove an entry from the LDAP tree, optionally removing all descendants in the process.
      Parameters:
        `dn` - The distinguished name to unbind.
        `recursive` - Whether to unbind all subcontexts as well. If this parameter is `false` and the entry has children, the operation will fail.
      Throws:
        `NamingException` - if any error occurs.

    - #### unbind

          void unbind(String dn,
                      boolean recursive)
               throws NamingException

      Remove an entry from the LDAP tree, optionally removing all descendants in the process.
      Parameters:
        `dn` - The distinguished name to unbind.
        `recursive` - Whether to unbind all subcontexts as well. If this parameter is `false` and the entry has children, the operation will fail.
      Throws:
        `NamingException` - if any error occurs.

    - #### rebind

          void rebind(Name dn,
                      Object obj,
                      Attributes attributes)
               throws NamingException

      Remove an entry and replace it with a new one. The attributes used to create the entry are either retrieved from the `obj` parameter or the `attributes` parameter (or both). One of these parameters may be `null` but not both. This method assumes that the specified context already exists - if not it will fail.
      Parameters:
        `dn` - The distinguished name to rebind.
        `obj` - The object to bind to the DN, may be `null`. Typically a `DirContext` implementation.
        `attributes` - The attributes to bind, may be `null`.
      Throws:
        `NamingException` - if any error occurs.
      See Also:
        `DirContextAdapter`

    - #### rebind

          void rebind(String dn,
                      Object obj,
                      Attributes attributes)
               throws NamingException

      Remove an entry and replace it with a new one. The attributes used to create the entry are either retrieved from the `obj` parameter or the `attributes` parameter (or both). One of these parameters may be `null` but not both. This method assumes that the specified context already exists - if not it will fail.
      Parameters:
        `dn` - The distinguished name to rebind.
        `obj` - The object to bind to the DN, may be `null`. Typically a `DirContext` implementation.
        `attributes` - The attributes to bind, may be `null`.
      Throws:
        `NamingException` - if any error occurs.
      See Also:
        `DirContextAdapter`

    - #### rename

          void rename(Name oldDn,
                      Name newDn)
               throws NamingException

      Move an entry in the LDAP tree to a new location.
      Parameters:
        `oldDn` - The distinguished name of the entry to move; may not be `null` or empty.
        `newDn` - The distinguished name where the entry should be moved; may not be `null` or empty.
      Throws:
        `ContextNotEmptyException` - if newDn is already bound
        `NamingException` - if any other error occurs.

    - #### rename

          void rename(String oldDn,
                      String newDn)
               throws NamingException

      Move an entry in the LDAP tree to a new location.
      Parameters:
        `oldDn` - The distinguished name of the entry to move; may not be `null` or empty.
        `newDn` - The distinguished name where the entry should be moved; may not be `null` or empty.
      Throws:
        `ContextNotEmptyException` - if newDn is already bound
        `NamingException` - if any other error occurs.

    - #### lookupContext

          DirContextOperations lookupContext(Name dn)
                                      throws NamingException,
                                             ClassCastException

      Convenience method to lookup the supplied DN and automatically cast it to `DirContextOperations`.
      Parameters:
        `dn` - The distinguished name of the object to find.
      Returns:
        The found object, cast to `DirContextOperations`.
      Throws:
        `ClassCastException` - if an alternative `DirObjectFactory` has been registered with the `ContextSource`, causing the actual class of the returned object to be something else than `DirContextOperations`.
        `NamingException` - if any other error occurs.
      Since:
        1.2
      See Also:
        `lookup(Name)`, `modifyAttributes(DirContextOperations)`

    - #### lookupContext

          DirContextOperations lookupContext(String dn)
                                      throws NamingException,
                                             ClassCastException

      Convenience method to lookup the supplied DN and automatically cast it to `DirContextOperations`.
      Parameters:
        `dn` - The distinguished name of the object to find.
      Returns:
        The found object, cast to `DirContextOperations`.
      Throws:
        `ClassCastException` - if an alternative `DirObjectFactory` has been registered with the `ContextSource`, causing the actual class of the returned object to be something else than `DirContextOperations`.
        `NamingException` - if any other error occurs.
      Since:
        1.2
      See Also:
        `lookup(String)`, `modifyAttributes(DirContextOperations)`

    - #### modifyAttributes

          void modifyAttributes(DirContextOperations ctx)
                         throws IllegalStateException,
                                NamingException

      Modify the attributes of the entry referenced by the supplied `DirContextOperations` instance. The DN to update will be the DN of the `DirContextOperations`instance, and the `ModificationItem` array is retrieved from the `DirContextOperations` instance using a call to `AttributeModificationsAware.getModificationItems()`. NB: The supplied instance needs to have been properly initialized; this means that if it hasn't been received from a `lookup` operation, its DN needs to be initialized and it must have been put in update mode ( `DirContextAdapter.setUpdateMode(boolean)`).

      Typical use of this method would be as follows:

           public void update(Person person) {
                  DirContextOperations ctx = ldapOperations.lookupContext(person.getDn());

                  ctx.setAttributeValue("description", person.getDescription());
                  ctx.setAttributeValue("telephoneNumber", person.getPhone());
                  // More modifications here

                  ldapOperations.modifyAttributes(ctx);
           }

      Parameters:
        `ctx` - the DirContextOperations instance to use in the update.
      Throws:
        `IllegalStateException` - if the supplied instance is not in update mode or has not been properly initialized.
        `NamingException` - if any other error occurs.
      Since:
        1.2
      See Also:
        `lookupContext(Name)`, `DirContextAdapter`

    - #### bind

          void bind(DirContextOperations ctx)

      Bind the data in the supplied context in the tree. All specified attributes `ctx`in will be bound to the DN set on `ctx`.

      Example:

           DirContextOperations ctx = new DirContextAdapter(dn);
           ctx.setAttributeValue("cn", "john doe");
           ctx.setAttributeValue("description", "some description");
           //More initialization here.

           ldapTemplate.bind(ctx);

      Parameters:
        `ctx` - the context to bind
      Throws:
        `IllegalStateException` - if no DN is set or if the instance is in update mode.
      Since:
        1.3

    - #### rebind

          void rebind(DirContextOperations ctx)

      Remove an entry and replace it with a new one. The attributes used to create the entry are retrieved from the `ctx` parameter. This method assumes that the specified context already exists - if not it will fail. The entry will be bound to the DN set on `ctx`.

      Example:

           DirContextOperations ctx = new DirContextAdapter(dn);
           ctx.setAttributeValue("cn", "john doe");
           ctx.setAttributeValue("description", "some description");
           //More initialization here.

           ldapTemplate.rebind(ctx);

      Parameters:
        `ctx` - the context to rebind
      Throws:
        `IllegalStateException` - if no DN is set or if the instance is in update mode.
      Since:
        1.3

    - #### authenticate

          boolean authenticate(Name base,
                               String filter,
                               String password)

      Deprecated. use `authenticate(org.springframework.ldap.query.LdapQuery, String)` or `authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)`
      Utility method to perform a simple LDAP 'bind' authentication. Search for the LDAP entry to authenticate using the supplied base DN and filter; use the DN of the found entry together with the password as input to `ContextSource.getContext(String, String)`, thus authenticating the entry.

      Example:

           AndFilter filter = new AndFilter();
           filter.and("objectclass", "person").and("uid", userId);
           boolean authenticated = ldapTemplate.authenticate(LdapUtils.emptyLdapName(), filter.toString(), password);

      Parameters:
        `base` - the DN to use as the base of the search.
        `filter` - the search filter - must result in a unique result.
        `password` - the password to use for authentication.
      Returns:
        `true` if the authentication was successful, `false` otherwise.
      Since:
        1.3

    - #### authenticate

          boolean authenticate(String base,
                               String filter,
                               String password)

      Deprecated. use `authenticate(org.springframework.ldap.query.LdapQuery, String)` or `authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)`
      Utility method to perform a simple LDAP 'bind' authentication. Search for the LDAP entry to authenticate using the supplied base DN and filter; use the DN of the found entry together with the password as input to `ContextSource.getContext(String, String)`, thus authenticating the entry.

      Example:

           AndFilter filter = new AndFilter();
           filter.and("objectclass", "person").and("uid", userId);
           boolean authenticated = ldapTemplate.authenticate(LdapUtils.emptyLdapName(), filter.toString(), password);

      Parameters:
        `base` - the DN to use as the base of the search.
        `filter` - the search filter - must result in a unique result.
        `password` - the password to use for authentication.
      Returns:
        `true` if the authentication was successful, `false` otherwise.
      Since:
        1.3

    - #### authenticate

          boolean authenticate(Name base,
                               String filter,
                               String password,
                               AuthenticatedLdapEntryContextCallback callback)

      Deprecated. use `authenticate(org.springframework.ldap.query.LdapQuery, String)` or `authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)`
      Utility method to perform a simple LDAP 'bind' authentication. Search for the LDAP entry to authenticate using the supplied base DN and filter; use the DN of the found entry together with the password as input to `ContextSource.getContext(String, String)`, thus authenticating the entry. The resulting DirContext instance is then used as input to the supplied `AuthenticatedLdapEntryContextCallback` to perform any additional LDAP operations against the authenticated DirContext.
      Parameters:
        `base` - the DN to use as the base of the search.
        `filter` - the search filter - must result in a unique result.
        `password` - the password to use for authentication.
        `callback` - the callback to that will be called to perform operations on the DirContext authenticated with the found user.
      Returns:
        `true` if the authentication was successful, `false` otherwise.
      Since:
        1.3
      See Also:
        `authenticate(Name, String, String)`

    - #### authenticate

          boolean authenticate(String base,
                               String filter,
                               String password,
                               AuthenticatedLdapEntryContextCallback callback)

      Deprecated. use `authenticate(org.springframework.ldap.query.LdapQuery, String)` or `authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)`
      Utility method to perform a simple LDAP 'bind' authentication. Search for the LDAP entry to authenticate using the supplied base DN and filter; use the DN of the found entry together with the password as input to `ContextSource.getContext(String, String)`, thus authenticating the entry. The resulting DirContext instance is then used as input to the supplied `AuthenticatedLdapEntryContextCallback` to perform any additional LDAP operations against the authenticated DirContext.
      Parameters:
        `base` - the DN to use as the base of the search.
        `filter` - the search filter - must result in a unique result.
        `password` - the password to use for authentication.
        `callback` - the callback to that will be called to perform operations on the DirContext authenticated with the found user.
      Returns:
        `true` if the authentication was successful, `false` otherwise.
      Since:
        1.3
      See Also:
        `authenticate(String, String, String)`

    - #### authenticate

          boolean authenticate(Name base,
                               String filter,
                               String password,
                               AuthenticatedLdapEntryContextCallback callback,
                               AuthenticationErrorCallback errorCallback)

      Deprecated. use `authenticate(org.springframework.ldap.query.LdapQuery, String)` or `authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)`
      Utility method to perform a simple LDAP 'bind' authentication. Search for the LDAP entry to authenticate using the supplied base DN and filter; use the DN of the found entry together with the password as input to `ContextSource.getContext(String, String)`, thus authenticating the entry. The resulting DirContext instance is then used as input to the supplied `AuthenticatedLdapEntryContextCallback` to perform any additional LDAP operations against the authenticated DirContext. If an exception is caught, the same exception is passed on to the given `AuthenticationErrorCallback`. This enables the caller to provide a callback that, for example, collects the exception for later processing.
      Parameters:
        `base` - the DN to use as the base of the search.
        `filter` - the search filter - must result in a unique result.
        `password` - the password to use for authentication.
        `callback` - the callback that will be called to perform operations on the DirContext authenticated with the found user.
        `errorCallback` - the callback that will be called if an exception is caught.
      Returns:
        `true` if the authentication was successful, `false` otherwise.
      Since:
        1.3.1
      See Also:
        `authenticate(Name, String, String, AuthenticatedLdapEntryContextCallback)`

    - #### authenticate

          boolean authenticate(String base,
                               String filter,
                               String password,
                               AuthenticatedLdapEntryContextCallback callback,
                               AuthenticationErrorCallback errorCallback)

      Deprecated. use `authenticate(org.springframework.ldap.query.LdapQuery, String)` or `authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)`
      Utility method to perform a simple LDAP 'bind' authentication. Search for the LDAP entry to authenticate using the supplied base DN and filter; use the DN of the found entry together with the password as input to `ContextSource.getContext(String, String)`, thus authenticating the entry. The resulting DirContext instance is then used as input to the supplied `AuthenticatedLdapEntryContextCallback` to perform any additional LDAP operations against the authenticated DirContext. If an exception is caught, the same exception is passed on to the given `AuthenticationErrorCallback`. This enables the caller to provide a callback that, for example, collects the exception for later processing.
      Parameters:
        `base` - the DN to use as the base of the search.
        `filter` - the search filter - must result in a unique result.
        `password` - the password to use for authentication.
        `callback` - the callback that will be called to perform operations on the DirContext authenticated with the found user.
        `errorCallback` - the callback that will be called if an exception is caught.
      Returns:
        `true` if the authentication was successful, `false` otherwise.
      Since:
        1.3.1
      See Also:
        `authenticate(String, String, String, AuthenticatedLdapEntryContextCallback)`

    - #### authenticate

          boolean authenticate(Name base,
                               String filter,
                               String password,
                               AuthenticationErrorCallback errorCallback)

      Deprecated. use `authenticate(org.springframework.ldap.query.LdapQuery, String)` or `authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)`
      Utility method to perform a simple LDAP 'bind' authentication. Search for the LDAP entry to authenticate using the supplied base DN and filter; use the DN of the found entry together with the password as input to `ContextSource.getContext(String, String)`, thus authenticating the entry. If an exception is caught, the same exception is passed on to the given `AuthenticationErrorCallback`. This enables the caller to provide a callback that, for example, collects the exception for later processing.
      Parameters:
        `base` - the DN to use as the base of the search.
        `filter` - the search filter - must result in a unique result.
        `password` - the password to use for authentication.
        `errorCallback` - the callback that will be called if an exception is caught.
      Returns:
        `true` if the authentication was successful, `false` otherwise.
      Since:
        1.3.1
      See Also:
        `authenticate(Name, String, String, AuthenticatedLdapEntryContextCallback, AuthenticationErrorCallback)`

    - #### authenticate

          boolean authenticate(String base,
                               String filter,
                               String password,
                               AuthenticationErrorCallback errorCallback)

      Deprecated. use `authenticate(org.springframework.ldap.query.LdapQuery, String)` or `authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)`
      Utility method to perform a simple LDAP 'bind' authentication. Search for the LDAP entry to authenticate using the supplied base DN and filter; use the DN of the found entry together with the password as input to `ContextSource.getContext(String, String)`, thus authenticating the entry. If an exception is caught, the same exception is passed on to the given `AuthenticationErrorCallback`. This enables the caller to provide a callback that, for example, collects the exception for later processing.
      Parameters:
        `base` - the DN to use as the base of the search.
        `filter` - the search filter - must result in a unique result.
        `password` - the password to use for authentication.
        `errorCallback` - the callback that will be called if an exception is caught.
      Returns:
        `true` if the authentication was successful, `false` otherwise.
      Throws:
        `IncorrectResultSizeDataAccessException` - if more than one users were found
      Since:
        1.3.1

    - #### authenticate

          <T> T authenticate(LdapQuery query,
                             String password,
                             AuthenticatedLdapEntryContextMapper<T> mapper)

      Utility method to perform a simple LDAP 'bind' authentication. Search for the LDAP entry to authenticate using the supplied LdapQuery; use the DN of the found entry together with the password as input to `ContextSource.getContext(String, String)`, thus authenticating the entry.

      Note: This method differs from the older authenticate methods in that encountered exceptions are thrown rather than supplied to a callback for handling.

      Parameters:
        `query` - the LdapQuery specifying the details of the search.
        `password` - the password to use for authentication.
        `mapper` - the callback that will be called to perform operations on the DirContext authenticated with the found user. `false` otherwise.
      Returns:
        the result from the callback.
      Throws:
        `IncorrectResultSizeDataAccessException` - if more than one users were found
        `EmptyResultDataAccessException` - if only one user was found
        `NamingException` - if something went wrong in authentication.
      Since:
        2.0
      See Also:
        `LdapQueryBuilder`

    - #### authenticate

          void authenticate(LdapQuery query,
                            String password)

      Utility method to perform a simple LDAP 'bind' authentication. Search for the LDAP entry to authenticate using the supplied base DN and filter; use the DN of the found entry together with the password as input to `ContextSource.getContext(String, String)`, thus authenticating the entry. If an exception is caught, the same exception is passed on to the given `AuthenticationErrorCallback`. This enables the caller to provide a callback that, for example, collects the exception for later processing.

      Note: This method differs from the older authenticate methods in that encountered exceptions are thrown rather than supplied to a callback for handling.

      Parameters:
        `query` - the LdapQuery specifying the details of the search.
        `password` - the password to use for authentication. `false` otherwise.
      Throws:
        `IncorrectResultSizeDataAccessException` - if more than one users were found
        `EmptyResultDataAccessException` - if only one user was found
        `NamingException` - if something went wrong in authentication.
      Since:
        2.0
      See Also:
        `LdapQueryBuilder`

    - #### searchForObject

          <T> T searchForObject(Name base,
                                String filter,
                                ContextMapper<T> mapper)

      Perform a search for a unique entry matching the specified search criteria and return the found object. If no entry is found or if there are more than one matching entry, an `IncorrectResultSizeDataAccessException` is thrown.
      Parameters:
        `base` - the DN to use as the base of the search.
        `filter` - the search filter.
        `mapper` - the mapper to use for the search.
      Returns:
        the single object returned by the mapper that matches the search criteria.
      Throws:
        `IncorrectResultSizeDataAccessException` - if the result is not one unique entry
      Since:
        1.3

    - #### searchForObject

          <T> T searchForObject(Name base,
                                String filter,
                                SearchControls searchControls,
                                ContextMapper<T> mapper)

      Perform a search for a unique entry matching the specified search criteria and return the found object. If no entry is found or if there are more than one matching entry, an `IncorrectResultSizeDataAccessException` is thrown.
      Parameters:
        `base` - the DN to use as the base of the search.
        `filter` - the search filter.
        `searchControls` - the searchControls to use for the search.
        `mapper` - the mapper to use for the search.
      Returns:
        the single object returned by the mapper that matches the search criteria.
      Throws:
        `IncorrectResultSizeDataAccessException` - if the result is not one unique entry
      Since:
        2.0

    - #### searchForObject

          <T> T searchForObject(String base,
                                String filter,
                                SearchControls searchControls,
                                ContextMapper<T> mapper)

      Perform a search for a unique entry matching the specified search criteria and return the found object. If no entry is found or if there are more than one matching entry, an `IncorrectResultSizeDataAccessException` is thrown.
      Parameters:
        `base` - the DN to use as the base of the search.
        `filter` - the search filter.
        `searchControls` - the searchControls to use for the search.
        `mapper` - the mapper to use for the search.
      Returns:
        the single object returned by the mapper that matches the search criteria.
      Throws:
        `IncorrectResultSizeDataAccessException` - if the result is not one unique entry
      Since:
        2.0

    - #### searchForObject

          <T> T searchForObject(String base,
                                String filter,
                                ContextMapper<T> mapper)

      Perform a search for a unique entry matching the specified search criteria and return the found object. If no entry is found or if there are more than one matching entry, an `IncorrectResultSizeDataAccessException` is thrown.
      Parameters:
        `base` - the DN to use as the base of the search.
        `filter` - the search filter.
        `mapper` - the mapper to use for the search.
      Returns:
        the single object returned by the mapper that matches the search criteria.
      Throws:
        `IncorrectResultSizeDataAccessException` - if the result is not one unique entry
      Since:
        1.3

    - #### search

          void search(LdapQuery query,
                      NameClassPairCallbackHandler callbackHandler)

      Perform a search with parameters from the specified LdapQuery. All found objects will be supplied to the `NameClassPairCallbackHandler` for processing.
      Parameters:
        `query` - the LDAP query specification.
        `callbackHandler` - the `NameClassPairCallbackHandler` to supply all found entries to.
      Throws:
        `NamingException` - if any error occurs.
      Since:
        2.0
      See Also:
        `LdapQueryBuilder`, `CountNameClassPairCallbackHandler`

    - #### search

          <T> List<T> search(LdapQuery query,
                             ContextMapper<T> mapper)

      Perform a search with parameters from the specified LdapQuery. All found objects will be supplied to the `ContextMapper` for processing, and all returned objects will be collected in a list to be returned.
      Parameters:
        `query` - the LDAP query specification.
        `mapper` - the `ContextMapper` to supply all found entries to.
      Returns:
        a `List` containing all entries received from the `ContextMapper`.
      Throws:
        `NamingException` - if any error occurs.
      Since:
        2.0
      See Also:
        `LdapQueryBuilder`

    - #### search

          <T> List<T> search(LdapQuery query,
                             AttributesMapper<T> mapper)

      Perform a search with parameters from the specified LdapQuery. The Attributes of the found entries will be supplied to the `AttributesMapper` for processing, and all returned objects will be collected in a list to be returned.
      Parameters:
        `query` - the LDAP query specification.
        `mapper` - the `Attributes` to supply all found Attributes to.
      Returns:
        a `List` containing all entries received from the `Attributes`.
      Throws:
        `NamingException` - if any error occurs.
      Since:
        2.0
      See Also:
        `LdapQueryBuilder`

    - #### searchForContext

          DirContextOperations searchForContext(LdapQuery query)

      Perform a search for a unique entry matching the specified LDAP query and return the found entry as a DirContextOperation instance. If no entry is found or if there are more than one matching entry, an `IncorrectResultSizeDataAccessException` is thrown.
      Parameters:
        `query` - the LDAP query specification.
      Returns:
        the single entry matching the query as a DirContextOperations instance.
      Throws:
        `IncorrectResultSizeDataAccessException` - if the result is not one unique entry
      Since:
        2.0
      See Also:
        `LdapQueryBuilder`

    - #### searchForObject

          <T> T searchForObject(LdapQuery query,
                                ContextMapper<T> mapper)

      Perform a search for a unique entry matching the specified LDAP query and return the found object. If no entry is found or if there are more than one matching entry, an `IncorrectResultSizeDataAccessException` is thrown.
      Parameters:
        `query` - the LDAP query specification.
      Returns:
        the single object returned by the mapper that matches the search criteria.
      Throws:
        `IncorrectResultSizeDataAccessException` - if the result is not one unique entry
      Since:
        2.0
      See Also:
        `LdapQueryBuilder`

    - #### findByDn

          <T> T findByDn(Name dn,
                         Class<T> clazz)

      Read a named entry from the LDAP directory. The referenced class must have object-directory mapping metadata specified using `Entry` and associated annotations.
      Type Parameters:
        `T` - The Java type to return
      Parameters:
        `dn` - The distinguished name of the entry to read from the LDAP directory.
        `clazz` - The Java type to return
      Returns:
        The entry as read from the directory
      Throws:
        `NamingException` - on error.
      Since:
        2.0

    - #### create

          void create(Object entry)

      Create the given entry in the LDAP directory. The referenced class must have object-directory mapping metadata specified using `Entry` and associated annotations. If the field annotated with `Id` is set in the object, this will be used as the distinguished name of the new entry. If no explicit DN is specified, an attempt will be made to calculate the name from fields annotated with `DnAttribute`. If an id can be calculated, this will be populated in the supplied object.
      Parameters:
        `entry` - The entry to be create, it must not be null or already exist in the directory.
      Throws:
        `NamingException` - on error.
        `IllegalArgumentException` - if the entry is null or on failure to determine the distinguished name.
      Since:
        2.0

    - #### update

          void update(Object entry)

      Update the given entry in the LDAP directory. The referenced class must have object-directory mapping metadata specified using `Entry` and associated annotations. If the distinguished name is not explicitly specified (i.e. if the field annotated with `Id` is `null`), an attempt will be made to calculate the name from fields annotated with `DnAttribute`. If the `Id` field and the calculated DN is different, the entry will be moved (i.e., an `unbind(javax.naming.Name)` followed by a `bind(DirContextOperations)`. Otherwise the current data of the entry will be read from the directory and a `modifyAttributes(DirContextOperations)` operation will be performed using the `ModificationItems` resulting from the changes of the entry compared to its current state in the directory. If the id of the entry has changed, i.e. if it wasn't specified from the beginning, or if it is calculated to have changed, the new value will be populated in the supplied object.
      Parameters:
        `entry` - The entry to update, it must already exist in the directory.
      Throws:
        `NamingException` - on error.
        `IllegalArgumentException` - if the entry is null or on failure to determine the distinguished name.
      Since:
        2.0

    - #### delete

          void delete(Object entry)

      Delete an entry from the LDAP directory. The referenced class must have object-directory mapping metadata specified using `Entry` and associated annotations. If the field annotated with `Id` is set in the object, this will be used as the distinguished name of the new entry. If no explicit DN is specified, an attempt will be made to calculate the name from fields annotated with `DnAttribute`.
      Parameters:
        `entry` - The entry to delete, it must already exist in the directory.
      Throws:
        `NamingException` - on error.
        `IllegalArgumentException` - if the entry is null or on failure to determine the distinguished name.
      Since:
        2.0

    - #### findAll

          <T> List<T> findAll(Class<T> clazz)

      Find all entries in the LDAP directory of a given type. The referenced class must have object-directory mapping metadata specified using `Entry` and associated annotations.
      Type Parameters:
        `T` - The Java type to return
      Parameters:
        `clazz` - The Java type to return
      Returns:
        All entries that are of the type represented by the given Java class
      Throws:
        `NamingException` - on error.
      Since:
        2.0

    - #### findAll

          <T> List<T> findAll(Name base,
                              SearchControls searchControls,
                              Class<T> clazz)

      Find all entries in the LDAP directory of a given type. The referenced class must have object-directory mapping metadata specified using `Entry` and associated annotations.
      Type Parameters:
        `T` - The Java type to return
      Parameters:
        `base` - The root of the sub-tree at which to begin the search.
        `searchControls` - The search controls of the search. Note that the 'returned attributes' parameter should typically not be tampered with, since that may affect the attributes populated in returned entries.
        `clazz` - The Java type to return
      Returns:
        All entries that are of the type represented by the given Java class
      Throws:
        `NamingException` - on error.
      Since:
        2.0

    - #### find

          <T> List<T> find(Name base,
                           Filter filter,
                           SearchControls searchControls,
                           Class<T> clazz)

      Find all entries in the LDAP directory of a given type that matches the specified filter. The referenced class must have object-directory mapping metadata specified using `Entry` and associated annotations.
      Type Parameters:
        `T` - The Java type to return
      Parameters:
        `base` - The root of the sub-tree at which to begin the search.
        `filter` - The search filter.
        `searchControls` - The search controls of the search. Note that the 'returned attributes' parameter should typically not be tampered with, since that may affect the attributes populated in returned entries.
        `clazz` - The Java type to return
      Returns:
        All entries that are of the type represented by the given Java class
      Throws:
        `NamingException` - on error.
      Since:
        2.0

    - #### find

          <T> List<T> find(LdapQuery query,
                           Class<T> clazz)

      Search for entries in the LDAP directory. The referenced class must have object-directory mapping metadata specified using `Entry` and associated annotations.

      Only those entries that both match the query search filter and are represented by the given Java class are returned.

      Type Parameters:
        `T` - The Java type to return
      Parameters:
        `query` - the LDAP query specification
        `clazz` - The Java type to return
      Returns:
        All matching entries.
      Throws:
        `NamingException` - on error.
      Since:
        2.0
      See Also:
        `LdapQueryBuilder`

    - #### findOne

          <T> T findOne(LdapQuery query,
                        Class<T> clazz)

      Search for objects in the directory tree matching the specified LdapQuery, expecting to find exactly one match. The referenced class must have object-directory mapping metadata specified using `Entry` and associated annotations.
      Type Parameters:
        `T` - The Java type to return
      Parameters:
        `query` - the LDAP query specification
        `clazz` - The Java type to return
      Returns:
        The single entry matching the search specification.
      Throws:
        `NamingException` - on LDAP error.
        `EmptyResultDataAccessException` - if no matching entry can be found
        `IncorrectResultSizeDataAccessException` - if more than one matching entry is found
      Since:
        2.0

    - #### getObjectDirectoryMapper

          ObjectDirectoryMapper getObjectDirectoryMapper()

      Get the configured ObjectDirectoryMapper. For internal use.
      Returns:
        the configured ObjectDirectoryMapper.
      Since:
        2.0