From 59a675ef5c9ccf99b09d79fd9411c16ccbdba087 Mon Sep 17 00:00:00 2001 From: Mattias Arthursson Date: Mon, 8 Oct 2007 18:11:25 +0000 Subject: [PATCH] Javadoc review --- .../core/support/AbstractContextMapper.java | 9 ++- .../core/support/AbstractContextSource.java | 67 ++++++++++++------- .../support/AggregateDirContextProcessor.java | 4 +- .../CountNameClassPairCallbackHandler.java | 2 +- .../core/support/DefaultDirObjectFactory.java | 3 +- 5 files changed, 52 insertions(+), 33 deletions(-) diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/support/AbstractContextMapper.java b/spring-ldap/src/main/java/org/springframework/ldap/core/support/AbstractContextMapper.java index fc25f06e..003a2438 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/support/AbstractContextMapper.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/support/AbstractContextMapper.java @@ -31,10 +31,13 @@ import org.springframework.ldap.core.DirContextOperations; */ public abstract class AbstractContextMapper implements ContextMapper { - /* - * (non-Javadoc) + /** + * {@inheritDoc} * - * @see org.springframework.ldap.core.ContextMapper#mapFromContext(java.lang.Object) + * @throws ClassCastException + * if a custom DirObjectFactory implementation is + * used, causing the objects passed in be anything else than + * {@link DirContextOperations} instances. */ public final Object mapFromContext(Object ctx) { return doMapFromContext((DirContextOperations) ctx); diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/support/AbstractContextSource.java b/spring-ldap/src/main/java/org/springframework/ldap/core/support/AbstractContextSource.java index 74878b8e..c2ab5a82 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/support/AbstractContextSource.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/support/AbstractContextSource.java @@ -34,18 +34,19 @@ import org.springframework.ldap.core.DistinguishedName; import org.springframework.ldap.support.LdapUtils; /** - * Abstract implementation of the ContextSource interface. By default, returns - * an authenticated DirContext implementation for both read-only and read-write - * operations. To have an anonymous environment created for read-only - * operations, set the anonymousReadOnly property to true. + * Abstract implementation of the {@link ContextSource} interface. By default, + * returns an authenticated + * DirContext implementation for both read-only and + * read-write operations. To have an anonymous environment created for read-only + * operations, set the anonymousReadOnly property to true. *

* Implementing classes need to implement - * {@link #getDirContextInstance(Hashtable)} to create a DirContext instance of + * {@link #getDirContextInstance(Hashtable)} to create a DirContext instance of * the desired type. *

- * If an AuthenticationSource is set, this will be used for getting user name + * If an {@link AuthenticationSource} is set, this will be used for getting user principal * and password for each new connection, otherwise a default one will be created - * using the specified userDn and password. + * using the specified userDn and password. *

* Note: When using implementations of this class outside of a Spring * Context it is necessary to call {@link #afterPropertiesSet()} when all @@ -97,6 +98,11 @@ public abstract class AbstractContextSource implements ContextSource, private static final String JDK_142 = "1.4.2"; + /* + * (non-Javadoc) + * + * @see org.springframework.ldap.core.ContextSource#getReadOnlyContext() + */ public DirContext getReadOnlyContext() { if (!anonymousReadOnly) { return createContext(getAuthenticatedEnv()); @@ -105,14 +111,18 @@ public abstract class AbstractContextSource implements ContextSource, } } + /* + * (non-Javadoc) + * + * @see org.springframework.ldap.core.ContextSource#getReadWriteContext() + */ public DirContext getReadWriteContext() { return createContext(getAuthenticatedEnv()); } /** * Default implementation of setting the environment up to be authenticated. - * Override in subclass if necessary. This is needed for Active Directory - * connectivity, for example. + * Override in subclass if necessary. * * @param env * the environment to modify. @@ -143,7 +153,7 @@ public abstract class AbstractContextSource implements ContextSource, /** * Assemble a valid url String from all registered urls to add as - * PROVIDER_URL to the environment. + * PROVIDER_URL to the environment. * * @param ldapUrls * all individual url Strings. @@ -166,8 +176,8 @@ public abstract class AbstractContextSource implements ContextSource, /** * Set the base suffix from which all operations should origin. If a base - * suffix is set, you will not have to (and, indeed, should not) specify the - * full distinguished names in the operations performed. + * suffix is set, you will not have to (and, indeed, must not) specify the + * full distinguished names in any operations performed. * * @param base * the base suffix. @@ -178,8 +188,8 @@ public abstract class AbstractContextSource implements ContextSource, /** * Get the base suffix from which all operations should originate. If a base - * suffix is set, you will not have to (and, indeed, should not) specify the - * full distinguished names in the operations performed. + * suffix is set, you will not have to (and, indeed, must not) specify the + * full distinguished names in any operations performed. * * @return the base suffix */ @@ -191,7 +201,8 @@ public abstract class AbstractContextSource implements ContextSource, * Create a DirContext using the supplied environment. * * @param environment - * the Ldap environment to use when creating the DirContext. + * the Ldap environment to use when creating the + * DirContext. * @return a new DirContext implpementation initialized with the supplied * environment. */ @@ -387,7 +398,13 @@ public abstract class AbstractContextSource implements ContextSource, } /** - * Set whether the pooling flag should be set. Default is true. + * Set whether the pooling flag should be set. Default is true. Note that + * since LDAP pooling is system wide, full configuration of this needs be + * done using system parameters as specified in the LDAP/JNDI documentation. + * Also note, that pooling is done on user dn basis, i.e. each individually + * authenticated connection will be pooled separately. This means that LDAP + * pooling will be most efficient using anonymous connections or connections + * authenticated using one single system user. * * @param pooled * whether Contexts should be pooled. @@ -439,7 +456,7 @@ public abstract class AbstractContextSource implements ContextSource, * credentials. * * @param authenticationSource - * the AuthenticationSource that will provide user info. + * the {@link AuthenticationSource} that will provide user info. */ public void setAuthenticationSource( AuthenticationSource authenticationSource) { @@ -449,7 +466,7 @@ public abstract class AbstractContextSource implements ContextSource, /** * Get the authentication source. * - * @return the AuthenticationSource that will provide user info. + * @return the {@link AuthenticationSource} that will provide user info. */ public AuthenticationSource getAuthenticationSource() { return authenticationSource; @@ -457,15 +474,15 @@ public abstract class AbstractContextSource implements ContextSource, /** * Set whether environment properties should be cached between requsts for - * anonymous environment. Default is true; setting this property to false - * causes the environment Hashmap to be rebuilt from the current property - * settings of this instance between each request for an anonymous - * environment. + * anonymous environment. Default is true; setting this + * property to false causes the environment Hashmap to be + * rebuilt from the current property settings of this instance between each + * request for an anonymous environment. * * @param cacheEnvironmentProperties - * true causes that the anonymous environment properties should - * be cached, false causes the Hashmap to be rebuilt for each - * request. + * true causes that the anonymous environment + * properties should be cached, false causes the + * Hashmap to be rebuilt for each request. */ public void setCacheEnvironmentProperties(boolean cacheEnvironmentProperties) { this.cacheEnvironmentProperties = cacheEnvironmentProperties; diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/support/AggregateDirContextProcessor.java b/spring-ldap/src/main/java/org/springframework/ldap/core/support/AggregateDirContextProcessor.java index 2b36e43e..5f4cd33d 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/support/AggregateDirContextProcessor.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/support/AggregateDirContextProcessor.java @@ -26,7 +26,7 @@ import javax.naming.directory.DirContext; import org.springframework.ldap.core.DirContextProcessor; /** - * Manages a sequence of DirContextProcessor instances. Applies + * Manages a sequence of {@link DirContextProcessor} instances. Applies * {@link #preProcess(DirContext)} and {@link #postProcess(DirContext)} * respectively in sequence on the managed objects. * @@ -48,7 +48,7 @@ public class AggregateDirContextProcessor implements DirContextProcessor { } /** - * Get the list of managed DirContextProcessors. + * Get the list of managed {@link DirContextProcessor} instances. * * @return the managed list of {@link DirContextProcessor} instances. */ diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/support/CountNameClassPairCallbackHandler.java b/spring-ldap/src/main/java/org/springframework/ldap/core/support/CountNameClassPairCallbackHandler.java index fab81fcb..ce51601a 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/support/CountNameClassPairCallbackHandler.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/support/CountNameClassPairCallbackHandler.java @@ -20,7 +20,7 @@ import javax.naming.NameClassPair; import org.springframework.ldap.core.NameClassPairCallbackHandler; /** - * A NameClassPairCallbackHandler for counting all returned entries. + * A {@link NameClassPairCallbackHandler} for counting all returned entries. * * @author Mattias Arthursson * diff --git a/spring-ldap/src/main/java/org/springframework/ldap/core/support/DefaultDirObjectFactory.java b/spring-ldap/src/main/java/org/springframework/ldap/core/support/DefaultDirObjectFactory.java index 21d6c067..a5e28476 100644 --- a/spring-ldap/src/main/java/org/springframework/ldap/core/support/DefaultDirObjectFactory.java +++ b/spring-ldap/src/main/java/org/springframework/ldap/core/support/DefaultDirObjectFactory.java @@ -26,10 +26,9 @@ import javax.naming.spi.DirObjectFactory; import org.springframework.ldap.core.DirContextAdapter; import org.springframework.ldap.core.DistinguishedName; - /** * Default implementation of the DirObjectFactory interface. Creates a - * DirContextAdapter from the supplied arguments. + * {@link DirContextAdapter} from the supplied arguments. * * @author Mattias Arthursson */