Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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
`ExceptionHandler()`

Method Summary
`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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002-2009 Sun Microsystems, Inc. All Rights Reserved.