viewbuilder.java

Please read your package and describe it at least 40 bytes in English. System will automatically de

/*
 * Copyright 2002-2004 the original author or authors.
 *
 * Licensed 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 de.mindmatters.faces.application;

import java.io.IOException;

import javax.faces.application.ViewHandler;
import javax.faces.component.UIViewRoot;
import javax.faces.context.FacesContext;

/**
 * <strong>ViewBuilder</strong> is the pluggablity mechanism for allowing
 * implementations of or applications using the JavaServer Faces specification
 * to provide their own handling of the activities in the
 * <em>Render Response</em> and <em>Restore View</em> phases of the request
 * processing lifecycle.
 * 
 * <p>
 * A <strong>ViewBuilder</strong> has the ability to create, restore and
 * <strong>build</strong> a view. Building a view means restoring the component
 * tree structure of a faces view without the need of a serialized tree
 * structure state. Method {@link ViewBuilder#buildView(FacesContext, String)}
 * will be invoked everytime a view id ({@link de.mindmatters.faces.FacesUtils#VIEWID_PARAM})
 * and <strong>no</strong> component view state is submitted by a request.
 * </p>
 * 
 * <p>
 * <em><strong>Note: Usually a view created by
 * {@link ViewBuilder#buildView(FacesContext, String)} holds the default
 * component state. Any state changes of the components during the request
 * lifecycle will be ignored since it cannot be restored (because usually
 * whether component tree state nor component value state is submitted)</strong></em>
 * </p>
 * 
 * @author Andreas Kuhrwahl
 * @see AbstractDelegatingViewBuilder
 * @see FaceletViewBuilder
 */
public abstract class ViewBuilder extends ViewHandler {

    /**
     * Marks a request to <strong>not</strong> save the state of the view into
     * the response.
     */
    private static final String DO_NOT_SAVESTATE_MARKER = ViewBuilder.class
            .getName();

    /**
     * Marks a request to <strong>not</strong> save the state of the view into
     * the response.
     * 
     * @param context
     *            {@link FacesContext} for the current request
     */
    public static final void markForTransientState(final FacesContext context) {
        context.getExternalContext().getRequestMap().put(
                DO_NOT_SAVESTATE_MARKER, DO_NOT_SAVESTATE_MARKER);
    }

    /**
     * Releases the marker to <strong>not</strong> save the state of the view
     * into the response.
     * 
     * @param context
     *            {@link FacesContext} for the current request
     */
    public static final void unmarkTransientState(final FacesContext context) {
        context.getExternalContext().getRequestMap().remove(
                DO_NOT_SAVESTATE_MARKER);
    }

    /**
     * Checks whether the request is marked for writing the state of a view or
     * not.
     * 
     * @param context
     *            {@link FacesContext} for the current request
     * @return <code>true</code> if the request is marked for state saving
     *         <code>false</code> otherwise
     */
    private static boolean isMarkedForStateWriting(final FacesContext context) {
        return !context.getExternalContext().getRequestMap().containsKey(
                DO_NOT_SAVESTATE_MARKER);
    }

    /**
     * {@inheritDoc}
     */
    public final void writeState(final FacesContext context) throws IOException {
        if (context == null) {
            throw new NullPointerException("FacesContext");
        }
        if (isMarkedForStateWriting(context)
                && context.getApplication().getStateManager()
                        .isSavingStateInClient(context)) {
            writeStateInClient(context);
        }
    }

    /**
     * Writes the state of a view into the response. Usually this is done by
     * calling {@link javax.faces.application.StateManager#writeState}
     * 
     * @param context
     *            {@link FacesContext} for the current request
     * @throws IOException
     *             if an input/output error occurs
     * @see ViewHandler#writeState(FacesContext)
     */
    protected abstract void writeStateInClient(FacesContext context)
            throws IOException;

    /**
     * Perform whatever actions are required to build the view associated with
     * the specified {@link FacesContext} and <code>viewId</code>. Building a
     * view means to restore the component tree structure of a view
     * <strong>without</strong> the need of a serialized state representing the
     * structure.
     * 
     * @param context
     *            {@link FacesContext} for the current request
     * @param viewId
     *            the view identifier for the current request
     * @return Built {@link UIViewRoot} representing the view
     * 
     * @exception NullPointerException
     *                if <code>context</code> is <code>null</code>
     * @exception javax.faces.FacesException
     *                if a servlet error occurs
     */
    public abstract UIViewRoot buildView(FacesContext context, String viewId);

}