The PropertyPlaceholderConfigurer lets us externalize configuration parameters from the XML configuration to property files, and that's excellent, but I've seen (and implemented myself) so many different cumbersome attempts on environment configuration it's not even funny.

The problem is this: We'll want to have one test-environment version of the property file bundled with the application source code to simplify starting the app in test mode from inside the IDE. So how do we reconfigure the application for production? Extract the war file, replace the property file with the production version, and re-pack the war? No, we really want to avoid this. Another, even worse solution is to have a number of different versions of the property files and then using different build profiles including the "correct" versions.

As it turns out there's a perfectly simple, obvious, but surprisingly hard-to-google solution to this problem: You probably know that it's possible to specify several property files when configuring the PropertyPlaceholderConfigurer; well it turns out that a property redefined in a later file will override a setting from a previous file. This allows us to do the following:

 
  <context:property-placeholder
    ignore-resource-not-found="true"
    location="WEB-INF/myApp.properties,file:///etc/myApp/myApp.properties" />
 

Note the ignore-resource-not-found attribute, which is needed to so that not all files need to be in place. Now consider that the bundled property file, WEB-INF/myApp.properties has the following contents:

 
db.url=dbc:jtds:sqlserver://testdb.example.com/mydb
db.user=testuser
db.password=testpass
 

and that there is no file at /etc/myApp/myApp.properties on your development machine. When we start the application in the IDE, it will load and run with the test settings.

If we now place an environment-specific property file at /etc/myApp/myApp.properties with the following contents:

 
db.url=dbc:jtds:sqlserver://proddb.example.com/mydb
db.user=produser
db.password=somethingreallysecret
 

these are the settings that will be used when the application is started on that machine. This is what we'll do on the production machine. And what's even better: it won't even be your responsibility - you just need to document where the property file should be placed and which properties that can be specified and then leave it for operations to actually make it so.

Simple as that.

The built-in support for rendering XML from RESTful web services in Spring is built on top of the Marshaller abstraction originally from Spring Web Services (now moved to Spring core). This is a pretty nice abstraction if you want to use one of the existing Object-XML marshalling frameworks (JAXB, Castor, XMLBeans, etc.), but if you want to move out of that box you're pretty much stranded.

I really do want to move out of the box because I think the control and readability greatly improves if you do your XML marshalling in Groovy. It's quite common that the same domain object will need to be marshalled differently depending on the scenario (an object will e.g. quite probably need to be marshalled differently in a detail view than in a list). Also, it is not uncommon that more complicated application logic will be required when rendering the XML; a common example of this is URI generation in 'linked' REST applications (HATEOAS). Hence, Groovy is the perfect choice: Very little code is needed, you are able to include some logic if necessary, and the code written exactly reflects the XML that will be produced.

The Building Blocks

I started out by defining a simple interface for a completely generic Marshaller:

 
public interface SimpleMarshaller {
  public void marshal(Writer writer, Object o);
}
 

I now needed a View implementation to render Model objects using the SimpleMarshaller interface (much of this code is actually borrowed from the Spring MarshallingView - Apache license rocks!):

 
public class SimpleMarshallingView extends AbstractView {
  public final static String DEFAULT_MODEL_KEY = "objectToMarshal";
  private static final boolean AUTOMATIC_FLUSH = true;
  private static final String DEFAULT_CHARSET = "utf8";
  private final SimpleMarshaller marshaller;
 
  public SimpleMarshallingView(SimpleMarshaller marshaller) {
    this.marshaller = marshaller;
  }
 
  @Override
  protected final void renderMergedOutputModel(Map<String, Object> model, HttpServletRequest request,
      HttpServletResponse response) throws Exception {
    ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
    PrintWriter writer = new PrintWriter(new OutputStreamWriter(outputStream, DEFAULT_CHARSET), AUTOMATIC_FLUSH);
    marshaller.marshal(writer, objectToRender(model));
    response.setContentType(getContentType());
    response.setContentLength(outputStream.size());
    FileCopyUtils.copy(outputStream.toByteArray(), response.getOutputStream());
  }
 
  private Object objectToRender(Map<String, Object> model) {
    Object o = model.get(DEFAULT_MODEL_KEY);
    if (o == null) {
      throw new IllegalArgumentException("Model does not contain the expected key '" + DEFAULT_MODEL_KEY + "'");
    }
    return o;
  }
}
 

