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

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

Go to download

This is the master POM file for Oracle's Implementation of the JSF 2.3 Specification.

There is a newer version: 2.3-pfd
Show newest version
/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 1997-2010 Oracle and/or its affiliates. All rights reserved.
 *
 * The contents of this file are subject to the terms of either the GNU
 * General Public License Version 2 only ("GPL") or the Common Development
 * and Distribution License("CDDL") (collectively, the "License").  You
 * may not use this file except in compliance with the License.  You can
 * obtain a copy of the License at
 * https://glassfish.java.net/public/CDDL+GPL_1_1.html
 * or packager/legal/LICENSE.txt.  See the License for the specific
 * language governing permissions and limitations under the License.
 *
 * When distributing the software, include this License Header Notice in each
 * file and include the License file at packager/legal/LICENSE.txt.
 *
 * GPL Classpath Exception:
 * Oracle designates this particular file as subject to the "Classpath"
 * exception as provided by Oracle in the GPL Version 2 section of the License
 * file that accompanied this code.
 *
 * Modifications:
 * If applicable, add the following below the License Header, with the fields
 * enclosed by brackets [] replaced by your own identifying information:
 * "Portions Copyright [year] [name of copyright owner]"
 *
 * Contributor(s):
 * If you wish your version of this file to be governed by only the CDDL or
 * only the GPL Version 2, indicate your decision by adding "[Contributor]
 * elects to include this software in this distribution under the [CDDL or GPL
 * Version 2] license."  If you don't indicate a single choice of license, a
 * recipient has the option to distribute your version of this file under
 * either the CDDL, the GPL Version 2 or to extend the choice of license to
 * its licensees as provided above.  However, if you add GPL Version 2 code
 * and therefore, elected the GPL Version 2 license, then the option applies
 * only if the new code is made subject to such option by the copyright
 * holder.
 */

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); }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy