Amazing!

Today, I found my own blog useful.  I was configuring Spring validation on my new project, and had to remind myself how to do it.  We configured validation on the new project in less than an hour, which beats the two days it took me to work out how to do it the first time.

And I impressed one of my new work collegues.  Apparently I am now the Spring Guru.  Oooops.

AOP Caching

Today I would like to document my experiences implementing caching with Aspect Oriented Programming (AOP) and annotations. 

Background context
 
Caching may need to be implemented in your application for a number of reasons. OK, actually usually only one: performance. I would like to add my own tuppence-worth to this though - if you can get away without caching (specifically in application that provide the ability to view and change data) then do so, unless you are using a cache implementation that will handle as much of the pain as possible for you. Implementing a home-grown cache from scratch is almost never the correct thing to do in my experience, you spend lots of time debugging and tweaking the cache when you should be working on your day-job, not re-inventing something that someone, somewhere, has already done a perfectly good job of

The example I'm about to show you is for a web application created to let users read and edit values from a database (not an unusual scenario!). 

Application Architecture
 
The application architecture I have assumed for this example is: 
Java 1.5, JSP, Spring MVC (2.0.1), Spring JDBC (2.0.4), running on Tomcat 5.5, connecting to a database (RDBMS type not important for this example). 

OSCache
 
A third party library, OSCache, provides the underlying cache for the application. This was chosen because it provides a simple solution which is easy to integrate into our Spring MVC layer and also provides JSP-level caching should we need it later. 

The application uses OSCache in a very basic way. Caching could've been implemented with a HashMap and it wouldn’t have provided much less functionality (the way I'm using it), but by using OSCache we can using the "group" functionality (which allows us to cache against a key AND a group name, so we can flush and reload a whole group if necessary), and we can potentially add timeouts and other more complex functionality simply with configuration changes. See the OSCache documentation for full details. 

CacheManager 
Primarily to aid unit testing, but also to provide some separation between the application and the implementation of the caching mechanism, a CacheManager interface was implemented, and the implementation version simply wraps the OSCache GeneralCacheAdministrator. 

Aspect Oriented Programming for Caching
 
If caching is implemented in a very simple way, it can be easy to forget to handle caching on all methods that require it. Also, the code to check something is in the cache and retrieve it from the database and store it in the cache if it is not, is standard for most functions. Therefore it seemed to make sense to implement caching using Aspect Oriented Programming, so it can cut across all functionality without it having to be explicitly declared in every method that might need to utilise the cache. 

Spring has built-in support for AOP (and that documentation also provides a good introduction to what AOP is), so given our use of Spring MVC it shouldn't be too complicated to add Aspects to our code. 

Implementation: Application Context file
 
You need to add a couple of things to the application context file for your app to set up the cache and enable the AOP. 

<!-- Initialisation for Caching -->
<!-- the actual cache -->
<bean id="cacheAdministrator"
    class="com.opensymphony.oscache.general.GeneralCacheAdministrator"
    destroy-method="destroy"/>

 

<bean id="cacheManager" class=" com.mechanitis.examples.cache.impl.CacheManagerImpl">
    <property name="cacheAdministrator" ref="cacheAdministrator"/>
</bean>

 

<!-- Magic to get the Spring aspectJ-style AOP working -->
<aop:aspectj-autoproxy />

 

<!-- Code that does the caching (the Aspect) -->
<bean id="cacheAOP" class="com.mechanitis.examples.aspect.CachingAspects">
     <property name="cache" ref="cacheManager" />
</bean>
   
<!-- End of Caching setup -->

Note that, like the validation, this makes use of schema-based configuration. 

Now these settings are in the configuration file, they should not need to be changed unless the cache provider is changed or caching is to be fundamentally altered. 

Implementation: Defining Items to be Cached
 
Originally I had the application "magically" caching anything returned from a “get” method in the service layer and purging the cache on any “save” or “update” method. 

However there are some types of objects that don’t need to be cached and cause errors when they do, as sometimes the data needs to be "fresh" from the database. So the service layer declares what needs attention from the cache manager by the use of annotations:

import com.mechanitis.examples.cache.Cache;
// ...more imports...

public class CustomerServiceImpl implements CustomerService {
private static final String CUSTOMER_CACHE_GROUP = "Customer";
private static final String BRANCH_CACHE_GROUP = "Branch";

private CustomerDAO customerDAO;

@Cache(groups=CUSTOMER_CACHE_GROUP)
public Client getCustomer(CustomerId customerId) {
return customerDAO.getCustomer(customerId);
}

@Cache(groups=CUSTOMER_CACHE_GROUP)
public ClientId saveCustomer(Customer customer, String username) {
return customerDAO.saveCustomer(customer, username);
}

@Cache(groups=CUSTOMER_CACHE_GROUP)
public void updateCustomer(Customer customer) {
this.customerDAO.updateCustomer(customer);
}

@Cache(groups={CUSTOMER_CACHE_GROUP,BRANCH_CACHE_GROUP})
public void saveCustomerBranch(CustomerBranch customerBranch) {
customerDAO.saveCustomerBranch (customerBranch);
}
}

