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.
WebApplicationInitializeris 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
AbstractDispatcherServletInitializermakes it even easier to register the
DispatcherServletby simply specifying its servlet mapping.
Did you manage to make it all the way through? Here’s a better version:
WebApplicationInitializerdetects code-based configuration to automatically initialize a Servlet 3 container. The abstract implementation
AbstractDispatcherServletInitializerdoes this by specifying a servlet mapping to register the
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.