Spring/spring-ldap
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Checked javadocs, core package down to LdapEncoder.

Browse Source
This commit is contained in:
Mattias Arthursson
2007-09-24 17:40:17 +00:00
parent 870216c9d7
commit ee80a19aa0
10 changed files with 165 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
spring-ldap/src/main/java/org/springframework/ldap/core/ContextMapper.java
View File

@@ -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 <code>search</code> and
* <code>listBindings</code> 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
* <code>search</code> and <code>listBindings</code> 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.
* <p>
* ContextMapper implementations are typically stateless and thus reusable; they
@@ -37,13 +38,13 @@ import org.springframework.ldap.core.support.DefaultDirObjectFactory;
* <p>
* 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
* <code>DirObjectFactory</code> has been specified on the
* <code>ContextSource</code>.
* @return an object built from the data in the context.
*/
public Object mapFromContext(Object ctx);

19
spring-ldap/src/main/java/org/springframework/ldap/core/ContextMapperCallbackHandler.java
View File

@@ -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.

2
spring-ldap/src/main/java/org/springframework/ldap/core/ContextSource.java
View File

@@ -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
*

25
spring-ldap/src/main/java/org/springframework/ldap/core/DirContextAdapter.java
View File

@@ -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.
* <code>ContextSource</code> (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 <code>ModificationItem</code> 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

36
spring-ldap/src/main/java/org/springframework/ldap/core/DirContextOperations.java
View File

@@ -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 <code>true</code> for a
* new entry and <code>true</code> 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 <code>true</code> for a new entry and <code>true</code>
* 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 (<code>getStringAttribute</code>
* 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 <code>SortedSet</code>.
*
* @param name
* name of the attribute.
* @return a SortedSet containing all values of the attribute.
* @return a <code>SortedSet</code> 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.
*

12
spring-ldap/src/main/java/org/springframework/ldap/core/DirContextProcessor.java
View File

@@ -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 <code>Context</code> 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 <code>DirContext</code> 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 <code>DirContext</code>.
*
* @param ctx
* the DirContext instance.
* the <code>DirContext</code> instance.
* @throws NamingException
* if thrown by the underlying operation.
*/

8
spring-ldap/src/main/java/org/springframework/ldap/core/DirContextProxy.java
View File

@@ -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 <code>DirContext</code>
* from proxies created by <code>ContextSource</code> proxies.
*
* @author Mattias Arthursson
* @since 1.2
*/
public interface DirContextProxy {
/**
* Get the target DirContext of the proxy.
* Get the target <code>DirContext</code> of the proxy.
*
* @return the target DirContext.
* @return the target <code>DirContext</code>.
*/
DirContext getTargetContext();
}

123
spring-ldap/src/main/java/org/springframework/ldap/core/DistinguishedName.java
View File

@@ -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 <code>DistinguishedName</code> 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:
*
* <pre>
* DistinguishedName path = new DistinguishedName();
* path.addLast(&quot;uid&quot;, person.getUid());
* path.addLast(&quot;ou&quot;, &quot;People&quot;);
* path.append(new DistinguishedName(&quot;dc=jayway,dc=se&quot;));
* DistinguishedName path = new DistinguishedName(&quot;dc=jayway,dc=se&quot;);
* path.add(&quot;ou&quot;, &quot;People&quot;);
* path.add(&quot;uid&quot;, &quot;adam.skogman&quot;);
* String dn = path.toString();
* </pre>
*
* will render <code>uid=adam.skogman, ou=People, dc=jayway, dc=se</code>
*
* @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 <code>DistinguishedName</code> 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 <code>DistinguishedName</code> from the supplied
* <code>List</code> 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 <code>DistinguishedName</code> 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
* <code>DistinguishedName</code> 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 <code>List</code>.
*
* @return the list of LdapRdns that this DistinguishedName consists of.
* @return the list of {@link LdapRdn}s that this
* <code>DistinguishedName</code> consists of.
*/
public List getNames() {
return names;
}
/**
* Get the String representation of this DistinguishedName.
* Get the String representation of this <code>DistinguishedName</code>.
*
* @return a syntactically correct, escaped String representation of the
* DistinguishedName.
* @return a syntactically correct, properly escaped String representation
* of the <code>DistinguishedName</code>.
*/
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 <code>DistinguishedName</code> path contains another
* path.
*
* @param path
* the path to check.
* @return true if the supplied path is conained in this instance, false
* otherwise.
* @return <code>true</code> if the supplied path is conained in this
* instance, <code>false</code> 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 <code>DistinguishedName</code>.
*
* @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 <path>. Useful for stripping base path suffix
* from a DistinguishedName.
* Remove the supplied path from the beginning of this
* <code>DistinguishedName</code> if this instance starts with
* <code>path</code>. Useful for stripping base path suffix from a
* <code>DistinguishedName</code>.
*
* @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 <code>DistinguishedName</code> 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
* <code>false</code>.
*
* @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 <code>DistinguishedName</code>.
*
* @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.

5
spring-ldap/src/main/java/org/springframework/ldap/core/DnParser.java
View File

@@ -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 <code>DistinguishedName</code> corresponding to the parsed
* stream.
*/
public DistinguishedName dn() throws ParseException;

22
spring-ldap/src/main/java/org/springframework/ldap/core/LdapEncoder.java
View File

@@ -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 {
* "\"" <br/> '\' [backslash] - "\\" <br/>
*
* @param value
* @return The escaped value
* the value to escape.
* @return The escaped value.
*/
static public String nameEncode(String value) {