Module jakarta.faces
Package jakarta.faces.context

Class ExceptionHandler

java.lang.Object
jakarta.faces.context.ExceptionHandler
All Implemented Interfaces:
FacesListener, SystemEventListener, EventListener
Direct Known Subclasses:
ExceptionHandlerImpl, ExceptionHandlerWrapper
public abstract class ExceptionHandler extends Object implements SystemEventListener

ExceptionHandler is the central point for handling unexpected Exceptions that are thrown during the Faces lifecycle. The ExceptionHandler must not be notified of any Exceptions that occur during application startup or shutdown.

See the Jakarta Faces Specification Document for the requirements for the default implementation. Exceptions may be passed to the ExceptionHandler in one of two ways:

  • by ensuring that Exceptions are not caught, or are caught and re-thrown.

    This approach allows the ExceptionHandler facility specified in section 6.2 "ExceptionHandler" of the Jakarta Faces Specification Document to operate on the Exception.

  • By using the system event facility to publish an ExceptionQueuedEvent that wraps the Exception.

    This approach requires manually publishing the ExceptionQueuedEvent, but allows more information about the Exceptionto be stored in the event. The following code is an example of how to do this. 

     

 //...
 } catch (Exception e) {
   FacesContext ctx = FacesContext.getCurrentInstance();
   ExceptionQueuedEventContext eventContext = new ExceptionQueuedEventContext(ctx, e);
   eventContext.getAttributes().put("key", "value");
   ctx.getApplication().publishEvent(ExceptionQueuedEvent.class, eventContext);
 }

    Because the Exception must not be re-thrown when using this approach, lifecycle processing may continue as normal, allowing more Exceptions to be published if necessary.

With either approach, any ExceptionQueuedEvent instances that are published in this way are accessible to the handle() method, which is called at the end of each lifecycle phase, as specified in section 6.2 "ExceptionHandler" of the Jakarta Faces Specification Document.

Note that if handle() happens to be invoked during PhaseId.RENDER_RESPONSE, the recovery options are more limited than when it is invoked during other phases. Specifically, it is not valid to call NavigationHandler.handleNavigation(jakarta.faces.context.FacesContext, java.lang.String, java.lang.String) during RENDER_RESPONSE.

Instances of this class are request scoped and are created by virtue of FacesContextFactory.getFacesContext(java.lang.Object, java.lang.Object, java.lang.Object, jakarta.faces.lifecycle.Lifecycle) calling ExceptionHandlerFactory.getExceptionHandler().

Since:
2.0