ExceptionHandler

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

All Implemented Interfaces:

FacesListener, SystemEventListener, java.util.EventListener

Direct Known Subclasses:

ExceptionHandlerWrapper
```
public abstract class ExceptionHandler
extends java.lang.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:
- by ensuring that Exceptions are not caught, or are caught and re-thrown.
  
  This approach allows the ExceptionHandler facility specified in section 6.2 of the spec prose 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 of the spec prose 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

Constructor Summary

Constructors
Constructor and Description

ExceptionHandler()

Constructors
Constructor and Description
`ExceptionHandler()`

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`abstract ExceptionQueuedEvent`	`getHandledExceptionQueuedEvent()` Return the first `ExceptionQueuedEvent` handled by this handler.
`abstract java.lang.Iterable<ExceptionQueuedEvent>`	`getHandledExceptionQueuedEvents()` The default implementation must return an `Iterable` over all `ExceptionQueuedEvent`s that have been handled by the `handle()` method.
`abstract java.lang.Throwable`	`getRootCause(java.lang.Throwable t)` Unwrap the argument `t` until the unwrapping encounters an Object whose `getClass()` is not equal to `FacesException.class` or `jakarta.el.ELException.class`.
`abstract java.lang.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(java.lang.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 6.2.1 of the spec prose document.
    
    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.
    
    Returns:
    
    instance of ExceptionQueuedEvent.
  - getUnhandledExceptionQueuedEvents
```
public abstract java.lang.Iterable<ExceptionQueuedEvent> getUnhandledExceptionQueuedEvents()
```
    Return an Iterable over all ExceptionQueuedEvents that have not yet been handled by the handle() method.
    
    Returns:
    
    the unhandled set of ExceptionQueuedEvents.
  - getHandledExceptionQueuedEvents
```
public abstract java.lang.Iterable<ExceptionQueuedEvent> getHandledExceptionQueuedEvents()
```
    The default implementation must return an Iterable over all ExceptionQueuedEvents that have been handled by the handle() method.
    
    Returns:
    
    an Iterable over all ExceptionQueuedEvents.
  - 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(java.lang.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.
    
    Returns:
    
    the value as specified above
  - getRootCause
```
public abstract java.lang.Throwable getRootCause(java.lang.Throwable t)
```
    Unwrap the argument t until the unwrapping encounters an Object whose getClass() is not equal to FacesException.class or jakarta.el.ELException.class. If there is no root cause, null is returned.
    
    Parameters:
    
    t - passed-in wrapped Throwable.
    
    Returns:
    
    unwrapped object.
    
    Throws:
    
    java.lang.NullPointerException - if argument t is null.
    
    Since:
    
    2.0

Class ExceptionHandler

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ExceptionHandler

Method Detail

handle

getHandledExceptionQueuedEvent

getUnhandledExceptionQueuedEvents

getHandledExceptionQueuedEvents

processEvent

isListenerForSource

getRootCause