    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
    015    package org.apache.tapestry5.internal.services;
    016
    017    import org.apache.tapestry5.MarkupWriter;
    018    import org.apache.tapestry5.internal.structure.Page;
    019    import org.apache.tapestry5.json.JSONObject;
    020    import org.apache.tapestry5.runtime.RenderCommand;
    021    import 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     */
    028    public 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    }