/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package javax.faces.application;

import javax.faces.FacesException;
import java.util.Locale;

/**
 * A ViewHandler manages the component-tree-creation and component-tree-rendering parts
 * of a request lifecycle (ie "create view", "restore view" and "render response").
 * <p>
 * A ViewHandler is responsible for generating the component tree when a new view is
 * requested; see method "createView".
 * <p>
 * When the user performs a "postback", ie activates a UICommand component within a view,
 * then the ViewHandler is resonsible for recreating a view tree identical to the one
 * used previously to render that view; see method "restoreView".
 * <p>
 * And the ViewHandler is also responsible for rendering the final output to be sent to the
 * user by invoking the rendering methods on components; see method "renderView".
 * <p>
 * This class also isolates callers from the underlying request/response system. In particular,
 * this class does not explicitly depend upon the javax.servlet apis. This allows JSF to be
 * used on servers that do not implement the servlet API (for example, plain CGI). 
 * <p>
 * Examples:
 * <ul>
 * <li>A JSP ViewHandler exists for using "jsp" pages as the presentation technology.
 * This class then works together with a taghandler class and a jsp servlet class to
 * implement the methods on this abstract class definition.
 * <li>A Facelets ViewHandler instead uses an xml file to define the components and non-component
 * data that make up a specific view. It stores all of the template content as nodes in the
 * component tree (wrapping data that is not directly a JSF component in its own special
 * component classes). Rendering a view is then just a matter of walking the component tree.
 * </ul>
 * Of course there is no reason why the "template" needs to be a textual file. A view could
 * be generated based on data in a database, or many other mechanisms.
 * <p>
 * This class is expected to be invoked via the concrete implementation of 
 * {@link javax.faces.lifecycle.Lifecycle}.
 * <p>
 * For the official specification for this class, see 
 * <a href="http://java.sun.com/j2ee/javaserverfaces/1.1_01/docs/api/index.html">JSF Specification</a>.
 *
 * @author Manfred Geiler (latest modification by $Author$)
 * @version $Revision$ $Date$
 */
public abstract class ViewHandler
{
    public static final String CHARACTER_ENCODING_KEY = "javax.faces.request.charset";
    public static final String DEFAULT_SUFFIX_PARAM_NAME = "javax.faces.DEFAULT_SUFFIX";
    public static final String DEFAULT_SUFFIX = ".jsp";

    /**
     * Return the Locale object that should be used when rendering this view to the
     * current user.
     * <p>
     * Some request protocols allow an application user to specify what locale they prefer
     * the response to be in. For example, HTTP requests can specify the "accept-language"
     * header.
     * <p>
     * Method {@link javax.faces.application.Application#getSupportedLocales()} defines
     * what locales this JSF application is capable of supporting.
     * <p>
     * This method should match such sources of data up and return the Locale object that
     * is the best choice for rendering the current application to the current user.
     */
    public abstract Locale calculateLocale(javax.faces.context.FacesContext context);

    /**
     * Return the id of an available render-kit that should be used to map the JSF
     * components into user presentation.
     * <p>
     * The render-kit selected (eg html, xhtml, pdf, xul, ...) may depend upon the user,
     * properties associated with the request, etc.
     */
    public abstract String calculateRenderKitId(javax.faces.context.FacesContext context);

    /**
     * Build a root node for a component tree.
     * <p>
     * When a request is received, this method is called if restoreView returns null,
     * ie this is not a "postback". In this case, a root node is created and then renderView
     * is invoked. It is the responsibility of the renderView method to build the full
     * component tree (ie populate the UIViewRoot with descendant nodes).
     * <p>
     * This method is also invoked when navigation occurs from one view to another, where
     * the viewId passed is the id of the new view to be displayed. Again it is the responsibility
     * of renderView to then populate the viewroot with descendants.
     */
    public abstract javax.faces.component.UIViewRoot createView(javax.faces.context.FacesContext context,
                                                                String viewId);

    /**
     * Return a URL that a remote system can invoke in order to access the specified view.
     */
    public abstract String getActionURL(javax.faces.context.FacesContext context,
                                        String viewId);

    /**
     * Return a URL that a remote system can invoke in order to access the specified resource..
     */
    public abstract String getResourceURL(javax.faces.context.FacesContext context,
                                          String path);

    /**
     * Combine the output of all the components in the viewToRender with data from the
     * original view template (if any) and write the result to context.externalContext.response.
     * <p>
     * Component output is generated by invoking the encodeBegin, encodeChildren (optional)
     * and encodeEnd methods on relevant components in the specified view. How this is
     * interleaved with the non-component content of the view template (if any) is left
     * to the ViewHandler implementation.
     * <p>
     * The actual type of the Response object depends upon the concrete implementation of
     * this class. It will almost certainly be an OutputStream of some sort, but may be
     * specific to the particular request/response  system in use.
     * <p>
     * If the view cannot be rendered (eg due to an error in a component) then a FacesException
     * is thrown.
     * <p>
     * Note that if a "postback" has occurred but no navigation to a different view, then
     * the viewToRender will be fully populated with components already. However on direct
     * access to a new view, or when navigation has occurred, the viewToRender will just
     * contain an empty UIViewRoot object that must be populated with components from
     * the "view template". 
     */
    public abstract void renderView(javax.faces.context.FacesContext context,
                                    javax.faces.component.UIViewRoot viewToRender)
            throws java.io.IOException,
            FacesException;

    /**
     * Handle a "postback" request by recreating the component tree that was most recently
     * presented to the user for the specified view.
     * <p>
     * When the user performs a "postback" of a view that has previously been created, ie
     * is updating the state of an existing view tree, then the view handler must recreate
     * a view tree identical to the one used previously to render that view to the user,
     * so that the data received from the user can be compared to the old state and the
     * correct "changes" detected.
     * <p>
     * The components in this tree will then be given the opportunity to examine new input
     * data provided by the user, and react in the appropriate manner for that component,
     * as specified for the JSF lifecycle.
     * <p>
     * Much of the work required by this method <i>must</i> be delegated to an instance
     * of StateManager.
     * <p>
     * If there is no record of the current user having been sent the specified view
     * (ie no saved state information available), then NULL should be returned.
     * <p>
     * Note that input data provided by the user may also be used to determine exactly
     * how to restore this view. In the case of "client side state", information
     * about the components to be restored will be available here. Even for
     * "server side state", user input may include an indicator that is used to
     * select among a number of different saved states available for this viewId and
     * this user.
     * <p>
     * Note that data received from users is inherently untrustworthy; care should be
     * taken to validate this information appropriately.
     * <p>
     * See saveState for more details. 
     */
    public abstract javax.faces.component.UIViewRoot restoreView(javax.faces.context.FacesContext context,
                                                                 String viewId);

    /**
     * Write sufficient information to context.externalContext.response in order to
     * be able to restore this view if the user performs a "postback" using that
     * rendered response.
     * <p>
     * For "client side state saving", sufficient information about the view
     * state should be written to allow a "restore view" operation to succeed 
     * later. This does not necessarily mean storing <i>all</i> data about the
     * current view; only data that cannot be recreated from the "template" for
     * this view needs to be saved.
     * <p>
     * For "server side state saving", this method may write out nothing. Alternately
     * it may write out a "state identifier" to identify which of multiple saved
     * user states for a particular view should be selected (or just verify that the
     * saved state does indeed correspond to the expected one).
     */
    public abstract void writeState(javax.faces.context.FacesContext context)
            throws java.io.IOException;
}