Spring MVC 3, JSF 2 with Maven 2 and Tomcat 7

So, recently I started on a little hobby-project and I wanted to see if I could harness the strengths of Spring MVC together with JSF 2 and run it all on Tomcat 7. The reasons for these are several:

  • I wanted a combined template and component-oriented approach to view construction. Granted, there are numerous different frameworks out there that does this, but I wanted to try out JSF 2 as it seems to accomplish these things in a fairly easy and concise way.
  • I don’t care much for the request handling pattern and URL scheme that JSF brings with it. Call me conservative, but I like a clean MVC pattern with a clear division of roles. Most component-based frameworks, in my opinion, blur the lines unduly between controller and view. I’m typically not very fond of automagic form generation and post-back and the whole “code behind” concept that JSF (and Tapestry and ASP.NET and a bunch of other component frameworks) use. So, Spring MVC is more my style. There are other action-oriented frameworks you can use, but Spring MVC is as good as any plus…
  • …I’m not to eager to go the full JEE CDI approach. Spring can still offers most of what JEE’s got and it’s definitely got everything I need. It also has some things that JEE is still lacking, for example AOP support. With Spring’s support for JPA, the circle is complete and CDI is out.
  • Since I don’t need the full JEE package, I can deploy it all in my favorite light-weight container, Tomcat. Yay!
  • Since I prefer to write most of my client-side code myself (using either Prototype/Scriptaculous or jQuery), I typically fore go using pre-built component frameworks (PrimeFaces et al). In my experience, they tend to deliver almost what you want, but never exactly. And when you run into situations and cases that aren’t covered by the framework, you’ll start to work against it instead of with it, which usually ends up burning more time than just doing it yourself.

You’d think that all this would be a walk in the park. I mean, it’s two of the largest and most established frameworks – there should be no problems bridging the two, right? Well, it turns out it’s still a bit tricky…

The major obstacles that you have to get around are

  1. Exposing Spring beans to the JSF pages.
  2. Using JSF pages as views in a Spring MVC request.
  3. Maintaining the JSF resource handling intact
  4. Maintaining support for JSF form handling (h:form, h:commandButton etc)

Number 4, i found, is very tricky to accomplish. It would require hooking in a lot of custom handling into the JSF framework. However, like I stated previously, I don’t even want the whole automagical form madness. I wan’t clean forms I have full control over myself (sometimes I want regular posts, sometimes I want AJAX posts with HTML fragment responses, sometimes I want AJAX posts with JSON responses), and I want them to post to my own Spring MVC controllers. With all that in mind, I completely dropped trying to get JSF h:form to work. If you can’t live without that, this might not be for you.

So, without further ado I’ll just go ahead and show you my various configurations.

Directory layout

Standard maven 2 layout, with JSF conventions applied

- src/
  - main/
    - java/ (Java sources
    - resources/
      - applicationContext.xml (spring config)
      - log4j.properties (log4j config)
      - MessageResources.properties (JSF message resources)
      - META-INF/
        - persistence.xml (JPA config)
    - webapp/
      - resources/ (all static resources go in this directory, as per JSF convention)
      - WEB-INF/
        - faces-config.xml (JSF config)
        - web.xml (web config)
        - templates/ (all JSF templates go in this directory)
        - views/ (all JSF views go in this directory)


The maven config is fairly standard. As you might notice, I’m using the reference implementation of JSF 2 here (Mojarra). If you plan to deploy this to a JEE container (JBoss etc), you should mark them as “provided” to prevent conflicts. You might also notice I’m including spring-webflow. I’m not planning to use anything related to webflow as such, but that module includes the class JsfView that is required when configuring Spring MVC to use JSF views. You could strip that class out and clean it up from webflow dependencies, but I couldn’t be bothered yet.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">




No mysteries here, just bootstrap spring and JSF, make Spring handle everything except .jsf requests (this is so the JSF resource handling will still work, more on that further down).

    <servlet-name>Faces Servlet</servlet-name>
    <servlet-name>Faces Servlet</servlet-name>


<?xml version="1.0" encoding="UTF-8"?>
<faces-config version="2.0" xmlns="http://java.sun.com/xml/ns/javaee"


The SpringBeanFacesELResolver is the glue that allows JSF pages to use Spring beans is if they were @ManagedBeans. In our scenario here, I’m completely ignoring to use @ManagedBean. Instead, I’m using spring beans and spring scopes.

The CustomResourceHandler is something I wrote to allow the JSF resource handler to function properly. This is needed if you want JSF tags like h:outputScript, h:outputStylesheet and h:graphicImage to work (served from the webapp/resources directory).


package helloworld.faces.application;

import javax.faces.application.Resource;
import javax.faces.application.ResourceHandler;
import javax.faces.application.ResourceHandlerWrapper;
import javax.faces.application.ResourceWrapper;
import javax.faces.context.FacesContext;

import com.sun.faces.util.Util;

 * Custom JSF ResourceHandler.
 * This handler bridges between Spring MVC and JSF managed resources. The handler takes
 * care of the case when a JSF facelet is used as a view by a Spring MVC Controller and the
 * view uses components like h:outputScript and h:outputStylesheet by correctly pointing the 
 * resource URLs generated to the JSF resource handler.
 * The reason this custom handler wrapper is needed is because the JSF internal logic assumes
 * that the request URL for the current page/view is a JSF url. If it is a Spring MVC request, JSF
 * will create URLs that incorrectly includes the Spring controller context.
 * This handler will strip out the Spring context for the URL and add the ".jsf" suffix, so the
 * resource request will be routed to the FacesServlet with a correct resource context (assuming the
 * faces servlet is mapped to the *.jsf pattern). 
public class CustomResourceHandler extends ResourceHandlerWrapper {

    private ResourceHandler wrapped;
    public CustomResourceHandler(ResourceHandler wrapped) {
        this.wrapped = wrapped;
    public ResourceHandler getWrapped() {
        return this.wrapped;    
    public Resource createResource(String resourceName, String libraryName) {
        return new CustomResource(super.createResource(resourceName, libraryName));
    public Resource createResource(String resourceName, String libraryName,
            String contentType) {
        return new CustomResource(super.createResource(resourceName, libraryName, contentType));
    private static class CustomResource extends ResourceWrapper {

        private Resource wrapped;
        private CustomResource(Resource wrapped) {
            this.wrapped = wrapped;
        public Resource getWrapped() {
            return this.wrapped;
        public String getRequestPath() {
            String path = super.getRequestPath();
            FacesContext context = FacesContext.getCurrentInstance();
            String facesServletMapping = Util.getFacesMapping(context);
            // if prefix-mapped, this is a resource that is requested from a faces page
            // rendered as a view to a Spring MVC controller.
            // facesServletMapping will, in fact, be the Spring mapping
            if (Util.isPrefixMapped(facesServletMapping)) {
                // remove the Spring mapping
                path = path.replaceFirst("(" + facesServletMapping + ")/", "/");
                // append .jsf to route this URL to the FacesServlet
                path = path.replace(wrapped.getResourceName(), wrapped.getResourceName() + ".jsf");
            return path;


<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"

    <context:component-scan base-package="helloworld" />
    <!-- map all requests to /resources/** to the container default servlet (ie, don't let Spring handle them) -->
    <bean id="defaultServletHttpRequestHandler" class="org.springframework.web.servlet.resource.DefaultServletHttpRequestHandler" />
    <bean id="simpleUrlHandlerMapping" class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
        <property name="urlMap">
            <entry key="/resources/**" value-ref="defaultServletHttpRequestHandler" />
    <bean class="org.springframework.web.servlet.mvc.HttpRequestHandlerAdapter" />
    <bean id="viewResolver" class="org.springframework.web.servlet.view.UrlBasedViewResolver">
        <property name="cache" value="false" />
        <property name="viewClass" value="org.springframework.faces.mvc.JsfView" />
        <property name="prefix" value="/WEB-INF/views/" />
        <property name="suffix" value=".xhtml" />

Important things to note here is the view resolver that uses the JsfView viewClass. Like I mentioned, this class lives in the spring-faces module in spring webflow. The three beans defined above are to allow static resources to be served outside of Spring. Since I mapped the DispatcherServlet in web.xml to the “/” url-pattern, Spring will effectivly take over all request handling. The DefaultServletHttpRequestHandler is a handler that will defer handling to the container default handler (ie Tomcats default servlet). My simpleUrlHandlerMapping maps all requests to /resources/** to the default handler and finally you need to create and adapter (HttpRquestHandlerAdapter) that can work with the handler. All this will allow me to access static resources under the /resources folder using normal linking. I mentioned above that my custom resource handler allowed me to access them using JSF tags like h:graphicImage. This is for when I want to access them using a regular img, script or link tag.

Hello World example

This short example consists of 2 java classes (controller and model) and one JSF xhtml page (view).

HelloWorld (request-scoped model bean>

package helloworld;

import org.springframework.context.annotation.Scope;
import org.springframework.context.annotation.ScopedProxyMode;
import org.springframework.stereotype.Component;

@Scope(value="request", proxyMode=ScopedProxyMode.TARGET_CLASS)
public class HelloWorld {
    private String message;

    public String getMessage() {
        return message;

    public void setMessage(String message) {
        this.message = message;

HelloWorldController (controller)

package helloworld;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;

public class HelloWorldController {

	private HelloWorld helloWorld;
	@RequestMapping(value="/helloWorld", method=RequestMethod.GET)
	public void helloWorld() {
		helloWorld.setMessage("Hello World from Spring MVC to JSF");
	@RequestMapping(value="/helloWorld", method=RequestMethod.POST)
	public void helloWorldPost(@RequestParam String msg) {

helloWorld.xhtml (JSF view, goes under WEB-INF/views

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
<html xmlns="http://www.w3.org/1999/xhtml"
        <title>Hello World</title>
        <p>Say something: </p>
        <form method="post">
            <input name="msg" type="text"></input>
            <input type="submit" ></input>
        <p>This image is linked as a JSF resource</p>
        <h:graphicImage name="images/jsf.jpg" />
        <p>This image is directly linked</p>
        <img src="resources/images/spring.png"></img>

As you can see, this page demonstrates how to access a Spring bean using JSF EL (${helloWorld.message}) and how to render an image both using JSF resources handling and a regular img tag. You will have to manually put some images in the webapp/resources/images folder to try this.
Posting the form should reload the page and display the message you entered in the textbox.


Understanding Tomcat Executor thread pooling

In the default configuration, Tomcat will always create a bounded worker-thread pool for each Connector (with max-size 200). Mostly, this is not something that you’ll need to change (other than maybe increasing the max threads to accomodate for higher load). However, like I discussed in my previous post, Tomcat has a propensity for caching a lot of scaffolding objects (like PageContext and tag buffers) in thread-local context in each worker thread. Because of this, there are instances where you might want Tomcat to be able to close threads down to clean out some memory. Also, having each connector maintaining it’s own pool makes it harder to set a firm top-limit on what load your server will accept. The answer to this is to use a shared Executor.

By having all connectors share the same executor, you can configure with more predictability how many simultaneous requests that is allowed to run across your entire application. The Executor also brings the ability of having a thread-pool that can shrink as well as grow to accomodate load. At least in theory…


The standard, built-in executor that Tomcat uses by default is the StandardThreadExecutor. The configuration is documented here: http://tomcat.apache.org/tomcat-6.0-doc/config/executor.html
The configuration options include the somewhat misnamed paremter “maxIdleTime” and here is what you need to be aware of regarding the standard executor and closing idle threads.

The standard executor internally uses a java.util.concurrent.ThreadPoolExecutor. This works (somewhat simplified) by having a variable size pool of worker-threads that, once they have completed a task, will wait on a blocking queue until a new task is entered. Or until it has waited for a set amount of time, in which case it will have “timed out” and the thread will be closed. The crux of this is that since the first thread to complete a task will be first in line to get a new task, the pool will behave in a First-In-First-Out (FIFO) way. This is important to keep in mind when we examine how this will affect the Tomcat executor.

maxIdleTime is really minIdleTime

Because of the FIFO behaviour of the java ThreadPoolExecutor, each thread will at minimum wait for a new task for “maxIdleTime” before being eligable for closure. Moreover, again because of the FIFO behaviour of the thread pool, for a thread to be closed it’s required that a period of time at least equal to maxIdleTime passes without ANY request coming in, since the thread that has been idle the longest will be first in line for a new task. The effect is that the executor will not really be able to size the pool to fit the average load (concurrent requests), it will rather be sized according to the rate at which requests come in. This may sound like a distinction without a difference but in terms of a web-server, it’s quite significant. For example, 40 requests come in at the same time. The thread-pool will be expanded to 40 to accomodate the load. After that, you have a period where only one request comes in at a time. Say each request takes 500 ms to complete, that means it would take 20 seconds to cycle through the entire thread-pool (remember, FIFO). Unless you have your maxIdleTime set to less than 20 seconds, the pool will continue to hold 40 threads indefinitly, even though the concurrent load is never more than 1. And you don’t want to set your maxIdleTime too low either – that will risk flapping behaviour where threads are killed too soon.


To get a more predictable thread-pooling behaviour that attempts to size to average load rather than to rate of requests coming in, it would be preferable to have an executor that worked on a “Last-In-First-Out” (LIFO) basis. If the pool would always assign the thread that had been idle to SHORTEST period of time to incoming tasks, the server would be better equipped to close down threads during periods of lower load (and in a more predictable manner). In the very simplistic example above, the initial load of 40 followed by a period with a load of 1, a LIFO pool would correctly size down to 1 after the maxIdleTime period. Of course, it may not always be required (or desired) to have such an aggressive puring strategy but if your goal is to minimize the amount of resources reserved by Tomcat, the standard executor might unfortunately not be able do what you expect it to do for you.

Some notes on tweaking Tomcat memory usage

Firstly, the golden rule of memory optimization should always be to start in your own code. I won’t go into any deeper details on JVM tweaking, there are plenty of articles out there if you google. Sufficient to say that if you find yourself tweaking around with GC strategy, then you have dug too deep. The JVM will pick the strategy that it deems best for your HW config and if you feel a need to change that your app is in some way badly designed. Only once have I encountered a situation where changing GC strategy was the only solution (involved a huge lucene index and limited memory), but in general it should never be required.

Some common indications of excessive memory usage includes:

  1. OutOfMemory error “Java heap space”
    Simple enough, your application requires more memory than you actually have allocated
  2. OutOfMemory error “GC overhead limit exceeded”
    Often comes hand in hand with the “Java heap space” error and it’s very similar but subtly different. In short, it means that while the JVM percieves that it may have enough memory in absolute terms, the rate of consumption is so high that the time it has to spend garbage collecting is leaving it with no time to actually execute your application. If this is the prevailing error you are getting, it’s an indication that you have a combination of lots and or very big long-lived objects in memory and a high rate of consumption of short-lived objects. This will force frequent and long-running full GC cycles since the “old gen” heap will be near full and “young gen” will reach it’s limit in very short cycles.
  3. Long periods when the system “freezes” up for full GC cycles
    Often tied to high memory consumption rate (lots and lots of short-lived objects) and not enough CPU cores. The collector generally seems to favour dropping short-lived, de-referenced objects down to the “old gen” in the small cycles rather than throwing them out, letting the full GC cycle take care of them. Adding more memory to the JVM may decrease the frequency of these “freezes”, but unless you back that with more CPU power, the length each “freeze” will increase. In my personal opinion, a server-grade machine should always have more than 2 CPU cores, to at least be able to leverage the Parallell GC in the JVM

With this in mind, there are some configurations available in Tomcat that do have their specific usages and I thought I’d share my experiences/thoughts about a few of them. This applies primarily to Tomcat version 6 as that is where I have done the most experimenting and analysis.


This is a tomcat system property (http://tomcat.apache.org/tomcat-6.0-doc/config/systemprops.html). The documentation on it refers to the “tag buffer”, which may or may not mean anything to you. If not, this is what it is, in short:

Each time you use a taglib tag on your JSP page like a <c:set> JSTL tag or really any tag (except the <jsp:*> tags as they are not really “tags” as such and handled differently), a char buffer will be set up to receive the body of that tag. The Servlet/JSP specs demand that there be no limit to the size of a tag’s body, so this buffer can grow infinitly. Additionally, if you nest a tag inside another tag, an additional buffer is set up for the nested tag, and so on. These buffers are all maintained in a stack in the PageContext, but never actually dereferenced. Because of this, all these character buffers will contiue to live and be re-used by later requests.

What LIMIT_BUFFER does is to force Tomcat to discard the buffer before each usage if it’s larger than the default size (512 characters) and allocate a new buffer of the default size (which may of course grow if it’s not enough to handle the tag body).

When is this relevant

This is mainly an issue if you have tags with very large bodies. For instance, HTML fragment-caching tags (like oscache) or taglib-based templating frameworks (like tiles). If this is not the case, the sum of these buffers will be negligable. For instance, 400 worker-threads with an average tag nesting depth of 3 = 400*3*512 =~ 614 KB. But say you’re using tiles and you have a page that’s 1 MB large and 5 levels of templates.  Then you’re looking at 2 GB of memory indefinitly allocated. And you have to consider the worst case since eventually, every worker-thread will have served that one large page at least once and without LIMIT_BUFFER, once those buffers have been sized up, they will never size down.

org.apache.jasper.runtime.JspFactoryImpl.USE_POOL and POOL_SIZE

Two other system properties which have similar implications as LIMIT_BUFFER. Each worker thread (the threads that handles the actual requests in tomcat) will, by default, pool PageContext objects for use on JSP pages in a thread-local context. As I mentioned in connection to LIMIT_BUFFER, the tag buffers are maintained in a stack in the PageContext. By setting USE_POOL=false, Tomcat will discard a PageContext after the request it served is completed and create a new PageContext for each new request. Since this will, in effect, throw away all the tag buffers as well, the implications are very similar.

Why pool PageContexts on a per-thread basis to begin with, you might ask yourself? Simply because each time you do an include, or a forward, a new PageContext is required to handle the included page, even though it’s handled by the same thread as the “top level” request. This is analogous to nesting tags – each nesting requires a new buffer (“context”) in which to live. Because of this, one request may require more than on PageContext, so Tomcat pools them so it doesn’t have to recreate a bunch of new ones all the time.

When is this relevant

Sizing the pool is relevant primarily if your application relies heavily on dynamic includes (<jsp:include> or <c:import>) and you have many levels of “includes within includes”. In combination with large tag bodies, tweaking the pool size (or not pooling at all) can have a very significant impact on memory-usage.


There is definitly a trade-off to consider with both these settings. By limiting the pooling and size of the tag buffers, you reduce the amount of “base” memory needed, but at the cost of more garbage collection and re-allocation of objects. My own experiments with a real-life, tiles-based application gave me pretty much exactly the type of behaviour I expected. Limiting buffers would reduce the amount of “base memory” needed vastly (that is, the amount of heap still used after a full GC) but it would increase the CPU load significantly and reduce overall performance. In my case, the average response time nearly doubled. So if you’re going to limit buffer usage, be prepared to back that up with either more CPU cores or with more servers in your cluster if you are near your load limit to begin with.

However, “more memory, more CPU” may not always be an option. If you are forced (or you prefer) 32-bit environments, memory will be your bottleneck. Some Cloud services (like Amazon AWS) charges significantly more for 64-bit instances and CPU is cheaper to scale than memory on AWS as well. In other scenarious, you may have an application that already uses a lot of base memory (like big caches or indexes like Lucene) so having Tomcat eat up all your heap is simply not an option.