javax.faces.context.ExceptionHandler Maven / Gradle / Ivy
Show all versions of jboss-jsf-api_2.3_spec Show documentation
/*
* Copyright (c) 1997, 2018 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
package javax.faces.context;
import javax.faces.FacesException;
import javax.faces.event.AbortProcessingException;
import javax.faces.event.ExceptionQueuedEvent;
import javax.faces.event.SystemEvent;
import javax.faces.event.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 JSF.6.2 to operate on the
* Exception.
*
* By using the system event facility to publish an {@link
* ExceptionQueuedEvent} that wraps the Exception.
*
* This approach requires manually publishing the {@link
* 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 {@link #handle}
* method, which is called at the end of each lifecycle phase, as
* specified in section JSF.6.2.
* Note that if {@link #handle} happens to
* be invoked during {@link javax.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 {@link
* javax.faces.application.NavigationHandler#handleNavigation} during
* {@code RENDER_RESPONSE}.
* Instances of this class are request scoped and are created by
* virtue of {@link FacesContextFactory#getFacesContext} calling {@link
* ExceptionHandlerFactory#getExceptionHandler}.
*
*
*
* @since 2.0
*/
public abstract class ExceptionHandler implements SystemEventListener {
/**
* Take action to handle the
* Exception instances residing inside the {@link
* 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
*/
public abstract void handle() throws FacesException;
/**
* Return the first
* ExceptionQueuedEvent handled by this handler.
*
* @return instance of ExceptionQueuedEvent.
*
*/
public abstract ExceptionQueuedEvent getHandledExceptionQueuedEvent();
/**
* Return an Iterable over
* all ExceptionQueuedEvents that have not yet been handled
* by the {@link #handle} method.
*
* @return the unhandled set of ExceptionQueuedEvents.
*
*/
public abstract Iterable getUnhandledExceptionQueuedEvents();
/**
* The default implementation must
* return an Iterable over all
* ExceptionQueuedEvents that have been handled by the {@link
* #handle} method.
*
* @return an Iterable over all ExceptionQueuedEvents.
*
*/
public abstract Iterable getHandledExceptionQueuedEvents();
/**
* {@inheritDoc}
*/
@Override
public abstract void processEvent(SystemEvent exceptionQueuedEvent) throws AbortProcessingException;
/**
* {@inheritDoc}
*/
@Override
public abstract boolean isListenerForSource(Object source);
/**
* 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.
*
* @param t passed-in wrapped Throwable.
*
* @return unwrapped object.
*
* @throws NullPointerException if argument t is
* null.
*
* @since 2.0
*/
public abstract Throwable getRootCause(Throwable t);
}