Finalized SimpleLdapTemplate.

spring-ldap-tiger/src/itest/java/org/springframework/ldap/core/simple/SimpleLdapTemplateITest.java

@@ -0,0 +1,76 @@
+/*
+ * Copyright 2005-2007 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.ldap.core.simple;
+
+import java.util.List;
+
+import org.springframework.ldap.AbstractLdapTemplateIntegrationTest;
+import org.springframework.ldap.core.DirContextAdapter;
+import org.springframework.ldap.core.DirContextOperations;
+
+public class SimpleLdapTemplateITest extends AbstractLdapTemplateIntegrationTest {
+
+	private SimpleLdapTemplate ldapTemplate;
+
+	protected String[] getConfigLocations() {
+		return new String[] { "/conf/ldapTemplateTestContext.xml" };
+	}
+
+	public void setSimplLdapTemplate(SimpleLdapTemplate ldapTemplate) {
+		this.ldapTemplate = ldapTemplate;
+	}
+
+	public void testLookup() {
+		String result = ldapTemplate.lookup("cn=Some Person,ou=company1,c=Sweden", new CnContextMapper());
+		assertEquals("Some Person", result);
+	}
+
+	public void testSearch() {
+		List<String> cns = ldapTemplate.search("", "(&(objectclass=person)(sn=Person3))", new CnContextMapper());
+
+		assertEquals(1, cns.size());
+		assertEquals("Some Person3", cns.get(0));
+	}
+
+	public void testModifyAttributes() {
+		DirContextOperations ctx = ldapTemplate.lookup("cn=Some Person,ou=company1,c=Sweden");
+
+		ctx.setAttributeValue("description", "updated description");
+		ctx.setAttributeValue("telephoneNumber", "0000001");
+
+		ldapTemplate.modifyAttributes(ctx);
+
+		// verify that the data was properly updated.
+		ldapTemplate.lookup("cn=Some Person,ou=company1,c=Sweden", new ParametrizedContextMapper<Object>() {
+			public Object mapFromContext(Object ctx) {
+				DirContextAdapter adapter = (DirContextAdapter) ctx;
+				assertEquals("updated description", adapter.getStringAttribute("description"));
+				assertEquals("0000001", adapter.getStringAttribute("telephoneNumber"));
+				return null;
+			}
+		});
+	}
+
+	private static class CnContextMapper implements ParametrizedContextMapper<String> {
+
+		public String mapFromContext(Object ctx) {
+			DirContextAdapter adapter = (DirContextAdapter) ctx;
+
+			return adapter.getStringAttribute("cn");
+		}
+	}
+
+}

spring-ldap-tiger/src/itest/java/org/springframework/ldap/core/simple/SimpleLdapTemplateTest.java

@@ -1,41 +0,0 @@
-package org.springframework.ldap.core.simple;
-
-import java.util.List;
-
-import org.springframework.ldap.AbstractLdapTemplateIntegrationTest;
-import org.springframework.ldap.core.DirContextAdapter;
-
-public class SimpleLdapTemplateTest extends AbstractLdapTemplateIntegrationTest {
-
-	private SimpleLdapTemplate ldapTemplate;
-
-	protected String[] getConfigLocations() {
-		return new String[] { "/conf/ldapTemplateTestContext.xml" };
-	}
-
-	public void setSimplLdapTemplate(SimpleLdapTemplate ldapTemplate) {
-		this.ldapTemplate = ldapTemplate;
-	}
-
-	public void testLookup() {
-		String result = ldapTemplate.lookup("cn=Some Person,ou=company1,c=Sweden", new CnContextMapper());
-		assertEquals("Some Person", result);
-	}
-
-	public void testSearch1() {
-		List<String> cns = ldapTemplate.search("", "(&(objectclass=person)(sn=Person3))", new CnContextMapper());
-
-		assertEquals(1, cns.size());
-		assertEquals("Some Person3", cns.get(0));
-	}
-
-	private static class CnContextMapper implements ParametrizedContextMapper<String> {
-
-		public String mapFromContext(Object ctx) {
-			DirContextAdapter adapter = (DirContextAdapter) ctx;
-
-			return adapter.getStringAttribute("cn");
-		}
-	}
-
-}

spring-ldap-tiger/src/main/java/org/springframework/ldap/core/simple/SimpleLdapOperations.java

@@ -1,20 +1,145 @@
+/*
+ * Copyright 2005-2007 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 package org.springframework.ldap.core.simple;
 
 import java.util.List;
 
+import javax.naming.Name;
+import javax.naming.directory.Attributes;
 import javax.naming.directory.SearchControls;
 
+import org.springframework.ldap.NamingException;
+import org.springframework.ldap.core.DirContextOperations;
 import org.springframework.ldap.core.DirContextProcessor;
 import org.springframework.ldap.core.LdapOperations;
 
+/**
+ * LDAP operations interface usable on Java 5 and above, exposing a set of
+ * common LDAP operations.
+ * 
+ * @author Mattias Arthursson
+ */
 public interface SimpleLdapOperations {
 
+	/**
+	 * Get the wrapped LdapOperations instance.
+	 * 
+	 * @return the wrapped LdapOperations instance.
+	 * @throws NamingException if any error occurs.
+	 */
 	LdapOperations getLdapOperations();
 
+	/**
+	 * Search for a List of type T using the supplied filter and link
+	 * ParametrizedContextMapper.
+	 * 
+	 * @param base Base DN relative to the base of the ContextSource - where to
+	 * start the search.
+	 * @param filter Search filter.
+	 * @param mapper the Mapper to supply all results to.
+	 * @return a List of type T containing objects for all entries found, as
+	 * mapped by the ParametrizedContextMapper.
+	 * @throws NamingException if any error occurs.
+	 */
 	<T> List<T> search(String base, String filter, ParametrizedContextMapper<T> mapper);
 
+	/**
+	 * Search for a List of type T using the supplied filter, SearchControls,
+	 * DirContextProcessor and ParametrizedContextMapper.
+	 * 
+	 * @param base Base DN relative to the base of the ContextSource - where to
+	 * start the search.
+	 * @param filter Search filter.
+	 * @param controls the SearchControls. Make sure that the returningObjFlag
+	 * is set to <code>true</code>.
+	 * @param mapper the Mapper to supply all results to.
+	 * @param processor the DirContextProcessor to be used for applying pre/post
+	 * processing on the DirContext instance.
+	 * @return a List of type T containing objects for all entries found, as
+	 * mapped by the ParametrizedContextMapper.
+	 * @throws NamingException if any error occurs.
+	 */
 	<T> List<T> search(String base, String filter, SearchControls controls, ParametrizedContextMapper<T> mapper,
 			DirContextProcessor processor);
 
+	/**
+	 * Perform a lookup of the specified DN and map the result using the mapper.
+	 * 
+	 * @param dn the Distinguished Name to look up.
+	 * @param mapper the mapper to use.
+	 * @return the mapped object, as received by the ParametrizedContextMapper.
+	 * @throws NamingException if any error occurs.
+	 */
 	<T> T lookup(String dn, ParametrizedContextMapper<T> mapper);
+
+	/**
+	 * Look up the specified DN, and automatically cast it to a
+	 * {@link DirContextOperations} instance.
+	 * 
+	 * @param dn The Distinguished Name of the entry to look up.
+	 * @return A {@link DirContextOperations} instance constructed from the
+	 * found entry.
+	 * @throws NamingException if any error occurs.
+	 */
+	DirContextOperations lookup(String dn);
+
+	/**
+	 * Create an entry in the LDAP tree. The attributes used to create the entry
+	 * are either retrieved from the <code>obj</code> parameter or the
+	 * <code>attributes</code> parameter (or both). One of these parameters
+	 * 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.
+	 * @param attributes The attributes to bind, may be null.
+	 * @throws NamingException if any error occurs.
+	 */
+	void bind(String dn, Object obj, Attributes attributes);
+
+	/**
+	 * Remove an entry from the LDAP tree. The entry must not have any children -
+	 * if you suspect that the entry might have descendants, use
+	 * {@link #unbind(Name, boolean)} in stead.
+	 * 
+	 * @param dn The distinguished name to unbind.
+	 * @throws NamingException if any error occurs.
+	 */
+	void unbind(String dn);
+
+	/**
+	 * Modify the Attributes of the entry corresponsing to the supplied
+	 * {@link DirContextOperations} instance. The instance should have been
+	 * received from the {@link #lookup(String)} operation, and then modified to
+	 * match the current state of the matching domain object, e.g.:
+	 * 
+	 * <pre>
+	 * public void update(Person person) {
+	 * 	DirContextOperations ctx = simpleLdapOperations.lookup(person.getDn());
+	 * 
+	 * 	ctx.setAttributeValue(&quot;description&quot;, person.getDescription());
+	 * 	ctx.setAttributeValue(&quot;telephoneNumber&quot;, person.getPhone());
+	 * 	// More modifications here
+	 * 
+	 * 	simpleLdapOperations.modifyAttributes(ctx);
+	 * }
+	 * </pre>
+	 * 
+	 * @param ctx the entry to update in the LDAP tree.
+	 * @throws NamingException if any error occurs.
+	 */
+	void modifyAttributes(DirContextOperations ctx);
 }

