diff --git a/spring-ldap/src/main/java/org/springframework/ldap/authentication/DefaultValuesAuthenticationSourceDecorator.java b/spring-ldap/src/main/java/org/springframework/ldap/authentication/DefaultValuesAuthenticationSourceDecorator.java index ff6968a1..7f5acc9a 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/authentication/DefaultValuesAuthenticationSourceDecorator.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/authentication/DefaultValuesAuthenticationSourceDecorator.java @@ -87,10 +87,10 @@ public class DefaultValuesAuthenticationSourceDecorator implements /** * Checks if the target's principal is not empty; if not, this is returned - - * otherwise return the defaultUser. + * otherwise return the defaultPassword. * * @return the target's principal if it is not empty, the - * defaultUser otherwise. + * defaultPassword otherwise. */ public String getPrincipal() { String principal = target.getPrincipal(); diff --git a/spring-ldap/src/main/java/org/springframework/ldap/control/AbstractRequestControlDirContextProcessor.java b/spring-ldap/src/main/java/org/springframework/ldap/control/AbstractRequestControlDirContextProcessor.java index 7b2ec041..5ecdee02 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/control/AbstractRequestControlDirContextProcessor.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/control/AbstractRequestControlDirContextProcessor.java @@ -48,7 +48,7 @@ public abstract class AbstractRequestControlDirContextProcessor implements * to {@link LdapContext}. However, the generic DirContextProcessor * mechanism used for calling preProcess and * postProcess uses DirContext, since it also works for LDAP - * v2. This is the reason that DirContext has to be cast into LdapContext. + * v2. This is the reason that DirContext has to be cast to a LdapContext. * * @param ctx * an LdapContext instance. diff --git a/spring-ldap/src/main/java/org/springframework/ldap/control/PagedResult.java b/spring-ldap/src/main/java/org/springframework/ldap/control/PagedResult.java index 7c93a61b..d2e898af 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/control/PagedResult.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/control/PagedResult.java @@ -23,6 +23,9 @@ import org.apache.commons.lang.builder.HashCodeBuilder; /** * Bean to encapsulate a result List and a {@link PagedResultsCookie} to use for * returning the results when using {@link PagedResultsRequestControl}. + * + * @author Mattias Arthursson + * @author Ulrik Sandberg */ public class PagedResult { diff --git a/spring-ldap/src/main/java/org/springframework/ldap/control/PagedResultsRequestControl.java b/spring-ldap/src/main/java/org/springframework/ldap/control/PagedResultsRequestControl.java index 15d1853d..dcc9dc6c 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/control/PagedResultsRequestControl.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/control/PagedResultsRequestControl.java @@ -31,7 +31,7 @@ import com.sun.jndi.ldap.ctl.PagedResultsControl; import com.sun.jndi.ldap.ctl.PagedResultsResponseControl; /** - * DirContextProcessor implementation for managing the paged results. + * DirContextProcessor implementation for managing the paged results control. * * @author Mattias Arthursson * @author Ulrik Sandberg @@ -57,24 +57,60 @@ public class PagedResultsRequestControl extends private Class currentResponseControlClass; + /** + * Constructs a new instance. This constructor should be used when + * performing the first paged search operation, when no other results have + * been retrieved. + * + * @param pageSize + * the page size. + */ public PagedResultsRequestControl(int pageSize) { this(pageSize, null); } + /** + * Constructs a new instance with the supplied page size and cookie. The + * cookie must be the exact same instance as received from a previous paged + * resullts search, or null if it is the first in an + * operation sequence. + * + * @param pageSize + * the page size. + * @param cookie + * the cookie, as received from a previous search. + */ public PagedResultsRequestControl(int pageSize, PagedResultsCookie cookie) { this.pageSize = pageSize; this.cookie = cookie; fallbackResponseControlClass = loadFallbackResponseControlClass(); } + /** + * Get the cookie. + * + * @return the cookie. + */ public PagedResultsCookie getCookie() { return cookie; } + /** + * Get the page size. + * + * @return the page size. + */ public int getPageSize() { return pageSize; } + /** + * Get the total estimated number of entries that matches the issued search. + * Note that this value is optional for the LDAP server to return, so it + * does not always contain any valid data. + * + * @return the estimated result size, if returned from the server. + */ public int getResultSize() { return resultSize; } diff --git a/spring-ldap/src/main/java/org/springframework/ldap/control/SortControlDirContextProcessor.java b/spring-ldap/src/main/java/org/springframework/ldap/control/SortControlDirContextProcessor.java index b10db96d..94c6f92a 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/control/SortControlDirContextProcessor.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/control/SortControlDirContextProcessor.java @@ -34,6 +34,8 @@ import com.sun.jndi.ldap.ctl.SortResponseControl; /** * DirContextProcessor implementation for managing the {@link SortControl}. + * Note that this class is stateful, so a new instance needs to be instantiated + * for each new search. * * @author Ulrik Sandberg */ @@ -67,6 +69,12 @@ public class SortControlDirContextProcessor extends private Class currentResponseControlClass; + /** + * Constructs a new instance using the supplied sort key. + * + * @param sortKey + * the sort key, i.e. the attribute name to sort on. + */ public SortControlDirContextProcessor(String sortKey) { this.sortKey = sortKey; fallbackResponseControlClass = loadFallbackResponseControlClass(); @@ -85,14 +93,25 @@ public class SortControlDirContextProcessor extends this.responseControlClass = responseControlClass; } + /** + * Check whether the returned values were actually sorted by the server. + * + * @return true if the result was sorted, false + * otherwise. + */ public boolean isSorted() { return sorted; } private void setSorted(boolean sorted) { this.sorted = sorted; - } + } + /** + * Get the result code returned by the control. + * + * @return result code. + */ public int getResultCode() { return resultCode; } @@ -101,10 +120,21 @@ public class SortControlDirContextProcessor extends this.resultCode = sortResult; } + /** + * Get the sort key. + * + * @return the sort key. + */ public String getSortKey() { return sortKey; } + /** + * Set the sort key, i.e. the attribute on which to sort on. + * + * @param sortKey + * the sort key. + */ public void setSortKey(String sortKey) { this.sortKey = sortKey; } diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/AttributeModificationsAware.java b/spring-ldap/src/main/java/org/springframework/ldap/core/AttributeModificationsAware.java index 1460f0b4..089ca336 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/AttributeModificationsAware.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/AttributeModificationsAware.java @@ -19,8 +19,8 @@ package org.springframework.ldap.core; import javax.naming.directory.ModificationItem; /** - * Indicates that the implementor is capable of keeping track of any attribute - * modifications and return them as ModificationItems. + * Indicates that the implementing class is capable of keeping track of any + * attribute modifications and return them as ModificationItems. * * @author Mattias Arthursson * @@ -28,9 +28,10 @@ import javax.naming.directory.ModificationItem; public interface AttributeModificationsAware { /** - * Creates an array of which attributes have been changed or added or removed. + * Creates an array of which attributes have been changed, added or removed + * since the initialization of this object. * - * @return an array of modification items + * @return an array of modification items. */ public ModificationItem[] getModificationItems(); } diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/AttributesMapper.java b/spring-ldap/src/main/java/org/springframework/ldap/core/AttributesMapper.java index afbec196..b090bf1f 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/AttributesMapper.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/AttributesMapper.java @@ -23,17 +23,18 @@ import javax.naming.directory.Attributes; /** * An interface used by LdapTemplate for mapping LDAP Attributes to beans. * Implementions of this interface perform the actual work of extracting - * results, but need not worry about exception handling. NamingExceptions will - * be caught and handled correctly by the LdapTemplate class. + * results, but need not worry about exception handling. NamingExceptions will + * be caught and handled correctly by the {@link LdapTemplate} class. *

- * Typically used in LdapTemplate's search methods. AttributeMapper objects are - * typically stateless and thus reusable; they are ideal for implementing - * attribute-mapping logic in one place. + * Typically used in search methods of {@link LdapTemplate}. + * AttributeMapper objects are normally stateless and thus + * reusable; they are ideal for implementing attribute-mapping logic in one + * place. *

* Alternatively, consider using a {@link ContextMapper} in stead. * - * @see org.springframework.ldap.core.LdapTemplate#search(Name, String, - * AttributesMapper) + * @see LdapTemplate#search(Name, String, AttributesMapper) + * @see LdapTemplate#lookup(Name, AttributesMapper) * @see ContextMapper * * @author Mattias Arthursson @@ -46,7 +47,8 @@ public interface AttributesMapper { * @param attributes * attributes from a SearchResult. * @return an object built from the attributes. - * @throws NamingException if any error occurs mapping the attributes + * @throws NamingException + * if any error occurs mapping the attributes */ public Object mapFromAttributes(Attributes attributes) throws NamingException; diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/AttributesMapperCallbackHandler.java b/spring-ldap/src/main/java/org/springframework/ldap/core/AttributesMapperCallbackHandler.java index 1e1ced2b..dfbdd552 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/AttributesMapperCallbackHandler.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/AttributesMapperCallbackHandler.java @@ -23,10 +23,10 @@ import javax.naming.directory.SearchResult; import org.springframework.ldap.support.LdapUtils; /** - * A CollectingNameClassPairCallbackHandler to wrap an AttributesMapper. - * That is, the found object is extracted from the {@link Attributes} of - * each {@link SearchResult}, and then passed to the specified - * AttributesMapper for translation. + * A CollectingNameClassPairCallbackHandler to wrap an {@link AttributesMapper}. + * That is, the found object is extracted from the {@link Attributes} of each + * {@link SearchResult}, and then passed to the specified + * {@link AttributesMapper} for translation. * * @author Mattias Arthursson * @author Ulrik Sandberg @@ -36,17 +36,23 @@ public class AttributesMapperCallbackHandler extends CollectingNameClassPairCallbackHandler { private AttributesMapper mapper; + /** + * Constructs a new instance around the specified {@link AttributesMapper}. + * + * @param mapper + * the target mapper. + */ public AttributesMapperCallbackHandler(AttributesMapper mapper) { this.mapper = mapper; } /** - * Cast the NameClassPair to a SearchResult and pass its attributes to - * the AttributesMapper. + * Cast the NameClassPair to a SearchResult and pass its attributes to the + * {@link AttributesMapper}. * * @param nameClassPair - * a SearchResult instance. - * @return the Object returned from the Mapper. + * a SearchResult instance. + * @return the Object returned from the mapper. */ public Object getObjectFromNameClassPair(NameClassPair nameClassPair) { SearchResult searchResult = (SearchResult) nameClassPair; diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/AuthenticationSource.java b/spring-ldap/src/main/java/org/springframework/ldap/core/AuthenticationSource.java index ed2a18d0..4f368e09 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/AuthenticationSource.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/AuthenticationSource.java @@ -17,8 +17,8 @@ package org.springframework.ldap.core; /** - * An AuthenticationSource is responsible for providing the principal and - * credentials to be used when creating a new context. + * An AuthenticationSource is responsible for providing the + * principal (user DN) and credentials to be used when creating a new context. * * @author Mattias Arthursson * diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/CollectingNameClassPairCallbackHandler.java b/spring-ldap/src/main/java/org/springframework/ldap/core/CollectingNameClassPairCallbackHandler.java index 6cb2f127..ebb3a5dd 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/CollectingNameClassPairCallbackHandler.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/CollectingNameClassPairCallbackHandler.java @@ -23,7 +23,7 @@ import javax.naming.NameClassPair; /** * A NameClassPairCallbackHandler to collect all results in an internal List. * - * @see org.springframework.ldap.core.LdapTemplate + * @see LdapTemplate * * @author Mattias Arthursson */ diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/ContextExecutor.java b/spring-ldap/src/main/java/org/springframework/ldap/core/ContextExecutor.java index c68f2c69..3feb41bf 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/ContextExecutor.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/ContextExecutor.java @@ -19,20 +19,20 @@ import javax.naming.NamingException; import javax.naming.directory.DirContext; /** - * Interface for delegating an actual operation to be performed on an - * DirContext. For searches, use {@link org.springframework.ldap.core.SearchExecutor} in + * Interface for delegating an actual operation to be performed on a + * DirContext. For searches, use {@link SearchExecutor} in * stead. A typical usage of this interface could be e.g.: * * 

- * ContextExecutor executor = new ContextExecutor(){
- *   public Object executeWithContext(DirContext ctx) throws NamingException{
- *     return ctx.lookup(dn);
- *   }
+ * ContextExecutor executor = new ContextExecutor() {
+ *     public Object executeWithContext(DirContext ctx) throws NamingException {
+ *         return ctx.lookup(dn);
+ *     }
  * };
  *
* - * @see org.springframework.ldap.core.LdapTemplate#executeReadOnly(ContextExecutor) - * @see org.springframework.ldap.core.LdapTemplate#executeReadWrite(ContextExecutor) + * @see LdapTemplate#executeReadOnly(ContextExecutor) + * @see LdapTemplate#executeReadWrite(ContextExecutor) * * @author Mattias Arthursson */ diff --git a/spring-ldap/src/main/java/org/springframework/ldap/package.html b/spring-ldap/src/main/java/org/springframework/ldap/package.html index 74a2fbdd..f3059be9 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/package.html +++ b/spring-ldap/src/main/java/org/springframework/ldap/package.html @@ -1,8 +1,7 @@ -This package contains integration classes for JNDI/LDAP, -allowing for Spring-style LDAP access. +Base package of Spring LDAP, containing an unchecked mirror of the JNDI NamingException hierarchy.