javax.faces.context

## Class ExceptionHandler

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

- All Implemented Interfaces:
    EventListener, FacesListener, SystemEventListener
  Direct Known Subclasses:
    ExceptionHandlerWrapper

      public abstract class ExceptionHandler
      extends Object
      implements SystemEventListener

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

  See the specification prose document for the requirements for the default implementation. `Exception`s may be passed to the `ExceptionHandler` in one of two ways:

  - by ensuring that `Exception`s 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 `Exception`to 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 `Exception`s 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(java.lang.Object, java.lang.Object, java.lang.Object, javax.faces.lifecycle.Lifecycle)` calling `ExceptionHandlerFactory.getExceptionHandler()`.

  Since:
    2.0

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ExceptionHandler()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract ExceptionQueuedEvent` | `getHandledExceptionQueuedEvent()` Return the first `ExceptionQueuedEvent` handled by this handler.
    `abstract Iterable<ExceptionQueuedEvent>` | `getHandledExceptionQueuedEvents()` The default implementation must return an `Iterable` over all `ExceptionQueuedEvent`s that have been handled by the `handle()` method.
    `abstract 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`.
    `abstract Iterable<ExceptionQueuedEvent>` | `getUnhandledExceptionQueuedEvents()` Return an `Iterable` over all `ExceptionQueuedEvent`s that have not yet been handled by the `handle()` method.
    `abstract void` | `handle()` Take action to handle the `Exception` instances residing inside the `ExceptionQueuedEvent` instances that have been queued by calls to `Application().publishEvent(ExceptionQueuedEvent.class, eventContext)`.
    `abstract boolean` | `isListenerForSource(Object source)` This method must return `true` if and only if this listener instance is interested in receiving events from the instance referenced by the `source` parameter.
    `abstract void` | `processEvent(SystemEvent exceptionQueuedEvent)` When called, the listener can assume that any guarantees given in the javadoc for the specific `SystemEvent` subclass are true.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### ExceptionHandler

          public ExceptionHandler()

  - ### Method Detail

    - #### handle

          public abstract 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.

      Throws:
        `FacesException` - if and only if a problem occurs while performing the algorithm to handle the `Exception`, not as a means of conveying a handled `Exception` itself.
      Since:
        2.0

    - #### getHandledExceptionQueuedEvent

          public abstract ExceptionQueuedEvent getHandledExceptionQueuedEvent()

      Return the first `ExceptionQueuedEvent` handled by this handler.

    - #### getUnhandledExceptionQueuedEvents

          public abstract Iterable<ExceptionQueuedEvent> getUnhandledExceptionQueuedEvents()

      Return an `Iterable` over all `ExceptionQueuedEvent`s that have not yet been handled by the `handle()` method.

    - #### getHandledExceptionQueuedEvents

          public abstract Iterable<ExceptionQueuedEvent> getHandledExceptionQueuedEvents()

      The default implementation must return an `Iterable` over all `ExceptionQueuedEvent`s that have been handled by the `handle()` method.

    - #### processEvent

          public abstract void processEvent(SystemEvent exceptionQueuedEvent)
                                     throws AbortProcessingException

      When called, the listener can assume that any guarantees given in the javadoc for the specific `SystemEvent` subclass are true.

      Specified by:
        `processEvent` in interface `SystemEventListener`
      Parameters:
        `exceptionQueuedEvent` - the `SystemEvent` instance that is being processed.
      Throws:
        `AbortProcessingException` - if lifecycle processing should cease for this request.

    - #### isListenerForSource

          public abstract boolean isListenerForSource(Object source)

      This method must return `true` if and only if this listener instance is interested in receiving events from the instance referenced by the `source` parameter.

      Specified by:
        `isListenerForSource` in interface `SystemEventListener`
      Parameters:
        `source` - the source that is inquiring about the appropriateness of sending an event to this listener instance.

    - #### getRootCause

          public abstract 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.

      Throws:
        `NullPointerException` - if argument `t` is `null`.
      Since:
        2.0

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.