diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/LdapOperations.java b/spring-ldap/src/main/java/org/springframework/ldap/core/LdapOperations.java index 323e5552..66b15728 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/LdapOperations.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/LdapOperations.java @@ -24,10 +24,11 @@ import javax.naming.NameClassPair; import javax.naming.directory.Attributes; import javax.naming.directory.ModificationItem; import javax.naming.directory.SearchControls; -import javax.naming.spi.DirObjectFactory; import org.springframework.ldap.ContextNotEmptyException; import org.springframework.ldap.NamingException; +import org.springframework.ldap.core.support.AbstractContextSource; +import org.springframework.ldap.support.LdapUtils; /** * Interface that specifies a basic set of LDAP operations. Implemented by @@ -39,104 +40,126 @@ import org.springframework.ldap.NamingException; */ public interface LdapOperations { /** - * Perform a search using a custom 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 - * SearchResult is passed to the CallbackHandler. Any encountered - * NamingException will be translated using the NamingExceptionTranslator. + * 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. + * The SearchExecutor to use for performing the + * actual search. * @param handler - * The NameClassPairCallbackHandler to which each found entry - * will be passed. + * The NameClassPairCallbackHandler to which each + * found entry will be passed. * @param processor - * DirContextProcessor for custom pre- and post-processing. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted as no entries being found. */ public void search(SearchExecutor se, NameClassPairCallbackHandler handler, DirContextProcessor processor) throws NamingException; /** - * Perform a search. 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 SearchResult is passed to the - * CallbackHandler. Any encountered NamingException will be translated using - * the NamingExceptionTranslator. + * 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. + * The SearchExecutor to use for performing the + * actual search. * @param handler - * The NameClassPairCallbackHandler to which each found entry - * will be passed. + * 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. + * 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) */ public 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 + * 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. + * 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. + * if the operation resulted in a NamingException. + * + * @see #search(SearchExecutor, NameClassPairCallbackHandler) + * @see #search(Name, String, AttributesMapper) + * @see #search(Name, String, ContextMapper) */ public Object 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 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. + * 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. + * 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[])) */ public Object 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. + * 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. + * The SearchControls to use in the search. * @param handler - * The NameClassPairCallbackHandler to supply the SearchResults - * to. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public void search(Name base, String filter, SearchControls controls, NameClassPairCallbackHandler handler) throws NamingException; @@ -151,41 +174,45 @@ public interface LdapOperations { * @param filter * The filter to use in the search. * @param controls - * The SearchControls to use in the search. + * The SearchControls to use in the search. * @param handler - * The NameClassPairCallbackHandler to supply the SearchResults - * to. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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. + * 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. + * The SearchControls to use in the search. * @param handler - * The NameClassPairCallbackHandler to supply the SearchResults - * to. + * The NameClassPairCallbackHandler to supply the + * SearchResult to. * @param processor - * The DirContextProcessor to use before and after the search. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public void search(Name base, String filter, SearchControls controls, NameClassPairCallbackHandler handler, DirContextProcessor processor) @@ -193,26 +220,30 @@ public interface LdapOperations { /** * 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. + * 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. + * The SearchControls to use in the search. * @param mapper - * The AttributesMapper to use for translating each entry. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public List search(String base, String filter, SearchControls controls, AttributesMapper mapper, DirContextProcessor processor) @@ -220,26 +251,30 @@ public interface LdapOperations { /** * 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. + * 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. + * The SearchControls to use in the search. * @param mapper - * The AttributesMapper to use for translating each entry. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public List search(Name base, String filter, SearchControls controls, AttributesMapper mapper, DirContextProcessor processor) @@ -247,29 +282,33 @@ public interface LdapOperations { /** * 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. + * 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. + * 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. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public List search(String base, String filter, SearchControls controls, ContextMapper mapper, DirContextProcessor processor) @@ -277,29 +316,33 @@ public interface LdapOperations { /** * 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. + * 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. + * 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. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public List search(Name base, String filter, SearchControls controls, ContextMapper mapper, DirContextProcessor processor) @@ -315,536 +358,593 @@ public interface LdapOperations { * @param filter * The filter to use in the search. * @param controls - * The SearchControls to use in the search. + * The SearchControls to use in the search. * @param handler - * The NameClassPairCallbackHandler to supply the SearchResults - * to. + * The NameClassPairCallbackHandler to supply the + * SearchResults to. * @param processor - * The DirContextProcessor to use before and after the search. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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. + * 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. + * 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. + * Must be set to true if a + * ContextMapper is used. * @param handler - * The NameClassPairCallbackHandler to supply the SearchResults - * to. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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 - * search scope and return objects flag in search controls. + * 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. + * The search scope to set in SearchControls. * @param returningObjFlag - * whether the bound object should be returned in search results. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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 no the - * returnObjects will be set to false. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public void search(String base, String filter, NameClassPairCallbackHandler handler) throws NamingException; /** - * Search for all objects matching the supplied filter. Only search for the - * specified attributes. The Attributes in each SearchResult is supplied to - * the specified AttributesMapper. + * 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. + * The search scope to set in SearchControls. * @param attrs - * The attributes to return, null means returning all attributes. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public List search(Name base, String filter, int searchScope, String[] attrs, AttributesMapper mapper) throws NamingException; /** - * Search for all objects matching the supplied filter. Only search for the - * specified attributes. The Attributes in each SearchResult is supplied to - * the specified AttributesMapper. + * 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. + * The search scope to set in SearchControls. * @param attrs - * The attributes to return, null means returning all attributes. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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. + * 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. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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. + * 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. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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 seach scope will be used. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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 seach scope will be used. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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 - * look for the supplied attributes. + * 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. + * The search scope to set in SearchControls. * @param attrs - * The attributes to return, null means all attributes. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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 - * look for the supplied attributes. + * 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. + * The search scope to set in SearchControls. * @param attrs - * The attributes to return, null means all attributes. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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. + * 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. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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. + * 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. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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. + * 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 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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. + * 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. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public List search(Name 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 AttributesMapper. + * 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. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public List search(String base, String filter, SearchControls controls, AttributesMapper mapper) throws NamingException; /** - * Search for all objects matching the supplied filter. The Object returned - * in each SearchResult is supplied to the specified AttributesMapper. + * 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. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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. + * 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 + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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. + * 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 + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public List list(Name base, NameClassPairMapper mapper) throws NamingException; @@ -858,14 +958,14 @@ public interface LdapOperations { * @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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public List list(String base) throws NamingException; /** - * Perform a non-recursive listing of the contexts bound to the given + * Perform a non-recursive listing of the children of the given * base. * * @param base @@ -873,80 +973,86 @@ public interface LdapOperations { * @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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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. + * 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 + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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. + * 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 + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public List listBindings(Name base, NameClassPairMapper mapper) throws NamingException; @@ -957,44 +1063,46 @@ public interface LdapOperations { * * @param base * The base DN where the list should be performed. - * @return a List containing the names of all the contexts bound to - * base. + * @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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public List listBindings(final String base) throws NamingException; /** - * Perform a non-recursive listing of the children of the given + * 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. + * @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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public List listBindings(String base, ContextMapper mapper) throws NamingException; @@ -1002,25 +1110,27 @@ public interface LdapOperations { /** * 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. + * 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. + * 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. + * if any error occurs. Note that a + * NameNotFoundException will be ignored. Instead + * this is interpreted that no entries were found. */ public 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. + * be a {@link DirContextAdapter}, unless the DirObjectFactory + * has been modified in the ContextSource. * * @param dn * The distinguished name of the object to find. @@ -1028,31 +1138,34 @@ public interface LdapOperations { * @throws NamingException * if any error occurs. * @see #lookupContext(Name) + * @see AbstractContextSource#setDirObjectFactory(Class) */ public 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. + * 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 #lookupContext(String) + * @see AbstractContextSource#setDirObjectFactory(Class) */ public Object lookup(String dn) throws NamingException; /** * Convenience method to get the attributes of a specified DN and - * automatically pass them to an AttributesMapper. + * automatically pass them to an AttributesMapper. * * @param dn * The distinguished name to find. * @param mapper - * The AttributesMapper to use for mapping the found object. + * The AttributesMapper to use for mapping the + * found object. * @return the object returned from the mapper. * @throws NamingException * if any error occurs. @@ -1062,12 +1175,13 @@ public interface LdapOperations { /** * Convenience method to get the attributes of a specified DN and - * automatically pass them to an AttributesMapper. + * automatically pass them to an AttributesMapper. * * @param dn * The distinguished name to find. * @param mapper - * The AttributesMapper to use for mapping the found object. + * The AttributesMapper to use for mapping the + * found object. * @return the object returned from the mapper. * @throws NamingException * if any error occurs. @@ -1077,12 +1191,13 @@ public interface LdapOperations { /** * Convenience method to lookup a specified DN and automatically pass the - * found object to a ContextMapper. + * found object to a ContextMapper. * * @param dn * The distinguished name to find. * @param mapper - * The ContextMapper to use for mapping the found object. + * The ContextMapper to use for mapping the found + * object. * @return the object returned from the mapper. * @throws NamingException * if any error occurs. @@ -1091,12 +1206,13 @@ public interface LdapOperations { /** * Convenience method to lookup a specified DN and automatically pass the - * found object to a ContextMapper. + * found object to a ContextMapper. * * @param dn * The distinguished name to find. * @param mapper - * The ContextMapper to use for mapping the found object. + * The ContextMapper to use for mapping the found + * object. * @return the object returned from the mapper. * @throws NamingException * if any error occurs. @@ -1106,14 +1222,15 @@ public interface LdapOperations { /** * Convenience method to get the specified attributes of a specified DN and - * automatically pass them to an AttributesMapper. + * 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. + * The AttributesMapper to use for mapping the + * found object. * @return the object returned from the mapper. * @throws NamingException * if any error occurs. @@ -1123,14 +1240,15 @@ public interface LdapOperations { /** * Convenience method to get the specified attributes of a specified DN and - * automatically pass them to an AttributesMapper. + * 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. + * The AttributesMapper to use for mapping the + * found object. * @return the object returned from the mapper. * @throws NamingException * if any error occurs. @@ -1140,14 +1258,15 @@ public interface LdapOperations { /** * Convenience method to get the specified attributes of a specified DN and - * automatically pass them to a ContextMapper. + * 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. + * The ContextMapper to use for mapping the found + * object. * @return the object returned from the mapper. * @throws NamingException * if any error occurs. @@ -1157,14 +1276,15 @@ public interface LdapOperations { /** * Convenience method to get the specified attributes of a specified DN and - * automatically pass them to a ContextMapper. + * 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. + * The ContextMapper to use for mapping the found + * object. * @return the object returned from the mapper. * @throws NamingException * if any error occurs. @@ -1173,7 +1293,8 @@ public interface LdapOperations { throws NamingException; /** - * Modify an entry in the LDAP tree using the supplied ModificationItems. + * Modify an entry in the LDAP tree using the supplied + * ModificationItems. * * @param dn * The distinguished name of the node to modify. @@ -1181,12 +1302,14 @@ public interface LdapOperations { * The modifications to perform. * @throws NamingException * if any error occurs. + * @see #modifyAttributes(DirContextOperations) */ public void modifyAttributes(Name dn, ModificationItem[] mods) throws NamingException; /** - * Modify an entry in the LDAP tree using the supplied ModificationItems. + * Modify an entry in the LDAP tree using the supplied + * ModificationItems. * * @param dn * The distinguished name of the node to modify. @@ -1194,6 +1317,7 @@ public interface LdapOperations { * The modifications to perform. * @throws NamingException * if any error occurs. + * @see #modifyAttributes(DirContextOperations) */ public void modifyAttributes(String dn, ModificationItem[] mods) throws NamingException; @@ -1202,17 +1326,18 @@ public interface LdapOperations { * 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. + * 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. + * The object to bind, may be null. Typically a + * DirContext implementation. * @param attributes - * The attributes to bind, may be null. + * The attributes to bind, may be null. * @throws NamingException * if any error occurs. + * @see DirContextAdapter */ public void bind(Name dn, Object obj, Attributes attributes) throws NamingException; @@ -1221,17 +1346,18 @@ public interface LdapOperations { * 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. + * 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. + * The object to bind, may be null. Typically a + * DirContext implementation. * @param attributes - * The attributes to bind, may be null. + * The attributes to bind, may be null. * @throws NamingException * if any error occurs. + * @see DirContextAdapter */ public void bind(String dn, Object obj, Attributes attributes) throws NamingException; @@ -1294,18 +1420,19 @@ public interface LdapOperations { * 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. + * 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. + * The object to bind to the DN, may be null. + * Typically a DirContext implementation. * @param attributes - * The attributes to bind, may be null. + * The attributes to bind, may be null. * @throws NamingException * if any error occurs. + * @see DirContextAdapter */ public void rebind(Name dn, Object obj, Attributes attributes) throws NamingException; @@ -1314,18 +1441,19 @@ public interface LdapOperations { * 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. + * 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. + * The object to bind to the DN, may be null. + * Typically a DirContext implementation. * @param attributes - * The attributes to bind, may be null. + * The attributes to bind, may be null. * @throws NamingException * if any error occurs. + * @see DirContextAdapter */ public void rebind(String dn, Object obj, Attributes attributes) throws NamingException; @@ -1334,11 +1462,11 @@ public interface LdapOperations { * 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. + * 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. + * not be null or empty. * @throws ContextNotEmptyException * if newDn is already bound * @throws NamingException @@ -1351,11 +1479,11 @@ public interface LdapOperations { * 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. + * 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. + * not be null or empty. * @throws ContextNotEmptyException * if newDn is already bound * @throws NamingException @@ -1372,12 +1500,14 @@ public interface LdapOperations { * 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 woth - * the ContextSource, causing the actual class of the returned - * object to be something else than {@link DirContextOperations}. + * 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) + * @since 1.2 */ public DirContextOperations lookupContext(Name dn) throws NamingException, ClassCastException; @@ -1390,12 +1520,14 @@ public interface LdapOperations { * 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 woth - * the ContextSource, causing the actual class of the returned - * object to be something else than {@link DirContextOperations}. + * 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) + * @since 1.2 */ public DirContextOperations lookupContext(String dn) throws NamingException, ClassCastException; @@ -1432,7 +1564,9 @@ public interface LdapOperations { * been properly initialized. * @throws NamingException * if any other error occurs. - * + * @since 1.2 + * @see #lookupContext(Name) + * @see DirContextAdapter */ public void modifyAttributes(DirContextOperations ctx) throws IllegalStateException, NamingException; diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/LdapRdn.java b/spring-ldap/src/main/java/org/springframework/ldap/core/LdapRdn.java index 1f1c6639..4186ce09 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/LdapRdn.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/LdapRdn.java @@ -40,7 +40,7 @@ public class LdapRdn implements Serializable, Comparable { private List components = new LinkedList(); /** - * Default constructor. + * Default constructor. Create an empty, uninitialized LdapRdn. */ public LdapRdn() { } @@ -68,7 +68,9 @@ public class LdapRdn implements Serializable, Comparable { * Construct an LdapRdn using the supplied key and value. * * @param key + * the attribute name. * @param value + * the attribute value. */ public LdapRdn(String key, String value) { components.add(new LdapRdnComponent(key, value)); @@ -98,7 +100,7 @@ public class LdapRdn implements Serializable, Comparable { * * @return The first LdapRdnComponent of this LdapRdn. * @throws IndexOutOfBoundsException - * if no components have been added. + * if there are no components in this Rdn. */ public LdapRdnComponent getComponent() { return (LdapRdnComponent) components.get(0); @@ -109,18 +111,20 @@ public class LdapRdn implements Serializable, Comparable { * * @param idx * the 0-based index of the component to get. - * @return the LdapRdnComponent at indet idx. + * @return the LdapRdnComponent at index idx. * @throws IndexOutOfBoundsException - * if no component exists at index idx. + * if there are no components in this Rdn. */ public LdapRdnComponent getComponent(int idx) { return (LdapRdnComponent) components.get(idx); } /** - * Get a properly rfc2253-encoded String representation to this LdapRdn. + * Get a properly rfc2253-encoded String representation of this LdapRdn. * - * @return an encoded String corresponding to this LdapRdn. + * @return an escaped String corresponding to this LdapRdn. + * @throws IndexOutOfBoundsException + * if there are no components in this Rdn. */ public String getLdapEncoded() { if (components.size() == 0) { @@ -170,6 +174,11 @@ public class LdapRdn implements Serializable, Comparable { return comparator.compare(this.components, that.components); } + /* + * (non-Javadoc) + * + * @see java.lang.Object#equals(java.lang.Object) + */ public boolean equals(Object obj) { if (obj == null || obj.getClass() != this.getClass()) { return false; @@ -205,7 +214,7 @@ public class LdapRdn implements Serializable, Comparable { * * @return the (first) value of this LdapRdn. * @throws IndexOutOfBoundsException - * if there is no components in this Rdn. + * if there are no components in this Rdn. */ public String getValue() { return getComponent().getValue(); @@ -219,7 +228,7 @@ public class LdapRdn implements Serializable, Comparable { * * @return the (first) key of this LdapRdn. * @throws IndexOutOfBoundsException - * if there is no components in this Rdn. + * if there are no components in this Rdn. */ public String getKey() { return getComponent().getKey(); diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/LdapRdnComponent.java b/spring-ldap/src/main/java/org/springframework/ldap/core/LdapRdnComponent.java index bdae1d62..1f5d1c94 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/LdapRdnComponent.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/LdapRdnComponent.java @@ -114,9 +114,9 @@ public class LdapRdnComponent implements Comparable, Serializable { } /** - * Encode key and value to ldap + * Encode key and value to ldap. * - * @return The ldap encoded rdn + * @return Properly ldap escaped rdn. */ protected String encodeLdap() { StringBuffer buff = new StringBuffer(key.length() + value.length() * 2); @@ -144,6 +144,11 @@ public class LdapRdnComponent implements Comparable, Serializable { return encodeLdap(); } + /** + * Get a String representation of this instance for use in URLs. + * + * @return a properly URL encoded representation of this instancs. + */ public String encodeUrl() { // Use the URI class to properly URL encode the value. try { @@ -155,13 +160,20 @@ public class LdapRdnComponent implements Comparable, Serializable { } } - /** + /* + * (non-Javadoc) + * * @see java.lang.Object#hashCode() */ public int hashCode() { return key.hashCode() ^ value.hashCode(); } + /* + * (non-Javadoc) + * + * @see java.lang.Object#equals(java.lang.Object) + */ public boolean equals(Object obj) { if (obj != null && obj.getClass() == LdapRdnComponent.class) { LdapRdnComponent that = (LdapRdnComponent) obj; diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/LdapTemplate.java b/spring-ldap/src/main/java/org/springframework/ldap/core/LdapTemplate.java index b06f2da8..2ed4a796 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/LdapTemplate.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/LdapTemplate.java @@ -1295,14 +1295,29 @@ public class LdapTemplate implements LdapOperations, InitializingBean { } } + /* + * (non-Javadoc) + * + * @see org.springframework.ldap.core.LdapOperations#lookupContext(javax.naming.Name) + */ public DirContextOperations lookupContext(Name dn) { return (DirContextOperations) lookup(dn); } + /* + * (non-Javadoc) + * + * @see org.springframework.ldap.core.LdapOperations#lookupContext(java.lang.String) + */ public DirContextOperations lookupContext(String dn) { return (DirContextOperations) lookup(dn); } + /* + * (non-Javadoc) + * + * @see org.springframework.ldap.core.LdapOperations#modifyAttributes(org.springframework.ldap.core.DirContextOperations) + */ public void modifyAttributes(DirContextOperations ctx) { Name dn = ctx.getDn(); if (dn != null && ctx.isUpdateMode()) { diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/NameClassPairCallbackHandler.java b/spring-ldap/src/main/java/org/springframework/ldap/core/NameClassPairCallbackHandler.java index c2231cd5..5913c4de 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/NameClassPairCallbackHandler.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/NameClassPairCallbackHandler.java @@ -19,10 +19,11 @@ package org.springframework.ldap.core; import javax.naming.NameClassPair; /** - * Callback interface used by LdapTemplate's search, list and listBindings + * Callback interface used by {@link LdapTemplate} search, list and listBindings * methods. Implementations of this interface perform the actual work of - * extracting results from a single NameClassPair (a NameClassPair, - * Binding or SearchResult depending on the search operation) returned by an + * extracting results from a single NameClassPair (a + * NameClassPair, Binding or + * SearchResult depending on the search operation) returned by an * LDAP seach operation, such as search(), list(), and listBindings(). * * @author Mattias Arthursson @@ -33,7 +34,8 @@ public interface NameClassPairCallbackHandler { * by a search or list. * * @param nameClassPair - * the NameClassPair returned from the NamingEnumeration. + * the NameClassPair returned from the + * NamingEnumeration. */ public void handleNameClassPair(NameClassPair nameClassPair); } diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/NameClassPairMapper.java b/spring-ldap/src/main/java/org/springframework/ldap/core/NameClassPairMapper.java index be473916..8282368a 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/NameClassPairMapper.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/NameClassPairMapper.java @@ -20,20 +20,22 @@ import javax.naming.NameClassPair; import javax.naming.NamingException; /** - * Responsible for mapping NameClassPair objects to beans. + * Responsible for mapping NameClassPair objects to beans. * * @author Mattias Arthursson */ public interface NameClassPairMapper { /** - * Map NameClassPair to an Object. The supplied NameClassPair is one of the - * results from a search operation (search, list or listBindings). Depending - * on which search operation is being performed, the NameClassPair might be - * a SearchResult, Binding or NameClassPair. + * Map NameClassPair to an Object. The supplied + * NameClassPair is one of the results from a search + * operation (search, list or listBindings). Depending on which search + * operation is being performed, the NameClassPair might be a + * SearchResult, Binding or + * NameClassPair. * * @param nameClassPair - * NameClassPair from a search operation. - * @return and Object built from the NameClassPair. + * NameClassPair from a search operation. + * @return and Object built from the NameClassPair. * @throws NamingException * if one is encountered in the operation. */ diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/ObjectRetrievalException.java b/spring-ldap/src/main/java/org/springframework/ldap/core/ObjectRetrievalException.java index 11670807..94a4235f 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/ObjectRetrievalException.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/ObjectRetrievalException.java @@ -19,8 +19,8 @@ package org.springframework.ldap.core; import org.springframework.ldap.NamingException; /** - * Thrown by a ContextMapperCallbackHandler when it cannot retrieve an object - * from the given Binding. + * Thrown by a {@link ContextMapperCallbackHandler} when it cannot retrieve an + * object from the given Binding. * * @author Ulrik Sandberg * @since 1.2 diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/SearchExecutor.java b/spring-ldap/src/main/java/org/springframework/ldap/core/SearchExecutor.java index bd524490..36f3d2d2 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/SearchExecutor.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/SearchExecutor.java @@ -41,8 +41,9 @@ public interface SearchExecutor { * Execute the actual search. * * @param ctx - * the DirContext on which to work. - * @return the NamingEnumeration resulting from the search operation. + * the DirContext on which to work. + * @return the NamingEnumeration resulting from the search + * operation. * @throws NamingException * if the search results in one. */