Next I created an abstract SimpleMarshaller implementation for marshalling using a Groovy MarkupBuilder:

 
public abstract class AbstractMarkupBuilderSimpleMarshaller implements SimpleMarshaller {
  public final void marshal(Writer writer, Object o) {
    MarkupBuilder builder = new MarkupBuilder(writer);
    marshalToBuilder(builder, o);
  }
  protected abstract void marshalToBuilder(MarkupBuilder builder, Object o);
}
 

Now all that is left is to create a new Groovy View implementation for specific XML response you want, e.g.:

 
class UserXmlMarshallingView extends SimpleMarshallingView {
  @Autowired
  public UserXmlMarshallingView(UriConstructionService uriConstructionService){
    super(new UserXmlMarshaller(uriConstructionService))
    setContentType("application/xml")
  }
 
  static class UserXmlMarshaller extends AbstractMarkupBuilderSimpleMarshaller {
    private UriConstructionService uriConstructionService;
 
    public UserXmlMarshaller(UriConstructionService uriConstructionService) {
      this.uriConstructionService = uriConstructionService;
    }
 
    @Override
    protected void marshalToBuilder(MarkupBuilder builder, Object user) {
      builder.'user'('name': user.name, 'email': user.email) {
        user.orders.each {
          'order-ref'('dateCreated': it.dateCreated.format('yyyy-MM-dd hh:mm:ss'), 'uri': uriConstructionService.orderUri(it))
        }
      }
    }
  }
}
 

Note above that we included some processing logic as well - we get a formatted date and we also make use of a service for producing URIs for referencing sub-entities.

Each individual View implementations now needs to be registered in the DispatcherServlet's ApplicationContext:

 
<bean id="user" class="com.jayway.demo.xml.UserXmlMarshallingView"/>
...
<bean class="org.springframework.web.servlet.view.BeanNameViewResolver"/>
 

Since we have defined a BeanNameViewResolver we can now refer to these Views using their bean names when pointing them out from a Controller:

 
@Controller
public class UserController {
  @Autowired
  private Repo repo;
 
  @RequestMapping(value = "/users/{id}")
  public ModelAndView user(@PathVariable int id) {
    User user = repo.userById(id);
    return new ModelAndView("user", SimpleMarshallingView.DEFAULT_MODEL_KEY, user);
  }
}
 

Infrastructure

Obviously, for the above to work we need organize our code appropriately and make sure that our build system properly builds the groovy files. This turned out to be surprisingly easy (using maven). All groovy code should be placed under src/main/groovy. Then maven needs to be configured to build the groovy files using the gmaven plugin. Also, make sure you include the groovy libs in your dependency list:

 
<dependency>
  <groupId>org.codehaus.groovy</groupId>
  <artifactId>groovy-all</artifactId>
  <version>1.7.1</version>
</dependency>
 

Conclusion

With the above setup it's easy to quickly implement (and test) new marshalling views for the different resources in a REST application. Even though this was used in a rather small proof-of-concept project my general feeling is that the approach will work pretty well. My next step with this will be to add some simplifications for working with HTTP status codes (the approach to HTTP response codes with the @ResponseCode annotation in Spring MVC feels insufficient for many cases).

Finally it should be noted that the approach with a completely generic marshaller makes it easy to expand this to working with other representations as well, e.g. JSON (although the JSON support in Groovy is still a little bit shaky).

Now, if you want to apply security in a Grails application you are typically pointed in the direction of the Grails Acegi Plugin, which does a rather decent job at applying basic security to your Grails application. It quickly falls short however when you need to start doing something more than the bare basics (which you pretty much always need to do); even though the plugin is based on Spring Security, far from everything in the original framework is supported in the plugin, and hooking in custom components is pretty much out of the question. In addition to this, the Acegi Plugin is haunted by a couple of pretty annoying bugs.

Bottom line: for any real-world scenario you will most likely want to fall back to the original, i.e. use the original Spring Security framework in your Grails application. Since Grails is Spring-based it shouldn't be all that much work to set that up, right? Well basically yes, but as I set out do to it I ran into a number of problems before I got it right, so I thought I might as well line out the steps and pitfalls.

