|Version status: 0.1.2 beta, used in production|
In your Tapestry 5 applications, are you missing the standard error-page/exception-type configuration option specified by the servlet spec? For some rarely occurring exceptions, it's simpler to just catch them at the outermost layer of your application rather than carry a typed exception through multiple layers of abstractions just so you could show a sensible error message to the user, especially if you can't do anything more clever about it anyway. Unfortunately Tapestry wraps up all of your exceptions inside a ComponentEventException making the error-page/exception-type configuration in your web.xml useless. The default Tapestry 5 exception page is great for development but typically, you don't want to show that in production.
The servlet spec, as always, is rather restrictive in regards to error-page configuration. If your email service or an external payment service goes down, you can't do much more than display an error message to the user, so why would you need to implement separate pages for each exception? Often, it'd be nicer if you could just reuse the page template for any fatal exception and simply display a different error message. Tapestry-exceptionpage allows you to contribute handlers for specific types of exceptions and provide context for rendering the error page for that specific exception.
To use the feature, you need to add the following dependency to your pom.xml:
You can contribute an error page, mapping it to an exception type:
If a simple exception type to page mapping doesn't do it for you, you can also contribute a custom handler for that particular exception type. An ExceptionHandlerAssistant can contain arbitrarily complex logic for handling a specific exception type and use other Tapestry services. If ExceptionHandlerAssistant.handleRequestException(Throwable exception, List<Object> exceptionContext) returns an Object representing an URL the main handler will issue a redirect to that URL. It's valid to return either a String, a Link or a Class; the last case implies a page class. If the ExceptionHandlerAssistant returns null, it's assumed that the assistant has independently handled the exception. You can either contribute an instance of an ExceptionHandlerAssistant or a class that implements ExceptionHandlerAssistant. Below, we contribute an instance handling ServiceExceptions:
You can also specify context for the exception page. For generic exceptions, the context is taken from the exception class name minus the word "Exception" in case that's how the class name ends. For example, you have a following class:
If your custom-handled exception implements the interface ContextAwareException you can fully specify the context for the error page. For example, you could implement a following Exception class:
This exception handling mechanism can easily be overused. Typically, if you can handle the exception locally, you should. Likewise, you shouldn't blindly wrap any checked exceptions inside runtime exceptions just to avoid writing try-catch blocks in higher layers. The exceptionpage module is best used for handling serious but rarely occurring exceptions happening in the action request cycle that you cannot otherwise cope with.