All Downloads are FREE. Search and download functionalities are using the official Maven repository.

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

Go to download

Jakarta Faces defines an MVC framework for building user interfaces for web applications, including UI components, state management, event handing, input validation, page navigation, and support for internationalization and accessibility.

There is a newer version: 4.1.2
Show newest version
/*
 * 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); }




© 2015 - 2025 Weber Informatics LLC | Privacy Policy