Handling errors in a REST way is seemingly simple enough: upon requesting a resource, when an error occurs, a proper status code and a body that contains a parseable message and using the content-type of the request should be returned.
The default error pages in Tomcat are ugly. Not only they expose too much of the server internals, they are only HTML formatted and making them a poor choice if a RESTful web service is deployed in that Tomcat container. Substituting them to simple static pages is still no enough since I want a dynamic response containing error information.

Here’s how to do it in 3 simple steps:

Step 1
In web.xml

   <servlet-mapping>
      <servlet-name>jsp</servlet-name>
      <url-pattern>/error.jsp<url-pattern>
   </servlet-mapping>
   <!-- other servlet mappings --&&gt&

  <error-page>
    <error-code>404</error-code>
    <location>/error.jsp</location>
  </error-page>
  <error-page>
    <error-code>400</error-code>
    <location>/error.jsp</location>
  </error-page>
...
  <error-page>
    <exception-type>java.lang.Throwable</exception-type>
    <location>/error.jsp</location>
  </error-page>

The servlet called jsp comes out-of the box with the Tomcat container and is the one responsible for processing JSPs . Make sure this mapping comes first, especially if you have a catch-all url-pattern that should map all other URLs to your webapp.

Step 2
Create a file called errors.jsp in the root of your web application:

<%@ page contentType="application/json" pageEncoding="UTF-8"%>
{
   status:<%=request.getAttribute("javax.servlet.error.status_code") %>,
   reason:<%=request.getAttribute("javax.servlet.error.message") %>
}

Step 3
Hook the exception handling using @ExceptionHandler:

@Controller
public class SomeController {
...

@ExceptionHandler(BusinessException.class, ValidationException.class, ...)
public void handleApplicationExceptions(Throwable exception, HttpServletResponse response) {
   String formattedErrorForFrontEnd = formatErrMessage(exception);
   if(exception instanceof BusinessException) {
      response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR,
formattedErrorForFrontEnd);
   } else if (exception instanceof ValidationException) {
      response.sendError(HttpServletResponse.SC_BAD_REQUEST, formattedErrorForFrontEnd);
   }
   ...
}

//other @ExceptionHandlers skipped

   private String formatErrMessage(Throwable exception) {
      //skipped
   }
}

I used @ExceptionHandler to map between application exceptions and error codes. You can apply message formatting as well if the default messages are not sufficient. Also, consider having an @ExceptionHandler(Throwable.class) for the “all other exceptions” case.

As you can see, there is no need to write another Spring Controller that handles exceptional paths. The error-page mappings in web.xml, a 2 line JSP and the standard @ExceptionHandler combination was sufficient.

Update Mar.04 Thanks to @ewolff some of the points described below are now official feature requests. One (SPR-6928) is actually scheduled in Spring 3.1 (cool!). I’ve updated the post and added all open tickets. Please vote!

This post is somewhat a response to InfoQ’s Comparison of Spring MVC and JAX-RS.
Recently I have completed a migration from a JAX-RS implementation of a web service to Spring 3.0 MVC annotation-based @Controllers. The aforementioned post on InfoQ was published a few days after my migration so I’m dumping below the list of problems I had, along with solutions.

Full list of issues:

• Same relative paths in multiple controllers not supported
• @ExceptionHandler is controller-centric
• Standard content negotiation can’t respond with a fixed response type
• JSR 303 bean validation not applied in @Controllers
• Formatting responses (i.e. Date) not working when using Spring formatter annotations

Same relative paths in multiple @Controllers not supported
Consider two Controllers where I use a versioned URL and a web.xml file that uses two URL mappings:

@Controller
public class AdminController {
   @RequestMapping("/v1/{userId}")
   public SomeResponse showUserDetails(String userId) {
      ...
   }
}

@Controller
public class UserController {
   @RequestMapping("/v1/{userId}")
   public SomeOtherResponse showUserStreamtring userId) {
      ...
   }
}
In web.xml:
	<servlet-mapping>
	  <servlet-name>public-api</servlet-name>
	  <url-pattern>/public</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
	  <servlet-name>admin-api</servlet-name>
	  <url-pattern>/admin</url-pattern>
	</servlet-mapping>

