facesview.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.spring.context.servlet;

import java.util.Map;

import javax.faces.FactoryFinder;
import javax.faces.component.UIViewRoot;
import javax.faces.context.FacesContext;
import javax.faces.lifecycle.Lifecycle;
import javax.faces.lifecycle.LifecycleFactory;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.springframework.util.Assert;
import org.springframework.web.servlet.view.AbstractUrlBasedView;

import de.mindmatters.faces.lifecycle.LifecycleImpl;

/**
 * Wrapper for a JSP or other resource within the same faces web application.
 * 
 * <p>
 * Rendering is delegated to the {@link Lifecycle} of the underlying JSF
 * implementation.
 * </p>
 * 
 * <p>
 * {@link UIViewRoot} creation is done by this class (if not already created by
 * other components such as a NavigationHandler).
 * </p>
 * 
 * <p>
 * Typical usage with {@link FacesViewResolver} would look as follows, from the
 * perspective of the {@link FacesDispatcherServlet} context definition:
 * 
 * <pre class="code">
 * &lt;bean id=&quot;viewResolver&quot; class=&quot;de.mindmatters.faces.spring.context.servlet.FacesViewResolver&quot;&gt;
 *    &lt;property name=&quot;prefix&quot; value=&quot;/WEB-INF/jsp/&quot;/&gt;
 *    &lt;property name=&quot;suffix&quot; value=&quot;.jsp&quot;/&gt;
 * &lt;/bean&gt;
 * </pre>
 * 
 * Every view name returned from a handler will be translated to a JSP resource
 * (for example: "myView" -> "/WEB-INF/jsp/myView.jsp"), using this view class
 * by default.
 * </p>
 * 
 * @author Andreas Kuhrwahl
 * @see Lifecycle#render(FacesContext)
 * @see javax.faces.application.ViewHandler#createView(FacesContext, String)
 * 
 */
public class FacesView extends AbstractUrlBasedView {

    /** The JSF lifecycle for execution and rendering. */
    private Lifecycle lifecycle;

    /** The id for the currently used lifecycle. */
    private String lifecycleId = LifecycleImpl.JSF_SPRING_LIFECYCLE_ID;

    /**
     * Constructor for use as a bean.
     */
    public FacesView() {
    }

    /**
     * Create a new FacesView with the given URL <code>url</code>.
     * 
     * @param url
     *            the URL to forward to
     */
    public FacesView(final String url) {
        setUrl(url);
    }

    /**
     * Create a new FacesView with the given {@link UIViewRoot}
     * <code>viewRoot</code>.
     * 
     * @param viewRoot
     *            the {@link UIViewRoot} to render
     */
    public FacesView(final UIViewRoot viewRoot) {
        this(viewRoot.getViewId());
    }

    /**
     * Resolves the appropriate {@link Lifecycle} depending on the configured
     * lifecycle-id.
     * 
     * @throws Exception
     *             in the case of errors
     * 
     * @see #setLifecycleId(String)
     */
    public final void afterPropertiesSet() throws Exception {
        super.afterPropertiesSet();
        final LifecycleFactory lifecycleFactory = (LifecycleFactory) FactoryFinder
                .getFactory(FactoryFinder.LIFECYCLE_FACTORY);
        this.lifecycle = lifecycleFactory.getLifecycle(this.lifecycleId);
        initFacesView();
    }

    /**
     * This hook method will be invoked after any bean properties have been set
     * and the {@link Lifecycle} has been resolved. The default implementation
     * is empty; subclasses may override this method to perform any
     * initialization they require.
     */
    protected void initFacesView() {
    }

    /**
     * @return The resolved {@link Lifecycle} that will be used by this
     *         {@link org.springframework.web.servlet.View} for rendering.
     */
    protected final Lifecycle getLifecycle() {
        return lifecycle;
    }

    /**
     * Sets the lifecycle-id for resolving the appropriate {@link Lifecycle}.
     * 
     * @param lifecycleId
     *            the lifecycle-id identifying the {@link Lifecycle} to use
     */
    public final void setLifecycleId(final String lifecycleId) {
        Assert.notNull(lifecycleId);
        this.lifecycleId = lifecycleId;
    }

    /**
     * Expose helpers unique to each rendering operation. This is necessary so
     * that different rendering operations can't overwrite each other's contexts
     * etc.
     * <p>
     * Called by
     * {@link #renderMergedOutputModel(Map, HttpServletRequest, HttpServletResponse)}.
     * The default implementation is empty. This method can be overridden to add
     * custom helpers as request attributes.
     * </p>
     * 
     * @param request
     *            current HTTP request
     * @throws Exception
     *             if there's a fatal error while we're adding attributes
     * @see #renderMergedOutputModel
     */
    protected void exposeHelpers(final HttpServletRequest request)
            throws Exception {
    }

    /**
     * Prepare for rendering, and determine the the view id to render by the
     * resolved {@link Lifecycle}.
     * <p>
     * This implementation simply returns the configured URL. Subclasses can
     * override this to determine a resource to render, typically interpreting
     * the URL in a different manner.
     * </p>
     * 
     * @param request
     *            current HTTP request
     * @param response
     *            current HTTP response
     * @return the request dispatcher path to use
     * @throws Exception
     *             if preparations failed
     * @see #getUrl
     */
    protected String prepareViewIdForRendering(
            final HttpServletRequest request, final HttpServletResponse response)
            throws Exception {
        return getUrl();
    }

    /**
     * {@inheritDoc}
     */
    protected final void renderMergedOutputModel(final Map model,
            final HttpServletRequest request, final HttpServletResponse response)
            throws Exception {
        FacesContext context = FacesContext.getCurrentInstance();
        Assert.notNull(context);
        exposeModelAsRequestAttributes(model, request);
        exposeHelpers(request);
        exposeViewRootIfNecessary(context, prepareViewIdForRendering(request,
                response));
        render(context);
    }

    /**
     * Creates and exposes the {@link UIViewRoot} to the given
     * {@link FacesContext} if necessary. This could be the case if the creation
     * of the {@link UIViewRoot} is not done yet by another component such as
     * the {@link javax.faces.application.NavigationHandler}.
     * 
     * @param context
     *            {@link FacesContext} for the current request
     * @param viewId
     *            the prepared view identifier of the view to render
     * @see FacesContext#getRenderResponse()
     */
    protected void exposeViewRootIfNecessary(final FacesContext context,
            final String viewId) {
        Assert.hasText(viewId);
        if (!context.getRenderResponse()) {
            UIViewRoot viewRoot = context.getViewRoot();
            if (!viewId.equals(viewRoot.getViewId())) {
                viewRoot = context.getApplication().getViewHandler()
                        .createView(context, viewId);
                context.setViewRoot(viewRoot);
            }
            context.renderResponse();
        }
    }

    /**
     * Renders the appropriate view with the help of the resolved
     * {@link Lifecycle}.
     * 
     * @param context
     *            {@link FacesContext} for the current request
     * @throws javax.faces.FacesException
     *             if an exception is thrown during the rendering
     * @see Lifecycle#render(FacesContext)
     */
    protected void render(final FacesContext context) {
        this.lifecycle.render(context);
    }

}