org.springframework.ldap.core.LdapOperations Maven / Gradle / Ivy
/*
* Copyright 2005-2022 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
*
* https://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 java.util.List;
import java.util.stream.Stream;
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 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;
/**
* 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(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(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(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(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(Name oldDn, 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(String oldDn, 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.
* @since 1.2
* @see #lookup(Name)
* @see #modifyAttributes(DirContextOperations)
*/
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.
* @since 1.2
* @see #lookup(String)
* @see #modifyAttributes(DirContextOperations)
*/
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
* DirContextOperations
instance, 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
* 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);
*
* @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)}
*/
@Deprecated
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)}
*/
@Deprecated
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.
* @since 1.3
* @deprecated use
* {@link #authenticate(org.springframework.ldap.query.LdapQuery, String)} or
* {@link #authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)}
* @see #authenticate(Name, String, String)
*/
@Deprecated
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.
* @since 1.3
* @deprecated use
* {@link #authenticate(org.springframework.ldap.query.LdapQuery, String)} or
* {@link #authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)}
* @see #authenticate(String, String, String)
*/
@Deprecated
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.
* @since 1.3.1
* @deprecated use
* {@link #authenticate(org.springframework.ldap.query.LdapQuery, String)} or
* {@link #authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)}
* @see #authenticate(Name, String, String, AuthenticatedLdapEntryContextCallback)
*/
@Deprecated
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.
* @since 1.3.1
* @deprecated use
* {@link #authenticate(org.springframework.ldap.query.LdapQuery, String)} or
* {@link #authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)}
* @see #authenticate(String, String, String, AuthenticatedLdapEntryContextCallback)
*/
@Deprecated
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.
* @since 1.3.1
* @deprecated use
* {@link #authenticate(org.springframework.ldap.query.LdapQuery, String)} or
* {@link #authenticate(org.springframework.ldap.query.LdapQuery, String, AuthenticatedLdapEntryContextMapper)}
* @see #authenticate(Name, String, String, AuthenticatedLdapEntryContextCallback,
* AuthenticationErrorCallback)
*/
@Deprecated
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)}
*/
@Deprecated
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);
/**
* 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 Stream
of all entries received from the
* Attributes
.
* @throws NamingException if any error occurs.
* @since 3.0
* @see org.springframework.ldap.query.LdapQueryBuilder
*/
Stream searchForStream(LdapQuery query, AttributesMapper 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.
* @param query the LDAP query specification.
* @param mapper the ContextMapper
to supply all found entries to.
* @return a Stream
of all entries received from the
* ContextMapper
.
* @throws NamingException if any error occurs.
* @since 3.0
* @see org.springframework.ldap.query.LdapQueryBuilder
*/
Stream searchForStream(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);
/**
* 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 3.0
*/
Stream findForStream(LdapQuery query, Class clazz);
/**
* Get the configured ObjectDirectoryMapper. For internal use.
* @return the configured ObjectDirectoryMapper.
* @since 2.0
*/
ObjectDirectoryMapper getObjectDirectoryMapper();
}