Next, imagine that the Facade class and the Delegate interface below are part of a bigger system:

Create a matching easymock-test-config.xml (or mockito-test-config.xml).

Now, we have all the bits and pieces that are needed to start writing the integration test. We start simple to make sure that we autowiring and Spring context has been configured correctly:

The test is executed and it passes without any problem.

A second test is added to the same file with some added mock behavior:

Excellent, that test also passes.

Now that we have warmed up, we add a third test to the test class:

As expected, this test also passes without any problem.

Unfortunately, that is not always true. A closer investigation reveals that all tests pass when they are executed individually. When executing all three tests (either from the IDE or from a build tool like Maven), the third test fails unexpectedly:

java.lang.AssertionError:
  Unexpected method call Delegate.doSomethingElse():
        at org.easymock.internal.MockInvocationHandler.invoke(MockInvocationHandler.java:44)
	at org.easymock.internal.ObjectMethodsFilter.invoke(ObjectMethodsFilter.java:85)
	at $Proxy8.doSomethingElse(Unknown Source)
        [...]

This is EasyMock telling us that the mock object is in the wrong state. An EasyMock mock object goes through a series of steps:

1. Initialization - Instantiate the mock object.
2. Record - Record the expectations of the mock object.
3. Replay - Call replay() on the mock object so that it can replay the recorded state.
4. Test - Execute the test assertions.
5. Verify - Call verify() on the mock object to certify that the recorded mock expectations are fulfilled.

In an ordinary unit test, the mock object is thrown away after the verify phase, a new mock instance is created before the next test that can be used to record the new behavior. However, since we are creating a Spring integration test, there is one more thing to consider.

Reused beans

In the testing chapter of the Spring manual it is stated that:

By default, once loaded, the configured ApplicationContext and all of its beans are reused for each test method. Thus the setup cost is incurred only once (per test fixture), and subsequent test execution is much faster.

Consequently, all Spring beans, including mocked beans, will preserve their state between different test methods. The mock object will be in the verify state when the last test begins and not in the record state when delegateMock.doSomethingElse() is called. To solve the problem, we need some mechanism to ensure that the mock object is in a known, well-defined state before each test.

Reset mocks

Both EasyMock and Mockito provide methods to reset() the state of the mocked objects. Normally, resetting mock objects in the middle of a test method is considered to be a potential code smell, because it is likely that you are testing too much and that the test could be refactored into two separate tests accordingly. Nonetheless, resetting the mock instance @Before each test allow us to keep the same mock instance through the entire lifetime of the test class and yet put it in the record state when before each test starts:

When executing all tests in the test class, we see that that the problem has been solved and all tests pass.
For reference, click the link for the full source code of the EasyMock test class (and the Mockito test class).

Comments

You may choose to reset the mocks @After each test, the result will be the same.

The reset() method is called between the different test methods (because of the nature of @After and @Before), so the code smell of calling reset within a test is avoided.

Tests written using Mockito mocks are generally more tolerant for this kind of problem. In contrast to EasyMock, Mockito has no replay() method and no notion of steps. Therefore, it is possible to add additional mock expectations and to replace existing expectations, both after the test has been executed as well as after the result has been verified. Hence, you should always reset your mock objects before each test so that you do not get any accidental mocking behavior.

As a side note, another solution would be to annotate the test class (or all of its test methods) with the @DirtiesContext annotation. This will effectively recreate the entire application context after each test has been executed, causing all Spring beans to be in their initial state and thus the mock beans to be in the record state. Although this will work, there will be a significant performance penalty compared to the suggested reset() and @Before / @After solution, because all beans in the application context will be recreated and re-wired before each test method.

Dependencies

• Spring 3.0.6
• Mockito 1.8.5
• jUnit 4.10
• EasyMock 3.1

References

• Spring Reference Manual - Test Context Management and Caching
• Spring Reference Manual - SpringJunit4ClassRunner
• Spring Reference Manual - ContextConfiguration
• EasyMock
• Mockito

Previous post: Spring Integration Tests, Part I, Creating Mock Objects

@Entity
public class MyEntity {
...
    @Autowired @Transient
    private SomeService someService;

}

Notice the @Transient annotation that tells Morphia to avoid persisting this field! I solved this problem by adding an EntityInterceptor that autowires all entities:

public class SpringAutowiringEntityInterceptor extends AbstractEntityInterceptor {
	@Autowired
	private ApplicationContext applicationContext;

    @Autowired
    private Morphia morphia;

	@PostConstruct
	public void postConstruct() {
		morphia.getMapper().addInterceptor(this);
	}

	@Override
	public void preLoad(Object ent, DBObject dbObj, Mapper mapr) {
		applicationContext.getAutowireCapableBeanFactory().autowireBean(ent);
	}
}

Here is the complete source code SpringAutowiringEntityInterceptor.java. Let me know what you think!

(In this post, Mockito has been used for creating mock objects, but the same problem applies to EasyMock as well. You can find the corresponding files if you follow the provided links.)

Test setup

In the following example the SomeClass needs a reference to an instance of the SomeDependency interface:

When writing the integration test, we use the static Mockito.mock(Class classToMock) method to create a mock instance. The straightforward approach would be to let Spring instantiate the mock object with a static factory method in the xml configuration, e.g.

(Corresponding EasyMock config.)

To verify that the beans are created and wired correctly, we write a simple test:

(Same test for EasyMock, just update the @ContextConfiguration with the EasyMock config file.)

To our surprise, the test fails:

[...]
java.lang.IllegalStateException: Failed to load ApplicationContext
Caused by: org.springframework.beans.factory.BeanCreationException:
    Error creating bean with name 'someClass': Injection of autowired dependencies failed;
nested exception is org.springframework.beans.factory.BeanCreationException:
    Could not autowire field: private com.jayway.example.SomeDependency com.jayway.example.SomeClass.someDependency;
