MemeStorm

Testing Java Persistence API (JPA) Entities Outside the Container

Jon — Mon, 06 Nov 2006 22:22:53 +0000

When I wrote about the Java Persistence API (JPA), Spring and Eclipse Web Tools Platform (WTP) I neglected to show how easy it was to test our JPA entities.

Traditionally, testing EJBs outside of a container was an absolute pain. Testing JPA is embarrassingly easy, especially with Spring doing all the heavy lifting. You’ll have no excuse to write your integration tests now..

Our goal

Our goal here is to test or DAO class, MyDAO, shown here. This can be used as the basis of larger integration tests for example. Here are some of the issues in setting up a test, which we’ll neatly sidestep later:

We need to set up the entity manager, hopefully just once as this is time consuming.
We need to handle the automatic dependency injection. Remember that this DAO can run on a server, where it expects the entity manager to be automatically injected.
We need some kind of transaction management. Ideally we don’t want to start and commit transactions in every test method. DRY!
A popular way of testing code that interacts with databases these days is to start each test with a transaction, and then after running the test, roll back the transaction so that any database changes aren’t actually committed. This leaves your database in an orderly state.
Ideally we’d like access to JDBC too - just to check our JPA stuff is doing its thang.
We may need to handle class instrumentation when using JPA

How to do it

Well, I’m going to show you some code that does all of the above. You’ll be shocked at how little I have to do:

import org.springframework.test.jpa.AbstractJpaTests;

public class MyDAOTests extends AbstractJpaTests {
    MyDAO myDAO;
    @Override
    protected String[] getConfigLocations() {
        return new String[] {
                "/com/memestorm/service/jpa/applicationContext.xml",
                "/com/memestorm/service/jpa/applicationContext-jpa.xml"
        };
    }

    public void testInsertUser() {
            Collection users = getMemeService().getUsers();
            int found = users.size();
            User u = new User("test", "test");
            getMemeService().addUser(u);
            users = getMemeService().getUsers();
            assertEquals(found + 1, users.size());
    }

    // More tests... then

    public MyDAO getMemeService() {
            return myDAO;
    }
}

I’m sorry, did you blink? Go read that again. Isn’t that neat? Let’s look at what’s happening:

Obviously the getConfigLocations() method points to our application context configuration files (I’m using the same ones as in the previous blog entry). Spring uses this to establish the entity manager, database connections etc. It does this once, and all the tests methods use the results.
Spring automatically injected the dependencies. Did you see that myDAO variable and its setter? Spring managed that itself.
Spring automatically starts a transaction for every test method and rolls it back afterwards.
Spring silently handles all class instrumentation.

Now you have no excuses for writing your own tests. You are positively coddled by AbstractJpaTests.

Adding a few features

AbstractJpaTests provides a lot of additional functionality.

JDBC

Sometimes you want to incorporate some JDBC too. Here’s a method that does so:

public void testInsertUserSQL() {
    Collection users = getMemeService().getUsers();
    int count = jdbcTemplate.queryForInt("SELECT COUNT(*) FROM USER");
    assertEquals(users.size(), count);
}

Easy huh? The jdbcTemplate is set up for you in one of the superclasses.

Transactions

You don’t have to wait until the method ends to end the transaction. You can optionally call the method endTransaction() if you like. By default, this will force the rollback of the transaction—remember that’s what typically happens automatically for you at the end of each test method.
If you want the transaction to actually commit for a particular test method, then call the setComplete() method. This sets a flag, read in the endTransaction() method, to tell the test harness to commit instead of rollback. More complex operations can be carried out too, for example you can end a transaction in a test method, and in the same method begin a new one by calling startNewTransaction(). Check out Spring’s AbstractTransactionalSpringContextTests for all of this support.

Entity Manager

You can also get access to the entity manager. Here’s an example that uses some of JPA’s Query interface:

public void testNamedParameter() {
  User us = new User("test","last");
  getMemeService().storeUser(us);

  Query q = this.sharedEntityManager.createQuery(
         "select u from User u where u.firstName = :name");
  q.setParameter("name", "test");
  User u = (User) q.getSingleResult();
  assertEquals(u.getFirstName(), "test");
}

As you can see, the exposed sharedEntityManager is the entity manager attached to the current transaction.

Caveats

Say you have a User class that’s in a ManyToOne unidirectional relationship with a Building class, like this:

@Entity
public class User {
    /* Unidirectional */
    @ManyToOne
    @JoinColumn(name="bldng_id")
    Building building;

    // ..
}

Imagine we write a test case, like this:

public void testBuilding() {
    User u = new User("test","test");
    Building b = new Building();
    b.setName("BuildingA");
    u.setBuilding(b);
    getMemeService().addUser(u);
    **//getMemeService().addBuilding(b);**
}

Here we’ve made a mistake and didn’t persist the building object (it’s required - it’s not cascaded after all). What will happen when you run this test?

Well, the green flag will be raised high, unfortunately. Say we changed the test like so:

public void testBuilding() {
    User u = new User("test","test");
    Building b = new Building();
    b.setName("BuildingA");
    u.setBuilding(b);
    getMemeService().addUser(u);

    Collection usersAfter = getMemeService().getUsers();
}

If you run this test, you’ll get an exception

java.lang.IllegalStateException: During synchronization
a new object was found through a relationship that was
not marked cascade PERSIST.

In other words, the getUsers() method, which simply does em.createQuery("SELECT user from User user").getResultList(), results in the persistence context realizing that there is indeed an object that should have been persisted.

My point is this: I’ve added the final test line there for no good reason, but it’s caught a bug in my persistence logic. That’s a bit ugly - I wish there was some way in which I could force the O/R tool to do some kind of “spot consistency check” to help me out. Hopefully if we have enough tests in our service layer going through to the DAO layer, it’ll catch these types of things. Perhaps Andy over at the excellent Disco Blog will be kind enough to point the way one day

Java Persistence API (JPA), Spring and Eclipse Web Tools Platform (WTP)

Jon — Mon, 30 Oct 2006 14:52:23 +0000

It’s time to add some persistence to our talks. I spent a good two hours trying to get Spring, JPA and Eclipse to play along. Here’s what I eventually did…So our goal is to create a project that I can run from within Eclipse, or deploy to something like Tomcat or an application server. It uses HSQLDB, though you can obviously change database, and Toplink Essentials (though you can obviously change JPA provider too). I use Tomcat 5.5.20 here. Oh, and Spring 2.0. All of the necessary software libraries (besides Tomcat) can be found bundled in the full Spring 2.0 distribution. I don’t use all of Spring’s JPA utilities either - I tried to stick to generic JPA stuff.

Our JPA Code

The only tricky part is setting up the application context for JPA’s entity manager factory. After that it’s plain sailing, writing nice JPA code. Here’s an example of one of the beans in our model:

@Entity
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    private Integer id;

    String firstName;
    String lastName;

    @OneToOne
    @JoinColumn(name="pwd_id")
    Password password;

    @ManyToOne
    @JoinColumn(name="bldng_id")
    Building building;

    @OneToOne(mappedBy="owner")
    Cup cup;

    // omitted getters and setters
}

It’s a POJO, appropriately annotated. In this case we have some extra OneToOne (unidirectional), ManyToOne (unidirectional) and OneToOne(bidirectional) relationships, but feel free to omit them. This is pure POJO and JPA - there is no Spring in here at all.

That’s the kind of code we want to write for our domain model, so what about our DAO code? Here’s our full DAO:

@Transactional
public class MyDAOImpl implements MyDAO {

    private EntityManager em;

    // Spring will inject this:
    @PersistenceContext
    public void setEntityManager(EntityManager em) {
        this.em = em;
    }

    public Collection getUsers() {
        return em.createQuery("SELECT user from User user").
             getResultList();
    }

    public User loadUser(int id) {
        return em.find(User.class, id);
    }

    public void addUser(User user) {
        em.persist(user);
    }

    public Cup getCup(int id) {
        return em.find(Cup.class, id);
    }

}

This is pretty straightforward. The only Spring dependency we have here is the @Transactional, and that’s because I wanted Spring to make all the methods transactional and avoid writing blobs of repeated code. Notice the standard @PersistenceContext annotation. Spring will magically fill this in for us - it acts like a JPA container.

I like this code. It’s all neat, with minimal dependencies. Let’s look at how to wire it up to work with Spring.

Spring’s Application Context

I’ve created an applicationContext-jpa.xml configuration file for all the JPA stuff. It’s all pretty obvious once explained, I think…Here are all the bits with commentary:

First we set up a nice little property configurer, so you can just modify jdbc.properties to change the database:

Now a simple datasource:

Now for the meaty bit:

Now the important bit is the type of Spring entity manager factory you choose, and the weaver. Many JPA implementations (not all) require a runtime weaver of some kind. I had real trouble getting things to work with the SimpleLoadTimeWeaver in Eclipse. I suspect class loading errors were causing the problem. I ended up with the InstrumentationLoadTimeWeaver which requires that you start your Java VM with an additional argument:

-javaagent:/Java/workspace2/spring/dist/weavers/spring-agent.jar

To do this in Eclipse, hit “Run”, then “Run…” - select your server (for example, “Tomcat 5.5 Server”), hit the “Arguments” tab and insert the above in the “VM Arguments” box.

Some of the other weavers require me to modify Tomcat (by adding a context.xml file for example) to make Tomcat use Spring’s weaver - but I could not figure out how to do this with WTP - WTP provides no way for me to set this.

Moving on:

Here we create a simple transaction manager, and tell Spring we want to use its declarative @Transaction management.

This makes Spring perform the magic @PersistenceContext/@PersitenceUnit injection:

Finally, we can declare our DAO:

Note that we don’t specify the entity manager as a dependency. The bean post processor above will sort that out for us.

That’s it, we’re done! In the end, there wasn’t too much to it except for the wrangling with the various weavers and entity managers. Ben Hale provides a similar writeup though I got the same org.springframework.dao.InvalidDataAccessApiUsageException exceptions as some of his readers.

