    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.internal.services;
    014
    015import org.apache.tapestry5.MarkupWriter;
    016import org.apache.tapestry5.internal.structure.Page;
    017import org.apache.tapestry5.json.JSONObject;
    018import org.apache.tapestry5.runtime.RenderCommand;
    019import org.apache.tapestry5.services.PartialMarkupRendererFilter;
    020
    021/**
    022 * A wrapper around {@link org.apache.tapestry5.runtime.RenderQueue}, but referencable as a (per-thread) service. This
    023 * service is scoped so that we can tell it what to render in one method, then have it do the render in another. Part of
    024 * an elaborate scheme to keep certain interfaces public and other closely related ones private.
    025 */
    026public interface PageRenderQueue
    027{
    028    /**
    029     * Initializes the queue for rendering of a complete page.
    030     */
    031    void initializeForCompletePage(Page page);
    032
    033    /**
    034     * Sets the default page that will render the response.
    035     */
    036    void setRenderingPage(Page page);
    037
    038    /**
    039     * Returns the page that is rendering markup content.
    040     */
    041    Page getRenderingPage();
    042
    043    /**
    044     * Adds a rendering command to the queue of rendering commands. This must not be invoked until after
    045     * the {@linkplain #setRenderingPage(org.apache.tapestry5.internal.structure.Page) rendering page has been identified}.
    046     *
    047     * @param renderer responsible for rendering a portion of the final markup
    048     */
    049    void addPartialRenderer(RenderCommand renderer);
    050
    051    /**
    052     * Returns true if either {@link #addPartialRenderer(org.apache.tapestry5.runtime.RenderCommand)} or
    053     * {@link #addPartialMarkupRendererFilter(org.apache.tapestry5.services.PartialMarkupRendererFilter)}
    054     * has been invoked.
    055     */
    056    boolean isPartialRenderInitialized();
    057
    058    /**
    059     * Render to the markup writer, as setup by the {@link #initializeForCompletePage(org.apache.tapestry5.internal.structure.Page)} or
    060     * {@link #addPartialRenderer(org.apache.tapestry5.runtime.RenderCommand)} methods.
    061     *
    062     * @param writer to write markup to
    063     */
    064    void render(MarkupWriter writer);
    065
    066    /**
    067     * Performs a partial markup render, as configured via
    068     * {@link #addPartialRenderer(org.apache.tapestry5.runtime.RenderCommand)}.
    069     *
    070     * @param writer to which markup should be written
    071     * @param reply  JSONObject which will contain the partial response
    072     */
    073    void renderPartial(MarkupWriter writer, JSONObject reply);
    074
    075    /**
    076     * Adds an optional filter to the rendering. Optional filters are <em>temporary</em>, used just during the current
    077     * partial render (as opposed to filters contributed to the
    078     * {@link org.apache.tapestry5.services.PartialMarkupRenderer} service which are permanent, shared and stateless.
    079     *
    080     * Filters are added to the <em>end</em> of the pipeline (after all permanent contributions).
    081     *
    082     * Filters will be executed in the order in which they are added.
    083     *
    084     * @param filter to add to the pipeline
    085     */
    086    void addPartialMarkupRendererFilter(PartialMarkupRendererFilter filter);
    087}