nested exception is org.springframework.beans.factory.NoSuchBeanDefinitionException:
    No matching bean of type [com.jayway.example.SomeDependency] found for dependency:
    expected at least 1 bean which qualifies as autowire candidate for this dependency.
    Dependency annotations: {@org.springframework.beans.factory.annotation.Autowired(required=true)}
[...]

Explanation

In order to find a solution to the problem, we need to understand Spring's initialization process:

1. Load bean definitions.
   This step includes scanning the application context XML files, scanning packages defined by component-scan, and loading the bean definitions found into the bean factory. (BeanFactoryPostProcessors such as the PropertyPlaceHolderConfigurer may be called to update the bean definitions.)
2. Instantiate beans and store them in the application context.
   The bean factory creates the bean from the bean definitions. Bean dependencies get injected.
3. Bean post processing.
   All initializing methods (e.g. annotated with @PostConstruct, init-methods declared in the XML and the afterPropertiesSet() method will execute. Annotations such as @Required will be validated. Dynamic proxies in an AOP environment will be created and so on.

The problem that we see occurs due to a corner case in the first two steps. When the bean definition is created Spring scans through the application context XML file. It finds the declaration of the mock bean and a reflective call is made to find out the return type of the method defined by the factory-method declaration in an attempt to determine the bean's type. The return type of this method is declared as the formal type parameter <T> (remember that we use the Mockito.mock(Class<T> classToMock) as factory method). Consequently, the bean definition of someDependencyMock will be of java.lang.Object and not SomeDependency as one would think.

In the second step, the someClass bean is instantiated. Springs discovers the @Autowired annotation and tries to fetch an existing SomeDependency bean from the application context. None has yet been created, so the bean factory proceeds and looks for suitable bean definition in order to create an instance of the requested bean on the fly. This operation fails because the bean definition of someDependency is mapped to java.lang.Object. At this point, Spring bails out and throws the NoSuchBeanDefinitionException.

FactoryBean to the rescue

The problem is solved by implementing a custom FactoryBean that can be used whenever we need to mock an object:

(In the EasyMockFactoryBean, I have added an enum to define the type of mock object.)

Next, the Spring test config is updated to use the factory bean:

(Corresponding EasyMock config.)

Spring will still instantiate the beans in the order that they were declared in the mockito-test-config.xml, i.e. starting by creating an instance of SomeClass and then attempt to inject an instance of a SomeDependency into it before any has been created. The good news is that bean factory will scan through all declared FactoryBeans, calls its getObjectType() method, and if the returned type is correct, call its getObject() which should return an instance of the requested type.

Alternative solution

There is another more brittle solution to the problem. By simply changing the order of the tags in the initial application context, e.g. putting the bean declaration that defines the mock above the component scan, will cause the test to pass. The bean definition will still be wrong in the sense that the someDependencyMock will be defined as a java.lang.Object, but there is another important difference. In this case, the bean factory will invoke the Mockito.mock(Class<T> classToMock) method with SomeDependency as parameter causing the someDependencyMock bean to be created and subsequently stored in the application context. Later, the someClass bean is created and the dependency can obtained from the application context when requested by the bean factory and the wiring of the beans will succeed. However, making sure that the order of the bean declarations in the XML is always correct may neither be simple nor obvious, and it will get increasingly more difficult the more beans you add to the configuration.

Disclaimer

As stated in the in the first paragraph, I would only consider this solution for integration tests because of performance reasons. The application context itself adds some overhead, but the big performance hit is to create and wire all beans that are associated with it. When writing unit tests there is no need for this, so you could revert to constructor or setter dependency injection, Spring's ReflectionTestUtils.setField(), PowerMock's Whitebox.setInternalState(), Mockito's @InjectMocks or similar techniques.

Acknowledgements

Thanks to Wilhelm Kleu at stack overflow for suggesting the solution and to Mattias Hellborg Arthursson for valuable discussions.

Dependencies

• Spring 3.0.6
• Mockito 1.8.5
• jUnit 4.10
• EasyMock 3.1

References

• Spring Reference Manual - Static Factory Method
• Spring Reference Manual - FactoryBean
• Spring Reference Manual - Integration Testing
• Mockito
• EasyMock

Next post: Spring Integration Tests, Part II, Using Mock Objects

Setup
I have used Roo 1.1.2.RELEASE for this tutorial and I started out with this simple Roo project.

project --topLevelPackage com.jayway.webflowexample
persistence setup --database H2_IN_MEMORY --provider HIBERNATE
entity --class ~.domain.Account
field string --fieldName username --sizeMin 6 --sizeMax 40
field string --fieldName password --sizeMin 6 --sizeMax 40
controller all --package ~.web
web flow --flowName registration
perform eclipse

Start the project in your favorite container and surf to http://localhost:8080/webflowexample/registration and you should see the initial state:

Web Flow
The "web flow --flowName registration" command will setup the needed configuration and create a sample web flow. To update with persistence do the following:

In the file src/main/webapp/WEB-INF/views/registration/flow.xml

• add creation of the new user account and save it in the flow scope (line 1-3)
• attach the model to the view by adding model="account" to the view-state tag (line 6)
• save the account in the end-state (line 17-19)

Put together it looks like this:

If you want to encode the password before storing it use a service instead for line 17-19 and implement it there. A bean with id "userRegistrationService" must be registered in the application context for the below snippet to work.

View

In the file src/main/webapp/WEB-INF/views/registration/view-state-1.jspx

• change the form tag to form:form, add the attribute modelAttribute to this tag (line 1) and make sure to add the form xml namespace xmlns:form="http://www.springframework.org/tags/form"
• add user input fields and tie them to the model and add display of error messages in case there are validation errors (line 3-16)

Put together this is how the form tag would look:

Username:





Password:






         
        

The account object needs to be serializable so add @RooSerializable to the Account class.
Make sure to have the Roo shell running in the background when adding this annotation.

Validation

In the 2.3.0.RELEASE version of Spring Web Flow you can take advantage of the annotations of the fields in the Account class for validation. If we take a look at the Account class we see that the username and the password have to be between 6 and 40 characters (line 7 and 10).

@RooJavaBean
@RooToString
@RooEntity
@RooSerializable
public class Account {

    @Size(min = 6, max = 40)
    private String username;

    @Size(min = 6, max = 40)
    private String password;
}

To activate this validation update your pom.xml to use 2.3.0.RELEASE for web flow and add the following to your webflow-config.xml:

And add the validator bean as attribute to the flowBuilderServices bean:

Replace the schema location

http://www.springframework.org/schema/webflow-config/spring-webflow-config-2.0.xsd

with

http://www.springframework.org/schema/webflow-config/spring-webflow-config-2.3.xsd

If you now enter a username or password that is too short you will see a validation error message:

That's it!
Here's the code

• Three different FTP protocols should be supported, namely FTP, FTPS and SFTP
• It should be possible to transmit different files to several different servers
• The files to be sent were generated in runtime, they had different file names and were stored in different directories

Basically, I should implement the following interface:

FtpSender.java

public interface FtpSender {

    /**
     * Uses the {@code ftpProperties} to transmit the provided {@code file} to a remote server
     *
     * @param ftpProperties The FTP properties of the remote server
     * @param file The file to transmit
     */
    void sendFile(FtpProperties ftpProperties, File file);
}

where the FtpProperties was another interface:

FtpProperties.java

public interface FtpProperties {

    /**
     * Gets the protocol
     * @return One of {@code ftp}, {@code ftps} or {@code sftp}
     */
    String getProtocol();

    /**
     * Gets the user name
     * @return The name of the user
     */
    String getUserName();

    /**
     * Gets the password
     * @return The password
     */
    String getPassword();

    /**
     * Gets the FTP host
     * @return The FTP host
     */
    String getHost();

    /**
     * Gets the name of the directory on the server where the file will be transferred
     * @return The name of the remote directory
     */
    String getRemoteDirectory();

    /**
     * Gets the passive mode, e.g. if the server is behind a firewall
     * @return whether or not passive mode should be used
     */
    boolean getPassiveMode();
}

Rather than implementing the entire FTP client from scratch, I investigated the capabilities of existing frameworks. Most solutions recommend using an existing FTP framework such as Apache Commons / Jakarta Commons Net for FTP and FTPS and then wrap it in a SSH layer like Jsch / Java Secure Channel for SFTP. However, soon I discovered Apache Camel, "a powerful open source integration framework based on known Enterprise Integration Patterns with powerful Bean Integration" (their words). They support a various range of components, anything from XQuery and Atom to XSLT and SQL, just to name a few. To my luck, they also support all three FTP protocols that I needed.

Fundamentals

What does the Camel FTP API look like? In its basic form it is a little more than a one-liner:

FtpRouteBuilder.java

public class FtpRouteBuilder extends RouteBuilder {

    @Override
    public void configure() throws Exception {
        from("file://localDirectory").to("ftp://user@host.com/remoteDirectory?password=secret&passiveMode=true");
    }
}

So what is going on here? The RouteBuilder is one of Camel's core classes that defines the Camel specific DSL. In this example, a Route from the localDirectory to a remoteDirectory over FTP with the provided credentials has been created. As can be seen, it is easy to create and configure different endpoints using String URIs. It should also be mentioned that it is possible to fetch files from the remote FTP server by swapping the URIs in the to and from methods.

A few more lines are needed to activate the route:

public static void main(String[]args) throws Exception {
    CamelContext camelContext = new DefaultCamelContext();
    try {
        camelContext.addRoutes(new FtpRouteBuilder());
        camelContext.start();
        // do other stuff...
    }
    finally {
        camelContext.stop();
    }
}

A CamelContext is created for managing the route. The previously described FtpRouteBuilder is instantiated and added to the camelContext which is subsequently started. As a consequence, any file that is placed in the "localDirectory" folder will be automatically transferred to the "remoteDirectory" of the FTP server while the program is running.

Adding Configurability

The requirement of supporting different FTP protocols is solved by changing the URI from ftp:// to ftps:// or sftp:// respectively. It is just as easy to fulfill the second requirement of multiple server support by changing the host, user, port and other parameters of the URI. Likewise, additional settings may be configured by adding more options if needed, see the Camel FTP documentation.

Adding Dynamism

The last challenge was to add the dynamic support of selecting source files and destination servers during runtime. The easiest solution is to use another of Camel's base classes, the ProducerTemplate. Again, the solution is a one-liner:

producerTemplate.sendBodyAndHeader("ftp://user@host.com/remoteDirectory?password=secret", file, Exchange.FILE_NAME, file.getName());

The sendBodyAndHeader() method name reveals a glimpse of Camel's underlying messaging architecture. The parameters used are the destination URI with additional options, the message body, i.e. the File to be sent, a message header parameter that identifies the last parameter as the name of the file it will have on the remote server once it has been transferred.

Spring Integration

With some refactoring and a little Spring magic we have all the bits and pieces needed to implement the previously defined FtpSender interface:

FtpSenderImpl.java

@Service
class FtpSenderImpl implements FtpSender {

    /** Camel URI, format is ftp://user@host/fileName?password=secret&passiveMode=true */
    private static final String CAMEL_FTP_PATTERN = "{0}://{1}@{2}/{3}?password={4}&passiveMode={5}";

    private final ProducerTemplate producerTemplate;

    /**
      * Constructor
      * @param producerTemplate The producer template to be be used
      */
    @Autowired
    FtpSenderImpl(ProducerTemplate producerTemplate) {
        this.producerTemplate = producerTemplate;
    }

    @Override
    public void sendFile(FtpProperties ftpProperties, File file) throws RuntimeException {
        producerTemplate.sendBodyAndHeader(createFtpUri(ftpProperties), file, Exchange.FILE_NAME, fileName);
    }

    /**
      * Creates a Camel FTP URI based on the provided FTP properties
      * @param ftpProperties The properties to be used
      */
    private String createFtpUri(FtpProperties ftpProperties) {
        return MessageFormat.format(CAMEL_FTP_PATTERN,
                ftpProperties.getProtocol(),
                ftpProperties.getUserName(),
                ftpProperties.getHost(),
                ftpProperties.getRemoteDirectory(),
                ftpProperties.getPassword(),
                ftpProperties.getPassiveMode());
    }
}

Using the Camel namespace, the required plumbing work is delegated to the Spring application config:

spring-config.xml

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:p="http://www.springframework.org/schema/p"
       xmlns:camel="http://camel.apache.org/schema/spring"
       xsi:schemaLocation="
		http://www.springframework.org/schema/beans   http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
		http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd
		http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd">

    <!-- Let Spring create the Camel context and the Camel template, including lifecycle management such as starting and stopping them -->
    <camel:camelContext id="camelContext">
        <camel:template id="camelTemplate" />
    </camel:camelContext>

    <!-- Use Spring component scan to find the FtpSenderImpl implementation -->
    <context:component-scan base-package="com.jayway.ftp" />

</beans>

Conclusions

Camel and Spring provide a simple, yet configurable, way of implementing a dynamic FTP client.

Acknowledgments

Thanks to Claus Ibsen and other members of the Apache Camel Forums for providing valuable and rapid support.

Glossary

• FTP File Transfer Protocol
• FTPS FTP Secure is an extension to FTP that adds support for the TLS, Transport Layer Security, and the SSL, Secure Sockets Layer, cryptographic protocols
• SFTP SSH File Transfer Protocol, i.e. FTP over the Secure Shell protocol

References

Camel API
Camel Components
Camel FTP
Camel ProducerTemplate
Camel Spring
Camel ProducerTemplate and Spring
Camel Enterprise Integration Patterns
Camel Forums

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

So what was the problem? Well, I've been using @Configurable and @Autowired to inject stuff in my domain object which I create in code. To get this working when running mvn test you have to pass in spring-agent.jar as javaagent. When you do this, everything worked great! To to this with Maven you have to do the following:

 
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>2.4</version>
    <configuration>
      <forkMode>once</forkMode>
      <argLine>
        -javaagent:${settings.localRepository}/org/springframework/spring-agent/${spring.version}/spring-agent-${spring.version}.jar
      </argLine>
      <useSystemClassloader>true</useSystemClassloader>
    </configuration>
</plugin>
 

Now, that's all cool, and it worked like a charm... for a while. When I added @Configurable to another class to autowire in a new dependency, I could not get that specific class to get weaved properly. Believe me, I tried everything I could think of, but nothing worked... until I found a hint on a thread with a related problem. By passing in a second javaagent, aspectjweaver.jar, the problem was solved! To do this in Maven you just add the second javaagent after the first, like this:

 
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>2.4</version>
    <configuration>
      <forkMode>once</forkMode>
      <argLine>
        -javaagent:${settings.localRepository}/org/springframework/spring-agent/${spring.version}/spring-agent-${spring.version}.jar -javaagent:${settings.localRepository}/org/aspectj/aspectjweaver/1.6.1/aspectjweaver-1.6.1.jar
      </argLine>
      <useSystemClassloader>true</useSystemClassloader>
    </configuration>
</plugin>
 

Note: If you add a line-break between the two javaagents, it doesn't work.

What was the problem I had? I have no idea! Why does this solution work? I have no idea! All I know is that I get a green light from my tests, and that I don't need this solution when running live in Tomcat or whatever, since the classloader there has addTransformer(ClassFileTransformer).

Still, if anyone has any idea of why I, after everything worked with only spring-agent.jar, needed to add aspectjweaver I am all ears! Don't get me wrong! I can live with not knowing, but I would get peace of mind from knowing...

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.

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.

I was playing around with creating a Twitter clone, in my opinion the "Hello World" of graph databases, and I started out with the following simple service.

Spring configurating:

 
<beans ... >
	<context:annotation-config />
 
	<bean id="neo" class="org.neo4j.api.core.EmbeddedNeo"
		destroy-method="shutdown">
		<constructor-arg>
			<value>var/neo</value>
		</constructor-arg>
	</bean>
 
	<bean id="indexService" class="org.neo4j.util.index.NeoIndexService"
		destroy-method="shutdown">
		<constructor-arg ref="neo" />
	</bean>
 
	<bean id="twitterService"
		class="com.jayway.twitter.neo.NeoBasedTweetService">
<property name="neo" ref="neo" />
<property name="indexService" ref="indexService" />
	</bean>
 
	<!-- Transactions -->
	<tx:annotation-driven />
        ...
</beans>
 

The service:

 
public class NeoBasedTweetService implements TweetService {
 
	protected NeoService neo;
	protected IndexService indexService;
 
	//Setters for neo and indexService
 
	@Transactional
	public Tweet createTweet(User user, String tweet) {
		UserNode userNode = new UserNode(indexService.getSingleNode(
				TwitterIndexConstants.INDEX_USER, user.getUserName()));
		TweetNode tweetNode = new TweetNode(neo.createNode());
		tweetNode.setKvitt(tweet);
		userNode.createRelationshipTo(tweetNode, KvittRelationships.KVITTRAT);
		return tweetNode;
	}
 
	//Services to create User and more
 
}
 

This doesn't feel very DDD. I would really want to do the User to be responsible for creating the Tweet. Like this:

 
public class NeoBasedTweetService implements TweetService {
 
	protected NeoService neo;
	protected IndexService indexService;
 
	//Setters for neo and indexService
 
	@Transactional
	public Tweet createTweet(User user, String tweet) {
		UserNode userNode = new UserNode(indexService.getSingleNode(
				TwitterIndexConstants.INDEX_USER, user.getUserName()));
		return userNode.createTweet(tweet);
	}
 
	//Services to create User and more
 
}
 

The TweetNode and UserNode would look like this:

 
public class TweetNode extends NodeDelegate implements Tweet {
 
	TweetNode(Node underlyingNode) {
		super(underlyingNode);
	}
 
	//Methods for doing Tweet-stuff
 
}
 

 
public class UserNode extends NodeDelegate implements User{
 
	UserNode(Node underlyingNode) {
		super(underlyingNode);
	}
 
	//Methods for doing User-stuff
 
	public Tweet createTweet(String kvitt) {
		//Here comes a problem! I need a new Node
		//from the NeoService to create the TweetNode
		TweetNode tweetNode = new TweetNode(null);
		tweetNode.setTweet(tweet);
		createRelationshipTo(tweetNode, TwitterRelationships.TWEETED);
		return tweetNode;
	}
}
 

NodeDelegate, extended by both User- and TweetNode implements the Neo4j interface Node and delegates all the method calls to the underlying node ( for more on this, see my previous post) :

 
public class NodeDelegate implements Node {
 
	private Node delegate;
 
	protected NodeDelegate(Node underlyingNode) {
		delegate = underlyingNode;
	}
 
	//Methods for delegating all Node methods to the Node delegate
}
 

As you see I have a problem here. In the first version my NeoService is injected into NeoBasedTweetService and used when I create the new TweetNode. In the re-made, more DDD-style example I create the new TweetNode in the UserNode, where I don't have access to my NeoService. How do we solve this?

One alternative that I instinctively dislike is to inject the NeoService into the UserNode. The reason for me disliking this is that my UserNode IS a Node, and it feels very tangled if a Node holds a reference to its container. But I came to think of another solution thanks to a talk I did a while back together with Henrik Reinhold on what was new in Spring 2.5.

In Spring 2.5 load-time weaving (LTW) capabillites was introduced, and with LTW you can manipulate objects in load-time, as opposed to runtime weaving that is proxy based. This, combine it with @Configurable and @Autowired, proves to be very helpful when the Spring context is not in charge of creating the objects in question, as in the example above...

To enable LTW we add one tag in the Spring configuration:

 
<context:load-time-weaver />
 

After that we have to inform the Spring container of how we want thing done. To do we edit the TweetNode and NodeDelegate like this:

 
//Annotate the class with @Configurable so that Spring can find it.
@Configurable
public class TweetNode extends NodeDelegate implements Tweet {
 
	TweetNode(Node underlyingNode) {
		super(underlyingNode);
	}
 
	//Add a default constructor both in the TweetNode
	//and the NodeDelegate, it is new:able without a Node.
	public TweetNode() {
		super();
	}
 
	//Add a setter for the underlaying Node and annotate it with @Autowired.
	@Autowired
	public void setNode(Node nodeDelegate) {
		super.setNode(nodeDelegate);
	}
 
	//Tweet-methods as before
 
}
 

 
public class NodeDelegate implements Node {
 
	private Node delegate;
 
	protected NodeDelegate(Node underlyingNode) {
		delegate = underlyingNode;
	}
 
	protected NodeDelegate() {
	}
 
	protected void setNode(Node nodeDelegate) {
		if (delegate == null) {
			delegate = nodeDelegate;
		}
	}
 
	//Methods for delegating all Node methods to the Node delegate
 
}
 

Now Spring only has to be able to create Nodes. To do that we create a simple NodeFactory, like this:

 
public class NodeFactory implements FactoryBean{
 
	private NeoService neo = null;
 
	public void setNeo(NeoService neo) {
		this.neo = neo;
	}
 
	@Transactional
	public Object getObject() throws Exception {
		return neo.createNode();
	}
 
	public Class getObjectType() {
		return Node.class;
	}
 
	public boolean isSingleton() {
		return false;
	}
 
}
 

... and add it to the configuration, like this:

 
	<bean id="node" class="com.jayway.neo.utils.NodeFactory">
<property name="neo" ref="neo" />
	</bean>
 

The result of this is that Spring now has a NodeFactory that returns a new node for every request, I have annotated the TweetNode so that Spring knows of it (@Configurable) and what to do with it (@Autowired on setNode) and I've enabled load-time weaving in order to get the a new Node woven into a TweetNode every time a new instance of it is created in the code.

In UserNode I really don't have to make any changes. "setNode(Node)" will get a new Node after the instantiation of a TweetNode, even if the constructor that takes a Node is called. For clarity I still changed the UserNode as follows:

 
public class UserNode extends NodeDelegate implements User{
 
	UserNode(Node underlyingNode) {
		super(underlyingNode);
	}
 
	//Methods for doing User-stuff
 
	public Tweet createTweet(String kvitt) {
		//This TweetNode will get a Node set by Spring
		TweetNode tweetNode = new TweetNode();
		tweetNode.setTweet(tweet);
		createRelationshipTo(tweetNode, TwitterRelationships.TWEETED);
		return tweetNode;
	}
}
 

The problem I had when trying to make the UserNode responsible for creating its TweetNode's was that I needed to inject something that could create Nodes into the UserNodes. By using load-time weaving and instructing Spring of how to wire a TweetNode I don't have to pass my NeoService around to all the UserNodes created in my code. Instead I can rely on Spring to inject what is needed, when it's needed.

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.

BDD in Java with easyb (John Ferguson Smart)

John started out by arguing that TDD is not about testing, it's about writing better code. That is, it's about making your code more maintainable, flexible, reliable and simple. TDD is forces the programmer to think about how to test the class before actually writing the class. BDD, on the other hand, helps to determine what to test and to write more focused code, by starting with the behavior. Instead of thinking that you're testing your class, you should think that you're validating your requirements!

easyb is a BDD testing framework for Java, written in Groovy (hence providing full access to all Java API's). It ensures that tests become clearer and easier to both write and read! It helps the developer to focus on the requirements only. A competitor to easyb is JBehave, which is an extension to JUnit. However, according to John, JBehave is more cumbersome than easyb.

easyb makes use of stories, much like the story cards in the Agile world. In a story, a narrative approach is used to describe a precise requirement. In easyb, a story could look like this:

 
scenario “Make initial deposit onto a new account”, {
	given “a new account”
	when “an initial deposit is made”
	then “the balance should be equal to the amount deposited”
}
 

This scenario is quite clear and readable, isn't it!? Furthermore, it's self-documenting - a very appreciated feature =) And the syntax is so trivial that even a non-technical stakeholder would have no problem understanding it. The developer can then reuse the given scenario (pseudo) code and implement the test case, like this:

 
import com.mycompany.bankonline.domain.Account
 
scenario “Make initial deposit onto a new account”, {
	given “a new account”, {
		account = new Account()
	}
	when “an initial deposit is made”, {
		initialAmount = 100
		account.makeDeposit(initialAmount)
	}
	then “the balance should be equal to the amount deposited”, {
		account.balance.shouldBe initialAmount
	}
}
 

The shouldBe call is an intuitive and readable way to verify that the requirement holds. Another way to verify the outcomes is to use the ensure syntax. Example:

 
ensure(account.balance > 0)
 

or

 
ensure(account) {
	has([balance:100])
}
 

easyb could be extended to use DBUnit (and further plugins for Grails and Excel are on the way). On the IDE support, the only good option is IntelliJ IDEA. It really comes down to the Groovy support, and Eclipse and NetBeans doesn't shine here. In those cases, you're better off running the tests in Maven or Ant, which both are well supported. In the upcoming version, easyb will have full support for Continuous Integration (CI), enabling automatic test execution in a CI-server such as Hudson.

Furthermore, easyb comes with a web application - Easiness (cmp. Fitnesse) - where stakeholders can create stories in plain text. The developers can then go ahead and implement the stories defined by the stakeholders. This is an important features, that further improves the cooperation between the customer and the provider. It really seems like a quite nice little framework! If you agree, have a look at it at http://easyb.org/.

From Concurrent to Parallel – Library-based parallelism in JDK 7 (Brian Goetz)

Brian is an expert in the concurrency area, but he's not a good presenter! He speaks faster than I can read, and his slides are so packed with info that he doesn't have time to say the half of it. That put aside, in this very interesting session Brian presented some really cool concurrency features to be included in JDK 7.

As you probably know, JDK 5 introduced a set of very useful classes for course-grained parallelism. JDK 7 will introduce a framework for fine-grained parallelism - the "fork-join" framework.

We have now reach a point in time when Moore's laws isn't valid anymore. The new reality is not faster CPUs but more CPUs. To adapt to these changes, programmers have to change the way they think about parallelism. The unit of work (UoW) that represents a task to be solved must be split into even smaller parts to be able to keep all hardware busy. Nowadays, it isn't enough to for ex. spawn a new thread for each service call in a server, the UoW must be split up even further.

Examples of finer-grained parallelism is searching, sorting and filtering a data set. Such a task is preferably solved by dividing it into sub-problems and combining the sub-results at the end. We could use the course-grained concurrency tools (for ex. Executor + Future) introduced in JDK 5 to solve this problem. However, with multiple CPUs available, these tools doesn't perform optimally. For ex., the shared work queue in the Executor becomes a bottle neck when the number of threads/CPUs increases. Furthermore, these tools provide no form of load balancing, i.e. if one thread finishes before the others, it is never reused.

The divide-and-conquer algorithm could also be applied to solve the problem. This great advantage of this approach is that it's independent of the number of CPUs used! Using plain threads for this approach is too expensive though, since thread creation costs way too much. However, the fork-join-operation in JDK 7 solves problems like these using the divide-and-conquer algorithm in a much more effective way! Internally, it uses an slim thread pool to overcome the cost of thread creation. Furthermore, no data-copying penalty exist since the data set (for ex. an array) is not divided/copied during the solution. Instead, the indexes within the data structure is used to define each data subset. Another advantage is that the code doesn't know how many CPUs it executes on, hence it's portable!

While the Executor (JDK 5) should be used for tasks consisting of both IO and computing, the fork-join-operation (JDK 7) should be used for highly compute-intensive tasks. Examples of such tasks are matrix operations, numerical integrations and game playing. The JDK 7 class to be used for these kind of problems is ParallelArray. It's a utility class that greatly simplifies the work of solving a task in parallel. You can think of it as an in-memory database for data sets. Typical usage is:

 
ParallelLongArray pa = ParallelLongArray.createUsingHandoff(array, forkJoinPool);
long max = pa.max();
 

The ParallelArray class provides operations for:

• Filtering (nestable)
• Mapping
• Replacement
• Aggregation (max, count, sum, ...)
• Application (one action performed for each selected element)

To compare, the ParallelArray class acts much like the Map-Produce concept introduced by Google but it works in a different domain (local system instead of in a distributed system).

The only downside really is that JDK 7 isn't scheduled until mid 2010, meaning we'll have to wait quite some time before we can actually use these new concurrency features. But from the looks of it ... it may be worth the wait!

The SpringSource DM Server (Joris Kuipers)

The reasons why SpringSource decided to develop a new application server were many. Today, modularity is important and developers spend much time on achieving it in their applications (layering, separation of concerns, etc.). However, when the application is deployed, all modularity is lost - the deployable unit is one huge, monolithic WAR file. That means that sharing code (let alone services) between applications become hard if not impossible. In order to perform the smallest update on the application, whole WAR file have to be redeployed. Furthermore, the servers themselves lack modularity; they come prepackaged with a lot of modules but there's no way to configure that your application only make use of a couple of them. Hence, they are all left in there, consuming unnecessary CPU cycles and memory.

The DM (Dynamic Modules) server was developed to tackle these issues of non-modularity. In order to achieve true modularity, is has been built on top of OSGi (namely the Equinox container). Since OSGi can be quite hard sometimes, the DM server conceal the complexity of OSGi in the same way as the Spring framework does with for ex. Remoting or JMX.

In order to be able to use a third-party library from within the DM server (and from any other OSGi containers), the standard JAR library needs to be extended with OSGi-specific meta data - the OSGi manifest. SpringSource has therefore created the Enterprise Bundle Repository, where they have started to upload and publish OSGi-ified Java EE libraries. If you're using Maven or Ivy, the bundle repository can easily be configured as a remote (or local) repository.

The DM server also introduces a couple of new OSGi import constructs, enabling ease of development. One example is the "Import-library" that can be useful if you want to make use of a framework (for ex. Spring) but don't want to waste your time having to specify every single Import-package (for example Spring-Remoting) within the framework (as you normally would have had to do). This doesn't affect performance improvement since (thanks to OSGi) none of the pre-installed bundles are loaded before they are actually used! Furthermore, with the DM server it's now possible to remove the library bloat of monolithic Java EE WARs. Instead of building the external libraries into your WAR, you can instead declare them as dependencies in the OSGi manifest headers. The server will then convert these into plain "Import-package" constructs during deployment. That way, the size of the built/deployed WAR can be reduced significantly!

In the DM server, one can of course deploy plain OSGi bundles but also WARs, EARs etc. Typical scenarios for deploying a plain OSGi bundle are stand-alone libraries, global services and small stand-alone applications. However, being able to deploy a bundle is not enough in most cases ... A normal application normally consist of multiple bundles, which becomes hard to un/deploy since there is no single deployable unit. Furthermore, with multiple bundles you don't get a common log file or a notion of an application scope. To tackle this issue, the DM server adds the notion of an application by introducing the PAR (Platform Archive) format. It's basically a JAR with a number of 'Application-*' manifest headers. You can think of it as an EAR in Java EE. PARs are versioned and the versions apply to all of their bundles. This mean that one can deploy a PAR twice with different versions but with the same bundles, without conflicts.

The DM server comes in several versions. Of course there's the community version, using a GPL and SpringSource license. Then there's the commercial license where full support from SpringSource is included. On the extension side, better Maven support will soon be released so that the dependencies can be specified in a single place (not like now when you have to duplicate them in the pom and in the manifest). There's a Eclipse-plugin available that enables re/deployments from within the IDE.

These are some of the features in the DM server. There are plenty or more cool ones, read all about them here. There, you'll also find a lot of sample applications that can get you going! With the DM server, SpringSource feel that they are filling the (up until now) empty space of server side OSGi and states that "The DM server is the healthy new way to run your apps!". I must say it looks very promising! Why don't you go ahead and try it out!? I know I will!

If you appreciated these posts, you will definitely enjoy next years conference! Pick up your calendar and reserve December 2009 for a great week at Devoxx!

 
<bean id="traditionalPersonDao"
      class="org.springframework.ldap.samples.article.dao.TraditionalPersonDaoImpl">
<property name="url" value="ldap://localhost:3901" />
<property name="base" value="dc=jayway,dc=se" />
<property name="userDn" value="uid=admin,ou=system" />
<property name="password" value="secret" />
</bean>
 

In order to simplify deployment and maintenance, it's quite common to extract properties related to server names, ports, and user credentials from the Spring configuration file into a separate property file, like in this ldap.properties:

url=ldap://localhost:3901
userDn=uid=admin,ou=system
password=secret

In the configuration file, the previously hard-coded values are replaced with "property placeholders", ie variables enclosed with ${}:

 
<bean id="traditionalPersonDao"
      class="org.springframework.ldap.samples.article.dao.TraditionalPersonDaoImpl">
<property name="url" value="${url}" />
<property name="base" value="dc=jayway,dc=se" />
<property name="userDn" value="${userDn}" />
<property name="password" value="${password}" />
</bean>
 

In order to perform the property value substitution in a transparent way, a PropertyPlaceholderConfigurer is configured:

 
<bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
<property name="location" value="classpath:/config/ldap.properties" />
</bean>
 

Spring will pick up that one has been configured and run it before any beans are instantiated. It will read the property file and replace the placeholders with the actual values. Quite handy and very simple.

But what if your organization dislikes having sensitive information like passwords lying around in property files, in clear text? Let's say that your boss demands that all such passwords must be encrypted. Wouldn't it be great if the password then somehow could be automatically decrypted before being used? This can quite easily be achieved using the Jasypt library.

It's a two-step process. First we need to encrypt the password. Then we configure a different PropertyPlaceholderConfigurer that is capable of decrypting the property after it has been read.

Encrypting the password

The available encryption algorithms are currently limited to Password Based Encryptors (PBE). There are scripts for encrypting and decrypting in the Jasypt distribution. This is the procedure for encrypting a text (assuming the Jasypt library has been unpacked in JASYPT_HOME):

% cd $JASYPT_HOME/bin
% chmod +x *.sh
% ./encrypt.sh input="This is my message to be encrypted" password=MYPAS_WORD verbose=false
p3ZVFhK+aqQCyvSk9uWk7p/eisyPbXp3zt3sqnEZsn1Z5plr4CHNC/HHqlgRQ7I3

Let's verify that it can actually be decrypted:

% ./decrypt.sh input="p3ZVFhK+aqQCyvSk9uWk7p/eisyPbXp3zt3sqnEZsn1Z5plr4CHNC/HHqlgRQ7I3"
    password=MYPAS_WORD verbose=false
This is my message to be encrypted

Good. Note that the encryption is "salted", so you'll never get the same result twice. You'll always be able to decrypt it, though. Want to see? OK, one more time then:

% ./encrypt.sh input="This is my message to be encrypted" password=MYPAS_WORD verbose=false
Zi68CfrcLndtKg0npE9OScr+7qNJmWrcO8XI7ZGyucjFiqT9h1FnAIxyezbqNjQq

% ./decrypt.sh input="Zi68CfrcLndtKg0npE9OScr+7qNJmWrcO8XI7ZGyucjFiqT9h1FnAIxyezbqNjQq"
    password=MYPAS_WORD verbose=false
This is my message to be encrypted

Now, let's encrypt our password:

% ./encrypt.sh input="secret" password=MYPAS_WORD verbose=false
6mbJVZ6jozGYF1pjjqDQOQ==

We'll replace the password value in the properties file with the string above, surrounded by ENC():

url=ldap://localhost:3901
userDn=uid=admin,ou=system
password=ENC(6mbJVZ6jozGYF1pjjqDQOQ==)

Configure A Decrypting PropertyPlaceholderConfigurer

We'll simply replace our existing PropertyPlaceholderConfigurer with the Jasypt EncryptablePropertyPlaceholderConfigurer:

 
<bean class="org.jasypt.spring.properties.EncryptablePropertyPlaceholderConfigurer">
   <constructor-arg ref="configurationEncryptor" />
<property name="location" value="classpath:/config/ldap.properties" />
</bean>
 

It delegates the actual decryption to a StringEncryptor implementation:

 
<bean id="configurationEncryptor" class="org.jasypt.encryption.pbe.StandardPBEStringEncryptor">
<property name="config" ref="environmentVariablesConfiguration" />
</bean>
 

The encryptor in turn needs a configuration that provides information such as the algorithm to use and the encryption password. It delegates that responsibility to a PBEConfig implementation that expects the password to be available in an environment variable or a system property:

 
<bean id="environmentVariablesConfiguration"
      class="org.jasypt.encryption.pbe.config.EnvironmentStringPBEConfig">
<property name="algorithm" value="PBEWithMD5AndDES" />
<property name="passwordEnvName" value="APP_ENCRYPTION_PASSWORD" />
</bean>
 

Providing the encryption password as a system property is actually a good thing. A system property can be cleared just when the application has started, thereby minimizing considerably the time that the password is exposed.

Running The Application

It won't work with a Maven property:

% mvn test -DAPP_ENCRYPTION_PASSWORD=MYPAS_WORD
...
Tests run: 8, Failures: 0, Errors: 8, Skipped: 0
[INFO] ------------------------------------------------------------------------
[ERROR] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] There are test failures.