Download

The full source for the application is here. As usual, it assumes that you have the full Spring distribution unpacked in a sibling directory. Run the libraries Ant task to transfer the dependencies, and the server.sh in the db directory to start the database. I’ve run this within Eclipse (3.2.1) WTP (1.5.1) successfully, and deployed as a WAR to Tomcat 5.5.20.

springjpa.zip

Technorati Tags:
Spring Framework,
JPA

Session-scoped Beans in Spring 2.0

Jon — Tue, 10 Oct 2006 13:58:00 +0000

Spring 2.0 introduces a new way of scoping beans. We’ve spoken about singleton scoped beans in the past and there are factory beans too. Now there are session, request and other types of bean scopes. As you might imagine, a Spring bean scoped to the sessions means that it lives as long as the session. This means that if you ask Spring’s IoC container for a bean that is session-scoped, it will instantiate it once only for that particular user’s session—different users in different sessions will get their own bean instances. It gets even cooler if you set this bean as a dependency for another bean that is a singleton. It still works, but in this case Spring injects a smart proxy to handle the dynamic bean swapping (the container bean will get a different dependent bean depending on the session). All of this magic is dead simple to implement and use.

How to do it

Let’s look at how to create a simple session-scoped bean that can be retrieved from the context. If you are using a DispatcherServlet (which you will be if you are using Spring’s MVC) then all you need to do is tag the bean as session-scoped in your application context configuration file. For example:

  scope=”session”/>

Not much to do…as you’ll see, the only difference is the session attribute. If you aren’t using the DispatcherServlet then you’ll need to add a (small) bit of extra configuration to web.xml:

  
    org.springframework.web.context.request.RequestContextListener

You need to do this because of the mechanics of how this is implemented, which we’ll look at later. For now remember that if you’re already using Spring’s MVC, you don’t need to do anything. The bean, MyBean is nothing special—here’s the one we use:

    public class MyBean {
    	public MyBean() {
    		System.err.println("In Constructor!!!");
    	}
    }

So now that we’ve defined our bean in our context, how do we use it? Well, just like you’d use any other bean really! Here’s an example of a controller grabbing the bean from our application context:

 // retrieve context
 ApplicationContext ac = org.springframework.web.context.support.
   WebApplicationContextUtils.getRequiredWebApplicationContext(
                       request.getSession().getServletContext());
 // grab bean
 MyBean mb = (MyBean) ac.getBean("mybean");

This is what you’d do anyway. The key isn’t that you have change the way you program - but it’s the way Spring manages the creation of the bean.

What happens?

The bean (MyBean) won’t be created only once (a singleton) for all users—rather it will be created once for each user session. The magic is that it’s effectively tied to the user’s session (and created lazily as a result). Here’s a concrete use case used in the Spring documentation: User Preferences. If your user is logged on and you retrieve a session-scoped bean for the first time, it will be created. While the user is logged on (he has a session) that bean will remain effectively tied to the session so that if you access the bean again (from the context), it will simply retrieve it and not create it again.

You can test this with the supplied example. The index handler just tells me if the session is new (if it is, and you access the bean, you should expect a new instance to be created). The access handler actually tries to retrieve the bean from the context. You’d expect this to create the bean if the session is new, or simply just retrieve it if it’s not. The invalidate handler invalidates the session. Download the example and play - check the console to see the constructor message and when it appears.

More Advanced Work

Let’s look at the situation with dependencies. For example, imagine our session-scoped bean has a dependency on some singleton:

What happens now? Well, myotherbean will be created once with the context, and the same instance will be injected into each mybean instance that is created as each user creates a session. Neat huh? But I guess you’d expect that behaviour.

Even More Advanced Work

Let’s flip the injection described in the previous scenario. Imagine you have a bean that has a session-scoped bean as a dependency:

You’ll notice I had to do one surprising thing—it’s that magic AOP proxy incantation. Essentially the problem is this: if mybean is only created when accessed from a session, and multiple times for each different session, how do we know what to inject into yetanotherbean because yetanotherbean is a simple singleton created when the Spring context is created?

The answer is of course: it doesn’t and cannot know. So what we have to do is stuff in a proxy that behaves like the object (in fact it goes and grabs the object from the user’s session when you access it). Spring does all the heavy lifting for you in this case - all you need to do is add the scoped-proxy tag. This is pretty neat magic. I’ve included a download to a more advanced application that uses this approach too. Note that to do this proxying Spring needs cglib in the classpath.

Downloads

Simple: scopexample.zip
AOP dynamic dependency version: ascopexample.zip

Lazy bean instantiation in Spring 2.0

Jon — Sun, 04 Jun 2006 14:06:35 +0000

Spring 2.0 introduces a new way of instantiating beans defined in a
bean factory—lazily. Generally all singleton beans are
instantiated as one of the last things that a bean factory does. You
can now change this behaviour slightly and ensure that a bean factory
doesn’t instantiate your bean at all - until such time as it’s
requested for example.

How to do it

