org.omnifaces.exceptionhandler

Class FullAjaxExceptionHandler

java.lang.Object

javax.faces.context.ExceptionHandler

javax.faces.context.ExceptionHandlerWrapper

org.omnifaces.exceptionhandler.FullAjaxExceptionHandler

All Implemented Interfaces:

EventListener, javax.faces.event.FacesListener, javax.faces.event.SystemEventListener, javax.faces.FacesWrapper<javax.faces.context.ExceptionHandler>

public class FullAjaxExceptionHandler
extends javax.faces.context.ExceptionHandlerWrapper

This exception handler enables you to show the full error page in its entirety to the end-user in case of exceptions during ajax requests. Refer to the documentation of FullAjaxExceptionHandlerFactory to see how to set this up.

This exception handler will parse the web.xml and web-fragment.xml files to find the error page locations of the HTTP error code 500 and all declared specific exception types. Those locations need to point to Facelets files (JSP is not supported). The location of the HTTP error code 500 or the exception type java.lang.Throwable is required in order to get the full ajax exception handler to work, because there's then at least a fall back error page whenever there's no match with any of the declared specific exceptions. So, you must at least have either

 <error-page>
   <error-code>500</error-code>
   <location>/errors/500.xhtml</location>
 </error-page>
 

or

 <error-page>
   <exception-type>java.lang.Throwable</exception-type>
   <location>/errors/500.xhtml</location>
 </error-page>
 

You can have both, but the java.lang.Throwable one will always get precedence over the 500 one, as per the Servlet API specification, so the 500 one would be basically superfluous.

The exception detail is available in the request scope by the standard Servlet error request attributes like as in a normal synchronous error page response. You could for example show them in the error page as follows:

 <ul>
   <li>Date/time: #{of:formatDate(now, 'yyyy-MM-dd HH:mm:ss')}</li>
   <li>User agent: #{header['user-agent']}</li>
   <li>User IP: #{request.remoteAddr}</li>
   <li>Request URI: #{requestScope['javax.servlet.error.request_uri']}</li>
   <li>Ajax request: #{facesContext.partialViewContext.ajaxRequest ? 'Yes' : 'No'}</li>
   <li>Status code: #{requestScope['javax.servlet.error.status_code']}</li>
   <li>Exception type: #{requestScope['javax.servlet.error.exception_type']}</li>
   <li>Exception message: #{requestScope['javax.servlet.error.message']}</li>
   <li>Stack trace:
     <pre>#{of:printStackTrace(requestScope['javax.servlet.error.exception'])}</pre>
   </li>
 </ul>
 

Exceptions during render response can only be handled when the javax.faces.FACELETS_BUFFER_SIZE is large enough so that the so far rendered response until the occurrence of the exception fits in there and can therefore safely be resetted. When rendering of the error page itself fails due to a bug in the error page itself and the response can still be resetted, then a hardcoded message will be returned informing the developer about the double mistake.

If more fine grained control is desired for determining the root cause of the caught exception, or whether it should be handled, or determining the error page, or logging the exception, then the developer can opt to extend this FullAjaxExceptionHandler and override one or more of the following methods:

• findExceptionRootCause(FacesContext, Throwable)
• shouldHandleExceptionRootCause(FacesContext, Throwable)
• findErrorPageLocation(FacesContext, Throwable)
• logException(FacesContext, Throwable, String, String, Object...)

Author:

Bauke Scholtz

See Also:

FullAjaxExceptionHandlerFactory

Constructor Summary

Constructors

Constructor and Description
FullAjaxExceptionHandler(javax.faces.context.ExceptionHandler wrapped) Construct a new ajax exception handler around the given wrapped exception handler.

Method Summary

Methods

