Twitter GitHub Facebook Instagram

Daniel Irvine on building software

Some thoughts on Spring MVC

3 October 2014

For the past couple of weeks I’ve been working with Spring MVC. Here are some points of interest.

The official Spring documentation is next to useless

Rarely I have I read such poor documentation. Long Java class names like AnnotationConfigWebApplicationContext are hard to read to begin with, but combine this with poorly-edited, inconcise documentation and you are, essentially, shafted. I struggled to read more than a sentence without my mind wandering.

Writing documentation is a lot like writing code: keep the right level of abstraction (meaning, know your reading audience), and keep it concise.

Here’s an example from what appears to be the main documentation page for Spring MVC.

WebApplicationInitializer is an interface provided by Spring MVC that ensures your code-based configuration is detected and automatically used to initialize any Servlet 3 container. An abstract base class implementation of this interace named AbstractDispatcherServletInitializer makes it even easier to register the DispatcherServlet by simply specifying its servlet mapping.

Did you manage to make it all the way through? Here’s a better version:

WebApplicationInitializer  detects code-based configuration to automatically initialize a Servlet 3 container. The abstract implementation AbstractDispatcherServletInitializer does this by specifying a servlet mapping to register the DispatcherServlet.

I’ve applied two simple rules to create this: firstly, I assumed that my reader knows object-oriented programming and therefore I can omit needless teachings like (”is an interface provided by Spring MVC”), and secondly I activated verbs (”is detected” to “detects”).

The Internet is full of out-of-date Spring documentation

Huge swathes of the Internet’s discussion on Spring is hopelessly out-of-date.  I learned this lesson the hard way. Each new version of Spring seems to include radically new constructs to do things so you need to make sure that every single page you visit is about the version of Spring you’re using.

Here’s an example. I wanted to integrate Jackson JSON serialization for my controller. The first post I found detailed how to do this and looked like exactly what I needed. Except it didn’t work. I spent a fair amount of time (maybe an hour) trying to figure this out until I realized that Spring MVC 4 only supports Jackson 2, and this post was about Jackson 1.9.

I only figured this out because I noticed that the Spring MVC libraries I was compiling against included the type MappingJackson2HttpMessageConverter and I got curious about the “2” in there. Cue more Internet searching until the truth dawned on me.

A convention-based, XML-less approach is possible

I’m not going to post code for how I did this, because I don’t want to make it hard for some poor Joe when Spring MVC vNext is produced. But yes, you can produce a working Spring MVC implementation without any XML. Good luck finding examples of this.

I’m not convinced of the need for the front controller approach

Since Spring MVC builds on top of the standard Java servlet API, you have to know how Java servlets works as well as how Spring MVC works.

The Java servlet types are well-documented and do their job well. Spring’s DispatcherServlet, a front controller, seems odd in comparison: why exactly does the usual servlet approach need to be circumvented? I spent too much time working on integrating these two libraries. I found examples online showing Spring serving JSPs and resources, but it turns out to be the wrong approach: JSPs and resources are easily served by using the DefaultServlet from Java EE.


About the author

Daniel Irvine is a software craftsman at 8th Light, based in London. These days he prefers to code in Clojure and Ruby, despite having been a C++ and C# developer for the majority of his career.

For a longer bio please see To contact Daniel, send a tweet to @d_ir or use the comments section below.

Twitter GitHub Facebook Instagram