spring-ldap-tiger/src/main/java/org/springframework/ldap/core/simple/SimpleLdapTemplate.java

@@ -1,22 +1,60 @@
+/*
+ * Copyright 2005-2007 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 package org.springframework.ldap.core.simple;
 
 import java.util.List;
 
+import javax.naming.directory.Attributes;
 import javax.naming.directory.SearchControls;
 
 import org.springframework.ldap.core.ContextSource;
+import org.springframework.ldap.core.DirContextOperations;
 import org.springframework.ldap.core.DirContextProcessor;
 import org.springframework.ldap.core.LdapOperations;
 import org.springframework.ldap.core.LdapTemplate;
 
+/**
+ * Java-5-based convenience wrapper for the classic LdapTemplate, adding some
+ * convenient shortcuts and taking advantage of Java 5 Generics.
+ * 
+ * Use the {@link #getLdapOperations()} method if you need to invoke less
+ * commonly used template methods.
+ * 
+ * @author Mattias Arthursson
+ */
 public class SimpleLdapTemplate implements SimpleLdapOperations {
 
 	private LdapOperations ldapOperations;
 
+	/**
+	 * Constructs a new SimpleLdapTemplate instance wrapping the supplied
+	 * LdapOperations instance.
+	 * 
+	 * @param ldapOperations the LdapOperations instance to wrap.
+	 */
 	public SimpleLdapTemplate(LdapOperations ldapOperations) {
 		this.ldapOperations = ldapOperations;
 	}
 
+	/**
+	 * Constructs a new SimpleLdapTemplate instance, automatically creating a
+	 * wrapped LdapTemplate instance to work with.
+	 * 
+	 * @param contextSource
+	 */
 	public SimpleLdapTemplate(ContextSource contextSource) {
 		this.ldapOperations = new LdapTemplate(contextSource);
 	}
@@ -63,4 +101,37 @@ public class SimpleLdapTemplate implements SimpleLdapOperations {
 		return ldapOperations.search(base, filter, controls, mapper);
 	}
 
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.ldap.core.simple.SimpleLdapOperations#lookup(java.lang.String)
+	 */
+	public DirContextOperations lookup(String dn) {
+		return (DirContextOperations) ldapOperations.lookup(dn);
+	}
+
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.ldap.core.simple.SimpleLdapOperations#modifyAttributes(org.springframework.ldap.core.DirContextOperations)
+	 */
+	public void modifyAttributes(DirContextOperations ctx) {
+		ldapOperations.modifyAttributes(ctx.getDn(), ctx.getModificationItems());
+	}
+
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.ldap.core.simple.SimpleLdapOperations#bind(java.lang.String,
+	 * java.lang.Object, javax.naming.directory.Attributes)
+	 */
+	public void bind(String dn, Object obj, Attributes attributes) {
+		ldapOperations.bind(dn, obj, attributes);
+	}
+
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.ldap.core.simple.SimpleLdapOperations#unbind(java.lang.String)
+	 */
+	public void unbind(String dn) {
+		ldapOperations.unbind(dn);
+	}
+
 }

spring-ldap-tiger/src/main/java/org/springframework/ldap/core/simple/package.html

@@ -0,0 +1,7 @@
+<html>
+<body>
+
+Simplification layer over LdapTemplate for Java 5 and above.
+
+</body>
+</html>