javax.faces.context
Class ExceptionHandler

java.lang.Object
  extended by 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 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:

With either approach, any ExceptionEvent 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 12.3.

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  ExceptionEvent getHandledExceptionEvent()
          

Return the first ExceptionEvent handled by this handler.

abstract  Iterable<ExceptionEvent> getHandledExceptionEvents()
          

The default implementation must return an Iterable over all ExceptionEvents 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<ExceptionEvent> getUnhandledExceptionEvents()
          

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

abstract  void handle()
          

Take action to handle the Exception instances residing inside the ExceptionEvent instances that have been queued by calls to Application().publishEvent(ExceptionEvent.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 exceptionEvent)
          

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 ExceptionEvent instances that have been queued by calls to Application().publishEvent(ExceptionEvent.class, eventContext). The requirements of the default implementation are detailed in section 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

getHandledExceptionEvent

public abstract ExceptionEvent getHandledExceptionEvent()

Return the first ExceptionEvent handled by this handler.


getUnhandledExceptionEvents

public abstract Iterable<ExceptionEvent> getUnhandledExceptionEvents()

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


getHandledExceptionEvents

public abstract Iterable<ExceptionEvent> getHandledExceptionEvents()

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


processEvent

public abstract void processEvent(SystemEvent exceptionEvent)
                           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:
exceptionEvent - 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 © 2002-2008 Sun Microsystems, Inc. All Rights Reserved.