Integrating Spring & JavaServer Faces : Exception Handling

Most JSF developers will be familiar the “An Error Occurred” page that gets displayed when an unexpected exception is thrown somewhere their code. This page is really useful when developing but is not something you usually want for a production application. You generally have a couple of options when it comes to replacing this page with stock JSF; you can use define some HTML <error-page> elements in your web.xml or you can write a custom ExceptionHandler.

Neither option is ideal for a Spring developer, <error-page> elements tend to be too simplistic and it is hard to use Spring concepts, such as dependency injection, with custom ExceptionHandlers. Luckily both JSF and Spring are very extensible frameworks so a project that I have been working on to integrate the technologies can offer some compelling alternatives.

The first option available allows ExceptionHandlers to be registered as Spring beans. Rather than use the existing javax.faces.context.ExceptionHandler class a new org.springframework.springfaces.exceptionhandler.ExceptionHandler interface is available. The interface is pretty straight forward, it defines a single handle method that should return true if the exception has been handled. The interface uses a generic to limit the types of exception considered.

public interface ExceptionHandler<E extends Throwable> {
  boolean handle(E exception, ExceptionQueuedEvent event) throws Exception;
}

All relevant beans beans that implement the ExceptionHandler interface will be consulted when an exception occurs from JSF. The first handler to return true will ‘win’ and subsequent handlers will not be called. You can use the org.springframework.core.Ordered interface or the @Ordered annotation if you need to sort your handlers. Of course, now that exception handlers are regular Spring beans, you can use all the standard Spring functionality such a dependency injection and AOP.

Now that we have basic exception handler hooks we can go on to offer a couple of useful implementations:

Sometimes the best way to handle certain exceptions is to simply show a message and remain on the current screen. For example, suppose a service throws TooManyResultsException when search queries are too broad. A simple message telling the user to ‘try again with more precise terms’ might be the only exception handling required. The org.springframework.springfaces.exceptionhandler.ObjectMessageExceptionHandler class builds on previous work that maps Objects to messages. Include an entry in your Spring MessageSource with the fully qualified name of the Exception as the key and a FacesMessage will be shown if the exception is thrown.

com.mycorp.search.TooManyResultsException=Too many results found, please try again with more precise search terms

You can easily map any number of exceptions to messages, you can even refer to properties of the exception using ‘{property}‘ placeholders in your message string. Messages can be displayed on the screen using standard JSF techniques (usually a <h:messages/> component).

Support for quickly mapping exceptions to messages is nice but it won’t be enough for a lot of applications and writing ExceptionHandler beans can quickly become tiresome. The final optional available is org.springframework.springfaces.mvc.exceptionhandler.DispatcherExceptionHandler. The DispatcherExceptionHandler provides a bridge between JSF and Spring MVC that allows you to use @ExceptionHandler annotations in your @Controllers as you would with any other Spring MVC application. Methods annotated with @ExceptionHandler are really versatile and can have very flexible signatures; you can deal with exceptions directly or return a view that should be rendered:

@ExceptionHandler
public String handle(ExampleException e) {
  return "redirect:errorpage";
}

Using @ExceptionHandler annotations with Spring MVC is a very natural fit and there have been numerous articles written on the subject. Hopefully existing JSF developers will find the Spring MVC programming style an attractive alternative to standard JSF.

Please take a look at the other articles in this series and if you want to examine the exception handing code the ‘org.springframework.springfaces.exceptionhandler’ and ‘org.springframework.springfaces.mvc.exceptionhandler’ packages are a good place to start.