1   /*
    2    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    3    * 
    4    * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
    5    * 
    6    * The contents of this file are subject to the terms of either the GNU
    7    * General Public License Version 2 only ("GPL") or the Common Development
    8    * and Distribution License("CDDL") (collectively, the "License").  You
    9    * may not use this file except in compliance with the License. You can obtain
   10    * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
   11    * or glassfish/bootstrap/legal/LICENSE.txt.  See the License for the specific
   12    * language governing permissions and limitations under the License.
   13    * 
   14    * When distributing the software, include this License Header Notice in each
   15    * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
   16    * Sun designates this particular file as subject to the "Classpath" exception
   17    * as provided by Sun in the GPL Version 2 section of the License file that
   18    * accompanied this code.  If applicable, add the following below the License
   19    * Header, with the fields enclosed by brackets [] replaced by your own
   20    * identifying information: "Portions Copyrighted [year]
   21    * [name of copyright owner]"
   22    * 
   23    * Contributor(s):
   24    * 
   25    * If you wish your version of this file to be governed by only the CDDL or
   26    * only the GPL Version 2, indicate your decision by adding "[Contributor]
   27    * elects to include this software in this distribution under the [CDDL or GPL
   28    * Version 2] license."  If you don't indicate a single choice of license, a
   29    * recipient has the option to distribute your version of this file under
   30    * either the CDDL, the GPL Version 2 or to extend the choice of license to
   31    * its licensees as provided above.  However, if you add GPL Version 2 code
   32    * and therefore, elected the GPL Version 2 license, then the option applies
   33    * only if the new code is made subject to such option by the copyright
   34    * holder.
   35    */
   36   
   37   package javax.faces.context;
   38   
   39   import javax.faces.FacesWrapper;
   40   
   41   /**
   42    * <p class="changed_added_2_0"><strong>ExceptionHandlerFactory</strong>
   43    * is a factory object that creates (if needed) and returns a new {@link
   44    * ExceptionHandler} instance.</p>
   45    *
   46    * <div class="changed_added_2_0">
   47   
   48    * <p>There must be one <code>ExceptionHandlerFactory</code> instance per web
   49    * application that is utilizing JavaServer Faces.  This instance can be
   50    * acquired, in a portable manner, by calling:</p>
   51    *
   52    * <pre><code>
   53    *   ExceptionHandlerFactory factory = (ExceptionHandlerFactory)
   54    *    FactoryFinder.getFactory(FactoryFinder.EXCEPTION_HANDLER_FACTORY);
   55    * </code></pre>
   56    *
   57   
   58    * </div>
   59    *
   60    * @since 2.0
   61    */
   62   
   63   public abstract class ExceptionHandlerFactory implements FacesWrapper<ExceptionHandlerFactory> {
   64   
   65   
   66       /**
   67        * <p class="changed_added_2_0">If this factory has been decorated, the 
   68        * implementation doing the decorating may override this method to provide
   69        * access to the implementation being wrapped.  A default implementation
   70        * is provided that returns <code>null</code>.</p>
   71        */
   72       public ExceptionHandlerFactory getWrapped() {
   73           return null;
   74       }
   75   
   76       
   77       /**
   78        * <p class="changed_added_2_0">Create and return a A new
   79        * <code>ExceptionHandler</code> instance.  The implementation must return
   80        * an <code>ExceptionHandler</code> instance suitable for the environment.
   81        * For example, in some cases it may be desirable for an 
   82        * <code>ExceptionHandler</code> to write error information
   83        * to the response instead of throwing exceptions as in the case of
   84        * Ajax applications.</p> 
   85        */
   86       public abstract ExceptionHandler getExceptionHandler();
   87       
   88   }