Class ExceptionHandler
- All Implemented Interfaces:
FacesListener
,SystemEventListener
,EventListener
- Direct Known Subclasses:
ExceptionHandlerImpl
,ExceptionHandlerWrapper
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 Jakarta Faces Specification 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 6.2 "ExceptionHandler" of the Jakarta Faces Specification Document to operate on theException
. -
By using the system event facility to publish an
ExceptionQueuedEvent
that wraps theException
.This approach requires manually publishing the
ExceptionQueuedEvent
, but allows more information about theException
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 moreException
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 6.2 "ExceptionHandler" of the Jakarta Faces Specification 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
-
Method Summary
Modifier and TypeMethodDescriptionabstract ExceptionQueuedEvent
Return the firstExceptionQueuedEvent
handled by this handler.abstract Iterable<ExceptionQueuedEvent>
The default implementation must return anIterable
over allExceptionQueuedEvent
s that have been handled by thehandle()
method.abstract Throwable
Unwrap the argumentt
until the unwrapping encounters an Object whosegetClass()
is not equal toFacesException.class
orjakarta.el.ELException.class
.abstract Iterable<ExceptionQueuedEvent>
Return anIterable
over allExceptionQueuedEvent
s that have not yet been handled by thehandle()
method.abstract void
handle()
Take action to handle theException
instances residing inside theExceptionQueuedEvent
instances that have been queued by calls toApplication().publishEvent(ExceptionQueuedEvent.class, eventContext)
.abstract boolean
isListenerForSource
(Object source) This method must returntrue
if and only if this listener instance is interested in receiving events from the instance referenced by thesource
parameter.abstract void
processEvent
(SystemEvent exceptionQueuedEvent) When called, the listener can assume that any guarantees given in the javadoc for the specificSystemEvent
subclass are true.
-
Constructor Details
-
ExceptionHandler
public ExceptionHandler()
-
-
Method Details
-
handle
Take action to handle the
Exception
instances residing inside theExceptionQueuedEvent
instances that have been queued by calls toApplication().publishEvent(ExceptionQueuedEvent.class, eventContext)
. The requirements of the default implementation are detailed in section 6.2.1 "Default ExceptionHandler implementation" of the Jakarta Faces Specification Document.- Throws:
FacesException
- if and only if a problem occurs while performing the algorithm to handle theException
, not as a means of conveying a handledException
itself.- Since:
- 2.0
-
getHandledExceptionQueuedEvent
Return the first
ExceptionQueuedEvent
handled by this handler.- Returns:
- instance of
ExceptionQueuedEvent
.
-
getUnhandledExceptionQueuedEvents
Return an
Iterable
over allExceptionQueuedEvent
s that have not yet been handled by thehandle()
method.- Returns:
- the unhandled set of
ExceptionQueuedEvent
s.
-
getHandledExceptionQueuedEvents
The default implementation must return an
Iterable
over allExceptionQueuedEvent
s that have been handled by thehandle()
method.- Returns:
- an
Iterable
over allExceptionQueuedEvent
s.
-
processEvent
When called, the listener can assume that any guarantees given in the javadoc for the specific
SystemEvent
subclass are true.- Specified by:
processEvent
in interfaceSystemEventListener
- Parameters:
exceptionQueuedEvent
- theSystemEvent
instance that is being processed.- Throws:
AbortProcessingException
- if lifecycle processing should cease for this request.
-
isListenerForSource
This method must return
true
if and only if this listener instance is interested in receiving events from the instance referenced by thesource
parameter.- Specified by:
isListenerForSource
in interfaceSystemEventListener
- 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
Unwrap the argument
t
until the unwrapping encounters an Object whosegetClass()
is not equal toFacesException.class
orjakarta.el.ELException.class
. If there is no root cause,null
is returned.- Parameters:
t
- passed-in wrappedThrowable
.- Returns:
- unwrapped object.
- Throws:
NullPointerException
- if argumentt
isnull
.- Since:
- 2.0
-