1. Download and Install the Spring Security jars

Typically, for the basic setup you should need only the spring-security-core.jar and spring-security-core-tiger.jar, but depending on your requirements you might need to include more of the Spring Security binaries. Place the jars in your lib directory of your Grails application.

2. Install Templates

Spring Security is based on an HTTP filter chain, which needs to be declared in the WEB-INF/web.xml file of the web application. This file is normally automatically generated for you by Grails, but for the event that you need more control (such as this occasion) you can have the default file generated for you to edit. The command for this is grails install-templates. This will generate a number of files, and the web.xml will be ready for editing under src/templates/war.

3. Add the Spring Security Filter Chain

There will be a number of filters defined in the web.xml file already. Add the Spring Security filter after the other filter definitions, but before the filter-mapping entries (all the filter definitions need to be placed before the filter-mapping ones, or else evil things will happen with any additional filters generated by Grails and we'll get in trouble when we deploy in tomcat).

<filter>
	<filter-name>springSecurityFilterChain</filter-name>
	<filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
</filter>

Now, after the other filter-mapping entries, add the filter-mapping for the Spring Security filter:

<filter-mapping>
	<filter-name>springSecurityFilterChain</filter-name>
	<url-pattern>/*</url-pattern>
</filter-mapping>

4. Spring Security Configuration

Now we're ready to add the Spring Security configuration XML. Note that this configuration needs to be placed in grails-app/conf/spring/resources.xml. I initially tried to put it in WEB-APP/WEB-INF/applicationContext.xml but due to the Grails ApplicationContext loading magic that attempt failed spectacularly. We'll start out with a minimal Spring Security configuration just to get things going; for more information the configuration topic I'll refer to the reference documentation.

<beans xmlns="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
                http://www.springframework.org/schema/security http://www.springframework.org/schema/security/spring-security-2.0.4.xsd"
        xmlns:sec="http://www.springframework.org/schema/security">
        <sec:http>
                <sec:intercept-url pattern="/**" access="ROLE_USER"/>
                <sec:http-basic />
        </sec:http>
        <sec:authentication-provider>
                <sec:user-service>
                        <sec:user name="mattias" password="12345" authorities="ROLE_USER"/>
                </sec:user-service>
        </sec:authentication-provider>
</beans>

Another note of caution here: If there is anything incorrect in your resources.xml Grails will happily and silently ignore this and go ahead and start anyway. Therefore, whenever you start doing stuff with your own custom Spring configuration in a Grails app it is imperative to make sure to configure your logging so that Spring warning and error messages are logged properly or you'll be completely in the dark trying to figure out what went wrong.

All done

As it turns out this wasn't as bad as expected. You're now all set to unleash the full power of Spring Security on your Grails application.

Part of the problem was (I guess) that the projects were created outside of Idea, so they had to be imported. Another thing that turned out to be a big problem was that there are a number of inter-dependencies between the projects (set up as plugin dependencies in BuildConfig.groovy). Now, here are the steps I had to go through to make a multi-sub-project Grails project working in IntelliJ Idea:

• First of all, create an empty top-level project (actively uncheck the 'Create Module' checkbox).
• Then, for each of the sub projects, create a new module. The tricky part here is that it turned out that you need to select 'Create from scratch..' option and select the root directory of each Grails app as module directory (and name). Then, just select 'Grails module', and you're done (for now)
• Now we need to set up the build paths manually. For each of the modules that have local libraries included in the lib directory, that directory needs to be added manually as a jar directory dependency of that module. Make sure you check the 'export' checkbox as well, so that the binaries are included when you build and when if this module is referenced from another module (see below).
• Next step is to manually remove and re-add each of the required plugins in each module. Be sure to re-add them one at a time; it didn't work to add multiple plugins at once
• Now if you have inter-dependencies between your modules (e.g. one app uses a plugin you made yourself, set up in BuildConfig.groovy), these need to be set up as module dependencies.
• Finally we're done. Now, double check the build path in the module settings window and make sure nothing is marked red. Try to build the project and you should be all set.

Obviously, the bad thing here is that it's an incredible amount of work involved in getting everything up and working. The good thing however is that once you have it all set up it works really well. Code navigation and even debugging a remote Grails application works as a charm. That said, I'm still not comfortable with how Idea works. It just feels awkward somehow. I can't wait for when the SpringSource guys get this working in Spring IDE so that I can get back to my IDE of choice.

I've used Commons HttpClient in older versions on several occasions in the past and have found it to be extremely useful. I've only just started working with the new version, but there seems to quite a lot of good stuff in there. For example I'm thrilled to see that the Template pattern, heavily used in Spring, has now made its way to the Apache world (e.g. ResponseHandler, a callback interface to be used with HttpClient for handling results).

Now, configuration of HttpClient has always been a little bit tricky. There are so many features in there, and most of these are configured using generic parameters (HttpParams), basically name-value pairs of a setting identifier and its value. This has not been made that much easier in the new version.

In my current project I was struggling to find the appropriate parameters for configuring timeouts with the new version of the framework. It turned out to be quite difficult to find clear information on this - the documentation on the 4.0 version of HttpClient is still quite sparse. Since it took me a while to find out how to do this I figured I wasn't alone, so here goes:

My original solution for this problem - being completely unable to find the proper way to do it - was to use the hard-coded property values and set them as parameters in HttpParams. Fortunately, a reader with signature 'BoD' (see below) knew the right way to do this and was kind enough to share.

Right, the code looks as follows:

 
DefaultHttpClient httpClient = new DefaultHttpClient();
HttpParams params = httpClient.getParams();
HttpConnectionParams.setConnectionTimeout(httpParams, connectionTimeoutMillis);
HttpConnectionParams.setSoTimeout(httpParams, socketTimeoutMillis);
 

Simple as that - hard to understand why that should take me so long to figure out . Thanks again to 'BoD' for setting me straight on this.

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.

Seems this is not an uncommon problem, but the solution was not easy to find - there are lots of proposed solutions on different forums and I've tried several until I finally found the one that worked. It turned out that the culprit in my setup was pulse audio. The solution that worked for me was simply to remove that:

killall pulseaudio
sudo apt-get remove pulseaudio
sudo apt-get install esound esound-clients libao2
sudo rm /etc/X11/Xsession.d/70pulseaudio

After the above I just changed back to ALSA in sound settings, restarted Firefox and everything worked like a charm. Note that executing the apt-get remove statement above will display a prompt to stating that it will remove Ubuntu desktop. This is just a meta-package so it will NOT remove the ubuntu desktop for real.

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.

Basic Spring Remoting Configuration

In the general situation all you need to do is create a DispatcherServlet (just as you would with any Spring MVC application), add an Exporter on the server side and reference a ProxyFactoryBean on the client.
On the server side:

web.xml
<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>/WEB-INF/applicationContext.xml</param-value>
</context-param>
<listener>
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>
<servlet>
  <servlet-name>demo</servlet-name>
  <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
<param-name>contextConfigLocation</param-name>
<param-value>/WEB-INF/demo-servlet.xml</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>
 
<servlet-mapping>
  <servlet-name>demo</servlet-name>
  <url-pattern>/*</url-pattern>
</servlet-mapping>
 

demo-servlet.xml - exposes bean 'helloService' as remote service
<bean name="/hello"
    class="org.springframework.remoting.httpinvoker.HttpInvokerServiceExporter">
<property name="service" ref="helloService" />
<property name="serviceInterface"
      value="se.jayway.demo.server.HelloService" />
</bean>
 

On the client side:

clientContext.xml
<bean id="helloService"
  class="org.springframework.remoting.httpinvoker.HttpInvokerProxyFactoryBean">
<property name="serviceUrl"
      value="https://remote-host:8080/security-remoting/hello" />
<property name="serviceInterface"
      value="se.jayway.demo.server.HelloService" />
</bean>
 

Now, in the client application all you need to do is ask for the 'helloService' bean and you will be handed a proxy that talks to the target service on the server without the server or the client knowing anything about it.

Securing the Remote Service

Now, in many cases you'll want to apply some security restrictions on the exposed HTTP service. Being in the Spring world the natural choice for this purpose will be Spring Security. Far from the complications of its predecessor Acegi, Spring Security configuration is now a matter of very few lines of XML code:

web.xml
...
<filter>
  <filter-name>springSecurityFilterChain</filter-name>
  <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
</filter>
 
<filter-mapping>
  <filter-name>springSecurityFilterChain</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>
...
 

demo-servlet.xml - additions to the original file above; default with one hard coded user
<beans
  xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:sec="http://www.springframework.org/schema/security"
  xsi:schemaLocation=
        "http://www.springframework.org/schema/beans 
 
http://www.springframework.org/schema/beans/spring-beans.xsd
 
http://www.springframework.org/schema/security
 
         http://www.springframework.org/schema/security/spring-security-2.0.xsd">
...
<sec:http realm="Hello App">
  <sec:http-basic/>
  <sec:intercept-url pattern="/**" access="ROLE_USER" />
</sec:http>
<sec:authentication-provider>
  <sec:user-service>
    <sec:user name="someuser" password="somepassword" authorities="ROLE_USER" />
  </sec:user-service>
</sec:authentication-provider>
 

Note that we're defining the Spring Security XML schema in the schema definition.

clientContext.xml
<bean id="helloService"
  class="org.springframework.remoting.httpinvoker.HttpInvokerProxyFactoryBean">
<property name="serviceUrl"
      value="https://remote-host:8080/security-remoting/hello" />
<property name="serviceInterface"
      value="se.jayway.demo.server.HelloService" />
<property name="httpInvokerRequestExecutor">
    <bean class="org.springframework.security.context.httpinvoker.AuthenticationSimpleHttpInvokerRequestExecutor  />
  </property>
</bean>

The AuthenticationSimpleHttpInvokerRequestExecutor will make sure that any Spring Security applied on the client side will be transferred to the server side using Basic HTTP Authentication. The filters and the XML configuration on the server side will make sure the Authentication headers are inspected and checked against the valid principals and credentials.

Applying SSL

As most of you probably know, Basic HTTP Authentication is pretty much the same thing as sending the authentication information over the network in plain text. This is why you will typically want to use encrypted connections whenever you are working with this type of authentication. This gets us into the core of this post, because it's here it becomes tricky.

In the ideal world you would just configure your web server to expose the service over HTTPS, change the target URL on the client side and be on your way. The reality however is slightly more complicated.

The problem is that you the built-in HttpURLConnection class on which the AuthenticationSimpleHttpInvokerRequestExecutor relies is very picky when it comes to certificates. What you want to do when working with SSL in Spring Remoting is to use the CommonsHttpInvokerRequestExecutor, which relies on Commons HttpClient - a more flexible and capable HTTP client. Now, the problem with this is that then you cannot use the AuthenticationSimpleHttpInvokerRequestExecutor anymore - they plug into the HttpInvokerProxyFactoryBean at the same extension point.

It boils down to this: if you want to use Spring Remoting and Spring Security over SSL you will need to implement your own HttpInvokerRequestExecutor:

 
public class BasicAuthenticationCommonsHttpInvokerRequestExecutor extends
  CommonsHttpInvokerRequestExecutor {
 
  @Override
  protected PostMethod createPostMethod(HttpInvokerClientConfiguration config) throws IOException {
    PostMethod postMethod = super.createPostMethod(config);
 
    Authentication auth =
        SecurityContextHolder.getContext().getAuthentication();
 
    if ((auth != null) && (auth.getName() != null) &&
          (auth.getCredentials() != null)) {
      String base64 = auth.getName() + ":" + auth.getCredentials().toString();
      postMethod.setRequestHeader("Authorization", "Basic " +
          new String(Base64.encodeBase64(base64.getBytes())));
    }
 
    return postMethod;
  }
}
 

Now all you need to do is specify this implementation as HttpInvokerRequestExecutor for your client ProxyFactoryBean and you're all set:

clientContext.xml
<bean id="helloService"
  class="org.springframework.remoting.httpinvoker.HttpInvokerProxyFactoryBean">
<property name="serviceUrl"
      value="https://remote-host:8080/security-remoting/hello" />
<property name="serviceInterface"
      value="se.jayway.demo.server.HelloService" />
<property name="httpInvokerRequestExecutor">
    <bean class="se.jayway.demo.security.BasicAuthenticationCommonsHttpInvokerRequestExecutor"  />
  </property>
</bean>
 

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.