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

Go to download

Show more of this group Show more artifacts with this name
Show all versions of jakarta.faces-api Show documentation

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.0

Show newest version

/*
 * Copyright (c) 1997, 2018 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 javax.faces.context;

import javax.faces.FacesException;
import javax.faces.FacesWrapper;

/**
 * ExternalContextFactory
 * is a factory object that creates
 * (if needed) and returns new {@link ExternalContext} instances, initialized
 * for the processing of the specified request and response objects.
 *
 * There must be one ExternalContextFactory instance per web
 * application that is utilizing JavaServer Faces.  This instance can be
 * acquired, in a portable manner, by calling:
 *  *   ExternalContextFactory factory = (ExternalContextFactory)
 *    FactoryFinder.getFactory(FactoryFinder.EXTERNAL_CONTEXT_FACTORY);
 * 
 *
 * Usage: extend this class and push the implementation being wrapped to the
 * constructor and use {@link #getWrapped} to access the instance being wrapped.
 *
 */

public abstract class ExternalContextFactory implements FacesWrapper {

    private ExternalContextFactory wrapped;

    /**
     * @deprecated Use the other constructor taking the implementation being wrapped.
     */
    @Deprecated
    public ExternalContextFactory() {

    }

    /**
     * If this factory has been decorated,
     * the implementation doing the decorating should push the implementation being wrapped to this constructor.
     * The {@link #getWrapped()} will then return the implementation being wrapped.
     *
     * @param wrapped The implementation being wrapped.
     */
    public ExternalContextFactory(ExternalContextFactory wrapped) {
        this.wrapped = wrapped;
    }

    /**
     * If this factory has been decorated, the
     * implementation doing the decorating may override this method to provide
     * access to the implementation being wrapped.
     *
     * @since 2.0
     */
    @Override
    public ExternalContextFactory getWrapped() {
        return wrapped;
    }

    /**
     * Create (if needed)
     * and return an {@link ExternalContext} instance that is initialized
     * for the processing of the specified request and response objects,
     * for this web application.
     *
     * @param context In servlet environments, the
     * ServletContext that is associated with this web
     * application
     * @param request In servlet environments, the
     * ServletRequest that is to be processed
     * @param response In servlet environments, the
     * ServletResponse that is to be processed
     *
     * @return the instance of ExternalContext.
     *
     * @throws FacesException if a {@link ExternalContext} cannot be
     *  constructed for the specified parameters
     * @throws NullPointerException if any of the parameters
     *  are null
     *
     */
    public abstract ExternalContext getExternalContext
        (Object context, Object request,
         Object response) throws FacesException;


}