Simply use the new lazy-init attribute in your bean definition. For example:

lazy-init=”true” />
lazy-init=”false” />

Here turtle is defined to instantiate lazily, while fox will do so eagerly. In fact, we don’t need the lazy-init="false" attribute on fox at all - by default things are not lazy.

What happens?

Well, if these beans were defined in your application context then the fox bean will be created as usual (eagerly, as a singleton), but the turtle won’t be. That’s almost all there is to it. Of course, if your Java code tries to grab the bean from the context it will be instantiated at that time:

 FooF = (FooF) context.getBean("fox");

There is a caveat. If turtle was defined as dependency of fox, then of course the context will ensure that turtle is created eagerly too. It’s the only way to satisfy the constraint after all. So for example, here both beans will be created eagerly even though one is marked as lazy:

lazy-init=”true” />
depends-on=”turtle” />

A possible use

I found a possible use in the petclinic application distributed with Spring. Here it is in a nutshell. Say you have two beans, in this case implementing specialized functionality:

Now say one of these classes will be used somewhere, say as the target of an transaction intercepter:

Now it should be clear to you. If, in my properties file, I set petclinic.jdbcImplBeanName=hsqlClinic, then the hsqlClinic bean will be used. Moreover, the mysqlClinic bean won’t even be instantiated. This nicely externalizes the configuration. To switch implementations, merely change the property to mysqlClinic.

How does it work?

You don’t have to know this, but here’s how the magic happens. The essential difference is in the preInstantiateSingletons() method in DefaultListableBeanFactory. This is the magic method that pre-instantiates all singletons defined in the bean factory. All that’s changed here, is that it ignores the bean if the lazy-init is set to true:

for (Iterator it = this.beanDefinitionNames.iterator(); it.hasNext();) {
  String beanName = (String) it.next();
  if (!cacheContainsSingleton(beanName) && containsBeanDefinition(beanName)) {
    RootBeanDefinition bd = getMergedBeanDefinition(beanName, false);
    if (!bd.isAbstract() && bd.isSingleton() && !bd.isLazyInit()) {
      ….do instantiation work and put result in cache….
    }
  }
}

ioc lazy

Basic Spring Web services with XFire and JSR 181

Jon — Wed, 31 May 2006 02:13:49 +0000

I hadn’t intended to expose any of our functionality with Web services so soon, but that’s the great thing about Spring—many of the services are orthogonal to each other. Let’s look at how we can expose some Spring beans as Web services. We’ll do it using JSR 181 too, which means that the Web service implementation is so easy that even a Ruby hacker could write it…;-)

Web Services and JSR 181

Look here for an introduction to JSR 181 and where it fits in to the world of Web services. You need not though, as it’s pretty simple. First, let’s define the interface to our simple Web service:

package com.memestorm.ws;

import javax.jws.WebService;