Here I want to implement handling for /admin/v1/{userId} as well as /user/v1/{userId}. Each controller serves a different purpose (admin and public) and I want to keep the servlet application contexts separate for each servlet mapping (for instance add authentication and different view resolvers to all /admin/* URLs).
Deploying this configuration barfs the following exception:

java.lang.IllegalStateException: Cannot map handler [UserController] to URL path
[/v1/{userId}]: There is already handler [com.test.controller. UserController@6b177115]
mapped.

I would like Spring MVC to account for web.xml servlet mappings before deciding that two identical @RequestMappings in different controllers refer to the same URI. My solution was to have all @RequestMappings specifying the full path and resorting to a custom view to work around this issue).

@ExceptionHandler is controller-centric
RESTful web services respond with the usual HTTP responses (200s, 400s, 500s, etc.). These responses are being mapped from application exceptions and it only makes sense to specify the same @ExceptionHandler for all @Controllers since most (if not all) exceptions handled by them are for the same business domain. Currently SpringMVC only supports declaring and @ExceptionHander per controller and not globally per webapp. This forces the implementors to extend their @Controller classes from a common one where the @ExceptionHandler is specified or, to use composition and delegate exception handling to one service which leads to duplication. Both are ugly. There are several ways to deal with exceptions (check SPR-5622; please guys, add this to the main Spring documentation) but ideally I’d like to see a global scoped handler like @ExceptionHandler(scope=APPLICATION) where I can remap once framework exceptions to more suitable ones that translate into proper error codes (like working around SPR-5622 like issues).

Standard content negotiation can’t respond with a fixed response type (SPR-6937)
Here’s a simple requirement: Implement an RSS feed that serves a user’s activity stream.
Here’s another requirement (make that best practice):

Service methods should have as arguments primitives, wrappers or other POJOs and
 respond with void, primitives, wrappers or other POJOs.

I want testability, readability and portability for service classes and using framework objects for arguments/return objects adds unacceptable clutter.
As such, no framework objects are allowed as arguments or return types in a @Controller and in this case I don’t want to work with ModelAndViews just to be able to select the desired View.
Since this new requirement (add RSS view) belongs to the user domain, I want to add a method in the UserController class that returns a POJO which should be always unmarshalled into RSS regardless of request content type (there goes ContentNegotiationViewResolver). The same controller has other methods returning POJO view objects that I want marshalled into JSON or plain text response body and an HTTP response status. This is already available in RESTEasy via the elegant Produces annotation. The same RESTful controller should respond with different response types for different requests since I want to keep its domain centered around the user (and not response types).

...
public class UserController {
...
   @RequestHandler("/rss/{userId}")
   public SomePOJO getRssFeed(String userId) {
      ...
      //returns a POJO that should always be resolved by an RSS view
   }

   @RequestMapping("/activity/{userId}")
   public SomeOtherPOJO showUserStream(String userId) {
      ...
      //return POJO that should always be resolved by a JSON view
   }
...
}

It turns out this is not immediately possible. To my knowledge none of the included view resolvers provide a straight mapping between URLs and views so I had to write one that configures like this:

<bean class="UrlToViewViewResolver">
   <map name="urlToViewMap">
      <property key="/user/rss/*" value="rssView"/>
      <property key="/user/activity/*" value="jsonView"/>
      ...
   </map>
</bean>

The implementation (not included) is trivial and based on AntPathMatcher, a utility class readily available in Spring.

JSR 303 bean validation not applied in @Controllers (SPR-6928, scheduled for 3.1)
On Springsource’s weblog there’s a nice tutorial on how to get validation and type conversion in Spring 3.0 here. When it comes to validation though, Spring only supports it “after binding user input to it”. It is not possible to validate arguments and return types for a RESTful controller (no web forms or user input of any kind there). This means this won’t work out of the box:

   @RequestHandler("/admin/", method = RequestMethod.PUT )
   public void updateUser(@Valid User user) {
      ...
      //returns a POJO that should always be resolved by an RSS view
   }

since in a RESTful scenario the User object won’t be bound from a form but unmarshalled from XML/JSON/CSV or any other wire format.
To enable validation for a RESTful controller I chose to use @Valid at the method level and add an around advice that intercepts all methods annotated as such then use a Validator to validate arguments and return objects.

<aop:config proxy-target-class="true">
	<aop:pointcut id="validatableMethodExecution"
        expression="execution(* com.mycorp..*.*(..)) and @annotation(javax.validation.Valid)"/>

	<aop:aspect id="validateArgumentsAndReturnObject" ref="validatorAspect">
		<aop:around pointcut-ref="validatableMethodExecution" method="validate"/>
	</aop:aspect>
</aop:config>

public class ModelValidatorAspect {
	@Autowired
	private Validator validator;

    public Object validate(ProceedingJoinPoint pjp) throws Throwable {
        Set<ConstraintViolation> violations =new HashSet<ConstraintViolation>();
        for(Object obj : pjp.getArgs()) {
            if(obj != null) {
                violations.addAll(validator.validate(obj));
            }
        }
        if(!violations.isEmpty()) {
            throw new BadRequestException(composeErrorMessage(violations));
        }

        Object ret = pjp.proceed();

        //validate return object and throw exception if the validation fails.
        if(ret != null) {
            violations = validator.validate(ret);
        }
        if(!violations.isEmpty()) {
            throw new BusinessValidationException(violationsStr);
        }
   }
}

This could get more complex if you have deal with collections of validatable objects but it’s not hard to enhance the code to handle that.

Formatting responses (i.e. Date) not working using Spring formatter annotations
Spring comes with some niceties like @DateTimeFormat and @NumberFormat and naturally I want to rely on them by annotating the class attributes of return types used by @Controllers.
That’s not quite working since the formatters work with form-backed model objects. However, if you use a MappingJacksonJsonView there is a way of formatting using Jackson’s own @JsonSerialize.

Although at times it felt that the switch to SpringMVC was too much, the features that come with it (like abstracting web-related properties as annotations) will turn your RESTful controllers into annotated POJOs focused on the business domain which ultimately means maintainable code.

Update Mar.04 I left out several points about JSON marshalling that didn’t work as expected (Jackson marshaller is a handful).
- One enhancement I suggested to ease the pain of configuring JSON marshalling is creating a namespace similar to oxm (SPR-6943)
- The second was to add Jetisson support (SPR-6938) as an alternative to Jackson JSON marshaller.

I’m keen on your feedback regarding these issues so if you have better solutions please comment.

A short two months back I posted an article describing how to upgrade to Spring 3.0 M2. Spring folks are releasing at breakneck speed and so I got busy again upgrading spincloud.com to Spring 3.0 M3 released at the beginning of May. Just yesterday (June 3rd) the team released Spring Security 3.0 M1 and I decided to roll this in Spincloud as well.

Upgrading Spring Security from 2.0.4 to 3.0.0 M1
For Spring Security 3.0.0 M1 I’m doing a “soft” upgrade since I had done my homework when I migrated from Acegi. I won’t use any of the new 3.0 features, just getting ready to use them.

To digress a bit, Spring Security a technology that is harder to swallow due to its breadth. To simplify the picture, Spring Security (former Acegi) provides three major security concerns to enterprise applications:
- Authorization of method execution (either through standard JSR-250 JEE security annotations or via specific annotation-based method security).
- HTTP Request authorization (mapping URLs to accessible roles using Ant style or regexp’ed paths, dubbed channel security).
- Website authentication (integrating Single Sign On (SSO) services by supporting major SSO providers, HTTP BASIC authentication, OpenId authentication and other types).
For Spincloud I’m using OpenId for authentication and Channel Security to secure website pages.

To perform the upgrade you have to first grab the new jars. Here’s the Maven config:

	<repository>
		<id>Springframework milestone</id>
		<url>http://maven.springframework.org/milestone</url>
	</repository>
	<properties>
		<spring.version>3.0.0.M3</spring.version>
		<spring-security.version>3.0.0.M1</spring-security.version>
	</properties>
		<dependency>
			<groupId>org.springframework.security</groupId>
			<artifactId>spring-security-core</artifactId>
			<version>${spring-security.version}</version>
			<scope>compile</scope>
		</dependency>
		<dependency>
			<groupId>org.springframework.security</groupId>
			<artifactId>spring-security-config</artifactId>
			<version>${spring-security.version}</version>
			<scope>compile</scope>
		</dependency>
		<dependency>
			<groupId>org.springframework.security</groupId>
			<artifactId>spring-security-openid</artifactId>
			<version>${spring-security.version}</version>
			<scope>compile</scope>
		</dependency>
		<dependency>
			<groupId>org.springframework.security</groupId>
			<artifactId>spring-security-taglibs</artifactId>
			<version>${spring-security.version}</version>
			<scope>compile</scope>
		</dependency>
		<dependency>
			<groupId>org.springframework.security</groupId>
			<artifactId>spring-security-web</artifactId>
			<version>${spring-security.version}</version>
			<scope>compile</scope>
		</dependency>

Make sure your build process refers only to these jars.
in 3.0.0 M1, the package structure was changed. Here’s what I had to do to upgrade the packages:
Before

import org.springframework.security.Authentication;
import org.springframework.security.context.SecurityContext;
import org.springframework.security.context.SecurityContextHolder;
import org.springframework.security.context.SecurityContextImpl;
import org.springframework.security.providers.openid.OpenIDAuthenticationStatus;
import org.springframework.security.providers.openid.OpenIDAuthenticationToken;
import org.springframework.security.userdetails.UserDetails;
import org.springframework.security.userdetails.UserDetailsService;

After:

import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContext;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.core.context.SecurityContextImpl;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.openid.OpenIDAuthenticationStatus;
import org.springframework.security.openid.OpenIDAuthenticationToken;

The security namespace has changed too so I updated my security XML file namespace and I had only to change the packages for standard Spring Security beans defined to match the new package structure.

Upgrading Spring from 3.0.0 M2 to M3
This should be easy. First, grab the new jars through Maven by using the same Maven config I described at the beginning of this post and change the spring.version to 3.0.0.M3. I’m planning to move more XML configuration to annotations and M3 enables more of that (@Lazy for instance). I’m still waiting for the scheduling namespace due to appear in this milestone but pushed to RC1 apparently. I’m craving for some annotation-based timer configuration too…

Build and deployment
At first, the build failed on me with the follwing error:

java.lang.NoClassDefFoundError: org/springframework/asm/ClassVisitor
	at org.springframework.context.support.AbstractRefreshableApplicationContext.customizeBeanFactory(AbstractRefreshableApplicationContext.java:205)
	at org.springframework.context.support.AbstractRefreshableApplicationContext.refreshBeanFactory(AbstractRefreshableApplicationContext.java:125)
	at org.springframework.context.support.AbstractApplicationContext.obtainFreshBeanFactory(AbstractApplicationContext.java:419)

This is because M3 (finally) repackages asm. So I deleted the asm libraries I used to fix the M2 issues and added the repackaged Spring asm library:

		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>org.springframework.asm</artifactId>
			<version>${spring.version}</version>
		</dependency>

If you’re getting this error on container start-up:

SEVERE: Exception sending context initialized event to listener instance of class org.springframework.web.context.ContextLoaderListener
org.springframework.beans.factory.parsing.BeanDefinitionParsingException: Configuration problem: Unable to locate Spring NamespaceHandler for XML schema namespace [http://www.springframework.org/schema/security]
Offending resource: ServletContext resource [/WEB-INF/classes/applicationContext-security.xml]

means you have forgotten to add security-config jar (see the Maven config in the Security section).

That’s all. Done in 3 hours with no problems at all.

As I’m using the ubiquitous Hibernate 3.3 as the JPA 1.0 provider for Spincloud, I decided to try out another one. I had tried OpenJPA (spawned from Kodo JDO) when they only supported build-time bytecode enhancement and it was a pain to make it work. It worked all right but boy what a pain. There’s now an agent to provide on-the-fly enhancement but I’ll take transparent enhancement anytime.
I’ve heard about EclipseLink before. The project started when Oracle donated the respectable TopLink project to the Eclipse foundation. If the solid reputation behind TopLink was a good enough argument for me to try it, the announcement that it will be the JPA 2.0 reference implementation convinced me that I should try it out.
My goal is to evaluate if EclipseLink is production-ready. I’m applying a complex set of evaluation criteria (joking): if it can run Spincloud then it is (I was inspired by Seifer’s interview on Infoq about Ruby VMs; when asked what was the criteria for qualifying if a Ruby VM is production ready, he answered: if it runs Rails).

I have the following JPA requirements:
- column mappings, one-to-one, one-to-many
- supports BLOB fields
- supports NamedQueries and NamedNativeQueries
- support for object cache and query cache
- deployment/operational nice to have: ease of maintaining compatibility with both EclipseLink and Hibernate in the source code and runtime. Ideally I should plug-in any JPA provider without changing a single line of code. This was not attainable as I’ll explain below.

I started by downloading the binaries. I’m using Maven to bring the jars so I’ve followed the instructions here. I only changed the version since I wanted to use v1.1.0:

  <dependency>
    <groupId>org.eclipse.persistence</groupId>
    <artifactId>eclipselink</artifactId>
    <version>1.1.0</version>
    <scope>provided</scope>
  </dependency>

There’s a single jar file called eclipselink-1.1.0.jar downloaded which is a nice change from the multitude of Hibernate jars I was accustomed with.

Next, I created a new persistence.xml file since I didn’t know how different it would be from the one tied to Hibernate. Initially I just changed the JPA provider to:

  <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>

as the documentation stated.
Then I had a look at my current NamedQueries and NamedNativeQueries that looked like this:

@org.hibernate.annotations.NamedQueries({
	@org.hibernate.annotations.NamedQuery(name="findStationByPK",
	        query="select station from Station station where station.id=:stationPK"
	        , cacheable=true, cacheRegion="weatherStationsRegion"),
...

and I recalled that I did this in order to make use of Hibernate’s Query cache facility, alas a non-standard way of cache enablement (not until JPA 2.0 anyway). I had to put query caching to rest and switched all my Named*Queries to standard JPA:

@javax.persistence.NamedQueries({
	@javax.persistence.NamedQuery(name="findStationByPK",
	        query="select station from Station where id=:stationPK"),
...

I’m not using the integration unit tests I have due to the issues I had with the Spring integration test framework I’m using after switching to Spring 3.0 so I’m using ad-hoc testing for now. After rebuilding/deploying the project I didn’t notice any error on Tomcat start-up so I just tried the GUI, displaying the weather in a map area. I hit the first error:

Exception [EclipseLink-7060] (Eclipse Persistence Services - 1.1.0.r3639-SNAPSHOT):
org.eclipse.persistence.exceptions.ValidationException
Exception Description: Cannot acquire data source [java:comp/env/ds/MeteoDS].
Internal Exception: javax.naming.NamingException: This context must be accessed
throughout a java: URL

I dug through the documentation (what’s with this documentation and what does “No dynamic weaving (instrumentation) – static weaving of entities is still available via EclipseLink” means, why JPAEclipseLinkSessionCustomizer example is broken and finally why use teh deprecated SessionCustomizer?) and found that I have to use a session customizer to make it work in Tomcat. I didn’t like this one bit (it just works in Hibernate) but I followed the instructions and EclipseLink could establish the connection with the Tomcat-configured data source as expected. This was the first duly noted turn-off.
I redeployed and browsed the weather map just to hit another problem:

  Exception Description: Syntax error parsing the query [findStationByPK:
    select station from   Station where id=:stationPK], line 1, column 28:
    syntax error at [where].
 Internal Exception: MismatchedTokenException(65!=66)

Hmm, no compile-time JPA query check. Not good. I checked the JPA query, it was:

  @javax.persistence.NamedQuery(name="findStationByPK",
       query="select station from Station where id=:stationPK"),
...

which looked OK but looking closely I realized that it was not. The correct syntax is (notice the station. indirection:

@javax.persistence.NamedQueries({
	@javax.persistence.NamedQuery(name="findStationByPK",
	        query="select station from Station station where station.id=:stationPK"),
	@javax.persistence.NamedQuery(name="findByStationId",
...

Hibernate was happy with the “non-standard” syntax while EclipseLink is not. No big deal, it wasn’t in many places anyway. I scanned all my queries and fixed them. Redeployed and hit this:

  Exception Description: Syntax error parsing the query [findByStationId: from
    Station station where station.stationId=:stationId], line 1, column 0:
    unexpected token [from].

My JPA query is:

	@javax.persistence.NamedQuery(name="findByStationId",
	        query="from Station station where station.stationId=:stationId")

Again a Hibernate artifact. H3 supports the convenience of using queries that start with “from entity…” if they return entities (single or lists). The fix was simply to add “select station” in front of the JPA QL:

	@javax.persistence.NamedQuery(name="findByStationId",
	        query="select station from Station station where
                station.stationId=:stationId")

Not a biggie either, standard is better and Hibernate can parse this kind of query. Again, rebuilt/redeployed and queried the map again. This time the error was this:

[EL Warning]: 2009-03-21 19:02:42.135--UnitOfWork(2001070194)--Exception [EclipseLink-4002]
(Eclipse Persistence Services -
 1.1.0.r3639-SNAPSHOT): org.eclipse.persistence.exceptions.DatabaseException
Internal Exception: com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException:
You have an error in your SQL syntax; check
the manual that corresponds to your MySQL server version for the right syntax to use
near ':area) , LOCATION) and obs_time
> :minSynopDateToConsiderStr UNION select distin' at line 1
Error Code: 1064
Call: select distinct STATION_FK as STATION_IDENTIFIER, LOCATION,
obs_time as REPORT_TIME  from SYNOP where Contains(GeomFromText(:area) , LOCATION) and
obs_time > :minSynopDateToConsiderStr UNION
select distinct STATION_FK as STATION_IDENTIFIER,
LOCATION, REPORT_TIME as REPORT_TIME from METAR where
Contains(GeomFromText(:area) , LOCATION) and REPORT_TIME > :minMetarDateToConsiderStr

I couldn’t find anything at first in the documentation (getting really pissed at the documentation style, can’t find anything useful) but I finally found this:

Support for the EclipseLink # convention is helpful if you are already familiar with
EclipseLink queries or if you are migrating EclipseLink queries to a JPA application.

I’m not “already familiar with EclipseLink queries” and no, it’s not helpful. So now I have to use #area instead of :area named parameter. This is really smart. Why in the world would one want to change the column with sharp? I’m starting to suspect clumsiness or plain careless coding. I still want to maintain Hibernate/EclipseLink pluggability so I have no choice but creating a static class that holds all NamedNativeQueries and parametrizes the named parameter prefix:

class NativeQueries {
public final static String WEATHER_SNAPSHOT_IN_AREA_NATIVE_QUERY ="select distinct
STATION_FK as STATION_IDENTIFIER, LOCATION, obs_time as REPORT_TIME from SYNOP where
Contains (GeomFromText(@named-param-prefix@area) " +
 ", LOCATION) and obs_time > @named-param-prefix@minSynopDateToConsiderStr UNION " +
"select distinct STATION_FK as STATION_IDENTIFIER, LOCATION, REPORT_TIME
as REPORT_TIME from METAR where Contains(GeomFromText(@named-param-prefix@area) " +
", LOCATION) and REPORT_TIME > @named-param-prefix@minMetarDateToConsiderStr";
...
}

Then I have to use ant to perform a pre-compilation task that replaces @named-param-prefix@ with either : or #. This really got the best of me as I’ve hit a Java compilation quirk too: you have to delete all classes that rely on the NativeQueries class since they will not recompile if the values of the public static final String values change; you have to delete all .class files and force a full compilation for them.
After I did this build change it all started working. Victory at last. Or was it? Well, no; I still have to add query caching as I heavily use spatial queries to fetch area weather (activated every time the map is dragged/zoomed). There’s the @Cache but it’s for entity caching which is good but what I also need is query caching à la Hibernate:

 @org.hibernate.annotations.NamedQuery(name="qName", query="<query>",
    cacheable=true, cacheRegion="some-cache-region")

After another round of thorough search of the documentation I found what I needed but it wasn’t what I expected. EclipseLink doesn’t support annotation-level query cache configuration. Instead you have to code-in (or use AOP to) cache writes after the queries are executed, via its ReadQuery class.
Needless to say I didn’t do it. I gave up on it right there.
On a whole this felt a lot like my (undocumented) evaluation I did over a year ago with OpenJPA (no dice too). Poor documentation (worse than EL’s) and lack of (then) runtime weaving made it a nightmare to deploy. I haven’t tried it ever since.

Prognosis: negative

This is really a shame, EclipseLink seems to be quite fast and has a footprint similar to Hibernate but:
- the documentation is awful. Guys, look at Hibernate and follow their lead. I badly need a single page HTML up-to-date documentation that I can freely browse. I can find almost anything in a matter of seconds using Hibernate’s single page HTML doc and Ctrl-F. I feel so strongly about this, I’d make an addition to the Software Craftsmanship Manifesto: “Maintain top-notch documentation”. Spring and Hibernate projects got it right and this is one of the secrets of their success. Take note.
- Use : (column) for named parameters in NamedNativeQuery; it is consistent with NamedQuery syntax (and hopefully standardized in JPA 2.0).
- Use compile-time Named*Query syntax check. It adds a great deal to predictability.
- Add the Session Customizer fix into of the base platform and make it transparent to the user. Nobody wants to write integration code to fix oddities of popular containers. “Out of the box” is valuable.
- Work on a better query caching support or push hard for a JPA 2.0 beta since there’s standardized second-level caching.

Oh and guys, some documentation pages don’t render properly on Safari, the TOCs overlap the content. Unacceptable.

Until then I’m sticking with Hibernate 3.3. It just works.

<repository>
  <id>SpringSource Enterprise Bundle Repositorys</id>
  <url>http://repository.springsource.com/maven/bundles/milestone</url>
</repository>

and the spring packages that you need since the packaging has changed from 2.5.x. Instead of a single spring.jar file, now there is one per feature so you have to sort out what jars to include in the project. I ended up with the following:

  <properties>
      <spring.version>3.0.0.M2</spring.version>
  </properties>
  <dependencies>
   ...
  <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>org.springframework.core</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>org.springframework.web</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>org.springframework.transaction</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>org.springframework.orm</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>org.springframework.jdbc</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>org.springframework.web.servlet</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>org.springframework.context</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>org.springframework.aop</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>org.springframework.expression</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>org.springframework.test</artifactId>
      <version>${spring.version}</version>
    </dependency>
  </dependencies>

Once the jars are brought, I’ve replaced my old jarfiles with the all-new M2s then fired the build target.
The first issue I found was with the asm version.

Spring 2.5 uses a repackaged asm version 2.2.3 (more info here). The new Spring 3.0 M2 doesn’t package it anymore ( see comment) so I had to add it manually. I had to add the two asm 2.2.3 jars in order to resolve this dependency:

   <dependency>
     <groupId>asm</groupId>
     <artifactId>asm-commons</artifactId>
     <version>2.2.3</version>
   </dependency>
   <dependency>
     <groupId>asm</groupId>
     <artifactId>asm</artifactId>
     <version>2.2.3</version>
   </dependency>

After refreshing the jars and redeployed, I hit the first roadblock, a ClassNoDefFoundError:

Initialization of bean failed; nested exception is
java.lang.NoClassDefFoundError: Could not initialize class
net.sf.cglib.proxy.Enhancer
...
Caused by: java.lang.ClassNotFoundException:
org.objectweb.asm.CodeVisitor

Odd, I didn’t have this error before but as it turns out, I was using a cglib version 2.1.3 which has a hard dependency on asm and I actually had an asm jar version 1.5.3 packaged along with the other jar dependencies. On top of this, there is a problem with an antlr version conflict. Different versions of antlr are required by Spring 3.0 and Hibernate 3.3.1 which I’m also using. This is Jar hell! So I put together a version requirment matrix to sort-out the dependencies between these libraries:

Fortunately the Hibernate folks have changed the default bytecode generation library to javassist starting with v3.2.2. The bummer is the cglib dependency on asm 1.5.3 since this version is in conflict with asm 2.2.3 required by both Spring and Hibernate. The solution is to use a repackaged cglib as explained here.
To get the nodep version of cglib, I added the following snippet in my pom.xml file:

<dependency>
  <groupId>cglib</groupId>
  <artifactId>cglib-nodep</artifactId>
  <version>2.2</version>
</dependency>

I’m taking the opportunity and upgrade to the newer version 2.2 of cglib.
Next is antlr. Spring requires a different version of antlr than Hibernate but fortunately antlr has changed the package notation from antlr.* in v2.x to org.antlr.* in v3.x so it’s safe to include both jars. Let’s get both versions through Maven:

   <dependency>
     <groupId>antlr</groupId>
     <artifactId>antlr</artifactId>
     <version>2.7.7</version>
   </dependency>
   <dependency>
     <groupId>org.antlr</groupId>
     <artifactId>antlr</artifactId>
     <version>3.0.1</version>
   </dependency>

Here’s the mix of jars that works for me with Spring & Hibernate:

I can’t help but notice the compatibility problems with using the Spring & Hibernate mix. It wasn’t easy to fix them and it still feels more of a hack than an actual solution. In Spring’s defense, this is a milestone version so I should expect some wrinkles. I had similar issues when upgrading Hibernate a while back. Hibernate was the first to change their packaging to use feature-centric jars (I think). I recall having issues around antlr and asm. I remember being reluctant at first about the new dependency to javassist but it worked just fine.

Next on the list is refactoring the controllers to use the new REST support of Spring. The majority of my controllers are extending from org.springframework.web.servlet.mvc.AbstractController so I’ll upgrade them to use @Controller stereotype. I’m already familiar with @Controller, I’m using it to route all top URLs found on Spincloud’s header (i.e. features). I use a simple approach: drop the inheritance to AbstractController and change handleRequestInternal:

@Controller
public class WeatherDetailsController extends AbstractController {
...
  @Override
   protected ModelAndView handleRequestInternal(HttpServletRequest request,
     HttpServletResponse response) throws Exception {
    //parse URI to extract stationIDs
...
  }
}

with the much cooler:

@Controller
public class WeatherDetailsController {
...
 @RequestMapping(value="/weather/{stationIds}", method = RequestMethod.GET)
 public ModelAndView displayWeather(@PathVariable("stationIds") String idz,
   HttpServletRequest request, HttpServletResponse response) {
...
  }
}

Last, remove the carbonfive HandlerMapping bean in the spring servlet XML which used to look like this:

 <bean class="carbonfive.spring.web.pathparameter.ParameterizedUrlHandlerMapping">
  <property name="alwaysUseFullPath" value="true"/>
  <property name="mappings">
   <props>
    <prop key="/weather/*">weatherDetailsController</prop>
   </props>
  </property>
 </bean>

Deployed and started the container successfully but when I hit a URL that was supposed to be routed through the new controller, I got the following error:

2009-03-07 20:55:49,072: WARN  PageNotFound:1017
 No mapping found for HTTP request with URI [/weather/15150] in
DispatcherServlet with name 'weather'

Bummer: the URL is not routed to any controller. I initially suspected the DefaultAnnotationHandlerMapping I was using was to blame but after searching on the interweb and finding nothing else worthy and a couple of hours of research in my own code, I discovered that the problem was in web.xml. I had fine grained servlet-mapping URLs, including one that should have routed all URLs starting with /weather that looked like this:

 <servlet-mapping>
   <servlet-name>weather</servlet-name>
   <url-pattern>/weather/*</url-pattern>
 </servlet-mapping>

which is not good anymore. After checking the web.xml file in the Petstore example, I noticed that the servlet mappings can use the greedy <url-pattern>/</url-pattern> to route to one controller then more specific patterns for routing to other controllers. Since I have more than one controller, I changed the mappings like below:

 <servlet-mapping>
   <servlet-name>weather</servlet-name>
   <url-pattern>/</url-pattern>
 </servlet-mapping>
 <servlet-mapping>
   <servlet-name>tag</servlet-name>
   <url-pattern>/tag/*</url-pattern>
 </servlet-mapping>