3. Simpler Attribute Access and Manipulation with DirContextAdapter

3. Simpler Attribute Access and Manipulation with DirContextAdapter
Prev		Next

3.1. Introduction

A little-known--and probably underestimated--feature of the Java LDAP API is the ability to register a DirObjectFactory to automatically create objects from found contexts. One of the reasons why it is seldom used is that you will need an implementation of DirObjectFactory that creates instances of a meaningful implementation of DirContext. The Spring LDAP library provides the missing pieces: a default implementation of DirContext called DirContextAdapter, and a corresponding implementation of DirObjectFactory called DefaultDirObjectFactory. Used together with DefaultDirObjectFactory, the DirContextAdapter can be a very powerful tool.

3.2. Search and Lookup Using ContextMapper

The DefaultDirObjectFactory is registered with the ContextSource by default, which means that whenever a context is found in the LDAP tree, its Attributes and Distinguished Name (DN) will be used to construct a DirContextAdapter. This enables us to use a ContextMapper instead of an AttributesMapper to transform found values:

Example 3.1. Searching using a ContextMapper

package com.example.dao;

public class PersonDaoImpl implements PersonDao {
   ...
   private static class PersonContextMapper implements ContextMapper {
      public Object mapFromContext(Object ctx) {
         DirContextAdapter context = (DirContextAdapter)ctx;
         Person p = new Person();
         p.setFullName(context.getStringAttribute("cn"));
         p.setLastName(context.getStringAttribute("sn"));
         p.setDescription(context.getStringAttribute("description"));
         return p;
      }
   }

   public Person findByPrimaryKey(
      String name, String company, String country) {
      Name dn = buildDn(name, company, country);
      return ldapTemplate.lookup(dn, new PersonContextMapper());
   }
}

The above code shows that it is possible to retrieve the attributes directly by name, without having to go through the Attributes and BasicAttribute classes. This is particularly useful when working with multi-value attributes. Extracting values from multi-value attributes normally requires looping through a NamingEnumeration of attribute values returned from the Attributes implementation. The DirContextAdapter can do this for you, using the getStringAttributes() or getObjectAttributes() methods:

Example 3.2. Getting multi-value attribute values using getStringAttributes()

private static class PersonContextMapper implements ContextMapper {
   public Object mapFromContext(Object ctx) {
      DirContextAdapter context = (DirContextAdapter)ctx;
      Person p = new Person();
      p.setFullName(context.getStringAttribute("cn"));
      p.setLastName(context.getStringAttribute("sn"));
      p.setDescription(context.getStringAttribute("description"));
      // The roleNames property of Person is an String array
      p.setRoleNames(context.getStringAttributes("roleNames"));
      return p;
   }
}

3.2.1. The AbstractContextMapper

Spring LDAP provides an abstract base implementation of ContextMapper, AbstractContextMapper. This automatically takes care of the casting of the supplied Object parameter to DirContexOperations. The PersonContextMapper above can thus be re-written as follows:

Example 3.3. Using an AbstractContextMapper

  private static class PersonContextMapper extends AbstractContextMapper {
      public Object doMapFromContext(DirContextOperations ctx) {
         Person p = new Person();
         p.setFullName(context.getStringAttribute("cn"));
         p.setLastName(context.getStringAttribute("sn"));
         p.setDescription(context.getStringAttribute("description"));
         return p;
      }
  }

3.3. Binding and Modifying Using DirContextAdapter

While very useful when extracting attribute values, DirContextAdapter is even more powerful for hiding attribute details when binding and modifying data.

3.3.1. Binding

This is an example of an improved implementation of the create DAO method. Compare it with the previous implementation in Section 2.4.1, “Binding Data”.

Example 3.4. Binding using DirContextAdapter

package com.example.dao;

public class PersonDaoImpl implements PersonDao {
   ...
   public void create(Person p) {
      Name dn = buildDn(p);
      DirContextAdapter context = new DirContextAdapter(dn);

      context.setAttributeValues("objectclass", new String[] {"top", "person"});
      context.setAttributeValue("cn", p.getFullname());
      context.setAttributeValue("sn", p.getLastname());
      context.setAttributeValue("description", p.getDescription());

      ldapTemplate.bind(context);
   }
}

Note that we use the DirContextAdapter instance as the second parameter to bind, which should be a Context. The third parameter is null, since we're not using any Attributes.

Also note the use of the setAttributeValues() method when setting the objectclass attribute values. The objectclass attribute is multi-value, and similar to the troubles of extracting muti-value attribute data, building multi-value attributes is tedious and verbose work. Using the setAttributeValues() mehtod you can have DirContextAdapter handle that work for you.

3.3.2. Modifying

The code for a rebind would be pretty much identical to Example 3.4, “Binding using DirContextAdapter”, except that the method called would be rebind. As we saw in Section 2.5.2, “Modifying using modifyAttributes” a more correct approach would be to build a ModificationItem array containing the actual modifications you want to do. This would require you to determine the actual modifications compared to the data present in the LDAP tree. Again, this is something that DirContextAdapter can help you with; the DirContextAdapter has the ability to keep track of its modified attributes. The following example takes advantage of this feature:

Example 3.5. Modifying using DirContextAdapter

package com.example.dao;

public class PersonDaoImpl implements PersonDao {
   ...
   public void update(Person p) {
      Name dn = buildDn(p);
      DirContextOperations context = ldapTemplate.lookupContext(dn);

      context.setAttributeValues("objectclass", new String[] {"top", "person"});
      context.setAttributeValue("cn", p.getFullname());
      context.setAttributeValue("sn", p.getLastname());
      context.setAttributeValue("description", p.getDescription());

      ldapTemplate.modifyAttributes(context);
   }
}

