EE4J Web API 10.0.0 · jakarta.faces.context.ExceptionHandler

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 Jakarta Faces Specification 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 "ExceptionHandler" of the Jakarta Faces Specification 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 "ExceptionHandler" of the Jakarta Faces Specification Document.

Note that if handle happens to be invoked during jakarta.faces.event.PhaseId#RENDER_RESPONSE, the recovery options are more limited than when it is invoked during other phases. Specifically, it is not valid to call jakarta.faces.application.NavigationHandler#handleNavigation during RENDER_RESPONSE.

Instances of this class are request scoped and are created by virtue of FacesContextFactory#getFacesContext calling ExceptionHandlerFactory#getExceptionHandler.

Constructor Summary

Access	Constructor and Description
public	ExceptionHandler()

Method Summary

Modifier and Type	Method and Description
public abstract ExceptionQueuedEvent	Returns: instance of `ExceptionQueuedEvent`. getHandledExceptionQueuedEvent() Return the first `ExceptionQueuedEvent` handled by this handler.
public abstract Iterable<ExceptionQueuedEvent>	Returns: an `Iterable` over all `ExceptionQueuedEvent`s. getHandledExceptionQueuedEvents() The default implementation must return an `Iterable` over all `ExceptionQueuedEvent`s that have been handled by the `handle` method.
public abstract Throwable	Returns: unwrapped object. getRootCause(Throwable passed-in wrapped `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`.
public abstract Iterable<ExceptionQueuedEvent>	Returns: the unhandled set of `ExceptionQueuedEvent`s. getUnhandledExceptionQueuedEvents() Return an `Iterable` over all `ExceptionQueuedEvent`s that have not yet been handled by the `handle` method.
public 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)`.
public abstract boolean	isListenerForSource(Object the source that is inquiring about the appropriateness of sending an event to this listener instance. source) Redeclares jakarta.faces.event.SystemEventListener.isListenerForSource. 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.
public abstract void	processEvent(SystemEvent the `SystemEvent` instance that is being processed. exceptionQueuedEvent) Redeclares jakarta.faces.event.SystemEventListener.processEvent. When called, the listener can assume that any guarantees given in the javadoc for the specific `SystemEvent` subclass are true.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Detail

ExceptionHandler	back to summary
public ExceptionHandler()

Method Detail

getHandledExceptionQueuedEvent back to summary

getHandledExceptionQueuedEvent	back to summary
public abstract ExceptionQueuedEvent getHandledExceptionQueuedEvent() Return the first `ExceptionQueuedEvent` handled by this handler. Returns:ExceptionQueuedEvent instance of `ExceptionQueuedEvent`.

public abstract ExceptionQueuedEvent getHandledExceptionQueuedEvent()

Return the first ExceptionQueuedEvent handled by this handler.

Returns:ExceptionQueuedEvent: instance of ExceptionQueuedEvent.

getHandledExceptionQueuedEvents back to summary

getHandledExceptionQueuedEvents	back to summary
public abstract Iterable<ExceptionQueuedEvent> getHandledExceptionQueuedEvents() The default implementation must return an `Iterable` over all `ExceptionQueuedEvent`s that have been handled by the `handle` method. Returns:Iterable<ExceptionQueuedEvent> an `Iterable` over all `ExceptionQueuedEvent`s.

public abstract Iterable<ExceptionQueuedEvent> getHandledExceptionQueuedEvents()

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

Returns:Iterable<ExceptionQueuedEvent>: an Iterable over all ExceptionQueuedEvents.

getRootCause back to summary

getRootCause	back to summary
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 `jakarta.el.ELException.class`. If there is no root cause, `null` is returned. Parameters t:Throwable passed-in wrapped `Throwable`. Returns:Throwable unwrapped object. Exceptions NullPointerException: if argument `t` is `null`. Since 2.0

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 jakarta.el.ELException.class. If there is no root cause, null is returned.

Parameters

t:Throwable: passed-in wrapped Throwable.

Returns:Throwable

unwrapped object.

Exceptions

NullPointerException:: if argument t is null.

Since

2.0

getUnhandledExceptionQueuedEvents back to summary

getUnhandledExceptionQueuedEvents	back to summary
public abstract Iterable<ExceptionQueuedEvent> getUnhandledExceptionQueuedEvents() Return an `Iterable` over all `ExceptionQueuedEvent`s that have not yet been handled by the `handle` method. Returns:Iterable<ExceptionQueuedEvent> the unhandled set of `ExceptionQueuedEvent`s.

public abstract Iterable<ExceptionQueuedEvent> getUnhandledExceptionQueuedEvents()

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

Returns:Iterable<ExceptionQueuedEvent>: the unhandled set of ExceptionQueuedEvents.

handle back to summary

handle	back to summary
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 "Default ExceptionHandler implementation" of the Jakarta Faces Specification Document. Exceptions 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

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 "Default ExceptionHandler implementation" of the Jakarta Faces Specification Document.

Exceptions

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

isListenerForSource back to summary

isListenerForSource	back to summary
public abstract boolean isListenerForSource(Object source) Redeclares jakarta.faces.event.SystemEventListener.isListenerForSource. Doc from jakarta.faces.event.SystemEventListener.isListenerForSource. 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. Parameters source:Object the source that is inquiring about the appropriateness of sending an event to this listener instance. Returns:boolean the value as specified above Annotations @Override

public abstract boolean isListenerForSource(Object source)

Redeclares jakarta.faces.event.SystemEventListener.isListenerForSource.

Doc from jakarta.faces.event.SystemEventListener.isListenerForSource.

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.

Parameters

source:Object: the source that is inquiring about the appropriateness of sending an event to this listener instance.

Returns:boolean

the value as specified above

Annotations

@Override

processEvent back to summary

processEvent	back to summary
public abstract void processEvent(SystemEvent exceptionQueuedEvent) throws AbortProcessingException Redeclares jakarta.faces.event.SystemEventListener.processEvent. Doc from jakarta.faces.event.SystemEventListener.processEvent. When called, the listener can assume that any guarantees given in the javadoc for the specific `SystemEvent` subclass are true. Parameters exceptionQueuedEvent:SystemEvent the `SystemEvent` instance that is being processed. Annotations @Override Exceptions AbortProcessingException: if lifecycle processing should cease for this request.

public abstract void processEvent(SystemEvent exceptionQueuedEvent) throws AbortProcessingException

Redeclares jakarta.faces.event.SystemEventListener.processEvent.

Doc from jakarta.faces.event.SystemEventListener.processEvent.

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

Parameters

exceptionQueuedEvent:SystemEvent: the SystemEvent instance that is being processed.

Annotations

@Override

Exceptions

AbortProcessingException:: if lifecycle processing should cease for this request.

public abstract Class ExceptionHandler

Constructor Summary

Method Summary

Constructor Detail

Method Detail