Dependency injection and early validation is crucial for an enterprise application, and Spring is a boon in this regard. But do not fool yourself, Spring is good, but it is not a universal cure. Especially not in mobile space where startup times, low memory consumption, and avoiding interfaces are virtues.

The bottleneck in an enterprise application is most probably the database, spending a few extra milliseconds here and there seldom matters. On much less performant mobile device those clock cycles are not only time the user has to spend waiting, it will drain the battery. A simple thing as using an interface instead of an abstract superclass will perform at least twice as slow. Even passing an extra argument in the constructors a few nestings deep will have an impact.

Lazy Singeltons by Choice

Class loading in Java is lazy, the Java VM will not load classes until they are referenced. Odds are that the user will not trigger a full coverage of all classes in your app for a short time running mobile app. If the user just checks for incoming messages and quits, then every class involved in composing messages do not need to be loaded. Early dependency injection breaks this, as all classes will be referenced at startup. Most components will be initialized in vain, as they are never actually used.

So what we should do in mobile application is to work more like the Java VM, and less like Spring. If possible do not create a component until it is requested. The best way to do this is using a singleton pattern. Not a normal enforced singleton pattern, but rather a singleton by choice. Let the constructor be public, trust your users, and name the getter getSharedFoo(), not getInstance(). Let me show you using a example of an URL cache component:

public class URLCache {
  private static URLCache sharedCache;

  public static URLCache getSharedURLCache() {
    synchronized (URLCache.class) {
      if (sharedCache == null) {
        sharedCache = new URLCache();
      }
    }
    return sharedCache;
  }

  public URLCache() {
    // More code...
  }
  // Allot more code here...

}

Using this shared URL cache component from our imaginary HTTP provider would then be super easy, but not mandatory:

public class HTTPProvider {

  public InputStream inputStreamForURL(String url) {
    URLCache cache = URLCache.getSharedURLCache();
    // Use the cache...
  }

}

The big win here is that if the code path of this run of the application never tries to open an input stream then the URL cache never has to be created. Saving several hundred milliseconds of reading cache indexes, validation, etc.

But What About Testing?

Are not singletons bad for unit tests and mocking components? They used to be. These days we have PowerMock, you really should use it. Turns out that not even PowerMock is really required, if we just change our singleton pattern very slightly, and allows the outside to set the shared component as well:

public class URLCache {
  private static URLCache sharedCache;

  public static void setSharedURLCache(URLCache cache) {
    synchronized (URLCache.class) {
      sharedCache = cache;
    }
  }

  public static URLCache getSharedURLCache() {
    synchronized (URLCache.class) {
      if (sharedCache == null) {
        sharedCache = new URLCache();
      }
    }
    return sharedCache;
  }

  // Allot more code here...

}

This small addition allows us for setup up our own mock cache in the setup of our unit tests. With something as simple as this:

public class SomeTest extends TestCase {

  public void setUp() {
    URLCache.setSharedURLCache(new NoOpURLCache());
  }

  public void testRemoteResource() {
    assertNotNull(HTTPProvider.getSharedHTTPProvider().inputStreamForURL(TEST_URL));
  }
}

It also allows us for explicitly override a singleton if our application has special needs, perhaps a more aggressive cache on a low bandwidth mobile data connection, or special implementation on a buggy Java ME platform. But most importantly for the normal case it will not waste time creating the component until it is actually needed, vastly improving the user experience for your mobile users.

Take Aways

Do not fear singletons, it is a great way of lazy creations that will greatly improve startup times and memory consumption on mobile applications.

Avoid using interfaces, they are at least twice as slow as classes, and can not have static methods for acquiring the lazy created components.

Do not enforce the singleton pattern, always use singleton by choice. To allow for testing and easy implementation of special cases.

However, there can be cases where your directory server setup might have to avoid using this feature. In our case we had a multi master environment and the plug-in cannot be enabled on both machines as it would create a circular update loop between the master servers. To have one machine in production with the plug-in wasn't a good choice either as we want the master configurations to be same on both machines and if one master goes down then there is a 50-50 chance that the Referential Integrity goes down with it.

Another reason is that you might not store distinguished names on relations attributes, but values like guid or uid, and then the Referential Integrity won't work.

Still this point to an interesting feature which should be pretty easy to implement in Java using Spring LDAP.

Scenario 1

A person who's used as owner in some entries updates his/her uid from old.uid to new.uid, where uid is a part of the distinguished name. For example, Jane Unmarried changes here name to Jane Doe: "uid=jane.unmarried, dc=jayway, dc=com" -> "uid=jane.doe, dc=jayway, dc=com".
Feature: Update all owner references to the new distinguished name.
Prerequisite: Single value attribute. The owner attribute should be indexed for best performance.

The owner attribute might be featured in many different objectclasses, so the tiresome way would be to make searches per objectclass and update them one by one. However, we can make use of a nice feature in LDAP: attributes are global and standardized according to an LDAP schema. The owner attribute is of the same type everywhere, so there is no risk of accidentally changing an owner attribute that is used for something else. Thus, a much better way would be to make a more general search:

EqualsFilter filter = new EqualsFilter("owner", "uid=old.uid, dc=jayway, dc=com");

And what do we want to return? The distinguished name should be sufficient:

protected AbstractContextMapper getAbstractMapper() {
        return new AbstractContextMapper() {

            /* Returns the distinguished name of the object it found. */
            protected Object doMapFromContext(DirContextOperations ctx) {
                return ctx.getNameInNamespace();
            }
        };
    }
}

This is all the information we need; a list of pointers to all entries in the LDAP structure where there is an owner attribute with the value "uid=old.uid, dc=jayway, dc=com". We don't care which type of entries were found, as the only thing we're interested in is updating the value of the owner attribute.

Now do the search:

List hits =  ldapTemplate.search(
                 DistinguishedName.EMPTY_PATH,
                 filter.encode(),
                 getAbstractMapper());

We need to iterate through the search hits and only update the attribute, not the whole object, as we do not know anything about the object type:

for (Name someObjectDn: hits) {
    DirContextOperations context = ldapTemplate.lookupContext(someObjectDn);
    context.setAttributeValue("owner", "uid=new.uid, dc=jayway, dc=com");'

    ldapTemplate.modifyAttributes(context);
}

And we're done, the owner references are updated to uid=new.uid, dc=jayway, dc=com.

What if the owner person gets deleted? Well, then the owner values should be removed and all we need to do is replacing this:

context.setAttributeValue("owner", "uid=new.uid, dc=jayway, dc=com");

with this:

context.setAttributeValue("owner", null);

and the attribute owner will be removed from all the objects.

General

So we see that all we need for these kind of operations are:

1. The attribute name
2. The current value
3. The new value, null if to remove the attribute

Scenario 1 handles a single value attribute but it shouldn't be any harder with a multivalue attribute. The problem is that it's optional to define in an LDAP Schema whether an attribute is singlevalue or multivalue, so we cannot be certain what kind of attribute we're updating. The easiest way to solve this is to let the method have a boolean parameter for this:

4. Is multivalue.

Scenario 2

An person updates his/her uid (from old.uid to new.uid) and uid is a part of the distinguished name.
Feature: Update person references in all object classes she is a member of.
Prerequisite: Multivalue attribute. The uniqueMember attribute should be indexed for best performance.

The filter is almost the same as above:

EqualsFilter filter = new EqualsFilter("uniqueMember", "uid=old.uid, dc=jayway, dc=com");

The context mapper is the same as above, it's still the distinguished names of the objects that carry the attribute uniqueMember we're interested in. The search is also the same as above. But as uniqueMember is a list we need to iterate all the members in the list and replace the old value with the new:

for (Name someObjectDn: hits) {
    DirContextOperations context = ldapTemplate.lookupContext(someObjectDn);
    String[] members = context.getStringAttributes("uniqueMember");

     for (int i = 0; i < members.length; i++) {
            if (members[i].equals("uid=old.uid, dc=jayway, dc=com")) {
                members[i] = "uid=new.uid, dc=jayway, dc=com";

                break;
            }
    }

    context.setAttributeValues("uniqueMember", members);

    ldapTemplate.modifyAttributes(context);
}

Conclusion

It's easy to get the same functionality as the Referential Integrity using only Spring LDAP with very little custom code. You can introduce relationship attributes in new object classes and one method call will handle them all. An upside is that the filters use string values, so your relations attributes are not forced to contain distinguished names, but might be other values like uid or guid. However, using distinguished name is recommended.

As the searches all start from base, the searches might be less efficient as it scans the whole directory structure for the attribute. So this isn't recommended on non-indexed attributes when having large data volumes. The same applies to using the Referential Integrity within the directory server.

Thanks to Ulrik Sandberg and Andreas Andersson for their inputs on this blog.

Simple LDAP Authentication

One of the most requested pieces of functionality in Spring LDAP has been a means to perform simple authentication. We have previously hesitated to include this, not finding any logical place to put it. In this release however we got a couple of suggestions on suitable API additions that enabled us to attack this from a different angle, in the end resulting in explicit methods in LdapTemplate for this purpose.

Background

The problem with authentication in LDAP is that it normally requires two separate steps: First you need to find the principal to authenticate in the LDAP tree, typically performing an LDAP search based on e.g. a user name. A new LDAP connection will then be acquired, authenticating it using the Distinguished Name of the found entry (normally referred to as an 'LDAP Bind').

Example

Consider the LDAP tree below:

Let us say a user identifying himself as 'John Doe' is trying to log into our system. We would execute a search from the top of the LDAP tree using a search filter like (&(objectclass=person)(cn=John Doe)). The search would return one single entry, from which we would extract the absolute DN; cn=John Doe, ou=company1, c=Sweden, dc=jayway, dc=se. This DN would then be used for authenticating a new LDAP connection to the server, thus validating the password supplied by the user.

