001// Copyright 2006-2013 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.services;
016
017import org.apache.tapestry5.MarkupWriter;
018import org.apache.tapestry5.http.ContentType;
019import org.apache.tapestry5.internal.structure.Page;
020
021/**
022 * Source for {@link org.apache.tapestry5.MarkupWriter} instances.
023 */
024public interface MarkupWriterFactory
025{
026    /**
027     * Creates a markup writer for a particular content type.
028     *
029     * @param contentType type of content generated by the markup write; used to control the type of {@link
030     *                    org.apache.tapestry5.dom.MarkupModel} used with the {@link org.apache.tapestry5.dom.Document}
031     *                    the backs the markup writer.
032     *                    
033     * @deprecated use {@link #newMarkupWriter(Page)} instead which doesn't rely on the content type alone.
034     */
035    MarkupWriter newMarkupWriter(ContentType contentType);
036
037    /**
038     * Creates a markup writer for a particular content type, configured for <em>partial page rendering</em> (i.e., for
039     * a response to an Ajax request).
040     *
041     * @param contentType type of content generated by the markup write; used to control the type of {@link
042     *                    org.apache.tapestry5.dom.MarkupModel} used with the {@link org.apache.tapestry5.dom.Document}
043     *                    the backs the markup writer.
044     *
045     * @deprecated use {@link #newPartialMarkupWriter(Page)} instead which doesn't rely on the content type alone.
046     */
047    MarkupWriter newPartialMarkupWriter(ContentType contentType);
048
049    /**
050     * Obtains a markup writer that will render the content for the provided logical page name.
051     * Convenience method for {@link #newMarkupWriter(Page)}
052     * 
053     * @param pageName
054     *            logical page name
055     * @return writer configured for the page
056     */
057    MarkupWriter newMarkupWriter(String pageName);
058    
059    /**
060     * Obtains a markup writer that will render the content for the provided logical page name,
061     * configured for <em>partial page rendering</em> (i.e., for a response to an Ajax request).
062     * Convenience method for {@link #newPartialMarkupWriter(Page)}
063     * 
064     * @param pageName
065     *            logical page name
066     * @return writer configured for the page
067     * 
068     * @since 5.4
069     */
070    MarkupWriter newPartialMarkupWriter(String pageName);
071    
072    /**
073     * Obtains a markup writer that will render the content for the provided page. Takes into
074     * account all necessary information such as the page's content type and doctype.
075     * 
076     * @param page the page to obtain a writer for
077     * @return writer configured for the page
078     * 
079     * @since 5.4
080     */
081    MarkupWriter newMarkupWriter(Page page);
082    
083    /**
084     * Obtains a markup writer that will render the content for the provided page,
085     * configured for <em>partial page rendering</em> (i.e., for a response to an Ajax request).
086     * Takes into account all necessary information such as the page's content type and doctype.
087     * 
088     * @param page
089     *            the page to obtain a writer for
090     * @return writer configured for the page
091     * 
092     * @since 5.4
093     */
094    MarkupWriter newPartialMarkupWriter(Page page);
095}