Please refer to target/surefire-reports for the individual test results

We check the Surefire reports and find the cause of the error:

org.jasypt.exceptions.EncryptionInitializationException:
  Password not set for Password Based Encryptor

It does however work with an environment variable:

% export APP_ENCRYPTION_PASSWORD=MYPAS_WORD
% mvn test
...
Tests run: 8, Failures: 0, Errors: 0, Skipped: 0
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
...
% unset APP_ENCRYPTION_PASSWORD

Issues With Java5

If we're on Java5 (or lower), we'll need ICU4J. Otherwise, we'll run into this:

org.jasypt.exceptions.EncryptionInitializationException:
  java.lang.NoClassDefFoundError: com/ibm/icu/text/Normalizer

There are two places where we'll need ICU4J: the command line tools and our Maven project.

ICU4J With The Command Line Tools

Reviewing the Jasypt scripts, we find that it's possible to customize the classpath:

export JASYPT_CLASSPATH=~/Downloads/icu4j-4_0.jar

ICU4J With Maven

Add this profile to the Maven pom.xml to get ICU4J in the classpath:

 
<profiles>
<profile>
      <id>jdk15</id>
      <activation>
         <jdk>1.5</jdk>
      </activation>
      <dependencies>
         <dependency>
            <groupId>com.ibm.icu</groupId>
            <artifactId>icu4j</artifactId>
            <version>3.8</version>
         </dependency>
      </dependencies>
   </profile>