New Spring LDAP Authentication API

While the above has indeed been possible to do using previous versions of Spring LDAP, it has required quite a lot of work and resulted in rather messy code. Spring LDAP 1.3.0 adds a couple of methods to LdapTemplate, making the authentication procedure very straightforward:

public boolean authenticate(Name base, String filter, String password)
public boolean authenticate(Name base, String filter, String password, AuthenticatedLdapEntryContextCallback callback)

The first method performs exactly the procedure described above, returning true or false depending on the outcome. The second method goes one step further, allowing us to perform any operation on the authenticated LDAP connection. Focusing on the simplest case, a standard authentication method using Spring LDAP would look something like the following:

public boolean login(String username, String password){
  AndFilter filter = new AndFilter();
  filter.and(new EqualsFilter("objectclass", "person")).and(new EqualsFilter("cn", username));
  return ldapTemplate.authenticate(DistinguishedName.EMPTY_PATH, filter.toString(), password);
}

Simple, clean and to the point, especially compared to the mess that used to be required (won't linger on those nasty details here). Obviously however, using a Spring library we will be required to write a few lines of XML as well:

<bean id="contextSource" class="org.springframework.ldap.core.support.LdapContextSource">
<property name="url" value="ldap://url.to.ldap.server:389" />
<property name="userDn" value="uid=admin,ou=system" />
<property name="password" value="adminpassword" />
</bean>
<bean id="ldapTemplate" class="org.springframework.ldap.core.LdapTemplate">
  <constructor-arg ref="contextSource" />
</bean>
<bean id="myAuthenticator" class="com.example.MyAuthenticatingClass">
  <!-- Assuming constructor injection of LdapTemplate instance in your authentication class -->
  <constructor-arg ref="ldapTemplate" />
</bean>
 

A couple of comments on the suggested solution:

• The search needs to return exactly one result entry. In the example above, if there would be more than one person entry in the tree with cn 'John Doe' (which would be perfectly legal according to schema regulations), the call to authenticate would fail.
• In actual implementations the attribute to use for identification will likely be e.g. uid or sAMAccountname (in Active Directory). Both of these attributes have uniqueness enforced throughout the entire tree by the LDAP server.
• The method only returns true or false; thus the actual reason for failing will not be visible to the caller. The reason will however be logged, which might be useful useful when tracking down problems with search filters and such.
• A common reason for confusion in LDAP searches is the base parameter, which is used for pointing out where in the LDAP tree to start searching. Referring again to the potential problem where several users might have the same cn; in that case these entries would have to be located in different subtrees. The search could then be narrowed by specifying a different base DN to the authenticate method, e.g. c=Sweden, dc=jayway, dc=com

Note: While the provided methods will handle the simple task of authentication for you it is likely that your actual security requirements go way past plain authentication (e.g. authorization, web integration, etc.). The realm of security is a very complex one, which is the reason you should carefully consider your actual requirements - if they appear to go beyond simple authentication you should definitely consider using Spring Security instead. (Obviously, under the covers Spring LDAP would be used for the actual authentication anyway).

That said, for many systems the API provided with Spring LDAP will be quite sufficient.

Other improvements in Spring LDAP 1.3.0

As compared to the 1.2.1 version of Spring LDAP, 1.3.0 includes more than 50 fixes, varying from internal modifications and minor improvements to important bug fixes and significant functionality additions. The full list of modifications can be viewed in the the changelog.

About Spring LDAP

Spring LDAP is a Java library for simplifying LDAP operations, based on the pattern of Spring's JdbcTemplate. The framework relieves the user of common chores, such as looking up and closing contexts, looping through results, encoding/decoding values and filters, and more. The library is free, open source, and distributed under the Apache Licence version 2.

For more information on the Spring LDAP project, including downloads, maven usage, as well as project reference and API documentation, refer to its project home page on springsource.org. Support and enhancement requests will be answered in the Spring LDAP Forum at Spring Community Forums.

Simple Authentication Mechanism

By far the most requested feature for inclusion in Spring LDAP has been the ability to easily perform simple authentication using the library. While you would typically like to use Spring Security to implement full-blown application security many of our users have expressed the need to just do the authentication part, not having to worry about the full Spring Security framework. This is now explicitly supported with a new method in the ContextSource interface: getContext(String principal, String password). This means that in order to do simple user authentication you would write something like the following:

 
...
private SimpleLdapTemplate ldapTemplate;
private ContextSource contextSource;
public void setLdapTemplate(SimpleLdapTemplate ldapTemplate) {
	this.ldapTemplate = ldapTemplate;
}
public void setContextSource(ContextSource contextSource) {
	this.contextSource = contextSource;
}
 
public boolean authenticate(String userName, String password) {
	EqualsFilter filter = new EqualsFilter("uid", userName);
	// Actual filter will differ depending on LDAP Server and schema
	List<String> results = ldapTemplate.search("", filter.toString(),
			new DnContextMapper());
	if (results.size() != 1) {
		throw new IncorrectResultSizeDataAccessException(1, results.size());
	}
 
	DirContext ctx = null;
	try {
		ctx = contextSource.getContext(results.get(0), password);
		return true;
	} catch (Exception e) {
		return false;
	} finally {
		LdapUtils.closeContext(ctx);
	}
}
 
private final static class DnContextMapper extends
		AbstractParameterizedContextMapper<String> {
	@Override
	protected String doMapFromContext(DirContextOperations ctx) {
		return ctx.getNameInNamespace();
	}
}
 

The required XML configuration for this:

 
<bean id="ldapTemplate" class="org.springframework.ldap.core.LdapTemplate">
	<constructor-arg ref="contextSource" />
</bean>
<bean id="contextSource" class="org.springframework.ldap.core.support.LdapContextSource">
<property name="url" value="ldap://my.ldap.server" />
<property name="base" value="dc=mycompany, dc=com" />
<property name="userDn" value="cn=Administrator, ou=system" />
<property name="password" value="secret" />
</bean>
<bean id="dummy" class="se.jayway.web.Dummy">
<property name="ldapTemplate" ref="ldapTemplate" />
<property name="contextSource" ref="contextSource" />
</bean>
 

LDAP Data Management

Working with data in LDAP is usually tedious and verbose. Spring LDAP relieves the programmer from explicitly worrying about the details of the underlying Attributes and encapsulates all data regarding an LDAP entry in the DirContextAdapter class. You can get the Attributes of an entry using a DirContextAdapter in a ContextMapper (or ParameterizedContextMapper like above), or you can use the Attribute management capabilities in DirContextAdapter to help you when performing updates or creating entries.

This has been one of the key features from Spring LDAP from the very beginning, and the API has been improved further in this release; particularly a new bind has been added in Spring LDAP, enabling even simpler standard repository code using Spring LDAP:

 
public void create(Person p) {
	p.setDn(buildDn(p));
	DirContextOperations ctx = new DirContextAdapter(p.getDn());
	setAttributeValues(p, ctx);
	ldapTemplate.bind(ctx);
}
 
public void update(Person p) {
	DirContextOperations ctx = ldapTemplate.lookupContext(p.getDn());
	setAttributeValues(p, ctx);
	ldapTemplate.modifyAttributes(ctx);
}
 
private void setAttributeValues(Person p, DirContextOperations ctx) {
	ctx.setAttributeValue("description", p.getDescription());
	ctx.setAttributeValue("telephoneNumber", p.getPhone());
	// Set more attribute values here.
}
 

DirContextAdapter now also supports entries that represent referrals. This means that if you configure your ContextSource to follow referrals (setting the referral property to follow and properly configuring DNS settings so that the server names of the referrals can be resolved) you can get the server URL from any DirContextAdapter resulting from referrals.

TLS Connections

It is a very common setup that the LDAP server is configured only to accept TLS connections. This has previously not been supported by Spring LDAP, but due to some internal rework in AbstractContextSource it is now possible to perform some more elaborate authentication and connection negotiation logic by supplying a DirContextAuthenticationStrategy implementation to the ContextSource. To enable TLS connections you will supply a DefaultTlsDirContextAuthenticationStrategy to your LdapContextSource:

 
<bean id="contextSource" class="org.springframework.ldap.core.support.LdapContextSource">
<property name="url" value="ldap://my.ldap.server" />
<property name="base" value="dc=mycompany, dc=com" />
<property name="userDn" value="cn=Administrator, ou=system" />
<property name="password" value="secret" />
<property name="authenticationStrategy">
		<bean
			class="org.springframework.ldap.core.support.DefaultTlsDirContextAuthenticationStrategy" />
	</property>
</bean>
 

Authentication customization has previously often been done by subclassing LdapContextSource. The recommended approach from Spring LDAP 1.3 is to create a custom DirContextAuthenticationStrategy implementation to suit your need. This would be useful for e.g. LDAP Proxy Authentication or similar functionality.

Major Bug Fixes and Other Changes

Some interesting bug fixes are included in Spring LDAP. Also, some default behavior has been changed; the most important stuff is listed here:

Distinguished Name toString representation

It has long been requested that the Spring LDAP DistinguishedName toString representation should be changed. The toString representation has previously been focused on the readability of the string, adding spaces between the RDNs to make it less compact, e.g.:
cn=John Doe, ou=Some Company, c=Sweden
Several users have been complaining that their DN representations have been compact and that the discrepancy has been causing problems:
cn=John Doe,ou=Some Company,c=Sweden
We have changed the default string representation to the compact one in the 1.3 release. If your system should require the old, 'spaced' format, you can change the default by setting the system property org.springframework.ldap.core.spacedDnFormat to true.

Built-in JNDI Connection Pooling

The pooled property of ContextSource has previously defaulted to true, enabling the built-in Java LDAP connection pooling by default. However the built-in LDAP connection pooling suffers from several deficiencies (most notable there is no way of doing connection validation and configuration is cumbersome), which is why we decided to change the default to false . If you require connection pooling we strongly recommend using the Spring LDAP PoolingContextSource instead.

The Dreaded '\' in Distinguished Names Problem

Java JNDI cannot handle '\' in the Distinguished Names of entries in an LDAP tree. If they do, the DN returned from JNDI will be invalid, which previously caused Spring LDAP to throw an exception. We now work around this bug.

Downloads

We obviously want people to use our stuff. Here are the relevant links:
Binaries(sha)
Binary With Dependencies(sha)
Javadocs
Reference docs

Maven Users

Since this is a release candidate it is not published to the main maven repository. It is however available from the Spring Framework milestone repository:

 
<repositories>
	<repository>
		<id>spring-milestone</id>
		<name>Spring Portfolio Milestone Repository</name>
		<url>http://s3.amazonaws.com/maven.springframework.org/milestone</url>
	</repository>
</repositories>
 

The maven dependencies are as follows:

 
<dependency>
	<groupId>org.springframework.ldap</groupId>
	<artifactId>spring-ldap-core</artifactId>
	<version>1.3.0.RC1</version>
</dependency>
 

 
<dependency>
	<groupId>org.springframework.ldap</groupId>
	<artifactId>spring-ldap-core-tiger</artifactId>
	<version>1.3.0.RC1</version>
</dependency>
 

Summary

In addition to the above there's quite a number of minor feature enhancements and bug fixes. The full change log can be found here. We're obviously very interested in getting your feedback. Please post any comments you might have on the Sping LDAP Support Forum. Bugs should be submitted to the Spring Framework Jira System.

Prerequisites

In order to keep this reasonably brief I'll have to refer to the getting started guide for information on how to get going with Amazon EC2.

A FactoryBean to Launch EC2 Instances

What we want to achieve here is to launch an EC2 instance transparently and independently of the actual test code. Ideally, the test code should be oblivious of the target server and we want to externalize those details to external configuration. We will use Spring's excellent JUnit test support to automatically wire the integration test setup and make sure that the target server is up and running before the actual test code is running.

A powerful way to transparently perform complex initialization logic when using Spring is the FactoryBean concept. We will create a FactoryBean implementation to launch the EC2 image and set up our target resource:

AbstractEc2InstanceLaunchingFactoryBean.java
public abstract class AbstractEc2InstanceLaunchingFactoryBean extends AbstractFactoryBean {
  private static final int INSTANCE_START_SLEEP_TIME = 1000;
  private static final long DEFAULT_PREPARATION_SLEEP_TIME = 30000;
  private static final Log log = LogFactory.getLog(AbstractEc2InstanceLaunchingFactoryBean.class);
  private String imageName;
  private String awsKey;
  private String awsSecretKey;
  private String keypairName;
  private String groupName;
  private Instance instance;
  private long preparationSleepTime = DEFAULT_PREPARATION_SLEEP_TIME;
  public void setImageName(String imageName) {
      this.imageName = imageName;
  }
  public void setAwsKey(String awsKey) {
      this.awsKey = awsKey;
  }
  public void setAwsSecretKey(String awsSecretKey) {
      this.awsSecretKey = awsSecretKey;
  }
  public void setKeypairName(String keypairName) {
      this.keypairName = keypairName;
  }
  public void setGroupName(String groupName) {
      this.groupName = groupName;
  }
  public void setPreparationSleepTime(long preparationSleepTime) {
    this.preparationSleepTime = preparationSleepTime;
  }
  @Override
  protected final Object createInstance() throws Exception {
      Assert.hasLength(imageName, "ImageName must be set");
      Assert.hasLength(awsKey, "AwsKey must be set");
      Assert.hasLength(awsSecretKey, "AwsSecretKey must be set");
      Assert.hasLength(keypairName, "KeyName must be set");
      Assert.hasLength(groupName, "GroupName must be set");
 
      log.info("Launching EC2 instance for image: " + imageName);
 
      Jec2 jec2 = new Jec2(awsKey, awsSecretKey);
      LaunchConfiguration launchConfiguration = new LaunchConfiguration(imageName);
      launchConfiguration.setKeyName(keypairName);
      launchConfiguration.setSecurityGroup(Collections.singletonList(groupName));
 
      ReservationDescription reservationDescription = jec2.runInstances(launchConfiguration);
      instance = reservationDescription.getInstances().get(0);
      while (!instance.isRunning() && !instance.isTerminated()) {
          log.info("Instance still starting up; sleeping " + INSTANCE_START_SLEEP_TIME + "ms");
          Thread.sleep(INSTANCE_START_SLEEP_TIME);
          reservationDescription = jec2.describeInstances(Collections.singletonList(instance.getInstanceId())).get(0);
          instance = reservationDescription.getInstances().get(0);
      }
 
      if (instance.isRunning()) {
          log.info("EC2 instance is now running");
          if (preparationSleepTime > 0) {
              log.info("Sleeping " + preparationSleepTime + "ms allowing instance services to start up properly.");
              Thread.sleep(preparationSleepTime);
              log.info("Instance prepared - proceeding");
          }
          return doCreateInstance(instance.getDnsName());
      } else {
          throw new IllegalStateException("Failed to start a new instance");
      }
   }
 
  protected abstract Object doCreateInstance(String ip) throws Exception;
 
  @Override
  protected void destroyInstance(Object ignored) throws Exception {
    if (this.instance != null) {
      log.info("Shutting down instance");
      Jec2 jec2 = new Jec2(awsKey, awsSecretKey);
      jec2.terminateInstances(Collections.singletonList(this.instance.getInstanceId()));
    }
  }
}
 

This superclass makes use of the typica library (also available in maven) to launch the EC2 instance and delegates to doCreateInstance for creating the target resource that we will use in our test case. In our setup we want to create a ContextSource, which is the Spring LDAP equivalent of a DataSource:

ContextSourceEc2InstanceLaunchingFactoryBean.java
public class ContextSourceEc2InstanceLaunchingFactoryBean extends AbstractEc2InstanceLaunchingFactoryBean {
  private String base;
  private String userDn;
  private String password;
  @Override
  public final Class getObjectType() {
    return ContextSource.class;
  }
  @Override
  protected final Object doCreateInstance(final String dnsName) throws Exception {
    Assert.hasText(userDn);
    LdapContextSource instance = new LdapContextSource();
    instance.setUrl("ldap://" + dnsName);
    instance.setUserDn(userDn);
    instance.setPassword(password);
    instance.setBase(base);
 
    instance.afterPropertiesSet();
    return instance;
  }
  public void setBase(String base) {
    this.base = base;
  }
  public void setUserDn(String userDn) {
    this.userDn = userDn;
  }
  public void setPassword(String password) {
    this.password = password;
  }
}
 

Note that the AbstractEc2InstanceLaunchingFactoryBean will wait for the instance to start up properly. It will also wait an additional period of time once the instance is up and running to allow for all relevant services to start up properly. Finally it will automatically close down the launched instance once it is properly shut down (which it will be when executing using the Spring automated test support).

Test Case Configuration

We now have the infrastructure to have the EC2 instance launched transparently from a Spring Application Context. All we need to do is configure it:

testContext.xml
<bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
<property name="location" value="ldap.properties" />
<property name="systemPropertiesModeName" value="SYSTEM_PROPERTIES_MODE_OVERRIDE" />
</bean>
 
<bean id="contextSource" class="org.springframework.ldap.ContextSourceEc2InstanceLaunchingFactoryBean">
<property name="awsKey" value="${aws.key}" />
<property name="awsSecretKey" value="${aws.secret.key}" />
<property name="imageName" value="${aws.ami}" />
<property name="groupName" value="${aws.security.group}" />
<property name="keypairName" value="${aws.keypair}" />
<property name="base" value="dc=jayway,dc=se" />
<property name="userDn" value="${userDn}" />
<property name="password" value="${password}" />
</bean>
 
<bean id="ldapTemplate"
  class="org.springframework.ldap.core.LdapTemplate">
  <constructor-arg ref="contextSource" />
</bean>
 

We are referring to ldap.properties for the actual settings:

userDn=cn=admin,dc=jayway,dc=se
password=secret
base=dc=jayway,dc=se
aws.ami=ami-56ec083f
aws.keypair=spring-ldap-keypair
aws.security.group=spring-ldap

The referenced AMI is a public image specifically set up for our test cases. It has OpenLDAP installed and has been pre-populated with the test data that our test cases expect.

Note that we are not specifying any property value for aws.key and aws.secret.key, as this is the Amazon account access information. That will be the account settings of the individual developer and should be supplied at runtime using system properties (e.g. mvn -Daws.key=xxxxxxx -Daws.secret.key=xxxxxx test).

Performing the Test

Now all we need to do is use Spring's automated test support to start our test:

SomeLdapITest.java
@ContextConfiguration(locations = { "testContext.xml" })
public class SomeLdapITest extends AbstractJUnit4SpringContextTests {
  @Autowired
  private LdapTemplate tested;
 
  @Test
  public void testSomething() {
    // Use the automatically injected LdapTemplate instance to perform a test.
  }
}
 

Set to Go

With the above you should be all set to go to start using this powerful approach to integration testing. The actual code is available with the 1.3.0.RC1 release of Spring LDAP; links to downloads and documentation available here.

In the perfect world, each developer would at all times have access to a server park with all of these different server versions installed. Reality is however almost always a different question: Being an Open Source project with limited funding and developers located throughout the world this has been impossible for us, up until now. You're probably already guessing: The answer is in the Clouds.

Having used Amazon EC2 in a couple of customer projects, we suddenly realized this is the answer to our problems. For those of you not completely familiar with the concept, the general idea of Amazon EC2 is that you configure one or several machine images, installing whatever software and data you might need on each image. You will then start an instance from one of these pre-configured images, which will in effect start up a virtual computer somewhere in the amazon cloud, a computer that will then be yours to play around with in any way you might like until you're finished with it and just shut the instance down. All of this is available at a very reasonable pricing - you pay only (a very modest amount) for the time that your instances have been running.

The concept suits us perfectly: we want a number of isolated environments, each with a known start state where we can run our test suite against a particular server setup. So that's what we've started to do: we have now created an EC2 image with an Open LDAP installation, pre-loaded with the data that our test cases expect. We then devised support classes to have the JUnit test cases automatically start an appropriate instance (using the excellent typica library), run the tests against the started virtual machines, and shut down the instance after the tests are finished (regardless of the outcome - we don't want any stray instances running around costing us money ). We still have some more work to do with setting up more images for other server setups, but we're hoping to get that work going as we move on...

I'm planning to dig a little bit deeper into the details of the setup and the code involved in a later post. In the meantime: if you're really interested, feel free to check the code out from the svn repo and have a look at what we've done so far. The relevant code for this is in the test/integration-tests-openldap directory.

• They require extensive plumbing code, even to perform the simplest of tasks.
• All resources need to be correctly closed, no matter what happens.
• Exception handling is difficult.

The above points often lead to massive code duplication in common usages of the
APIs. As we all know, code duplication is one of the worst code smells. All in all, it
boils down to this: JDBC and LDAP programming in Java are both incredibly dull
and repetitive.
Spring JDBC, a part of the Spring framework, provides excellent utilities for sim-
plifying SQL programming. We need a similar framework for Java LDAP program-
ming.

The Traditional Way

Consider, for example, a method that should search some storage for all persons and
return their names in a list. Using JDBC, we would create a connection and execute
a query using a statement. We would then loop over the result set and retrieve the
column we want, adding it to a list. By contrast, using Java LDAP, we would create a
context and perform a search using a search filter. We would then loop over the re-
sulting naming enumeration and retrieve the attribute we want, adding it to a list.
The traditional way of implementing this person name search method in Java
LDAP is this:

public class TraditionalPersonDaoImpl implements
         PersonDao {
   public List getAllPersonNames() {
      Hashtable env = new Hashtable();
      env.put(Context.INITIAL_CONTEXT_FACTORY,
         ”com.sun.jndi.ldap.LdapCtxFactory”);
      env.put(Context.PROVIDER_URL,
         ”ldap://localhost:389/dc=jayway,dc=se”);
      DirContext ctx;
      try {
         ctx = new InitialDirContext(env);
      } catch (NamingException e) {
         throw new RuntimeException(e);
      }
      LinkedList list = new LinkedList();
      NamingEnumeration results = null;
      try {
         SearchControls controls =
            new SearchControls();
         controls.setSearchScope(
            SearchControls.SUBTREE_SCOPE);
         results = ctx.search(
            ””, ”(objectclass=person)”, controls);
         while (results.hasMore()) {
            SearchResult searchResult =
               (SearchResult) results.next();
            Attributes attributes =
               searchResult.getAttributes();
            Attribute attr = attributes.get(”cn”);
            String cn = (String) attr.get();
            list.add(cn);
         }
      } catch (NameNotFoundException e) {
         // The base context was not found.
         // Just clean up and exit.
      } catch (NamingException e) {
         throw new RuntimeException(e);
      } finally {
         if (results != null) {
            try {
               results.close();
            } catch (Exception e) {
               // Never mind this.
            }
         }
         if (ctx != null) {
            try {
               ctx.close();
            } catch (Exception e) {
               // Never mind this.
            }
         }
      }
      return list;
   }
} 

The method above produces a list containing the cn (common name) attribute of
the person objects found in the database. It is important to always close the naming
enumeration and the context. The same procedural manner of programming needs
to be used whether you want to search, create, update or delete data. It’s easy to see
how this leads to massive code duplication.

Introducing Spring LDAP

The above made us realize the need for help, which is why we created the Spring
LDAP project. It’s a library for simpler LDAP programming in Java, built on the
same principles as Spring JDBC. It was recently included as a Spring Framework
sub project.
Spring LDAP completely eliminates the need to worry about creating and closing
DirContext and looping through NamingEnumeration. It also provides a more
comprehensive unchecked exception hierarchy, built on Spring’s DataAccessEx-
ception. As a bonus, it also contains classes for dynamically building LDAP filters
and distinguished names. An LDAP filter corresponds somewhat to the WHERE
clause in a SQL SELECT statement. A distinguished name (dn) can be seen as a
handle or the path to a specific object in the LDAP database. If the dn is available,
an object can be looked up directly, rather than having to be searched for.
This article will present the core features of Spring LDAP and demonstrate how
LDAP programming really can be made simple.

Searches using AttributesMapper

In this example, we will use an AttributesMapper to easily build a list of all common
names of all person objects. This is exactly what we did in the earlier example using
the traditional way.

public class PersonDaoImpl implements PersonDao {
   private LdapTemplate ldapTemplate;
   public void setLdapTemplate(LdapTemplate ldapTemplate) {
      this.ldapTemplate = ldapTemplate;
   }
   public List getAllPersonNames() {
      return ldapTemplate.search(
         ””, ”(objectclass=person)”,
         new AttributesMapper() {
            public Object mapFromAttributes(Attributes attrs)
               throws NamingException {
               return attrs.get(”cn”).get();
            }
         });
   }
}

The inline implementation of AttributesMapper just gets the desired attribute
value from the Attributes and returns it. Internally, Spring LDAP iterates over
all entries found, calling the given AttributesMapper for each entry, and collects
the results in a list. The list is then returned by the search method.
Note that the AttributesMapper implementation could easily be modified to
return a full Person object:

public class PersonDaoImpl implements PersonDao {
   private LdapTemplate ldapTemplate;
   ...
   private static class PersonAttributesMapper
      implements AttributesMapper {
      public Object mapFromAttributes(Attributes attrs)
         throws NamingException {
         Person person = new Person();
         person.setFullName((String)attrs.get(”cn”).get());
         person.setLastName((String)attrs.get(”sn”).get());
         person.setDescription((String)attrs.get(”description”).get());
         return person;
      }
   }
   public List getAllPersons() {
      return ldapTemplate.search(
         ””, ”(objectclass=person)”,
         new PersonAttributesMapper();
   }
}

Dynamically Building Distinguished Names

The standard Name interface represents a generic name, which is basically an or-
dered sequence of components. The Name interface also provides operations on that
sequence; e.g., add or remove. Spring LDAP provides an implementation of the
Name interface: DistinguishedName. Using this class greatly simplifies building
distinguished names, especially considering the sometimes complex rules regarding
escapings and encodings. The following example illustrates how Distinguished-
Name can be used to dynamically construct a distinguished name:
public static final String BASE_DN = ”dc=jayway, dc=se”;

...
protected Name buildDn(Person p) {
   DistinguishedName dn = new DistinguishedName(BASE_DN);
   dn.add(”c”, p.getCountry());
   dn.add(”ou”, p.getCompany());
   dn.add(”cn”, p.getFullname());
   return dn;
}

Assuming that a Person has the following attributes:

• country: Sweden
• company: Some Company
• fullname: Some Person
  then the result of the code above would be the following dn: cn=Some
  Person, ou=Some Company, c=Sweden, dc=jayway, dc=se

Managing Attributes Using the DirContextAdapter

As demonstrated above, values in LDAP are managed using Attributes. Working
with Attributes is as dull and verbose as the rest of the standard LDAP API. This
is why the Spring LDAP library provides the DirContextAdapter.
Whenever a context is found in the LDAP tree, Spring LDAP will use its At-
tributes to construct a DirContextAdapter. This enables us to use a Con-
textMapper instead of an AttributesMapper to transform found values:

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 List getAllPersons() {
      return ldapTemplate.search(
         ””, ”(objectclass=person)”,
         new PersonContextMapper();
   }
}

While useful in searches and lookups, the DirContextAdapter is especially use-
ful when creating and updating data, which will be described below.

Binding Data

Inserting data in Java LDAP is called binding. In order to do that, a distinguished
name that uniquely identifies the new entry is required. The following example
shows how data is bound using Spring LDAP:

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(dn, context, null);
}

Unbinding Data

Removing data in Java LDAP is called unbinding. A distinguished name (dn) is re-
quired to identify the entry, just as in the binding operation. The following example
shows how data is unbound using Spring LDAP:
public class PersonDaoImpl implements PersonDao {

   ...
   public void delete(Person p) {
      Name dn = buildDn(p);
      ldapTemplate.unbind(dn);
   }
}
Modifying Data
In Java LDAP, data is usually modified using modifyAttributes. Using the mo-
difyAttributes method you need to keep track of the changes and construct a
ModificationItem array with the updated data - once again very tedious work.
Luckily, DirContextAdapter does this for us:
public void update(Person p) {
   Name dn = buildDn(p);
   DirContextAdapter context =
      (DirContextAdapter)ldapTemplate.lookup(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(dn,
      context.getModificationItems());
}

Conclusion

We have seen how Spring LDAP can provide substantial improvements compared
to code using JNDI directly. There is no longer any need for creating contexts manu-
ally or looping through naming enumerations. Nor is there any risk of forgetting to
close any of those.
By now it should be clear that the Spring LDAP library will be of great help for
any Java project that communicates with LDAP. Further information is available on
the Spring LDAP home page, including a full reference manual, API documenta-
tion, and links for downloading the library.

Mattias Arthursson and Ulrik Sandberg

Resources

Spring LDAP home page
http://www.springframework.org/ldap
Sun's JNDI pages:
http://java.sun.com/products/jndi/

Originally published in JayView.