1 // Copyright 2006, 2007, 2008 The Apache Software Foundation
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 package org.apache.tapestry5;
16
17 import org.apache.tapestry5.dom.Document;
18 import org.apache.tapestry5.dom.Element;
19 import org.apache.tapestry5.dom.MarkupModel;
20 import org.apache.tapestry5.dom.Raw;
21
22 import java.io.PrintWriter;
23
24 /**
25 * An interface used by objects, such as Tapestry components, that need to render themselves as some form of XML markup.
26 * A markup writer maintains the idea of a current element. Attributes are added to the current element, and new text
27 * and elements are placed inside the current element. In this way, the markup writer maintains a facade that XML markup
28 * is generated as a stream, even though the implementation builds a kind of DOM tree. The DOM tree can be also be
29 * manipulated. This solves a number of problems from Tapestry 4 (and earlier) where random access to the DOM was
30 * desired and had to be simulated through complex buffering.
31 */
32 public interface MarkupWriter
33 {
34 /**
35 * Begins a new element as a child of the current element. The new element becomes the current element. The new
36 * Element is returned and can be directly manipulated (possibly at a later date). Optionally, attributes for the
37 * new element can be specified directly.
38 * <p/>
39 *
40 * @param name the name of the element to create
41 * @param attributes an even number of values, alternating names and values
42 * @return the new DOM Element node
43 * @see #attributes(Object[])
44 */
45 Element element(String name, Object... attributes);
46
47 /**
48 * Ends the current element. The new current element will be the parent element. Returns the new current element
49 * (which may be null when ending the root element for the document).
50 */
51
52 Element end();
53
54 /**
55 * Writes the text as a child of the current element.
56 */
57
58 void write(String text);
59
60 /**
61 * Writes a formatted string.
62 */
63 void writef(String format, Object... args);
64
65 /**
66 * Writes <em>raw</em> text, text with existing markup that should be passed through the client without change. This
67 * can be useful when the markup is read from an external source (a file or a database) and is simply to be
68 * included.
69 *
70 * @param text
71 * @see Raw
72 */
73 void writeRaw(String text);
74
75 /**
76 * Adds an XML comment. The text should be just the comment content, the comment delimiters will be provided.
77 */
78 void comment(String text);
79
80
81 /**
82 * Adds parsed character content. This will be enclosed in a CDATA block if supported. When not supported, this is
83 * the same as {@link #write(String)}.
84 *
85 * @param content pre-parsed content
86 */
87 void cdata(String content);
88
89 /**
90 * Adds a series of attributes and values. Null values are quietly skipped. If a name already has a value, then the
91 * new value is <em>ignored</em>.
92 */
93 void attributes(Object... namesAndValues);
94
95 /**
96 * Converts the collected markup into an markup stream (according to rules provided by the {@link Document}'s {@link
97 * MarkupModel}). The markup stream is sent to the writer.
98 */
99 void toMarkup(PrintWriter writer);
100
101 /**
102 * Returns the Document into which this writer creates elements or other nodes.
103 */
104 Document getDocument();
105
106 /**
107 * Returns the currently active element.
108 */
109 Element getElement();
110
111 /**
112 * Defines a namespace for the currently active element. The namespace URI will be mapped to the provided namespace
113 * prefix within the Element.
114 *
115 * @param namespace the namespace URI
116 * @param namespacePrefix the prefix for elements and attributes associated with the namespace (may be the empty
117 * string for the default namespace)
118 * @return the currently active element
119 */
120 Element defineNamespace(String namespace, String namespacePrefix);
121
122 /**
123 * Starts an element within the given namespace. The correct namespace prefix will be identified and used. Must be
124 * balanced by a call to {@link #end()}.
125 *
126 * @param namespace URI containing the element
127 * @param elementName name of the element within the namespace
128 * @return the new Element
129 */
130 Element elementNS(String namespace, String elementName);
131
132 /**
133 * Creates an attribute within the namespace for the current element.
134 *
135 * @param namespace URI containing the element
136 * @param attributeName name of the attribute within the namespace
137 * @param attributeValue the value for the attribute
138 * @return the currently active element
139 */
140 Element attributeNS(String namespace, String attributeName, String attributeValue);
141
142 /**
143 * Adds a markup writer listener that will be notified as elements are started and ended.
144 */
145 void addListener(MarkupWriterListener listener);
146
147 /**
148 * Removes a previously added listener.
149 */
150 void removeListener(MarkupWriterListener listener);
151 }