jakarta.faces.context.ExceptionHandler Maven / Gradle / Ivy

Go to download
/*
 * Copyright (c) 1997, 2020 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 jakarta.faces.context;

import jakarta.faces.FacesException;
import jakarta.faces.event.AbortProcessingException;
import jakarta.faces.event.ExceptionQueuedEvent;
import jakarta.faces.event.SystemEvent;
import jakarta.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 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 {@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 6.2 "ExceptionHandler" of the Jakarta Faces Specification Document.
 * 
 *
 * 
 * Note that if {@link #handle} happens to be invoked during {@link 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
 * {@link jakarta.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 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 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 jakarta.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);

}