javax.faces.context: abstract public class: ExceptionHandler

javax.faces.context
abstract public class: ExceptionHandler [javadoc | source]

java.lang.Object
   javax.faces.context.ExceptionHandler

All Implemented Interfaces:
SystemEventListener

Direct Known Subclasses:
PreJsf2ExceptionHandler, ExceptionHandlerWrapper

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 specification prose 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 JSF.6.2 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 JSF.6.2.

Instances of this class are request scoped and are created by virtue of FacesContextFactory#getFacesContext calling ExceptionHandlerFactory#getExceptionHandler .

since: 2.0 -

Method from javax.faces.context.ExceptionHandler Summary:
getHandledExceptionQueuedEvent, getHandledExceptionQueuedEvents, getRootCause, getUnhandledExceptionQueuedEvents, handle, isListenerForSource, processEvent

Methods from java.lang.Object:
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method from javax.faces.context.ExceptionHandler Detail:
abstract public ExceptionQueuedEvent getHandledExceptionQueuedEvent() Return the first `ExceptionQueuedEvent` handled by this handler.
abstract public Iterable<ExceptionQueuedEvent> getHandledExceptionQueuedEvents() The default implementation must return an `Iterable` over all `ExceptionQueuedEvent`s that have been handled by the #handle method.
abstract public Throwable getRootCause(Throwable t) Unwrap the argument `t` until the unwrapping encounters an Object whose `getClass()` is not equal to `FacesException.class` or `javax.el.ELException.class`. If there is no root cause, `null` is returned.
abstract public Iterable<ExceptionQueuedEvent> getUnhandledExceptionQueuedEvents() Return an `Iterable` over all `ExceptionQueuedEvent`s that have not yet been handled by the #handle method.
abstract public void handle() throws FacesException Take action to handle the `Exception` instances residing inside the ExceptionQueuedEvent instances that have been queued by calls to `Application().publishEvent(ExceptionQueuedEvent.class, eventContext)`. The requirements of the default implementation are detailed in section JSF.6.2.1.
abstract public boolean isListenerForSource(Object source) {@inheritDoc}
abstract public void processEvent(SystemEvent exceptionQueuedEvent) throws AbortProcessingException {@inheritDoc}