From ee80a19aa0b8ad76d908bf4c232d3aac1e1f4308 Mon Sep 17 00:00:00 2001 From: Mattias Arthursson Date: Mon, 24 Sep 2007 17:40:17 +0000 Subject: [PATCH] Checked javadocs, core package down to LdapEncoder. --- .../ldap/core/ContextMapper.java | 24 ++-- .../core/ContextMapperCallbackHandler.java | 19 ++- .../ldap/core/ContextSource.java | 2 +- .../ldap/core/DirContextAdapter.java | 25 +++- .../ldap/core/DirContextOperations.java | 36 +++-- .../ldap/core/DirContextProcessor.java | 12 +- .../ldap/core/DirContextProxy.java | 8 +- .../ldap/core/DistinguishedName.java | 123 ++++++++++-------- .../springframework/ldap/core/DnParser.java | 5 +- .../ldap/core/LdapEncoder.java | 22 +++- 10 files changed, 165 insertions(+), 111 deletions(-) diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/ContextMapper.java b/spring-ldap/src/main/java/org/springframework/ldap/core/ContextMapper.java index 7d4ccdef..2d82c243 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/ContextMapper.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/ContextMapper.java @@ -20,16 +20,17 @@ import javax.naming.Binding; import javax.naming.Name; import javax.naming.directory.SearchResult; +import org.springframework.ldap.core.support.AbstractContextMapper; import org.springframework.ldap.core.support.DefaultDirObjectFactory; - /** - * An interface used by LdapTemplate to map LDAP Contexts to beans. Responsible - * for mapping from LDAP Contexts to beans. When a DirObjectFactory is set on - * the ContextSource, the objects returned from search and - * listBindings operations are automatically transformed to - * DirContext objects (when using the {@link DefaultDirObjectFactory}, you get - * a {@link DirContextAdapter} object). This object will then be passed to the + * An interface used by LdapTemplate to map LDAP Contexts to beans. When a + * DirObjectFactory is set on the ContextSource, the objects returned from + * search and listBindings operations are + * automatically transformed to DirContext objects (when using the + * {@link DefaultDirObjectFactory} - which is typically the case, unless + * something else has been explicitly specified - you get a + * {@link DirContextAdapter} object). This object will then be passed to the * ContextMapper implementation for transformation to the desired bean. *

* ContextMapper implementations are typically stateless and thus reusable; they @@ -37,13 +38,13 @@ import org.springframework.ldap.core.support.DefaultDirObjectFactory; *

* Alternatively, consider using an {@link AttributesMapper} in stead. * - * @see LdapTemplate#search(Name, String, - * ContextMapper) + * @see LdapTemplate#search(Name, String, ContextMapper) * @see LdapTemplate#listBindings(Name, ContextMapper) * @see LdapTemplate#lookup(Name, ContextMapper) * @see AttributesMapper * @see DefaultDirObjectFactory * @see DirContextAdapter + * @see AbstractContextMapper * * @author Mattias Arthursson */ @@ -54,7 +55,10 @@ public interface ContextMapper { * {@link Binding}, or a lookup operation. * * @param ctx - * the context to map to an object. + * the context to map to an object. Typically this will be a + * {@link DirContextAdapter} instance, unless a project specific + * DirObjectFactory has been specified on the + * ContextSource. * @return an object built from the data in the context. */ public Object mapFromContext(Object ctx); diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/ContextMapperCallbackHandler.java b/spring-ldap/src/main/java/org/springframework/ldap/core/ContextMapperCallbackHandler.java index dd2bae0b..54c737f0 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/ContextMapperCallbackHandler.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/ContextMapperCallbackHandler.java @@ -19,10 +19,12 @@ package org.springframework.ldap.core; import javax.naming.Binding; import javax.naming.NameClassPair; +import org.apache.commons.lang.Validate; + /** - * A CollectingNameClassPairCallbackHandler to wrap a ContextMapper. That - * is, the found object is extracted from each {@link Binding}, and then - * passed to the specified ContextMapper for translation. + * A CollectingNameClassPairCallbackHandler to wrap a ContextMapper. That is, + * the found object is extracted from each {@link Binding}, and then passed to + * the specified ContextMapper for translation. * * @author Mattias Arthursson * @author Ulrik Sandberg @@ -32,13 +34,20 @@ public class ContextMapperCallbackHandler extends CollectingNameClassPairCallbackHandler { private ContextMapper mapper; + /** + * Constructs a new instance wrapping the supplied {@link ContextMapper}. + * + * @param mapper + * the mapper to be called for each entry. + */ public ContextMapperCallbackHandler(ContextMapper mapper) { + Validate.notNull(mapper, "Mapper must not be empty"); this.mapper = mapper; } /** - * Cast the NameClassPair to a {@link Binding} and pass its attributes - * to the ContextMapper. + * Cast the NameClassPair to a {@link Binding} and pass its attributes to + * the ContextMapper. * * @param nameClassPair * a SearchResult instance. diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/ContextSource.java b/spring-ldap/src/main/java/org/springframework/ldap/core/ContextSource.java index 4e789013..87656e44 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/ContextSource.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/ContextSource.java @@ -21,7 +21,7 @@ import javax.naming.directory.DirContext; import org.springframework.ldap.NamingException; /** - * Interface used to retrieve and authenticate LDAP contexts. + * Interface used by {@link LdapTemplate} to create LDAP contexts. * * @see org.springframework.ldap.core.LdapTemplate * diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/DirContextAdapter.java b/spring-ldap/src/main/java/org/springframework/ldap/core/DirContextAdapter.java index bb752a4b..de8f0928 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/DirContextAdapter.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/DirContextAdapter.java @@ -46,13 +46,26 @@ import org.apache.commons.logging.LogFactory; import org.springframework.ldap.support.LdapUtils; /** - * Implements the interesting methods of the DirContext interface. In particular - * it contains utility methods for getting and setting Attributes. Using the + * Adapter that implements the interesting methods of the DirContext interface. + * In particular it contains utility methods for getting and setting attributes. + * Using the * {@link org.springframework.ldap.core.support.DefaultDirObjectFactory} in your - * ContextSource you may receive instances of this class from searches and - * lookups. This can be particularly useful when updating data, since this class - * implements {@link org.springframework.ldap.core.AttributeModificationsAware}, - * providing a {@link #getModificationItems()} method. + * ContextSource (which is the default) you will receive + * instances of this class from searches and lookups. This can be particularly + * useful when updating data, since this class implements + * {@link AttributeModificationsAware}, providing a + * {@link #getModificationItems()} method. When in update mode, an object of + * this class keeps track of the changes made to its attributes, making them + * available as an array of ModificationItem objects, suitable as + * input to {@link LdapTemplate#modifyAttributes(DirContextOperations)}. + * + * @see #setAttributeValue(String, Object) + * @see #setAttributeValues(String, Object[]) + * @see #getStringAttribute(String) + * @see #getStringAttributes(String) + * @see #getObjectAttribute(String) + * @see #setUpdateMode(boolean) + * @see #isUpdateMode() * * @author Magnus Robertsson * @author Andreas Ronge diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/DirContextOperations.java b/spring-ldap/src/main/java/org/springframework/ldap/core/DirContextOperations.java index 7f48da78..9a2cfceb 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/DirContextOperations.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/DirContextOperations.java @@ -22,19 +22,22 @@ import javax.naming.Name; import javax.naming.directory.DirContext; /** - * Interface for DirContextAdapter to simplify mock testing. + * Interface for DirContextAdapter. * * @author Mattias Arthursson + * @see DirContextAdapter */ public interface DirContextOperations extends DirContext, AttributeModificationsAware { /** - * Gets the update mode. The update mode should be true for a - * new entry and true for an existing entry that is being - * updated. + * Gets the update mode. An entry in update mode will keep track of its + * modifications so that they can be retrieved using + * {@link AttributeModificationsAware#getModificationItems()}. The update + * mode should be true for a new entry and true + * for an existing entry that is being updated. * - * @return update mode + * @return update mode. */ public boolean isUpdateMode(); @@ -50,16 +53,20 @@ public interface DirContextOperations extends DirContext, public String[] getNamesOfModifiedAttributes(); /** - * Get the value of a String attribute. + * Get the value of a String attribute. If more than one attribute value + * exists for the specified attribute, only the first one will be returned. * * @param name * name of the attribute. * @return the value of the attribute. + * @throws ClassCastException + * if the value of the entry is not a String. */ public String getStringAttribute(String name); /** - * Get the value of an Object attribute. + * Get the value of an Object attribute. If more than one attribute value + * exists for the specified attribute, only the first one will be returned. * * @param name * name of the attribute. @@ -141,9 +148,11 @@ public interface DirContextOperations extends DirContext, public void removeAttributeValue(String name, Object value); /** - * Update the attributes. This will mean that the getters - * (getStringAttribute methods) will return the updated values. Remove the - * attributes to be updated. + * Update the attributes.This will mean that the getters (getStringAttribute + * methods) will return the updated values, and the modifications will be + * forgotten (i.e. + * {@link AttributeModificationsAware#getModificationItems()} will return an + * empty array. */ public void update(); @@ -158,16 +167,17 @@ public interface DirContextOperations extends DirContext, public String[] getStringAttributes(String name); /** - * Get all String values of the attribute as a SortedSet. + * Get all String values of the attribute as a SortedSet. * * @param name * name of the attribute. - * @return a SortedSet containing all values of the attribute. + * @return a SortedSet containing all values of the + * attribute. */ public SortedSet getAttributeSortedStringSet(String name); /** - * Returns DN, without the base path. + * Returns the DN relative to the base path. * * @return The distinguished name of the current context. * diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/DirContextProcessor.java b/spring-ldap/src/main/java/org/springframework/ldap/core/DirContextProcessor.java index 7d7031e9..907a682e 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/DirContextProcessor.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/DirContextProcessor.java @@ -20,8 +20,10 @@ import javax.naming.NamingException; import javax.naming.directory.DirContext; /** - * Interface to be called in search by LdapTemplate before and after the actual - * search and enumeration traversal. + * Interface to be called in search by {@link LdapTemplate} before and after the + * actual search and enumeration traversal. Implementations may be used to apply + * search controls on the Context and retrieve the results of + * such controls afterwards. * * @author Mattias Arthursson * @author Ulrik Sandberg @@ -31,17 +33,17 @@ public interface DirContextProcessor { * Perform pre-processing on the supplied DirContext. * * @param ctx - * the DirContext instance. + * the DirContext instance. * @throws NamingException * if thrown by the underlying operation. */ public void preProcess(DirContext ctx) throws NamingException; /** - * Perform post-processing on the supplied DirContext. + * Perform post-processing on the supplied DirContext. * * @param ctx - * the DirContext instance. + * the DirContext instance. * @throws NamingException * if thrown by the underlying operation. */ diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/DirContextProxy.java b/spring-ldap/src/main/java/org/springframework/ldap/core/DirContextProxy.java index 39696566..7e2a997d 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/DirContextProxy.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/DirContextProxy.java @@ -18,17 +18,17 @@ package org.springframework.ldap.core; import javax.naming.directory.DirContext; /** - * Helper interface to be able to get hold of the target DirContext from proxies - * created by ContextSource proxies. + * Helper interface to be able to get hold of the target DirContext + * from proxies created by ContextSource proxies. * * @author Mattias Arthursson * @since 1.2 */ public interface DirContextProxy { /** - * Get the target DirContext of the proxy. + * Get the target DirContext of the proxy. * - * @return the target DirContext. + * @return the target DirContext. */ DirContext getTargetContext(); } diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/DistinguishedName.java b/spring-ldap/src/main/java/org/springframework/ldap/core/DistinguishedName.java index 7d0682da..9f8dd104 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/DistinguishedName.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/DistinguishedName.java @@ -26,18 +26,19 @@ import java.util.ListIterator; import javax.naming.CompositeName; import javax.naming.InvalidNameException; import javax.naming.Name; +import javax.naming.ldap.Rdn; import org.apache.commons.lang.StringUtils; import org.springframework.ldap.BadLdapGrammarException; import org.springframework.ldap.support.ListComparator; /** - * Default implementation of a Name corresponding to an LDAP path. A - * DistinguishedName implementation is included in JDK1.5 (LdapName), but not in - * prior releases. + * Default implementation of a {@link Name} corresponding to an LDAP path. A + * Distinguished Name manipulation implementation is included in JDK1.5 + * (LdapName), but not in prior releases. * - * A DistinguishedName is particularly useful when building or modifying an LDAP - * path dynamically, as escaping will be taken care of. + * A DistinguishedName is particularly useful when building or + * modifying an LDAP path dynamically, as escaping will be taken care of. * * A path is split into several names. The {@link Name} interface specifies that * the most significant part be in position 0. @@ -58,13 +59,14 @@ import org.springframework.ldap.support.ListComparator; * Example: * * 

- * DistinguishedName path = new DistinguishedName();
- * path.addLast("uid", person.getUid());
- * path.addLast("ou", "People");
- * path.append(new DistinguishedName("dc=jayway,dc=se"));
+ * DistinguishedName path = new DistinguishedName("dc=jayway,dc=se");
+ * path.add("ou", "People");
+ * path.add("uid", "adam.skogman");
  * String dn = path.toString();
  *
* + * will render uid=adam.skogman, ou=People, dc=jayway, dc=se + * * @author Adam Skogman * @author Mattias Arthursson */ @@ -87,7 +89,7 @@ public class DistinguishedName implements Name { } /** - * Construct a new DistinguishedName from a String. + * Construct a new DistinguishedName from a String. * * @param path * a String corresponding to a (syntactically) valid LDAP path. @@ -101,8 +103,8 @@ public class DistinguishedName implements Name { } /** - * Construct a new DistinguishedName from the supplied List of LdapRdn - * objects. + * Construct a new DistinguishedName from the supplied + * List of {@link LdapRdn} objects. * * @param list * the components that this instance will consist of. @@ -112,11 +114,13 @@ public class DistinguishedName implements Name { } /** - * Construct a new DistinguishedName from the supplied Name. The parts of - * the supplied Name must be syntactically correct LdapRdns. + * Construct a new DistinguishedName from the supplied + * {@link Name}. The parts of the supplied {@link Name} must be + * syntactically correct {@link LdapRdn}s. * * @param name - * the Name to construct a new DistinguishedName from. + * the {@link Name} to construct a new + * DistinguishedName from. */ public DistinguishedName(Name name) { names = new LinkedList(); @@ -149,7 +153,8 @@ public class DistinguishedName implements Name { /** * If path is surrounded by quotes, strip them. JNDI considers forward slash * ('/') special, but LDAP doesn't. {@link CompositeName#toString()} tends - * to mangle a Name with a slash by surrounding it with quotes ('"'). + * to mangle a {@link Name} with a slash by surrounding it with quotes + * ('"'). * * @param path * Path to check and possibly strip. @@ -167,24 +172,24 @@ public class DistinguishedName implements Name { } /** - * Get the LdapRdn at a specified position. + * Get the {@link LdapRdn} at a specified position. * * @param index - * the LdapRdn to retrieve. - * @return the LdapRdn at the requested position. + * the {@link LdapRdn} to retrieve. + * @return the {@link LdapRdn} at the requested position. */ public LdapRdn getLdapRdn(int index) { return (LdapRdn) names.get(index); } /** - * Get the LdapRdn with the specified key. If there are several Rdns with - * the same key, the first one found (in order of significance) will be - * returned. + * Get the {@link LdapRdn} with the specified key. If there are several + * {@link Rdn}s with the same key, the first one found (in order of + * significance) will be returned. * * @param key - * Attribute name of the LdapRdn to retrieve. - * @return the LdapRdn with the requested key. + * Attribute name of the {@link LdapRdn} to retrieve. + * @return the {@link LdapRdn} with the requested key. * @throws IllegalArgumentException * if no Rdn matches the given key. */ @@ -201,12 +206,12 @@ public class DistinguishedName implements Name { } /** - * Get the value of the RdnComponent with the specified key (Attribute - * value). If there are several Rdns with the same key, the value of the - * first one found (in order of significance) will be returned. + * Get the value of the {@link LdapRdnComponent} with the specified key + * (Attribute value). If there are several Rdns with the same key, the value + * of the first one found (in order of significance) will be returned. * * @param key - * Attribute name of the LdapRdn to retrieve. + * Attribute name of the {@link LdapRdn} to retrieve. * @return the value. * @throws IllegalArgumentException * if no Rdn matches the given key. @@ -216,19 +221,20 @@ public class DistinguishedName implements Name { } /** - * Get the name list. + * Get the name List. * - * @return the list of LdapRdns that this DistinguishedName consists of. + * @return the list of {@link LdapRdn}s that this + * DistinguishedName consists of. */ public List getNames() { return names; } /** - * Get the String representation of this DistinguishedName. + * Get the String representation of this DistinguishedName. * - * @return a syntactically correct, escaped String representation of the - * DistinguishedName. + * @return a syntactically correct, properly escaped String representation + * of the DistinguishedName. */ public String toString() { return encode(); @@ -283,12 +289,13 @@ public class DistinguishedName implements Name { } /** - * Determines if a ldap path contains another path. + * Determines if this DistinguishedName path contains another + * path. * * @param path * the path to check. - * @return true if the supplied path is conained in this instance, false - * otherwise. + * @return true if the supplied path is conained in this + * instance, false otherwise. */ public boolean contains(DistinguishedName path) { @@ -353,17 +360,17 @@ public class DistinguishedName implements Name { getNames().addAll(path.getNames()); return this; } - + /** - * Append a new LdapRdn using the supplied key and value. + * Append a new {@link LdapRdn} using the supplied key and value. * * @param key - * the key of the LdapRdn. + * the key of the {@link LdapRdn}. * @param value - * the value of the LdapRdn. + * the value of the {@link LdapRdn}. * @return this instance. */ - public DistinguishedName append(String key, String value){ + public DistinguishedName append(String key, String value) { add(key, value); return this; } @@ -390,7 +397,7 @@ public class DistinguishedName implements Name { } /** - * Remove the first part of this DistinguishedName. + * Remove the first part of this DistinguishedName. * * @return the removed entry. */ @@ -399,9 +406,10 @@ public class DistinguishedName implements Name { } /** - * Remove the supplied path from the beginning of this DistinguishedName if - * this instance starts with . Useful for stripping base path suffix - * from a DistinguishedName. + * Remove the supplied path from the beginning of this + * DistinguishedName if this instance starts with + * path. Useful for stripping base path suffix from a + * DistinguishedName. * * @param path * the path to remove from the beginning of this instance. @@ -563,13 +571,14 @@ public class DistinguishedName implements Name { } /** - * Determines if this ldap path ends with a certian path. + * Determines if this DistinguishedName ends with a certian + * path. * - * If the argument path is empty (no names in path) this methid will return - * false. + * If the argument path is empty (no names in path) this method will return + * false. * * @param name - * The suffix to check for + * The suffix to check for. * */ public boolean endsWith(Name name) { @@ -667,38 +676,38 @@ public class DistinguishedName implements Name { } /** - * Remove the ldast part of this DistinguishedName. + * Remove the last part of this DistinguishedName. * - * @return the removed LdapRdn. + * @return the removed {@link LdapRdn}. */ public LdapRdn removeLast() { return (LdapRdn) names.remove(names.size() - 1); } /** - * Add a new LdapRdn using the supplied key and value. + * Add a new {@link LdapRdn} using the supplied key and value. * * @param key - * the key of the LdapRdn. + * the key of the {@link LdapRdn}. * @param value - * the value of the LdapRdn. + * the value of the {@link LdapRdn}. */ public void add(String key, String value) { names.add(new LdapRdn(key, value)); } /** - * Add the supplied LdapRdn last in the list of Rdns. + * Add the supplied {@link LdapRdn} last in the list of Rdns. * * @param rdn - * the LdapRdn to add. + * the {@link LdapRdn} to add. */ public void add(LdapRdn rdn) { names.add(rdn); } /** - * Add the supplied LdapRdn att the specified index. + * Add the supplied {@link LdapRdn} att the specified index. * * @param idx * the index at which to add the LdapRdn. diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/DnParser.java b/spring-ldap/src/main/java/org/springframework/ldap/core/DnParser.java index 1aad7c0c..b4cbb81d 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/DnParser.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/DnParser.java @@ -15,8 +15,6 @@ */ package org.springframework.ldap.core; - - /** * A parser for RFC2253-compliant Distinguished Names. * @@ -27,7 +25,8 @@ public interface DnParser { /** * Parse a full Distinguished Name. * - * @return the DistinguishedName corresponding to the parsed stream. + * @return the DistinguishedName corresponding to the parsed + * stream. */ public DistinguishedName dn() throws ParseException; diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/LdapEncoder.java b/spring-ldap/src/main/java/org/springframework/ldap/core/LdapEncoder.java index 3d075006..8c54209f 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/LdapEncoder.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/LdapEncoder.java @@ -65,7 +65,13 @@ public class LdapEncoder { } - static protected String toTwoCharHex(char c) { + /** + * All static methods - not to be instantiated. + */ + private LdapEncoder() { + } + + protected static String toTwoCharHex(char c) { String raw = Integer.toHexString(c).toUpperCase(); @@ -76,12 +82,13 @@ public class LdapEncoder { } /** - * All static methods + * Escape a value for use in a filter. + * + * @param value + * the value to escape. + * @return a properly escaped representation of the supplied value. */ - private LdapEncoder() { - } - - static public String filterEncode(String value) { + public static String filterEncode(String value) { if (value == null) return null; @@ -116,7 +123,8 @@ public class LdapEncoder { * "\""
'\' [backslash] - "\\"
* * @param value - * @return The escaped value + * the value to escape. + * @return The escaped value. */ static public String nameEncode(String value) {