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 }