@WebService( targetNamespace = “http://memestorm.com/skeleton1/AuthorService” )
public interface AuthorService {

	public String sayHello();

}

That’s it. Note the nice @WebService annotation. It’s all that’s really necessary. I threw in the targetNamespace attribute to show how you can modify things. The system will automatically generate a WSDL file - and using these attributes (and others) you can modify the generated WSDL. Now that we have the interface, let’s implement it!

package com.memestorm.ws;

import javax.jws.WebService;

@WebService(
  serviceName = "MyAuthorService",
  endpointInterface = "com.memestorm.ws.AuthorService"
)
public class AuthorServiceImpl implements AuthorService {

  public String sayHello() {
    return "Hello World Services!";
  }
}

Oh my, that was easy….There’s nothing to say, except:

Do you see how there aren’t any external dependencies in this code? The only thing I import is the annotation…this is cool…
This is just a POJO - which we’ll be defining in a Spring context file. So we can easy wire it up with other beans using IoC.
This is an example of CoC again—you don’t have to do much other than write @WebService.

Okay, now that we’ve written our Web service - and you can write as many as you like of course, let’s look at how to wire it all together.

Hooking XFire into your Spring Application

I used XFire as the Web services stack here. It implements some nice things that I don’t find in Apache Axis, such as the JSR 181 stuff, multiple XML binding mechanisms, multiple transports (including Jabber & JMS) etc. You only have to hook it into your web application once. After that, simply create your POJOs and expose them. What you need to do is:

Create the XFire Spring context configuration file. It’s here that you expose your POJOs, and where you can wire in other Spring beans etc.
Modify the Web application web.xml to deploy the XFire servlet
Modify your build process to include all the right JARs

Let’s look at these in order.

1. XFire Configuration File

Now XFire’s pretty powerful. You can configure just about anything, and much of this you can do from the configuration file. It’s also where you expose your POJOs. The following file, xfire-servlet.xml, contains a little of both:

The lines in bold are the only ones that matter to us - it exposes our bean implemented by com.memestorm.ws.AuthorServiceImpl. The rest configures XFire to use annotations in the first place and sets up some defaults. You will want to come back here when you do more advanced stuff such as type mappings.

2. Configuring the XFire Servlet

As you’ve seen, we’ve got this xfire-servlet.xml context configuration file. You’ll want to tell Spring about it, and as we’ve shown before, you can do this by modifying the contextConfigLocation context parameter in web.xml:

 
   contextConfigLocation
   
     /WEB-INF/applicationContext.xml /WEB-INF/jdbcContext.xml
     /WEB-INF/xfire-servlet.xml

You also need to add the following lines:

   
     XFireServlet
     
       org.codehaus.xfire.spring.XFireSpringServlet
     
   
   
      XFireServlet
      /servlet/XFireServlet/*
   
   
     XFireServlet
     /services/*

That simply ensures that XFire is deployed as a servlet.

3. Build

XFire has an astounding array of dependencies - and you only need some under various circumstances. Here’s how I had to modify the build file to account for this:

Modify the master-classpath so that I had the right JARs in my path to compile everything:
```
 
   
 
 
   
 
```
Modify the libraries target to ensure all run-time JARs are available:
```
  


  
  
  
  
  
  
  
  
```

Okay, I admit there is a little pain here. But you only need to do this once of course, and you are deploying an awesome Web service stack that will bring you hours of pleasure…

4. Running it

That’s it though - grab the source below, run build, deploy, and you’ll have exposed the web service. The XFire servlet provides a nice way to view the deployed Web services too. If you go to http://localhost:8080/skeleton2/services/ you’ll see:

 Services:
  o MyAuthorService [wsdl]

with a link to the WSDL file. Viewing the WSDL file you’ll get the expected output:

xmlns:tns=”http://memestorm.com/skeleton1/AuthorService” xmlns:wsdlsoap=”http://schemas.xmlsoap.org/wsdl/soap/” xmlns:xsd=”http://www.w3.org/2001/XMLSchema” targetNamespace=”http://memestorm.com/skeleton1/AuthorService”>
  
    
      
        
      
      
        
          
            
          
        
      
    

……

  MyAuthorService“>

Nice huh? No hassle Web services…

A Client

Okay, here’s a client that you can run against the Web service. Read the XFire documentation to learn more about it if you like:

package com.memestorm.ws.client;

import org.codehaus.xfire.service.Service;
import org.codehaus.xfire.client.XFireProxyFactory;
import org.codehaus.xfire.annotations.AnnotationServiceFactory;
import com.memestorm.ws.*;

import java.net.MalformedURLException;

public class Test {
	public static void main(String[] args) {
		Service serviceModel = new AnnotationServiceFactory()
				.create(AuthorServiceImpl.class);
		try {
			AuthorService service = (AuthorService) new XFireProxyFactory().create(
					serviceModel,
					"http://localhost:8080/skeleton1/services/MyAuthorService");
			String s = service.sayHello();
			System.out.println(s);

		} catch (MalformedURLException e) {
			e.printStackTrace();
		}

	}
}

Summary

What we’ve done here is set up a scenario where you can easily expose POJOs as Web services using JSR 181 standard annotations. These are standard annotations that you’ll find in Java EE 5 - so it’s pretty nice to be able to use them here in the XFire Web services stack.

Moreover, this scenario is hooked into our Spring web application. We can trivially add additional POJOs, and use the full Spring toolbox to manipulate them.

Download

Here’s a JAR of all the source, with instructions on how to build and deploy:
skeleton2-1.zip

Acknowledgements

I’d like to reference the Logemann Blog that showed me how to do most of this stuff.

Spring Components - XML configuration on steroids

Jon — Thu, 30 Mar 2006 04:44:34 +0000

The single most important feature in Spring 2.0 (IMO) is a new XML
configuration convenience feature. I believe this is going to
revolutionize the way people develop for Spring and bootstrap a modest
component market too. This is a lot more than a convenience features
- it’s a fledgling component model too.

In the ‘old’ Spring configuration files, almost everything was a bean. That is, you would write:

In fact, if you look at the DTD you’ll see why:

In Spring 2 (I’m using M3) you can do something altogether different:

Note that there is no class attribute - all the necessary information is captured behind the namespace. If you look at it from an XML configuration point of view, what this provides is a way of avoiding laboriously repetitive bean definitions by capturing beans in their own namespace. Spring comes with a number of these already defined:

However, now think of the possibilities:

You can simplify configuration (as we’ve just seen)
You can hide implementation (all the ‘user’ needs to see is the namespace)
You can start distributing ‘Spring Components’ that folk can simply plug in by adding the JAR and referencing them from your application context!

I think it’s the last two points that are the most exciting. They’re perhaps not what the Spring developers intended, but they are the start of something new. You can now distribute a simple JAR that contains all your Spring beans that do something, say interface with Amazon, together with an XML schema describing those beans that you want to make public. Any user of this ‘Spring Component’ simply installs this JAR and starts typing:

You can even bung view tier stuff into beans, so the future is wide open.

How to do it

Let’s look at how you can roll your own component, resulting in a
simple JAR that you can distribute. See the attachment for a deployable
example: simple.jar. If this is in your application’s classpath, for example deployed in WEB-INF/lib then at the end of the day, all you need to do is wire it into your application context.

Wiring in the component

 xmlns:memestorm=”http://www.memestorm.com/schema/simple”
    xsi:schemaLocation=”http://www.springframework.org/schema/beans
     http://www.springframework.org/schema/beans/spring-beans.xsd
    http://www.memestorm.com/schema/simple
     http://www.memestorm.com/schema/simple/spring-simple.xsd”>

Notice that I’m using the XML Schema version of the bean configuration instead of DTD, and that I’ve defined my memestorm component as a namespace mapped to http://www.memestorm.com/schema/simple. We’ll later see how this name space gets mapped to a bean.

Coding the component

That’s it as far as the client goes. Just add the JAR and wire it in. Let’s look at the implementation. Instead of an Amazon component, we’ve written a rather simpler Simple component:

package com.memestorm.beandemo;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

public class SimpleBean {
   private String value;
   private String otherValue;

   Log logger = LogFactory.getLog(getClass());

   public SimpleBean () {
      logger.error("In the constructor of SimpleBean");
   }

   public void action() {
      logger.error("In action with value='" + value + "' and otherValue='" + otherValue + "'");
   }

   public String getValue() {
      return value;
   }

   public void setValue(String value) {
      this.value = value;
   }

   public String getOtherValue() {
      return otherValue;
   }

   public void setOtherValue(String otherValue) {
      this.otherValue = otherValue;
   }
}

As you can see, it has two properties (value, otherValue) and its constructor and action() method both log messages. (So to use the component, you need commons-logging in your app!)

Defining its XML interface

As you saw in the wiring, the XML interface is defined by an XML schema. So we need to define an XML schema that should be adhered to by clients of our component. Here is one we created, simple.xsd:

As you can see, it simply permits two attributes to an element called action. Look back to ‘Wiring in the component’ and you’ll see it all fits together.

The Namespace Handler

Behind the scenes, Spring invokes a namespace handler to create the actual bean instance from something like:

As a component developer, you have to supply this namespace handler. Here is our implementation:

package com.memestorm.tag;

import org.springframework.beans.factory.support.BeanDefinitionBuilder;
import org.springframework.beans.factory.xml.AbstractSimpleBeanDefinitionParser;
import org.springframework.beans.factory.xml.NamespaceHandlerSupport;
import org.w3c.dom.Element;
import com.memestorm.beandemo.SimpleBean;

public class SimpleNamespaceHandler extends NamespaceHandlerSupport {

  public SimpleNamespaceHandler() {
    registerBeanDefinitionParser(”action”, new SimpleBeanDefinitionParser());
  }

  private static class SimpleBeanDefinitionParser extends
      AbstractSimpleBeanDefinitionParser {

    protected Class getBeanClass(Element element) {
      return SimpleBean.class;
    }

    protected void postProcess(BeanDefinitionBuilder definitionBuilder,
        Element element) {
      definitionBuilder.addPropertyValue(”otherValue”, “fromPostProcess”);
      definitionBuilder.setInitMethodName(”action”);
    }
  }
}

Note that the constructor registers a bean definition parser, associating it with an element. You’ll later see how we map the namespace to the element. The bean definition parser itself is pretty simple. getBeanClass() should return the appropriate class - as you can see we return SimpleBean.clas. We also have a postProcess() method that you can use to add to the parsed bean definition. In this case we set another property value and we set the init-method to be invoked. What’s happening behind the scenes here, in AbstractSimpleBeanDefinitionParser, is that the XML snippet is parsed and all of its attributes (and values) are mapped to setters of properties on the bean instance (except for id). In other words, its programmatically creating the bean definition and its properties according to the values defined in the application context.

Packaging

To package everything, simply include all the XSD files, beans, and namespace handlers into a JAR with two special files in the META-INF directory. First you need spring.schemas:

http://www.memestorm.com/schema/simple/spring-simple.xsd=com/memestorm/tag/simp
le.xsd

As you can see, this maps the namespace location to the physical location of the schema in the JAR. Next, you need spring.handlers:

http://www.memestorm.com/schema/simple=com.memestorm.tag.SimpleNamespaceHandler

As you can see, this maps the schema namespace to the tag handler. That’s it.

Summary

In summary then:

Create the XML schema defining your component
Create your component bean/beans
Create a namespace handler that maps the schema to the beans
Create two packaging artifacts to tie it all together

Download

Here’s a deployable JAR with source (of course, you need to deploy to a Spring 2 M3 application, with commons-logging available too).

simple.jar

configuration ioc

Convention over Configuration in Spring’s MVC

Jon — Fri, 17 Mar 2006 18:13:06 +0000

Convention Over Configuration (CoC) is a term often bandied
around by Ruby on Rails followers. From the wikipedia it’s
defined as “the programmer only needs to specifically configure what
is unconventional.” Very sensible advice indeed, although it’s not without its problems. We’ve already
seen one example of CoC in Spring: the use of
InternalResourceViewResolver effectively lets programmers
forget about configuring resource views for incoming URLs, and instead
rely on the convention of mapping to a like-named view (it extracts
the view name from the URL). In fact, the MultiActionController is a type of CoC too - you don’t have to configure an action name; Spring tries to automatically invoke a like-named method on the controller class based on the URL. (The MethodNameResolver actually.) These two essentially enforce the convention of automatically selecting a view, and a method in a controller class respectively.

Now let’s look at a third example of CoC: ControllerClassNameHandlerMapping. This enforces the convention of automatically selecting a controller.

Background

As shown in Simple URL Mapping…, a URL Mapper has to map incoming URL requests to particular controllers. Typically we have to configure the URL mapper with each new controller that we add. Turning this on its head, we want to use CoC so that the convention is that the correct controller is automatically selected if it’s registered, without any configuration.

How to do it

Simply use the ControllerClassNameHandlerMapping as your URL mapper in your dispatch-servlet.xml configuration file. For example:

Define your controllers as usual. For example, I have this:

That’s it. You don’t have to wire your controllers to URLs, this is now automated. Now instead of explicitly configuring mappings between URLs and controllers, you can rely on the convention, which is to take the ClassUtils.getShortName() name of the controller class, remove the “Controller” suffix if it exists and the cap, and use the result as a mapping. For example our CommandController would be mapped to /command/.

For MultiActionController controllers (see our recent example) it works slightly differently. In this case, say for our DispatchController example, it will map /dispatch/* to the controller. (Note the extra wildcard).

Now you can concentrate on writing your controllers and action methods. Everything will be automatically wired in; nice.

How it works

It’s actually dead simple. The ControllerClassNameHandlerMapping class simply iterates through the application context looking for beans of type Controller, adding them to the mapping as described earlier.

Acknowledgements

Thanks to Matt for highlighting this class.

Spring Binding and Validation: Introduction

Jon — Mon, 20 Feb 2006 14:03:17 +0000

You want to slurp in some data, perhaps from a simple form or from
request parameters. To do this, we’ll explore the AbstractCommandController and learn about the related issues of binding and validation. Spring makes this kind of thing pretty effortless, and this will serve as the foundation of exploring more advanced form-handling.

How to do it

The controllers we wrote about in previous blog entries, such as the MultiActionController, are generally used for carrying out actions. What if you wanted to rather input some data first, perhaps through request parameters? Well one way to do this is the hard way:

String val = (String) request.getParameter("someParamName");

Those were the days. Untyped, inflexible, error-prone, with all sorts of casting (imagine if I wanted a date or an integer).

A much better approach use data binding - let Spring bind the incoming data to a Plain Old JavaBean (POJO) for you - then you can simply use that POJO as you’d expect. Spring calls these beans commands, which I think is a bit of a misnomer, but there you go. Let’s see this in action. First, we’re going to modify our dispatch-servlet.xml configuration file to include a new controller:

Now let’s modify our handler mappings (see previous blog entries if you need to understand these) to include a mapping to our command controller:

/cmd=commandController
/*=dispatchController

So in theory now, something like http://localhost:8080/send/cmd?age=10 will get sent to our command controller. Now the command controller we’ll use is the simplest around. It extends the AbstractCommandController. Here’s the code:

public class CommandController extends AbstractCommandController {

  public CommandController() {
    setCommandClass(SimpleCommand.class);
  }

  protected ModelAndView handle(HttpServletRequest request,
		HttpServletResponse response, Object command,
                BindException errors) throws Exception {

    SimpleCommand cmd = (SimpleCommand) command;

    PrintWriter pw = response.getWriter();
    pw.println(cmd);
    return null;
  }
}

The first thing you’ll notice (probably because I have it in bold) is that the constructor calls setCommandClass() with the class that will hold the incoming values. This is the command class I spoke about earlier. All incoming parameters are mapped onto this class, automatically, for you. We pass the setCommandClass() the class so that it can instantiate a new instance every time the controller is invoked. Now take a look at the handle() method, somewhat more complicated than the others that we’ve seen in Basic Spring Web MVC Example. The two extra parameters are the command (which Spring will have created and populated for you), and an object listing errors (which we’ll describe later).

The method is pretty simple: It casts the command object to the expected type, and then writes it to the response. Let’s look at the command object:

public class SimpleCommand {
 Integer age;
 String name;

 public String getName() {return name;}

 public void setName(String name) {this.name = name;}

 public Integer getAge() {return age;}

 public void setAge(Integer age) {this.age = age;}

 public String toString() {
   return "Name=[" + this.name + "], Age=[" + this.age + "]";
 }
}

You must admit, that’s pretty straightforward. A typed container, just ready to be populated by incoming values. Now, if you invoke something like http://localhost:8080/skeleton3/send/cmd?name=Jon&age=30 you’ll see the output as Name=[Jon], Age=[30]. This is pretty darn nice for a number of reasons:

Notice that I didn’t write any code to bind the incoming parameters to the command bean. It’s automatic.
Notice that the command bean is typed - getAge() returns an Integer and somehow Spring converted the incoming field to the appropriate type automatically.

This is a considerable step up from getRequestParameter(). It even works for a form input. For example, here is a simple form that you can use to invoke our controller:


 Name: 
 Age:

But wait, there’s more! If we extend our handler() method to dump some information found in the errors parameter, we’ll see further magic:

pw.println("" + "Error count=" + errors.getErrorCount());
pw.println("
Errors for age field"  + errors.getFieldErrors("age"));
pw.println("
Input value for age field: " + errors.getFieldValue("age"));
pw.println("
" + errors.getGlobalErrors());

Now if we invoke it with an error in the age value (for example, some letters instead of digits) as in: http://localhost:8080/skeleton3/send/cmd?name=Jon&age=crikey we’ll see the following output:

Name=[Jon], Age=[null]
Error count=1

Errors for age field[Field error in object 'command' on field 'age': rejected value [crikey]; codes [typeMismatch.command.age,typeMismatch.age,typeMismatch.java.lang.Integer,typeMismatch]; arguments [MessageSourceResolvable: codes [command.age,age]; arguments []; default message [age]]; default message [Failed to convert property value of type [java.lang.String] to required type [java.lang.Integer] for property 'age'; nested exception is java.lang.NumberFormatException: For input string: "crikey"]]

Input value for age field: crikey

Now notice that the age value is null (it can’t convert ‘crikey’), notice that we have an error count, that we have access to the original text that the user entered, and we have a good error message too. That’s a lot of magic for very little effort.

But wait, there’s even more. With a simple change to the constructor, we can validate input values too. Here is an example modification:

public CommandController() {
  setCommandClass(SimpleCommand.class);
  setValidator(new Validator(){
    public boolean supports(Class clazz) {
      return (clazz.equals(SimpleCommand.class));
    }
    public void validate(Object command, Errors errors) {
      SimpleCommand incoming = (SimpleCommand) command;
      ValidationUtils.rejectIfEmpty(errors, “age”, “required.age”);
      if (incoming.getAge() != null && incoming.getAge() > 30)
        errors.reject(”over.the.hill”, “too old”);
   }});
}

As you can see, we’ve set a validator. A validator simply implements the Validator interface—here we’ve done it with a simple anonymous class. You can instead write full classes for the validators and wire them in with the web context instead - in that way you can promote some reuse with your validators too. The validator interface has two methods. supports() tells the system what kind of class it validates. The validate method performs the actual validation. We make use of ValidationUtils to ensure that the age is not empty. You can, instead, write your own validation as we do checking that the age is not too high. So now, if we pass in an age of 34 say, we’ll get the following output:

...
[Error in object 'command': codes [over.the.hill.command,over.the.hill]; arguments []; default message [too old]]

There is in fact a little more magic too (message interpretation) but that will have to wait for another day.

Loading resources from files or the classpath

Jon — Sun, 19 Feb 2006 18:48:07 +0000

You want to load resources from the file system or classpath from
within beans initialized by a Spring context.

Background

Our HSQLDB utility class needs to load the SQL to create the database every time our application starts, as outlined in a Embedded Database Starting Up With Web Context. How does this bean get access to the file? Well, in the context configuration we supplied a file location, for example:


  ResourceLoaderAware interface.  This will then ensure that the setResourceLoader(ResourceLoader resourceLoader) method will get called on your bean, with a magic resource loader. (Look here for more information on the aware interfaces.)
The ResourceLoader

class is a fantastic utility class provided by Spring, that allows you

to load resources from all sorts of locations.  Given the location above, the resource loader will look for the file db/init.sql relative to the root of the web application (when used from a web context).  Our bean simply uses the location as follows:
Resource sql = this.resourceLoader.getResource(this.location);
JdbcTemplate jt = new JdbcTemplate(this.dataSource);
jt.execute(IOUtils.toString(sql.getInputStream()));

It’s so simply it belies how easy this makes life!  To load from an arbitrary file location, use the file: prefix instead.  For example,  file:///temp/foobar.sql.  You can also try and locate something in the classpath using the classpath prefix.  For example, classpath:config.xml.  
Have fun.
config  utils

Use Spring’s bean lifecycle callback methods to control your destiny

Jon — Sun, 19 Feb 2006 18:12:20 +0000

You want to run an initialize or destroy method on a bean after the context creates it. These lifecycle methods allow you to grab and release resources.

How to do it

Well, we did this in the previous blog entry, making use of an ApplicationListener and InitializingBean. This was overkill! There’s a better way that doesn’t require these interfaces. To have a method execute after the bean is initialized, or just before it’s destroyed (ie. at context start up or shutdown), simply modify your configuration file as follows:

init-method=”initialize” destroy-method=”destroy”>

You can of course omit either one, or both, of these attributes. The values of the attributes indicate the method that should be invoked. So for example, given the above definition the initialize() and destroy() method of the HSQLDB object will be invoked. This is great, and avoids any dependence on Spring interfaces.

If you’d like the same functionality relying on interfaces instead, then simply have the class implement InitializingBean and DisposableBean instead. In this case the configuration file will not have a init-method or destory-method attribute.

ioc