org.springframework.ldap.core.LdapOperations Maven / Gradle / Ivy
/*
* Copyright 2005-2010 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.ldap.core;
import org.springframework.dao.IncorrectResultSizeDataAccessException;
import org.springframework.ldap.ContextNotEmptyException;
import org.springframework.ldap.NamingException;
import org.springframework.ldap.core.support.AbstractContextSource;
import org.springframework.ldap.filter.Filter;
import org.springframework.ldap.odm.core.ObjectDirectoryMapper;
import org.springframework.ldap.query.LdapQuery;
import org.springframework.ldap.support.LdapUtils;
import javax.naming.Binding;
import javax.naming.Name;
import javax.naming.NameClassPair;
import javax.naming.directory.Attributes;
import javax.naming.directory.ModificationItem;
import javax.naming.directory.SearchControls;
import java.util.List;
/**
* 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
* @author Ulrik Sandberg
*/
public interface LdapOperations {
/**
* Perform a search using a particular {@link 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
* {@link LdapUtils#convertLdapException(javax.naming.NamingException)}.
*
* @param se The SearchExecutor to use for performing the
* actual search.
* @param handler The NameClassPairCallbackHandler to which
* each found entry will be passed.
* @param 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.
*/
void search(SearchExecutor se, NameClassPairCallbackHandler handler, DirContextProcessor processor)
throws NamingException;
/**
* Perform a search using a particular {@link 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
* {@link LdapUtils#convertLdapException(javax.naming.NamingException)}.
*
* @param se The SearchExecutor to use for performing the
* actual search.
* @param 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 #search(Name, String, AttributesMapper)
* @see #search(Name, String, ContextMapper)
*/
void search(SearchExecutor se, NameClassPairCallbackHandler handler) 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
* {@link #search(SearchExecutor, NameClassPairCallbackHandler)} or any of
* the overloaded search methods for this.
*
* @param ce The ContextExecutor to which the actual operation
* on the DirContext will be delegated.
* @return the result from the ContextExecutor's operation.
* @throws NamingException if the operation resulted in a
* NamingException.
*
* @see #search(SearchExecutor, NameClassPairCallbackHandler)
* @see #search(Name, String, AttributesMapper)
* @see #search(Name, String, ContextMapper)
*/
T executeReadOnly(ContextExecutor 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.
*
* @param ce The ContextExecutor to which the actual operation
* on the DirContext will be delegated.
* @return the result from the ContextExecutor's operation.
* @throws NamingException if the operation resulted in a
* NamingException.
* @see #bind(Name, Object, Attributes)
* @see #unbind(Name)
* @see #rebind(Name, Object, Attributes)
* @see #rename(Name, Name)
* @see #modifyAttributes(Name, ModificationItem[])
*/
T executeReadWrite(ContextExecutor ce) 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.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param controls The SearchControls to use in the search.
* @param 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.
*/
void search(Name base, String filter, SearchControls controls, NameClassPairCallbackHandler handler)
throws NamingException;
/**
* Search for all objects matching the supplied filter. See
* {@link #search(Name, String, SearchControls, NameClassPairCallbackHandler)}
* for details.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param controls The SearchControls to use in the search.
* @param 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.
*/
void search(String 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. The given DirContextProcessor
* will be called before and after the search.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param controls The SearchControls to use in the search.
* @param handler The NameClassPairCallbackHandler to supply
* the SearchResult to.
* @param 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.
*/
void search(Name base, String filter, SearchControls controls, NameClassPairCallbackHandler handler,
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.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param controls The SearchControls to use in the search.
* @param mapper The AttributesMapper to use for translating
* each entry.
* @param processor The DirContextProcessor to use before and
* after the search.
* @return 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.
*/
List search(String base, String filter, SearchControls controls, AttributesMapper 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.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param controls The SearchControls to use in the search.
* @param mapper The AttributesMapper to use for translating
* each entry.
* @param processor The DirContextProcessor to use before and
* after the search.
* @return 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.
*/
List search(Name base, String filter, SearchControls controls, AttributesMapper 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.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param 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.
* @param mapper The ContextMapper to use for translating each
* entry.
* @param processor The DirContextProcessor to use before and
* after the search.
* @return 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 search(String base, String filter, SearchControls controls, ContextMapper 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.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param 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.
* @param mapper The ContextMapper to use for translating each
* entry.
* @param processor The DirContextProcessor to use before and
* after the search.
* @return 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 search(Name base, String filter, SearchControls controls, ContextMapper mapper, DirContextProcessor processor)
throws NamingException;
/**
* Search for all objects matching the supplied filter. See
* {@link #search(Name, String, SearchControls, NameClassPairCallbackHandler, DirContextProcessor)}
* for details.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param controls The SearchControls to use in the search.
* @param handler The NameClassPairCallbackHandler to supply
* the SearchResults to.
* @param 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.
*/
void search(String 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. Use the specified values for
* search scope and return objects flag.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param searchScope The search scope to set in SearchControls
* .
* @param returningObjFlag Whether the bound object should be returned in
* search results. Must be set to true if a
* ContextMapper is used.
* @param 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.
*/
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.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param searchScope The search scope to set in SearchControls
* .
* @param returningObjFlag Whether the bound object should be returned in
* search results. Must be set to true if a
* ContextMapper is used.
* @param 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.
*/
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. The default Search scope (
* SearchControls.SUBTREE_SCOPE) will be used and the
* returnObjects flag will be set to false.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param 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.
*/
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.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param 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.
*/
void search(String base, String filter, NameClassPairCallbackHandler handler) 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.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param searchScope The search scope to set in SearchControls
* .
* @param attrs The attributes to return, null means returning
* all attributes.
* @param mapper The AttributesMapper to use for translating
* each entry.
* @return 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.
*/
List search(Name base, String filter, int searchScope, String[] attrs, AttributesMapper 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.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param searchScope The search scope to set in SearchControls
* .
* @param attrs The attributes to return, null means returning
* all attributes.
* @param mapper The AttributesMapper to use for translating
* each entry.
* @return 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.
*/
List search(String base, String filter, int searchScope, String[] attrs, AttributesMapper mapper)
throws NamingException;
/**
* Search for all objects matching the supplied filter. The Attributes in
* each SearchResult is supplied to the specified
* AttributesMapper.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param searchScope The search scope to set in SearchControls
* .
* @param mapper The AttributesMapper to use for translating
* each entry.
* @return 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.
*/
List search(Name base, String filter, int searchScope, AttributesMapper mapper) throws NamingException;
/**
* Search for all objects matching the supplied filter. The Attributes in
* each SearchResult is supplied to the specified
* AttributesMapper.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param searchScope The search scope to set in SearchControls
* .
* @param mapper The AttributesMapper to use for translating
* each entry.
* @return 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.
*/
List search(String base, String filter, int searchScope, AttributesMapper 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.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param mapper The AttributesMapper to use for translating
* each entry.
* @return 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.
*/
List search(Name base, String filter, AttributesMapper 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.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param mapper The AttributesMapper to use for translating
* each entry.
* @return 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.
*/
List search(String base, String filter, AttributesMapper 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.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param searchScope The search scope to set in SearchControls
* .
* @param attrs The attributes to return, null means all
* attributes.
* @param mapper The ContextMapper to use for translating each
* entry.
* @return 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 search(Name base, String filter, int searchScope, String[] attrs, ContextMapper 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.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param searchScope The search scope to set in SearchControls
* .
* @param attrs The attributes to return, null means all
* attributes.
* @param mapper The ContextMapper to use for translating each
* entry.
* @return 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 search(String base, String filter, int searchScope, String[] attrs, ContextMapper mapper)
throws NamingException;
/**
* Search for all objects matching the supplied filter. The
* Object returned in each SearchResult is
* supplied to the specified ContextMapper.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param searchScope The search scope to set in SearchControls
* .
* @param mapper The ContextMapper to use for translating each
* entry.
* @return 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 search(Name base, String filter, int searchScope, ContextMapper mapper) throws NamingException;
/**
* Search for all objects matching the supplied filter. The
* Object returned in each SearchResult is
* supplied to the specified ContextMapper.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param searchScope The search scope to set in SearchControls
* .
* @param mapper The ContextMapper to use for translating each
* entry.
* @return 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 search(String base, String filter, int searchScope, ContextMapper 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.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param mapper The ContextMapper to use for translating each
* entry.
* @return 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 search(Name base, String filter, ContextMapper 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.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param mapper The ContextMapper to use for translating each
* entry.
* @return 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 search(String base, String filter, ContextMapper 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.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param mapper The ContextMapper to use for translating each
* entry.
* @return 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 search(String base, String filter, SearchControls controls, ContextMapper mapper) throws NamingException;
/**
* Search for all objects matching the supplied filter. The Object returned
* in each SearchResult is supplied to the specified
* ContextMapper.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param 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.
* @param mapper The ContextMapper to use for translating each
* entry.
* @return 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 search(Name base, String filter, SearchControls controls, ContextMapper mapper) throws NamingException;
/**
* Search for all objects matching the supplied filter. The Attributes
* returned in each SearchResult is supplied to the specified
* AttributesMapper.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param controls The SearchControls to use in the search.
* @param mapper The AttributesMapper to use for translating
* each entry.
* @return 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 search(String base, String filter, SearchControls controls, AttributesMapper mapper) throws NamingException;
/**
* Search for all objects matching the supplied filter. The Attributes
* returned in each SearchResult is supplied to the specified
* AttributesMapper.
*
* @param base The base DN where the search should begin.
* @param filter The filter to use in the search.
* @param controls The SearchControls to use in the search.
* @param mapper The AttributesMapper to use for translating
* each entry.
* @return 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 search(Name base, String filter, SearchControls controls, AttributesMapper mapper) throws NamingException;
/**
* Perform a non-recursive listing of the children of the given
* base. Each resulting NameClassPair is supplied
* to the specified NameClassPairCallbackHandler.
*
* @param base The base DN where the list should be performed.
* @param handler The NameClassPairCallbackHandler to supply
* each {@link NameClassPair} to.
* @throws NamingException if any error occurs. Note that a
* NameNotFoundException will be ignored. Instead this is
* interpreted that no entries were found.
*/
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.
*
* @param base The base DN where the list should be performed.
* @param handler The NameClassPairCallbackHandler to supply
* each {@link NameClassPair} to.
* @throws NamingException if any error occurs. Note that a
* NameNotFoundException will be ignored. Instead this is
* interpreted that no entries were found.
*/
void list(Name base, NameClassPairCallbackHandler handler) 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.
*
* @param base The base DN where the list should be performed.
* @param mapper The NameClassPairMapper to supply each
* {@link NameClassPair} to.
* @return 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 base, NameClassPairMapper 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.
*
* @param base The base DN where the list should be performed.
* @param mapper The NameClassPairMapper to supply each
* {@link NameClassPair} to.
* @return 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(Name base, NameClassPairMapper mapper) throws NamingException;
/**
* Perform a non-recursive listing of the children of the given
* base.
*
* @param base The base DN where the list should be performed.
* @return 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 base) throws NamingException;
/**
* Perform a non-recursive listing of the children of the given
* base.
*
* @param base The base DN where the list should be performed.
* @return 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(Name base) throws NamingException;
/**
* Perform a non-recursive listing of the children of the given
* base. Each resulting Binding is supplied to the
* specified NameClassPairCallbackHandler.
*
* @param base The base DN where the list should be performed.
* @param handler The NameClassPairCallbackHandler to supply
* each {@link Binding} to.
* @throws NamingException if any error occurs. Note that a
* NameNotFoundException will be ignored. Instead this is
* interpreted that no entries were found.
*/
void listBindings(final 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.
*
* @param base The base DN where the list should be performed.
* @param handler The NameClassPairCallbackHandler to supply
* each {@link Binding} to.
* @throws NamingException if any error occurs. Note that a
* NameNotFoundException will be ignored. Instead this is
* interpreted that no entries were found.
*/
void listBindings(final Name base, NameClassPairCallbackHandler handler) 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.
*
* @param base The base DN where the list should be performed.
* @param mapper The NameClassPairMapper to supply each
* {@link Binding} to.
* @return 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 listBindings(String base, NameClassPairMapper 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.
*
* @param base The base DN where the list should be performed.
* @param mapper The NameClassPairMapper to supply each
* {@link Binding} to.
* @return 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 listBindings(Name base, NameClassPairMapper mapper) throws NamingException;
/**
* Perform a non-recursive listing of children of the given
* base.
*
* @param base The base DN where the list should be performed.
* @return 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 listBindings(final String base) throws NamingException;
/**
* Perform a non-recursive listing of children of the given
* base.
*
* @param base The base DN where the list should be performed.
* @return 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 listBindings(final Name base) throws NamingException;
/**
* Perform a non-recursive listing of the children of the given
* base. The Object returned in each {@link Binding} is
* supplied to the specified ContextMapper.
*
* @param base The base DN where the list should be performed.
* @param mapper The ContextMapper to use for mapping the found
* object.
* @return 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 listBindings(String base, ContextMapper mapper) throws NamingException;
/**
* Perform a non-recursive listing of the children of the given
* base. The Object returned in each {@link Binding} is
* supplied to the specified ContextMapper.
*
* @param base The base DN where the list should be performed.
* @param mapper The ContextMapper to use for mapping the found
* object.
* @return 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 listBindings(Name base, ContextMapper mapper) throws NamingException;
/**
* Lookup the supplied DN and return the found object. This will typically
* be a {@link DirContextAdapter}, unless the DirObjectFactory
* has been modified in the ContextSource.
*
* @param dn The distinguished name of the object to find.
* @return the found object, typically a {@link DirContextAdapter} instance.
* @throws NamingException if any error occurs.
* @see #lookupContext(Name)
* @see AbstractContextSource#setDirObjectFactory(Class)
*/
Object lookup(Name dn) throws NamingException;
/**
* Lookup the supplied DN and return the found object. This will typically
* be a {@link DirContextAdapter}, unless the DirObjectFactory
* has been modified in the ContextSource.
*
* @param dn The distinguished name of the object to find.
* @return the found object, typically a {@link DirContextAdapter} instance.
* @throws NamingException if any error occurs.
* @see #lookupContext(String)
* @see AbstractContextSource#setDirObjectFactory(Class)
*/
Object lookup(String dn) throws NamingException;
/**
* Convenience method to get the attributes of a specified DN and
* automatically pass them to an AttributesMapper.
*
* @param dn The distinguished name to find.
* @param mapper The AttributesMapper to use for mapping the
* found object.
* @return the object returned from the mapper.
* @throws NamingException if any error occurs.
*/
T lookup(Name dn, AttributesMapper mapper) throws NamingException;
/**
* Convenience method to get the attributes of a specified DN and
* automatically pass them to an AttributesMapper.
*
* @param dn The distinguished name to find.
* @param mapper The AttributesMapper to use for mapping the
* found object.
* @return the object returned from the mapper.
* @throws NamingException if any error occurs.
*/
T lookup(String dn, AttributesMapper mapper) throws NamingException;
/**
* Convenience method to lookup a specified DN and automatically pass the
* found object to a ContextMapper.
*
* @param dn The distinguished name to find.
* @param mapper The ContextMapper to use for mapping the found
* object.
* @return the object returned from the mapper.
* @throws NamingException if any error occurs.
*/
T lookup(Name dn, ContextMapper mapper) throws NamingException;
/**
* Convenience method to lookup a specified DN and automatically pass the
* found object to a ContextMapper.
*
* @param dn The distinguished name to find.
* @param mapper The ContextMapper to use for mapping the found
* object.
* @return the object returned from the mapper.
* @throws NamingException if any error occurs.
*/
T lookup(String dn, ContextMapper mapper) throws NamingException;
/**
* Convenience method to get the specified attributes of a specified DN and
* automatically pass them to an AttributesMapper.
*
* @param dn The distinguished name to find.
* @param attributes The names of the attributes to pass to the mapper.
* @param mapper The AttributesMapper to use for mapping the
* found object.
* @return the object returned from the mapper.
* @throws NamingException if any error occurs.
*/
T lookup(Name dn, String[] attributes, AttributesMapper mapper) throws NamingException;
/**
* Convenience method to get the specified attributes of a specified DN and
* automatically pass them to an AttributesMapper.
*
* @param dn The distinguished name to find.
* @param attributes The names of the attributes to pass to the mapper.
* @param mapper The AttributesMapper to use for mapping the
* found object.
* @return the object returned from the mapper.
* @throws NamingException if any error occurs.
*/
T lookup(String dn, String[] attributes, AttributesMapper mapper) throws NamingException;
/**
* Convenience method to get the specified attributes of a specified DN and
* automatically pass them to a ContextMapper.
*
* @param dn The distinguished name to find.
* @param attributes The names of the attributes to pass to the mapper.
* @param mapper The ContextMapper to use for mapping the found
* object.
* @return the object returned from the mapper.
* @throws NamingException if any error occurs.
*/
T lookup(Name dn, String[] attributes, ContextMapper mapper) throws NamingException;
/**
* Convenience method to get the specified attributes of a specified DN and
* automatically pass them to a ContextMapper.
*
* @param dn The distinguished name to find.
* @param attributes The names of the attributes to pass to the mapper.
* @param mapper The ContextMapper to use for mapping the found
* object.
* @return the object returned from the mapper.
* @throws NamingException if any error occurs.
*/
T lookup(String dn, String[] attributes, ContextMapper mapper) throws NamingException;
/**
* Modify an entry in the LDAP tree using the supplied
* ModificationItems.
*
* @param dn The distinguished name of the node to modify.
* @param mods The modifications to perform.
* @throws NamingException if any error occurs.
* @see #modifyAttributes(DirContextOperations)
*/
void modifyAttributes(Name dn, ModificationItem[] mods) throws NamingException;
/**
* Modify an entry in the LDAP tree using the supplied
* ModificationItems.
*
* @param dn The distinguished name of the node to modify.
* @param mods The modifications to perform.
* @throws NamingException if any error occurs.
* @see #modifyAttributes(DirContextOperations)
*/
void modifyAttributes(String dn, ModificationItem[] mods) 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.
*
* @param dn The distinguished name to bind the object and attributes to.
* @param obj The object to bind, may be null. Typically a
* DirContext implementation.
* @param attributes The attributes to bind, may be null.
* @throws NamingException if any error occurs.
* @see DirContextAdapter
*/
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.
*
* @param dn The distinguished name to bind the object and attributes to.
* @param obj The object to bind, may be null. Typically a
* DirContext implementation.
* @param attributes The attributes to bind, may be null.
* @throws NamingException if any error occurs.
* @see DirContextAdapter
*/
void bind(String dn, Object obj, Attributes attributes) 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
* {@link #unbind(Name, boolean)} in stead.
*
* @param dn The distinguished name of the entry to remove.
* @throws NamingException if any error occurs.
*/
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
* {@link #unbind(Name, boolean)} in stead.
*
* @param dn The distinguished name to unbind.
* @throws NamingException if any error occurs.
*/
void unbind(String dn) throws NamingException;
/**
* Remove an entry from the LDAP tree, optionally removing all descendants
* in the process.
*
* @param dn The distinguished name to unbind.
* @param 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.
*/
void unbind(Name dn, boolean recursive) throws NamingException;
/**
* Remove an entry from the LDAP tree, optionally removing all descendants
* in the process.
*
* @param dn The distinguished name to unbind.
* @param 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.
*/
void unbind(String dn, boolean recursive) 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.
*
* @param dn The distinguished name to rebind.
* @param obj The object to bind to the DN, may be null.
* Typically a DirContext implementation.
* @param attributes The attributes to bind, may be null.
* @throws NamingException if any error occurs.
* @see DirContextAdapter
*/
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.
*
* @param dn The distinguished name to rebind.
* @param obj The object to bind to the DN, may be null.
* Typically a DirContext implementation.
* @param attributes The attributes to bind, may be null.
* @throws NamingException if any error occurs.
* @see DirContextAdapter
*/
void rebind(String dn, Object obj, Attributes attributes) throws NamingException;
/**
* Move an entry in the LDAP tree to a new location.
*
* @param oldDn The distinguished name of the entry to move; may not be
* null or empty.
* @param newDn The distinguished name where the entry should be moved; may
* not be null or empty.
* @throws ContextNotEmptyException if newDn is already bound
* @throws NamingException if any other error occurs.
*/
void rename(final Name oldDn, final Name newDn) throws NamingException;
/**
* Move an entry in the LDAP tree to a new location.
*
* @param oldDn The distinguished name of the entry to move; may not be
* null or empty.
* @param newDn The distinguished name where the entry should be moved; may
* not be null or empty.
* @throws ContextNotEmptyException if newDn is already bound
* @throws NamingException if any other error occurs.
*/
void rename(final String oldDn, final String newDn) throws NamingException;
/**
* Convenience method to lookup the supplied DN and automatically cast it to
* {@link DirContextOperations}.
*
* @param dn The distinguished name of the object to find.
* @return The found object, cast to {@link 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 {@link DirContextOperations}.
* @throws NamingException if any other error occurs.
* @see #lookup(Name)
* @see #modifyAttributes(DirContextOperations)
* @since 1.2
*/
DirContextOperations lookupContext(Name dn) throws NamingException, ClassCastException;
/**
* Convenience method to lookup the supplied DN and automatically cast it to
* {@link DirContextOperations}.
*
* @param dn The distinguished name of the object to find.
* @return The found object, cast to {@link 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 {@link DirContextOperations}.
* @throws NamingException if any other error occurs.
* @see #lookup(String)
* @see #modifyAttributes(DirContextOperations)
* @since 1.2
*/
DirContextOperations lookupContext(String dn) throws NamingException, ClassCastException;
/**
* Modify the attributes of the entry referenced by the supplied
* {@link DirContextOperations} instance. The DN to update will be the DN of
* the DirContextOperationsinstance, and the
* ModificationItem array is retrieved from the
* DirContextOperations instance using a call to
* {@link 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 (
* {@link 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);
* }
*
*
* @param 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.
* @throws NamingException if any other error occurs.
* @since 1.2
* @see #lookupContext(Name)
* @see DirContextAdapter
*/
void modifyAttributes(DirContextOperations ctx) throws IllegalStateException, NamingException;
/**
* Bind the data in the supplied context in the tree. All specified
* attributes ctxin 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);
*
* @param ctx the context to bind
* @throws IllegalStateException if no DN is set or if the instance is in
* update mode.
* @since 1.3
*/
void bind(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);
*
* @param ctx the context to rebind
* @throws IllegalStateException if no DN is set or if the instance is in
* update mode.
* @since 1.3
*/
void rebind(DirContextOperations ctx);
/**
* 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
* {@link 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);
*
*
* @param base the DN to use as the base of the search.
* @param filter the search filter - must result in a unique result.
* @param password the password to use for authentication.
* @return true if the authentication was successful,
* false otherwise.
* @since 1.3
* @deprecated use {@link #authenticate(org.springframework.ldap.query.LdapQuery, String)}
* or {@link #authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)}
*/
boolean authenticate(Name base, String filter, 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
* {@link 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);
*
*
* @param base the DN to use as the base of the search.
* @param filter the search filter - must result in a unique result.
* @param password the password to use for authentication.
* @return true if the authentication was successful,
* false otherwise.
* @since 1.3
* @deprecated use {@link #authenticate(org.springframework.ldap.query.LdapQuery, String)}
* or {@link #authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)}
*/
boolean authenticate(String base, String filter, 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
* {@link ContextSource#getContext(String, String)}, thus authenticating the
* entry. The resulting DirContext instance is then used as input to the
* supplied {@link AuthenticatedLdapEntryContextCallback} to perform any
* additional LDAP operations against the authenticated DirContext.
*
* @param base the DN to use as the base of the search.
* @param filter the search filter - must result in a unique result.
* @param password the password to use for authentication.
* @param callback the callback to that will be called to perform operations
* on the DirContext authenticated with the found user.
* @return true if the authentication was successful,
* false otherwise.
* @see #authenticate(Name, String, String)
* @since 1.3
* @deprecated use {@link #authenticate(org.springframework.ldap.query.LdapQuery, String)}
* or {@link #authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)}
*/
boolean authenticate(Name base, String filter, String password, AuthenticatedLdapEntryContextCallback callback);
/**
* 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
* {@link ContextSource#getContext(String, String)}, thus authenticating the
* entry. The resulting DirContext instance is then used as input to the
* supplied {@link AuthenticatedLdapEntryContextCallback} to perform any
* additional LDAP operations against the authenticated DirContext.
*
* @param base the DN to use as the base of the search.
* @param filter the search filter - must result in a unique result.
* @param password the password to use for authentication.
* @param callback the callback to that will be called to perform operations
* on the DirContext authenticated with the found user.
* @return true if the authentication was successful,
* false otherwise.
* @see #authenticate(String, String, String)
* @since 1.3
* @deprecated use {@link #authenticate(org.springframework.ldap.query.LdapQuery, String)}
* or {@link #authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)}
*/
boolean authenticate(String base, String filter, String password, AuthenticatedLdapEntryContextCallback callback);
/**
* 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
* {@link ContextSource#getContext(String, String)}, thus authenticating the
* entry. The resulting DirContext instance is then used as input to the
* supplied {@link 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
* {@link AuthenticationErrorCallback}. This enables the caller to provide a
* callback that, for example, collects the exception for later processing.
*
* @param base the DN to use as the base of the search.
* @param filter the search filter - must result in a unique result.
* @param password the password to use for authentication.
* @param callback the callback that will be called to perform operations
* on the DirContext authenticated with the found user.
* @param errorCallback the callback that will be called if an exception is caught.
* @return true if the authentication was successful,
* false otherwise.
* @see #authenticate(Name, String, String, AuthenticatedLdapEntryContextCallback)
* @since 1.3.1
* @deprecated use {@link #authenticate(org.springframework.ldap.query.LdapQuery, String)}
* or {@link #authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)}
*/
boolean authenticate(Name base, String filter, String password,
AuthenticatedLdapEntryContextCallback callback,
AuthenticationErrorCallback errorCallback);
/**
* 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
* {@link ContextSource#getContext(String, String)}, thus authenticating the
* entry. The resulting DirContext instance is then used as input to the
* supplied {@link 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
* {@link AuthenticationErrorCallback}. This enables the caller to provide a
* callback that, for example, collects the exception for later processing.
*
* @param base the DN to use as the base of the search.
* @param filter the search filter - must result in a unique result.
* @param password the password to use for authentication.
* @param callback the callback that will be called to perform operations
* on the DirContext authenticated with the found user.
* @param errorCallback the callback that will be called if an exception is caught.
* @return true if the authentication was successful,
* false otherwise.
* @see #authenticate(String, String, String, AuthenticatedLdapEntryContextCallback)
* @since 1.3.1
* @deprecated use {@link #authenticate(org.springframework.ldap.query.LdapQuery, String)}
* or {@link #authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)}
*/
boolean authenticate(String base, String filter, String password,
AuthenticatedLdapEntryContextCallback callback,
AuthenticationErrorCallback errorCallback);
/**
* 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
* {@link ContextSource#getContext(String, String)}, thus authenticating the
* entry. If an exception is caught, the same exception is passed on to the given
* {@link AuthenticationErrorCallback}. This enables the caller to provide a
* callback that, for example, collects the exception for later processing.
*
* @param base the DN to use as the base of the search.
* @param filter the search filter - must result in a unique result.
* @param password the password to use for authentication.
* @param errorCallback the callback that will be called if an exception is caught.
* @return true if the authentication was successful,
* false otherwise.
* @see #authenticate(Name, String, String, AuthenticatedLdapEntryContextCallback, AuthenticationErrorCallback)
* @since 1.3.1
* @deprecated use {@link #authenticate(org.springframework.ldap.query.LdapQuery, String)}
* or {@link #authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)}
*/
boolean authenticate(Name base, String filter, String password,
AuthenticationErrorCallback errorCallback);
/**
* 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
* {@link ContextSource#getContext(String, String)}, thus authenticating the
* entry. If an exception is caught, the same exception is passed on to the given
* {@link AuthenticationErrorCallback}. This enables the caller to provide a
* callback that, for example, collects the exception for later processing.
*
* @param base the DN to use as the base of the search.
* @param filter the search filter - must result in a unique result.
* @param password the password to use for authentication.
* @param errorCallback the callback that will be called if an exception is caught.
* @return true if the authentication was successful,
* false otherwise.
* @throws IncorrectResultSizeDataAccessException if more than one users were found
* @since 1.3.1
* @deprecated use {@link #authenticate(org.springframework.ldap.query.LdapQuery, String)}
* or {@link #authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)}
*/
boolean authenticate(String base, String filter, String password,
AuthenticationErrorCallback errorCallback);
/**
* 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
* {@link 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.
*
*
* @param query the LdapQuery specifying the details of the search.
* @param password the password to use for authentication.
* @param mapper the callback that will be called to perform operations
* on the DirContext authenticated with the found user.
* false otherwise.
* @return the result from the callback.
* @throws IncorrectResultSizeDataAccessException if more than one users were found
* @throws org.springframework.dao.EmptyResultDataAccessException if only one user was found
* @throws NamingException if something went wrong in authentication.
*
* @since 2.0
* @see org.springframework.ldap.query.LdapQueryBuilder
*/
T authenticate(LdapQuery query, String password, AuthenticatedLdapEntryContextMapper mapper);
/**
* 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
* {@link ContextSource#getContext(String, String)}, thus authenticating the
* entry. If an exception is caught, the same exception is passed on to the given
* {@link 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.
*
*
* @param query the LdapQuery specifying the details of the search.
* @param password the password to use for authentication.
* false otherwise.
* @throws IncorrectResultSizeDataAccessException if more than one users were found
* @throws org.springframework.dao.EmptyResultDataAccessException if only one user was found
* @throws NamingException if something went wrong in authentication.
*
* @since 2.0
* @see org.springframework.ldap.query.LdapQueryBuilder
*/
void authenticate(LdapQuery query, String password);
/**
* 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
* {@link IncorrectResultSizeDataAccessException} is thrown.
* @param base the DN to use as the base of the search.
* @param filter the search filter.
* @param mapper the mapper to use for the search.
* @return 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
*/
T searchForObject(Name base, String filter, ContextMapper 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
* {@link IncorrectResultSizeDataAccessException} is thrown.
* @param base the DN to use as the base of the search.
* @param filter the search filter.
* @param searchControls the searchControls to use for the search.
* @param mapper the mapper to use for the search.
* @return 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
*/
T searchForObject(Name base, String filter, SearchControls searchControls, ContextMapper 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
* {@link IncorrectResultSizeDataAccessException} is thrown.
* @param base the DN to use as the base of the search.
* @param filter the search filter.
* @param searchControls the searchControls to use for the search.
* @param mapper the mapper to use for the search.
* @return 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
*/
T searchForObject(String base, String filter, SearchControls searchControls, ContextMapper 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
* {@link IncorrectResultSizeDataAccessException} is thrown.
* @param base the DN to use as the base of the search.
* @param filter the search filter.
* @param mapper the mapper to use for the search.
* @return 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
*/
T searchForObject(String base, String filter, ContextMapper mapper);
/**
* Perform a search with parameters from the specified LdapQuery. All found objects will be supplied to the
* NameClassPairCallbackHandler for processing.
*
* @param query the LDAP query specification.
* @param callbackHandler the NameClassPairCallbackHandler to supply all found entries to.
*
* @throws NamingException if any error occurs.
* @since 2.0
* @see org.springframework.ldap.query.LdapQueryBuilder
* @see org.springframework.ldap.core.support.CountNameClassPairCallbackHandler
*/
void search(LdapQuery query, NameClassPairCallbackHandler callbackHandler);
/**
* 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.
*
* @param query the LDAP query specification.
* @param mapper the ContextMapper to supply all found entries to.
* @return a List containing all entries received from the
* ContextMapper.
*
* @throws NamingException if any error occurs.
* @since 2.0
* @see org.springframework.ldap.query.LdapQueryBuilder
*/
List search(LdapQuery query, ContextMapper 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.
*
* @param query the LDAP query specification.
* @param mapper the Attributes to supply all found Attributes to.
* @return a List containing all entries received from the
* Attributes.
*
* @throws NamingException if any error occurs.
* @since 2.0
* @see org.springframework.ldap.query.LdapQueryBuilder
*/
List search(LdapQuery query, AttributesMapper mapper);
/**
* 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
* {@link IncorrectResultSizeDataAccessException} is thrown.
* @param query the LDAP query specification.
* @return the single entry matching the query as a DirContextOperations instance.
* @throws IncorrectResultSizeDataAccessException if the result is not one unique entry
* @since 2.0
* @see org.springframework.ldap.query.LdapQueryBuilder
*/
DirContextOperations searchForContext(LdapQuery query);
/**
* 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
* {@link IncorrectResultSizeDataAccessException} is thrown.
* @param query the LDAP query specification.
* @return 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 org.springframework.ldap.query.LdapQueryBuilder
*/
T searchForObject(LdapQuery query, ContextMapper mapper);
/**
* Read a named entry from the LDAP directory. The referenced class must have object-directory mapping metadata
* specified using {@link org.springframework.ldap.odm.annotations.Entry} and associated annotations.
*
* @param The Java type to return
* @param dn The distinguished name of the entry to read from the LDAP directory.
* @param clazz The Java type to return
* @return The entry as read from the directory
*
* @throws org.springframework.ldap.NamingException on error.
* @since 2.0
*/
T findByDn(Name dn, Class clazz);
/**
* Create the given entry in the LDAP directory. The referenced class must have object-directory mapping metadata
* specified using {@link org.springframework.ldap.odm.annotations.Entry} and associated annotations.
* If the field annotated with {@link org.springframework.ldap.odm.annotations.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 {@link org.springframework.ldap.odm.annotations.DnAttribute}.
* If an id can be calculated, this will be populated in the supplied object.
*
* @param entry The entry to be create, it must not be null or already exist in the directory.
*
* @throws org.springframework.ldap.NamingException on error.
* @throws IllegalArgumentException if the entry is null or on failure to determine the distinguished name.
* @since 2.0
*/
void create(Object entry);
/**
* Update the given entry in the LDAP directory. The referenced class must have object-directory mapping metadata
* specified using {@link org.springframework.ldap.odm.annotations.Entry} and associated annotations.
* If the distinguished name is not explicitly specified (i.e. if the
* field annotated with {@link org.springframework.ldap.odm.annotations.Id} is null),
* an attempt will be made to calculate the name from fields annotated with
* {@link org.springframework.ldap.odm.annotations.DnAttribute}. If the {@link org.springframework.ldap.odm.annotations.Id}
* field and the calculated DN is different, the entry will be moved (i.e., an {@link #unbind(javax.naming.Name)}
* followed by a {@link #bind(DirContextOperations)}. Otherwise
* the current data of the entry will be read from the directory and a {@link #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.
*
* @param entry The entry to update, it must already exist in the directory.
*
* @throws org.springframework.ldap.NamingException on error.
* @throws IllegalArgumentException if the entry is null or on failure to determine the distinguished name.
* @since 2.0
*/
void update(Object entry);
/**
* Delete an entry from the LDAP directory. The referenced class must have object-directory mapping metadata
* specified using {@link org.springframework.ldap.odm.annotations.Entry} and associated annotations.
* If the field annotated with {@link org.springframework.ldap.odm.annotations.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 {@link org.springframework.ldap.odm.annotations.DnAttribute}.
*
* @param entry The entry to delete, it must already exist in the directory.
*
* @throws org.springframework.ldap.NamingException on error.
* @throws IllegalArgumentException if the entry is null or on failure to determine the distinguished name.
* @since 2.0
*/
void delete(Object entry);
/**
* Find all entries in the LDAP directory of a given type. The referenced class must have object-directory mapping metadata
* specified using {@link org.springframework.ldap.odm.annotations.Entry} and associated annotations.
*
* @param The Java type to return
* @param clazz The Java type to return
* @return All entries that are of the type represented by the given
* Java class
*
* @throws org.springframework.ldap.NamingException on error.
* @since 2.0
*/
List findAll(Class clazz);
/**
* Find all entries in the LDAP directory of a given type. The referenced class must have object-directory mapping metadata
* specified using {@link org.springframework.ldap.odm.annotations.Entry} and associated annotations.
*
* @param The Java type to return
* @param base The root of the sub-tree at which to begin the search.
* @param 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.
* @param clazz The Java type to return
* @return All entries that are of the type represented by the given
* Java class
*
* @throws org.springframework.ldap.NamingException on error.
* @since 2.0
*/
List findAll(Name base, SearchControls searchControls, Class 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
* {@link org.springframework.ldap.odm.annotations.Entry} and associated annotations.
*
* @param The Java type to return
* @param base The root of the sub-tree at which to begin the search.
* @param filter The search filter.
* @param 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.
* @param clazz The Java type to return
* @return All entries that are of the type represented by the given
* Java class
*
* @throws org.springframework.ldap.NamingException on error.
* @since 2.0
*/
List find(Name base, Filter filter, SearchControls searchControls, Class clazz);
/**
* Search for entries in the LDAP directory. The referenced class must have object-directory
* mapping metadata specified using {@link org.springframework.ldap.odm.annotations.Entry} and associated annotations.
*
* Only those entries that both match the query search filter and
* are represented by the given Java class are returned.
*
* @param The Java type to return
* @param query the LDAP query specification
* @param clazz The Java type to return
* @return All matching entries.
*
* @throws org.springframework.ldap.NamingException on error.
* @see org.springframework.ldap.query.LdapQueryBuilder
* @since 2.0
*/
List find(LdapQuery query, Class 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
* {@link org.springframework.ldap.odm.annotations.Entry} and associated annotations.
* @param query the LDAP query specification
* @param clazz The Java type to return
* @param The Java type to return
* @return The single entry matching the search specification.
* @since 2.0
* @throws org.springframework.ldap.NamingException on LDAP error.
* @throws org.springframework.dao.EmptyResultDataAccessException if no matching entry can be found
* @throws IncorrectResultSizeDataAccessException if more than one matching entry is found
*/
T findOne(LdapQuery query, Class clazz);
/**
* Get the configured ObjectDirectoryMapper. For internal use.
*
* @return the configured ObjectDirectoryMapper.
* @since 2.0
*/
ObjectDirectoryMapper getObjectDirectoryMapper();
}