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