Dealing Gracefully with ViewExpiredException in JSF2

My previous entry dove under the covers for JSF 2.0 and examined composite component metadata. This one is far less esoteric and shows how to handle the ViewExpiredException using a new JSF feature, the ExceptionHandler, contributed by Pete Muir a JSF Expert Group representative from JBoss.

JSF throws a ViewExpiredException when a postback is made to a view and, for whatever reason, that view cannot be restored. Usually this is due to a session timeout, but a custom state management solution could also cause this exception to be thrown. The default behavior in JSF2 is to show the Facelets error page saying View Expired. The default page is illustrated at right.

One way to fix this is to declare an <error-page> element in your web.xml, as shown here.

This works well enough. You can even put JSF components on the error page if you put the proper Faces Servlet mapping in the <location> element, as shown above. If you want to do some application level manipulation in response to the exception, you'll want something different, however. In this case, a custom ExceptionHandler is just the trick. I cover this in much more detial in my upcoming book, JavaServer Faces 2.0: The Complete Reference, and the example shown in this blog entry is neatly integrated into the chapter 10 sample app. Consider this blog entry an appetizer. So delete that old web.xml (it's not needed if you have JSF2 and Servlet 3, which you get in Glassfish V3) and let's go.

First, we need to install a custom ExceptionHandler. This is done using the tried and true JSF decorator pattern. In this case, we place the following into the faces-config.xml. There's no annotation for this because it's relatively uncommon, and we expect advanced users to use the feature. Therefore, the EG tradeoff was to not add yet another "scan for this annotation" clause to the spec.

Here's the code for the class.

The interesting things happen on lines 15 - 20. This method is called once per request must return a new ExceptionHandler instance each time it's called. I know the method name should be createExceptionHandler, but we stuck with "get" for consistence with other JSF methods. On line 17, we call the real ExceptionHandlerFactory and ask it to create the instance, which we then wrap in our custom ViewExpiredExceptionExceptionHandlerFactory class. This is where the real interesting stuff happens.

On line 15, you see we take advantage of the javax.faces.context.ExceptionHandlerWrapper convenience class. JSF has lots of these wrapper classes and when you use them, you need only override the getWrapped() method to return the instance of the class you're wrapping, which is often simply passed to the constructor, as shown on lines 19 - 21. Once you override getWrapped(), you need only override those methods you're interested in. In this case, we want to override only handle(), which we do on lines 29 - 57.

We iterate over the unhandler exceptions using the iterator returned from getUnhandledExceptionQueuedEvents().iterator(), as shown on line 30. The ExeceptionQueuedEvent is a SystemEvent (also described in detail in my book) from which we can get the actual ViewExpiredException, which I do on line 35. I know I'm going to be ultimately showing a JSF page so I want to extract some information from the exception and place it in request scope, so I can access it via EL in the page. I do this on line 37.

On lines 45 and 46, I leverage the JSF implicit navigation system and cause the server to navigate to the "viewExpired" page. This assumes, of course, that there is a viewExpired.xhtml page out there. Naturally, you could parameterize this howevere you like, context-param, annotation, whatever. Line 46 causes the intervening lifecycle phases to be skipped.

Note that we have a try-finally block here, and in the finally block, on line 49, we call remove() on the iterator. This is an important part of the ExceptionHandler usage contract. If you handle an exception, you have to remove it from the list of unhandled exceptions. That way, we know it's safe to call getWrapped().handle() on line 55.

Finally, let's see my cheesy viewExpired.xhtml page in action, shown at left.

This page is not much more visually appealing than the default one, but that's not JSF's fault! The one in the JSF2 book will look nicer. Here's the source for this cheesy one.

Note that we show the data from the exception on line 15.

This entry showed you how to programmatically intercept the ViewExpiredException and do something nice with it. If you have any other state that you can show in the page, it's easy to include it in the Facelets view.

Technorati Tags: edburns