You may notice that this service doesn’t really add much value – it forwards the request to the DAO and little else. The purpose of the service layer, however, is to provide a simple place for things like caching, and in future potentially additional security, logging, transactions, or to string together multiple calls to DAOs for a more complex transaction. 

The methods that return objects that need to be cached or that affect items in the cache are tagged with the @Cache annotation. The single argument to this is a list of the groups in the cache that the Object should be or already is associated with. This group allows selective flushing of the cache – so when a new Customer is added, only the Customer group gets flushed (and consequently refreshed) rather than the whole cache. 

Note that these annotations have to be on the implementation class of the service layer, not the interface – this is because it's the implementation that is wrapped by the AOP proxy. For more information see Understanding AOP Proxies

Implementation: CachingAspects
This class is responsible for most of the work around the caching mechanism. It defines which methods in the service layer require attention from the caching mechanism and it performs the work around retrieving from the cache and dealing with cache misses. 

It uses the AspectJ AOP conventions in Spring 2.0, more information of which can be found in the Spring documentation. The main areas of interest are the annotations for each method which state when this method is to be called:

@Around("execution(@com.mechanitis.examples.cache.Cache java.util.List get* ())")
public Object cacheListWithNoArgs(ProceedingJoinPoint pjp) throws Throwable {...}

This states that this method should be called when any method that starts with the word "get" that returns a List and is tagged with the @Cache annotation is called. The @Around states that this method will be responsible for calling the original method – so in this case the original service method that was called (e.g. CustomerService.getAllCustomers()) will only be called if the list not is found in the cache. Another example is:

@Around("execution(@com.mechanitis.examples.cache.Cache “
+ " com.mechanitis.examples.common.domain.* "
+ "get* (com.mechanitis.examples.domain.id.*))")
public Object getIdentifiableObject(ProceedingJoinPoint pjp) throws Throwable {...}

This method is called when a service method is called that is tagged with the @Cache annotation, starts with “get”, is passed a domain ID and returns a domain object. This is a classic example of something to be dealt with by the cache manager – again it needs to check if the item is in the cache, return it if it is or retrieve it from its original source and store it in the cache if it is not. You can have similar methods for determining which methods need to flush the cache (e.g. "update" or "create" methods). 

And hey presto! An almost magical cache which does not require your developers to re-write the same caching code for all the "get", "update" and "create" methods on your service layer. All they have to do is tag the appropriate methods with @Cache and the AOP will take care of the rest of it. 

Disadvantages to AOP
 
As with many “magical” implementations, the main issue I found with this implementation of an AOP cache is that it can be difficult to debug. Caching can cause weird issues anyway (for example, if your update methods don’t correctly flush the cache you get old data being displayed, or if your cache update method doesn’t correctly retrieve the data). But when you throw Aspects into the mix, it can cause some interesting bugs that are hard to track down. 

The number one key to helping to overcome this issue is a good set of unit/functional tests for your cache. The advantage of testing a centralised AOP cache is that you don’t have to thoroughly test every method that might have caching implemented. So writing a lot of good tests for the AOP cache probably pays off vs. implementing and testing caching for individual methods. 

Still, strange things can creep in that can’t be detected by unit tests. For example, if a method has been tagged as a cache method through careless copy-paste coding, when it needs real-time data. Or, as I found, worse – if you don’t have a way to explicitly state which methods require caching but do it through the magic of naming conventions, you need all your developers to be fully aware of these conventions (and to not make mistakes in this area) in order to state which methods use the cache and which do not. 

Although I probably spent more time tweaking and debugging the cache than almost any other individual area of the application when I used it in anger, I would still say it was worthwhile implementing it in this fashion. The benefits from removing any “difficult” bits from the service layer, so junior developers can happily work, and the ease of adding an annotation to the appropriate methods, I think improved productivity enough and allowed for much cleaner code (which also improves productivity) so that it was the right choice to make.

Validation with Spring Modules Validation

So if java generics slightly disappointed me lately, what have I found cool?

I’m currently working on a web application using Spring MVC, which probably doesn’t come as a big surprise, it seems to be all the rage these days. Since this is my baby, I got to call the shots as to a lot of the framework choices. When it came to looking at implementing validation, I refused to believe I’d have to go through the primitive process of looking at all the values on the request and deciding if they pass muster, with some huge if statement. Even with Spring’s rather marvelous binding and validation mechanisms to take the worst of the tasks off you, it still looked like it would be a bit of a chore. Given all the cool things you can do with AOP etc I figured someone somewhere must’ve implemented an annotations-based validation plugin for Spring.