</profiles>
 

Currently, the 4.0 version is not available in the central Maven repo, but 3.8 seems to work just fine.

Summary

Using Jasypt, it's actually quite easy to use encrypted values in your property files. In a Spring-based application, it's simply a question of replacing the existing PropertyPlaceholderConfigurer with the Jasypt encrypting equivalent, plus two more beans providing encryption and configuration. Choose how to provide the encryption password, and you're set to go.

If running on Java5 or lower, you'll also need to add ICU4J to your classpath, for the encryption scripts as well as your build and deployment environment.

References

• http://jasypt.org
• http://www.springframework.org
• http://icu-project.org/

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.

We turned to Ulrik Sandberg, one of the founders of the group.

Tell us how you got started with the Sweden Spring User Group.
The Sweden Spring User Group was started in early 2007. I had spoken to Rod Johnson at The Spring Experience 2006 about creating a user group for Swedish users, and he thought that was an excellent idea. We decided to use Google Groups as the tool for collabo- ration. Jayway would be our financial backup, since we wanted to provide the group members with first-class confer- ence facilities, as well as food and drink.

Which are your goals?
Our primary goal is to gather all Swedish Spring users in a community, in order to get a forum where you can ask questions and present ideas to peo- ple who share the interest for Spring. We also want to provide high-quality sessions when we meet. The sessions should be held by the community, but we also aim to get an external speaker from either Interface21 or other inter- esting companies related to Spring.

What have you been doing so far?
The first meeting was held in late March, in Stockholm. We managed to get Arjen Poutsma from Interface21 to hold a session about Duck Typing in the Spring WebServices framework. Before that, there had been an Introduction to Spring and a session about the Aspect- Oriented Programming (AOP) support in Spring 2.0. It was very crowded, and people really enjoyed the short break for beer and pizza.
The second meeting in early July was also in Stockholm. The main speaker at that event was Ben Alex from Inter- face21, the inventor of Spring Security, previously known as Acegi Security. He had come all the way from Australia and held a session about his Real Object- Oriented (ROO) framework. There was also a session about Spring JDBC and a very interesting case study about the use of Spring MVC at PriceRunner.
The third meeting took place in Malmö in late September. The guest of honor was Jonas Bonér from Terracotta. He talked about how easy it is to clus- ter Java applications using Terracotta. There was a session about Spring and Mule, as well as a session about Declara- tive Caching Using Spring.

So what is your final message to the readers?
In short, the Sweden Spring User Group arranges high-quality mini-con- ferences about Spring and related tech- nologies four times a year. For free. You should join us.

Ulrik Sandberg, Björn Granvik

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