When no mapper is passed to a ldapTemplate.lookup() operation, the result will be a DirContextAdapter instance. While the lookup method returns an Object, the convenience method lookupContext method automatically casts the return value to a DirContextOperations (the interface that DirContextAdapter implements.

The observant reader will see that we have duplicated code in the create and update methods. This code maps from a domain object to a context. It can be extracted to a separate method:

Example 3.6. Binding and modifying using DirContextAdapter

package com.example.dao;

public class PersonDaoImpl implements PersonDao {
   private LdapTemplate ldapTemplate;

   ...
   public void create(Person p) {
      Name dn = buildDn(p);
      DirContextAdapter context = new DirContextAdapter(dn);
      mapToContext(p, context);
      ldapTemplate.bind(context);
   }

   public void update(Person p) {
      Name dn = buildDn(p);
      DirContextOperations context = ldapTemplate.lookupContext(dn);
      mapToContext(person, context);
      ldapTemplate.modifyAttributes(context);
   }

   protected void mapToContext (Person p, DirContextOperations context) {
      context.setAttributeValues("objectclass", new String[] {"top", "person"});
      context.setAttributeValue("cn", p.getFullName());
      context.setAttributeValue("sn", p.getLastName());
      context.setAttributeValue("description", p.getDescription());
   }
}

3.4. A Complete PersonDao Class

To illustrate the power of Spring LDAP, here is a complete Person DAO implementation for LDAP in just 68 lines:

Example 3.7. A complete PersonDao class

package com.example.dao;

import java.util.List;

import javax.naming.Name;
import javax.naming.NamingException;
import javax.naming.directory.Attributes;

import org.springframework.ldap.core.AttributesMapper;
import org.springframework.ldap.core.ContextMapper;
import org.springframework.ldap.core.LdapTemplate;
import org.springframework.ldap.core.DirContextAdapter;
import org.springframework.ldap.core.support.DistinguishedName;
import org.springframework.ldap.filter.AndFilter;
import org.springframework.ldap.filter.EqualsFilter;
import org.springframework.ldap.filter.WhitespaceWildcardsFilter;

public class PersonDaoImpl implements PersonDao {
   private LdapTemplate ldapTemplate;

   public void setLdapTemplate(LdapTemplate ldapTemplate) {
      this.ldapTemplate = ldapTemplate;
   }

   public void create(Person person) {
      DirContextAdapter context = new DirContextAdapter(buildDn(person));
      mapToContext(person, context);
      ldapTemplate.bind(context);
   }

   public void update(Person person) {
      Name dn = buildDn(person);
      DirContextOperations context = ldapTemplate.lookupContext(dn);
      mapToContext(person, context);
      ldapTemplate.modifyAttributes(context);
   }

   public void delete(Person person) {
      ldapTemplate.unbind(buildDn(person));
   }

   public Person findByPrimaryKey(String name, String company, String country) {
      Name dn = buildDn(name, company, country);
      return (Person) ldapTemplate.lookup(dn, getContextMapper());
   }

   public List findByName(String name) {
      AndFilter filter = new AndFilter();
      filter.and(new EqualsFilter("objectclass", "person")).and(new WhitespaceWildcardsFilter("cn",name));
      return ldapTemplate.search(DistinguishedName.EMPTY_PATH, filter.encode(), getContextMapper());
   }

   public List findAll() {
      EqualsFilter filter = new EqualsFilter("objectclass", "person");
      return ldapTemplate.search(DistinguishedName.EMPTY_PATH, filter.encode(), getContextMapper());
   }

   protected ContextMapper getContextMapper() {
      return new PersonContextMapper();
   }

   protected Name buildDn(Person person) {
      return buildDn(person.getFullname(), person.getCompany(), person.getCountry());
   }

   protected Name buildDn(String fullname, String company, String country) {
      DistinguishedName dn = new DistinguishedName();
      dn.add("c", country);
      dn.add("ou", company);
      dn.add("cn", fullname);
      return dn;
   }

   protected void mapToContext(Person person, DirContextOperations context) {
      context.setAttributeValues("objectclass", new String[] {"top", "person"});
      context.setAttributeValue("cn", person.getFullName());
      context.setAttributeValue("sn", person.getLastName());
      context.setAttributeValue("description", person.getDescription());
   }

   private static class PersonContextMapper extends AbstractContextMapper {
      public Object doMapFromContext(DirContextOperations context) {
         Person person = new Person();
         person.setFullName(context.getStringAttribute("cn"));
         person.setLastName(context.getStringAttribute("sn"));
         person.setDescription(context.getStringAttribute("description"));
         return person;
      }
   }
}

Note

	Note
In several cases the Distinguished Name (DN) of an object is constructed using properties of the object. E.g. in the above example, the country, company and full name of the `Person` are used in the DN, which means that updating any of these properties will actually require moving the entry in the LDAP tree using the `rename()` operation in addition to updating the `Attribute` values. Since this is highly implementation specific this is something you'll need to keep track of yourself - either by disallowing the user to change these properties or performing the `rename()` operation in your `update()` method if needed.

In several cases the Distinguished Name (DN) of an object is constructed using properties of the object. E.g. in the above example, the country, company and full name of the Person are used in the DN, which means that updating any of these properties will actually require moving the entry in the LDAP tree using the rename() operation in addition to updating the Attribute values. Since this is highly implementation specific this is something you'll need to keep track of yourself - either by disallowing the user to change these properties or performing the rename() operation in your update() method if needed.

Prev		Next
2. Basic Operations	Home	4. Adding Missing Overloaded API Methods