And they have. And there’s actually a reasonable amount of information about how to set it up and get it working. The problem is that it’s pretty flexible and has a lot of different options, so when you are running Java 1.5 and Spring 2.0, and actually want to use the validation in a simple, straightfoward fashion, the setup instructions get lost.

So here’s my record so I don’t forget in future how I did it.

As a brief summary for those who may not be familiar with Spring, or for those who need reminding (no doubt me in a few months when I’ve completely forgetten what I was working on), Spring provides a Validator interface that you can use to easily plug validation into your application. In the context of web applications, you create your various Validators and in your application context XML file you tell your Controllers to use those validators on form submission (for example).

Spring Modules validation provides a bunch of generic validation out of the box for all the tedious, standard stuff - length validation, mandatory fields, valid e-mail addresses etc (details here). And you can plug this straight into your application by using annotations. How? Easy.

This is my outline application context file:


<?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_vld="http://www.springmodules.org/validation/bean/validator "
xsi_schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
http://www.springmodules.org/validation/bean/validator http://www.springmodules.org/validation/bean/validator.xsd&quot;>

<vld:annotation-based-validator id="validator" />

<!– Load messages –>
<bean id="messageSource"
class="org.springframework.context.support.ResourceBundleMessageSource">
<property name="basenames" value="messages,errors" />
</bean>

<!– Bean initialisation for validation. You can put these explicitly into your controllers or set to autowire by name or type –>
<bean id="messageCodesResolver"
class="org.springmodules.validation.bean.converter.ModelAwareMessageCodesResolver" />

</beans>

Really all you’re interested in is the addition of the validation namespace and schema at the top of the file, and the <vld:annotation-based-validator id="validator" /> line which is your actual validator. The other sections are a message source so your error codes can have meaningful messages and a MessageCodeResolver to make use of these.

Eclipse does seem to moan about the way the springmodules schema is referenced, but when you actually start Tomcat up it seems happy enough.

I’ve chosen to give the validator the ID validator because I turned autowire by name on so that all my controllers picked up this validation by default. Note: autowire can be a little bit dangerous and I’ve actually turned it off now because I had a validator bean and a validators list in the context file and my poor SimpleFormController controllers were getting a bit confused over which one to use (in truth, the single validator was overwriting the list, which was not what I was after at all).

Anyway. Now what? We have a validator and we’ve probably wired it into the relevant controllers, either by autowiring them or poking it specifically into our controllers like this:


<bean id="somePersonController"
class="com.mechanitis.examples.validation.controller.MyPersonController">
<property name="commandClass"
value="com.mechanitis.examples.validation.command.PersonCommand" />
<property name="formView" value="person" />
<property name="successView" value="success" />
<property name="validator" ref="validator"/>
</bean>

Next step is to add some validation rules. The documentation will show you how to do this using an XML file, which you’re perfectly welcome to do. However what I wanted to show is how to use annotations on your command object to declare your validation. So here you are:


import org.springmodules.validation.bean.conf.loader.annotation.handler.CascadeValidation;
import org.springmodules.validation.bean.conf.loader.annotation.handler.Email;
import org.springmodules.validation.bean.conf.loader.annotation.handler.Length;
import org.springmodules.validation.bean.conf.loader.annotation.handler.Min;
import org.springmodules.validation.bean.conf.loader.annotation.handler.NotNull;

public class PersonCommand {
private static final int NAME_MAX_LENGTH = 50;

@NotNull
@Length(min = 1, max = NAME_MAX_LENGTH)
private String name;

@Min(value=1)
private Long age;

@Email
private String eMail;

@CascadeValidation
private RelationshipCommand relationship = new RelationshipCommand();

private String action;

//insert getters and setters etc

}

Note that @CascadeValidation tells the validator to run validation on the enclosed secondary Command.

This is just a simple example obviously. But hopefully you can see that now you’ve got the validator set up correctly in your application context file, all you need to cover 90% of your validation needs is to tag the relevant fields with the type of validation you want. If you want to get really clever, the validator supports Valang which allows you to write simple rules. For example, if I only want to validate the name when I’m saving the person rather than passing the command around for some other purpose, I might change the annotations on the name field:


@NotNull(applyIf="action EQUALS ‘savePerson’")
@Length(min = 1, max = NAME_MAX_LENGTH, applyIf="action EQUALS ‘savePerson’")
private String name;

That’s the basics. Before I let you go off and play though, a word about error messages. As usual with Spring validators, you can specify pretty messages to be displayed to the user when things go wrong. In my application context file above you should see that I’ve specified a properties file called errors. In this file you can map your error codes to the message to display. When using the spring modules validation I found the error codes generated were like the ones below so you might have an errors.properties file that looks like this:


# *** Errors for the Person screens
PersonCommand.age[min]=An age should be entered
PersonCommand.name[length]=Person name should be between 1 and 50 characters
# etc etc

# *** General errors
not.null=This field cannot be empty

Go play.