    001// Licensed under the Apache License, Version 2.0 (the "License");
    002// you may not use this file except in compliance with the License.
    003// You may obtain a copy of the License at
    004//
    005// http://www.apache.org/licenses/LICENSE-2.0
    006//
    007// Unless required by applicable law or agreed to in writing, software
    008// distributed under the License is distributed on an "AS IS" BASIS,
    009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    010// See the License for the specific language governing permissions and
    011// limitations under the License.
    012
    013package org.apache.tapestry5.services;
    014
    015/**
    016 * An event handler method may return an instance of this class to trigger the rendering
    017 * of a particular page without causing a redirect to that page; the rendering takes place as part
    018 * of the original component event request, thus forming the opposite of Tapestry's normal
    019 * redirect-after-event behavior.
    020 *
    021 * The page will be activated using the provided page activation context (or an empty page activation
    022 * context). Starting with 5.3, the page activation step can be bypassed. Rendering occurs using
    023 * the standard {@link PageRenderRequestHandler} pipeline.
    024 *
    025 *
    026 * @since 5.2.0
    027 */
    028public final class StreamPageContent
    029{
    030    private final Class<?> pageClass;
    031
    032    private final Object[] pageActivationContext;
    033
    034    private final boolean bypassActivation;
    035
    036    /**
    037     * Creates an instance that streams the activate page's content (that is, {@link #getPageClass()} will be null).
    038     * Unless otherwise configured, page activation will take place.
    039     *
    040     * @since 5.4
    041     */
    042    public StreamPageContent()
    043    {
    044        this(null);
    045    }
    046
    047    /**
    048     * Renders the page using an empty page activation context.
    049     *
    050     * @param pageClass class of the page to render
    051     */
    052    public StreamPageContent(final Class<?> pageClass)
    053    {
    054        this(pageClass, (Object[]) null);
    055    }
    056
    057    /**
    058     * Renders the page using the supplied page activation context.
    059     *
    060     * @param pageClass             class of the page to render, or null to render the currently active page (as per
    061     *                              {@link org.apache.tapestry5.services.RequestGlobals#getActivePageName()})
    062     * @param pageActivationContext activation context of the page
    063     */
    064    public StreamPageContent(final Class<?> pageClass, final Object... pageActivationContext)
    065    {
    066        this(pageClass, pageActivationContext, false);
    067    }
    068
    069    private StreamPageContent(Class<?> pageClass, Object[] pageActivationContext, boolean bypassActivation)
    070    {
    071        this.pageClass = pageClass;
    072        this.pageActivationContext = pageActivationContext;
    073        this.bypassActivation = bypassActivation;
    074    }
    075
    076    /**
    077     * Returns the class of the page to render, or null to indicate that the active page for the request should simply
    078     * be re-rendered.
    079     */
    080    public Class<?> getPageClass()
    081    {
    082        return this.pageClass;
    083    }
    084
    085    /**
    086     * Returns the activation context of the page. May return null to indicate an empty activation context.
    087     */
    088    public Object[] getPageActivationContext()
    089    {
    090        return this.pageActivationContext;
    091    }
    092
    093    /**
    094     * Returns a new StreamPageInstance with the {@linkplain #isBypassActivation bypass activation flag} set to true, such that
    095     * page activation will be bypassed when the page is rendered.
    096     *
    097     * @return new instance
    098     */
    099    public StreamPageContent withoutActivation()
    100    {
    101        if (pageActivationContext != null)
    102        {
    103            throw new IllegalStateException("A StreamPageContext instance created with a page activation context may not be converted to bypass page activation.");
    104        }
    105
    106        return new StreamPageContent(pageClass, null, true);
    107    }
    108
    109    /**
    110     * @return true if configured to bypass activation
    111     */
    112    public boolean isBypassActivation()
    113    {
    114        return bypassActivation;
    115    }
    116}