Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
IMarkupWriter |
|
| 1.0;1 |
1 | // Copyright 2004, 2005 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.tapestry; | |
16 | ||
17 | import org.apache.tapestry.markup.Attribute; | |
18 | ||
19 | /** | |
20 | * Defines an object that can write markup (XML, HTML, XHTML) style output. A | |
21 | * <code>IMarkupWriter</code> handles translation from unicode to the markup language (escaping | |
22 | * characters such as '<' and '>' to their entity equivalents, '&lt;' and '&gt;') as | |
23 | * well as assisting with nested elements, closing tags, etc. | |
24 | * | |
25 | * @author Howard Ship, David Solis | |
26 | */ | |
27 | ||
28 | public interface IMarkupWriter | |
29 | { | |
30 | /** | |
31 | * Writes an integer attribute into the currently open tag. | |
32 | * | |
33 | * @throws IllegalStateException | |
34 | * if there is no open tag. | |
35 | */ | |
36 | ||
37 | void attribute(String name, int value); | |
38 | ||
39 | /** | |
40 | * Writes a boolean attribute into the currently open tag. | |
41 | * | |
42 | * @throws IllegalStateException | |
43 | * if there is no open tag. | |
44 | * @since 3.0 | |
45 | */ | |
46 | ||
47 | void attribute(String name, boolean value); | |
48 | ||
49 | /** | |
50 | * Writes an attribute into the most recently opened tag. This must be called after | |
51 | * {@link #begin(String)}and before any other kind of writing (which closes the tag). | |
52 | * <p> | |
53 | * The value may be null. | |
54 | * | |
55 | * @throws IllegalStateException | |
56 | * if there is no open tag. | |
57 | */ | |
58 | ||
59 | void attribute(String name, String value); | |
60 | ||
61 | /** | |
62 | * Similar to {@link #attribute(String, String)}but no escaping of invalid elements is done for | |
63 | * the value. | |
64 | * | |
65 | * @throws IllegalStateException | |
66 | * if there is no open tag. | |
67 | * @since 3.0 | |
68 | */ | |
69 | ||
70 | void attributeRaw(String name, String value); | |
71 | ||
72 | /** | |
73 | * Appends an integer attribute to the current attribute with a matching | |
74 | * <code>name</code> key, if one exists. | |
75 | * | |
76 | * @throws IllegalStateException | |
77 | * if there is no open tag. | |
78 | */ | |
79 | ||
80 | void appendAttribute(String name, int value); | |
81 | ||
82 | /** | |
83 | * Appends a boolean attribute into the currently open tag. | |
84 | * | |
85 | * @throws IllegalStateException | |
86 | * if there is no open tag. | |
87 | * @since 3.0 | |
88 | */ | |
89 | ||
90 | void appendAttribute(String name, boolean value); | |
91 | ||
92 | /** | |
93 | * Appends an attribute into the most recently opened tag. This must be called after | |
94 | * {@link #begin(String)} and before any other kind of writing (which closes the tag). | |
95 | * <p> | |
96 | * The value may be null. | |
97 | * | |
98 | * @throws IllegalStateException | |
99 | * if there is no open tag. | |
100 | */ | |
101 | ||
102 | void appendAttribute(String name, String value); | |
103 | ||
104 | /** | |
105 | * Similar to {@link #attribute(String, String)} but no escaping of invalid elements is done for | |
106 | * the value. | |
107 | * | |
108 | * @throws IllegalStateException | |
109 | * if there is no open tag. | |
110 | * @since 3.0 | |
111 | */ | |
112 | ||
113 | void appendAttributeRaw(String name, String value); | |
114 | ||
115 | /** | |
116 | * Checks if the current tag has an attribute keyed off of <code>name</code>. | |
117 | * | |
118 | * @param name | |
119 | * The name of the attribute to check for existance of. | |
120 | * @return | |
121 | * True if the attribute exists, false otherwise. | |
122 | * @throws IllegalStateException | |
123 | * If there is no open tag. | |
124 | */ | |
125 | boolean hasAttribute(String name); | |
126 | ||
127 | /** | |
128 | * Gets the attribute matching <code>name</code> from the current open | |
129 | * tag, if it exists. | |
130 | * | |
131 | * @param name | |
132 | * The attribute to get the value of by name. | |
133 | * @return | |
134 | * The attribute value, or null if it doesn't exist. | |
135 | * @throws IllegalStateException | |
136 | * If there is no open tag. | |
137 | */ | |
138 | Attribute getAttribute(String name); | |
139 | ||
140 | /** | |
141 | * Removes the attribute specified with a matching <code>name</code> if | |
142 | * one exists. | |
143 | * | |
144 | * @param name | |
145 | * The attribute to remove. | |
146 | * @return | |
147 | * The removed attribute, null if one didn't exist. | |
148 | * @throws IllegalStateException | |
149 | * If there is no open tag. | |
150 | */ | |
151 | Attribute removeAttribute(String name); | |
152 | ||
153 | /** | |
154 | * Removes all current attributes on the open tag, if any. | |
155 | * | |
156 | * @throws IllegalStateException | |
157 | * If there is no open tag. | |
158 | */ | |
159 | void clearAttributes(); | |
160 | ||
161 | /** | |
162 | * Closes any existing tag then starts a new element. The new element is pushed onto the active | |
163 | * element stack. | |
164 | */ | |
165 | ||
166 | void begin(String name); | |
167 | ||
168 | /** | |
169 | * Starts an element that will not later be matched with an <code>end()</code> call. This is | |
170 | * useful for elements that do not need closing tags. | |
171 | */ | |
172 | ||
173 | void beginEmpty(String name); | |
174 | ||
175 | /** | |
176 | * Invokes checkError() on the <code>PrintWriter</code> used to format output. | |
177 | */ | |
178 | ||
179 | boolean checkError(); | |
180 | ||
181 | /** | |
182 | * Closes this <code>IMarkupWriter</code>. Close tags are written for any active elements. | |
183 | * The <code>PrintWriter</code> is then sent <code>close()</code>. A nested writer will | |
184 | * commit its buffer to its containing writer. | |
185 | */ | |
186 | ||
187 | void close(); | |
188 | ||
189 | /** | |
190 | * Closes the most recently opened element by writing the '>' that ends it. Once this is | |
191 | * invoked, the <code>attribute()</code> methods may not be used until a new element is opened | |
192 | * with {@link #begin(String)}or or {@link #beginEmpty(String)}. | |
193 | */ | |
194 | ||
195 | void closeTag(); | |
196 | ||
197 | /** | |
198 | * Writes an XML/HTML comment. Any open tag is first closed. The method takes care of providing | |
199 | * the <code><!--</code> and <code>--></code>, and provides a blank line after the | |
200 | * close of the comment. | |
201 | * <p> | |
202 | * <em>Most</em> characters are valid inside a comment, so no check of the contents is made | |
203 | * (much like {@link #printRaw(String)}. | |
204 | */ | |
205 | ||
206 | void comment(String value); | |
207 | ||
208 | /** | |
209 | * Ends the element most recently started by {@link #begin(String)}. The name of the tag is | |
210 | * popped off of the active element stack and used to form an HTML close tag. | |
211 | */ | |
212 | ||
213 | void end(); | |
214 | ||
215 | /** | |
216 | * Ends the most recently started element with the given name. This will also end any other | |
217 | * intermediate elements. This is very useful for easily ending a table or even an entire page. | |
218 | */ | |
219 | ||
220 | void end(String name); | |
221 | ||
222 | /** | |
223 | * Forwards <code>flush()</code> to this <code>IMarkupWriter</code>'s | |
224 | * <code>PrintWriter</code>. | |
225 | */ | |
226 | ||
227 | void flush(); | |
228 | ||
229 | /** | |
230 | * Returns a nested writer, one that accumulates its changes in a buffer. When the nested writer | |
231 | * is closed, it writes its buffer of markup into its containing <code>IMarkupWriter</code> | |
232 | * using {@link #printRaw(String)}. | |
233 | */ | |
234 | ||
235 | NestedMarkupWriter getNestedWriter(); | |
236 | ||
237 | /** | |
238 | * Version of {@link #print(char[], int, int, boolean)} that assumes filter is | |
239 | * <em>enabled</em>. | |
240 | */ | |
241 | ||
242 | void print(char[] data, int offset, int length); | |
243 | ||
244 | /** | |
245 | * The primary <code>print()</code> method, used by most other methods. | |
246 | * <p> | |
247 | * Prints the character array, first closing any open tag. Problematic characters ('<', | |
248 | * '>' and '&') are converted to appropriate entities. | |
249 | * <p> | |
250 | * Does <em>nothing</em> if <code>data</code> is null. | |
251 | * <p> | |
252 | * Closes any open tag. | |
253 | * | |
254 | * @param data | |
255 | * contains the characters to print, or null to not print anything | |
256 | * @param offset | |
257 | * offset into the array to start printing from | |
258 | * @param length | |
259 | * number of characters to print | |
260 | * @param raw | |
261 | * if true, filtering is disabled | |
262 | * @since 4.0 | |
263 | */ | |
264 | ||
265 | void print(char[] data, int offset, int length, boolean raw); | |
266 | ||
267 | /** | |
268 | * Prints a single character, or its equivalent entity. | |
269 | * <p> | |
270 | * Closes any open tag. | |
271 | */ | |
272 | ||
273 | void print(char value); | |
274 | ||
275 | /** | |
276 | * Prints an integer. | |
277 | * <p> | |
278 | * Closes any open tag. | |
279 | */ | |
280 | ||
281 | void print(int value); | |
282 | ||
283 | /** | |
284 | * As with {@link #print(char[], int, int, boolean)}, but the data to print is defined by the | |
285 | * String. Assumes filtering is <em>enabled</em>. | |
286 | */ | |
287 | ||
288 | void print(String value); | |
289 | ||
290 | /** | |
291 | * As with {@link #print(char[], int, int, boolean)}, but the data to print is defined by the | |
292 | * String. | |
293 | */ | |
294 | ||
295 | void print(String value, boolean raw); | |
296 | ||
297 | /** | |
298 | * Closes the open tag (if any), then prints a line seperator to the output stream. | |
299 | */ | |
300 | ||
301 | void println(); | |
302 | ||
303 | /** | |
304 | * Version of {@link #print(char[], int, int, boolean)}that assumes filter is <em>enabled</em>. | |
305 | */ | |
306 | ||
307 | void printRaw(char[] buffer, int offset, int length); | |
308 | ||
309 | /** | |
310 | * As with {@link #print(char[], int, int, boolean)}, but the data to print is defined by the | |
311 | * String. Assumes filtering is <em>disabled</em>. | |
312 | */ | |
313 | ||
314 | void printRaw(String value); | |
315 | ||
316 | /** | |
317 | * Returns the type of content generated by this response writer, as a MIME type. | |
318 | */ | |
319 | ||
320 | String getContentType(); | |
321 | } |