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.http.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}