001// Copyright 2007, 2008, 2009, 2011 The Apache Software Foundation
002//
003// Licensed under the Apache License, Version 2.0 (the "License");
004// you may not use this file except in compliance with the License.
005// You may obtain a copy of the License at
006//
007// http://www.apache.org/licenses/LICENSE-2.0
008//
009// Unless required by applicable law or agreed to in writing, software
010// distributed under the License is distributed on an "AS IS" BASIS,
011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012// See the License for the specific language governing permissions and
013// limitations under the License.
014
015package org.apache.tapestry5.internal.services;
016
017import org.apache.tapestry5.MarkupWriter;
018import org.apache.tapestry5.internal.structure.Page;
019import org.apache.tapestry5.json.JSONObject;
020import org.apache.tapestry5.runtime.RenderCommand;
021import org.apache.tapestry5.services.PartialMarkupRendererFilter;
022
023/**
024 * A wrapper around {@link org.apache.tapestry5.runtime.RenderQueue}, but referencable as a (per-thread) service. This
025 * 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
026 * an elaborate scheme to keep certain interfaces public and other closely related ones private.
027 */
028public interface PageRenderQueue
029{
030    /**
031     * Initializes the queue for rendering of a complete page.
032     */
033    void initializeForCompletePage(Page page);
034
035    /**
036     * Sets the default page that will render the response.
037     */
038    void setRenderingPage(Page page);
039
040    /**
041     * Returns the page that is rendering markup content.
042     */
043    Page getRenderingPage();
044
045    /**
046     * Adds a rendering command to the queue of rendering commands. This must not be invoked until after
047     * the {@linkplain #setRenderingPage(org.apache.tapestry5.internal.structure.Page) rendering page has been identified}.
048     *
049     * @param renderer responsible for rendering a portion of the final markup
050     */
051    void addPartialRenderer(RenderCommand renderer);
052
053    /**
054     * Returns true if either {@link #addPartialRenderer(org.apache.tapestry5.runtime.RenderCommand)} or
055     * {@link #addPartialMarkupRendererFilter(org.apache.tapestry5.services.PartialMarkupRendererFilter)}
056     * has been invoked.
057     */
058    boolean isPartialRenderInitialized();
059
060    /**
061     * Render to the markup writer, as setup by the {@link #initializeForCompletePage(org.apache.tapestry5.internal.structure.Page)} or
062     * {@link #addPartialRenderer(org.apache.tapestry5.runtime.RenderCommand)} methods.
063     *
064     * @param writer to write markup to
065     */
066    void render(MarkupWriter writer);
067
068    /**
069     * Performs a partial markup render, as configured via
070     * {@link #addPartialRenderer(org.apache.tapestry5.runtime.RenderCommand)}.
071     *
072     * @param writer to which markup should be written
073     * @param reply  JSONObject which will contain the partial response
074     */
075    void renderPartial(MarkupWriter writer, JSONObject reply);
076
077    /**
078     * Adds an optional filter to the rendering. Optional filters are <em>temporary</em>, used just during the current
079     * partial render (as opposed to filters contributed to the
080     * {@link org.apache.tapestry5.services.PartialMarkupRenderer} service which are permanent, shared and stateless.
081     * <p/>
082     * Filters are added to the <em>end</em> of the pipeline (after all permanent contributions).
083     * <p/>
084     * Filters will be executed in the order in which they are added.
085     *
086     * @param filter to add to the pipeline
087     */
088    void addPartialMarkupRendererFilter(PartialMarkupRendererFilter filter);
089}