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;
014
015import org.apache.tapestry5.dom.Document;
016import org.apache.tapestry5.dom.Element;
017import org.apache.tapestry5.dom.MarkupModel;
018import org.apache.tapestry5.dom.Raw;
019
020import java.io.PrintWriter;
021
022/**
023 * An interface used by objects, such as Tapestry components, that need to render themselves as some form of XML markup.
024 * A markup writer maintains the idea of a current element. Attributes are added to the current element, and new text
025 * and elements are placed inside the current element. In this way, the markup writer maintains a facade that XML markup
026 * is generated as a stream, even though the implementation builds a kind of DOM tree. The DOM tree can be also be
027 * manipulated. This solves a number of problems from Tapestry 4 (and earlier) where random access to the DOM was
028 * desired and had to be simulated through complex buffering.
029 */
030public interface MarkupWriter
031{
032    /**
033     * Begins a new element as a child of the current element. The new element becomes the current element. The new
034     * Element is returned and can be directly manipulated (possibly at a later date). Optionally, attributes for the
035     * new element can be specified directly.
036     *
037     *
038     * @param name       the name of the element to create
039     * @param attributes an even number of values, alternating names and values
040     * @return the new DOM Element node
041     * @see #attributes(Object[])
042     */
043    Element element(String name, Object... attributes);
044
045    /**
046     * Ends the current element. The new current element will be the parent element. Returns the new current element
047     * (which may be null when ending the root element for the document).
048     */
049
050    Element end();
051
052    /**
053     * Writes the text as a child of the current element.
054     */
055
056    void write(String text);
057
058    /**
059     * Writes a formatted string.
060     */
061    void writef(String format, Object... args);
062
063    /**
064     * Writes <em>raw</em> text, text with existing markup that should be passed through the client without change. This
065     * can be useful when the markup is read from an external source (a file or a database) and is simply to be
066     * included.
067     *
068     * @param text
069     * @see Raw
070     */
071    void writeRaw(String text);
072
073    /**
074     * Adds an XML comment. The text should be just the comment content, the comment delimiters will be provided.
075     * Note that, as of Tapestry 5.2., no extra whitespace is added (previous releases added a space around the text).
076     */
077    void comment(String text);
078
079
080    /**
081     * Adds parsed character content. This will be enclosed in a CDATA block if supported.  When not supported, this is
082     * the same as {@link #write(String)}.
083     *
084     * @param content pre-parsed content
085     */
086    void cdata(String content);
087
088    /**
089     * Adds a series of attributes and values. Null values are quietly skipped. If a name already has a value, then the
090     * new value is <em>ignored</em>.
091     */
092    void attributes(Object... namesAndValues);
093
094    /**
095     * Converts the collected markup into an markup stream (according to rules provided by the {@link Document}'s {@link
096     * MarkupModel}). The markup stream is sent to the writer.
097     */
098    void toMarkup(PrintWriter writer);
099
100    /**
101     * Returns the Document into which this writer creates elements or other nodes.
102     */
103    Document getDocument();
104
105    /**
106     * Returns the currently active element.
107     */
108    Element getElement();
109
110    /**
111     * Defines a namespace for the currently active element. The namespace URI will be mapped to the provided namespace
112     * prefix within the Element.
113     *
114     * @param namespace       the namespace URI
115     * @param namespacePrefix the prefix for elements and attributes associated with the namespace    (may be the empty
116     *                        string for the default namespace)
117     * @return the currently active element
118     */
119    Element defineNamespace(String namespace, String namespacePrefix);
120
121    /**
122     * Starts an element within the given namespace. The correct namespace prefix will be identified and used. Must be
123     * balanced by a call to {@link #end()}.
124     *
125     * @param namespace   URI containing the element
126     * @param elementName name of the element within the namespace
127     * @return the new Element
128     */
129    Element elementNS(String namespace, String elementName);
130
131    /**
132     * Creates an attribute within the namespace for the current element.
133     *
134     * @param namespace      URI containing the element
135     * @param attributeName  name of the attribute within the namespace
136     * @param attributeValue the value for the attribute
137     * @return the currently active element
138     */
139    Element attributeNS(String namespace, String attributeName, String attributeValue);
140
141    /**
142     * Adds a markup writer listener that will be notified as elements are started and ended.
143     */
144    void addListener(MarkupWriterListener listener);
145
146    /**
147     * Removes a previously added listener.
148     */
149    void removeListener(MarkupWriterListener listener);
150}