Modifier and Type	Method and Description
protected String	findErrorPageLocation(javax.faces.context.FacesContext context, Throwable exception) Determine the error page location based on the given exception.
protected Throwable	findExceptionRootCause(javax.faces.context.FacesContext context, Throwable exception) Determine the root cause based on the caught exception, which will then be used to find the error page location.
javax.faces.context.ExceptionHandler	getWrapped()
void	handle() Handle the ajax exception as follows, only and only if the current request is an ajax request with an uncommitted response and there is at least one unhandled exception: Find the root cause of the exception by findExceptionRootCause(FacesContext, Throwable).
protected void	logException(javax.faces.context.FacesContext context, Throwable exception, String location, String message, Object... parameters) Log the thrown exception and determined error page location with the given message, optionally parameterized with the given parameters.
protected boolean	shouldHandleExceptionRootCause(javax.faces.context.FacesContext context, Throwable exception) Returns true if the FullAjaxExceptionHandler should handle this exception root cause.

Methods inherited from class javax.faces.context.ExceptionHandlerWrapper

getHandledExceptionQueuedEvent, getHandledExceptionQueuedEvents, getRootCause, getUnhandledExceptionQueuedEvents, isListenerForSource, processEvent

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FullAjaxExceptionHandler

public FullAjaxExceptionHandler(javax.faces.context.ExceptionHandler wrapped)

Construct a new ajax exception handler around the given wrapped exception handler.

Parameters:

wrapped - The wrapped exception handler.

Method Detail

handle

public void handle()
            throws javax.faces.FacesException

Handle the ajax exception as follows, only and only if the current request is an ajax request with an uncommitted response and there is at least one unhandled exception:

• Find the root cause of the exception by findExceptionRootCause(FacesContext, Throwable).
• Find the error page location based on root cause by findErrorPageLocation(FacesContext, Throwable).
• Set the standard servlet error request attributes.
• Force JSF to render the full error page in its entirety.

Any remaining unhandled exceptions will be swallowed. Only the first one is relevant.

Overrides:

handle in class javax.faces.context.ExceptionHandlerWrapper

Throws:

javax.faces.FacesException

findExceptionRootCause

protected Throwable findExceptionRootCause(javax.faces.context.FacesContext context,
                               Throwable exception)

Determine the root cause based on the caught exception, which will then be used to find the error page location. The default implementation delegates to Exceptions.unwrap(Throwable).

Parameters:

context - The involved faces context.

exception - The caught exception to determine the root cause for.

Returns:

The root cause of the caught exception.

Since:

1.5

shouldHandleExceptionRootCause

protected boolean shouldHandleExceptionRootCause(javax.faces.context.FacesContext context,
                                     Throwable exception)

Returns true if the FullAjaxExceptionHandler should handle this exception root cause. If this returns false, then the FullAjaxExceptionHandler will skip handling this exception and delegate it further to the wrapped exception handler. The default implementation just returns true.

Parameters:

context - The involved faces context.

exception - The caught exception to determine the root cause for.

Returns:

true if the given exception should be handled by the FullAjaxExceptionHandler.

Since:

1.8

findErrorPageLocation

protected String findErrorPageLocation(javax.faces.context.FacesContext context,
                           Throwable exception)

Determine the error page location based on the given exception. The default implementation delegates to WebXml.findErrorPageLocation(Throwable).

Parameters:

context - The involved faces context.

exception - The exception to determine the error page for.

Returns:

The location of the error page. It must start with / and be relative to the context path.

Since:

1.5

logException

protected void logException(javax.faces.context.FacesContext context,
                Throwable exception,
                String location,
                String message,
                Object... parameters)

Log the thrown exception and determined error page location with the given message, optionally parameterized with the given parameters. The default implementation logs through java.util.logging as SEVERE.

Parameters:

context - The involved faces context.

exception - The exception to log.

location - The error page location.

message - The log message.

parameters - The log message parameters, if any.

Since:

1.6

getWrapped

public javax.faces.context.ExceptionHandler getWrapped()

Specified by:

getWrapped in interface javax.faces.FacesWrapper<javax.faces.context.ExceptionHandler>

Overrides:

getWrapped in class javax.faces.context.ExceptionHandlerWrapper