001 // Copyright 2004, 2005 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.tapestry;
016
017 /**
018 * Defines an object that can write markup (XML, HTML, XHTML) style output. A
019 * <code>IMarkupWriter</code> handles translation from unicode to the markup language (escaping
020 * characters such as '<' and '>' to their entity equivalents, '&lt;' and '&gt;') as
021 * well as assisting with nested elements, closing tags, etc.
022 *
023 * @author Howard Ship, David Solis
024 */
025
026 public interface IMarkupWriter
027 {
028 /**
029 * Writes an integer attribute into the currently open tag.
030 *
031 * @throws IllegalStateException
032 * if there is no open tag.
033 */
034
035 public void attribute(String name, int value);
036
037 /**
038 * Writes a boolean attribute into the currently open tag.
039 *
040 * @throws IllegalStateException
041 * if there is no open tag.
042 * @since 3.0
043 */
044
045 public void attribute(String name, boolean value);
046
047 /**
048 * Writes an attribute into the most recently opened tag. This must be called after
049 * {@link #begin(String)}and before any other kind of writing (which closes the tag).
050 * <p>
051 * The value may be null.
052 *
053 * @throws IllegalStateException
054 * if there is no open tag.
055 */
056
057 public void attribute(String name, String value);
058
059 /**
060 * Similar to {@link #attribute(String, String)}but no escaping of invalid elements is done for
061 * the value.
062 *
063 * @throws IllegalStateException
064 * if there is no open tag.
065 * @since 3.0
066 */
067
068 public void attributeRaw(String name, String value);
069
070 /**
071 * Closes any existing tag then starts a new element. The new element is pushed onto the active
072 * element stack.
073 */
074
075 public void begin(String name);
076
077 /**
078 * Starts an element that will not later be matched with an <code>end()</code> call. This is
079 * useful for elements that do not need closing tags.
080 */
081
082 public void beginEmpty(String name);
083
084 /**
085 * Invokes checkError() on the <code>PrintWriter</code> used to format output.
086 */
087
088 public boolean checkError();
089
090 /**
091 * Closes this <code>IMarkupWriter</code>. Close tags are written for any active elements.
092 * The <code>PrintWriter</code> is then sent <code>close()</code>. A nested writer will
093 * commit its buffer to its containing writer.
094 */
095
096 public void close();
097
098 /**
099 * Closes the most recently opened element by writing the '>' that ends it. Once this is
100 * invoked, the <code>attribute()</code> methods may not be used until a new element is opened
101 * with {@link #begin(String)}or or {@link #beginEmpty(String)}.
102 */
103
104 public void closeTag();
105
106 /**
107 * Writes an XML/HTML comment. Any open tag is first closed. The method takes care of providing
108 * the <code><!--</code> and <code>--></code>, and provides a blank line after the
109 * close of the comment.
110 * <p>
111 * <em>Most</em> characters are valid inside a comment, so no check of the contents is made
112 * (much like {@link #printRaw(String)}.
113 */
114
115 public void comment(String value);
116
117 /**
118 * Ends the element most recently started by {@link#begin(String)}. The name of the tag is
119 * popped off of the active element stack and used to form an HTML close tag.
120 */
121
122 public void end();
123
124 /**
125 * Ends the most recently started element with the given name. This will also end any other
126 * intermediate elements. This is very useful for easily ending a table or even an entire page.
127 */
128
129 public void end(String name);
130
131 /**
132 * Forwards <code>flush()</code> to this <code>IMarkupWriter</code>'s
133 * <code>PrintWriter</code>.
134 */
135
136 public void flush();
137
138 /**
139 * Returns a nested writer, one that accumulates its changes in a buffer. When the nested writer
140 * is closed, it writes its buffer of markup into its containing <code>IMarkupWriter</code>
141 * using {@link #printRaw(String)}.
142 */
143
144 public NestedMarkupWriter getNestedWriter();
145
146 /**
147 * Version of {@link #print(char[], int, int, boolean)} that assumes filter is
148 * <em>enabled</em>.
149 */
150
151 public void print(char[] data, int offset, int length);
152
153 /**
154 * The primary <code>print()</code> method, used by most other methods.
155 * <p>
156 * Prints the character array, first closing any open tag. Problematic characters ('<',
157 * '>' and '&') are converted to appropriate entities.
158 * <p>
159 * Does <em>nothing</em> if <code>data</code> is null.
160 * <p>
161 * Closes any open tag.
162 *
163 * @param data
164 * contains the characters to print, or null to not print anything
165 * @param offset
166 * offset into the array to start printing from
167 * @param length
168 * number of characters to print
169 * @param raw
170 * if true, filtering is disabled
171 * @since 4.0
172 */
173
174 public void print(char[] data, int offset, int length, boolean raw);
175
176 /**
177 * Prints a single character, or its equivalent entity.
178 * <p>
179 * Closes any open tag.
180 */
181
182 public void print(char value);
183
184 /**
185 * Prints an integer.
186 * <p>
187 * Closes any open tag.
188 */
189
190 public void print(int value);
191
192 /**
193 * As with {@link #print(char[], int, int, boolean)}, but the data to print is defined by the
194 * String. Assumes filtering is <em>enabled</em>.
195 */
196
197 public void print(String value);
198
199 /**
200 * As with {@link #print(char[], int, int, boolean)}, but the data to print is defined by the
201 * String.
202 */
203
204 public void print(String value, boolean raw);
205
206 /**
207 * Closes the open tag (if any), then prints a line seperator to the output stream.
208 */
209
210 public void println();
211
212 /**
213 * Version of {@link #print(char[], int, int, boolean)}that assumes filter is <em>enabled</em>.
214 */
215
216 public void printRaw(char[] buffer, int offset, int length);
217
218 /**
219 * As with {@link #print(char[], int, int, boolean)}, but the data to print is defined by the
220 * String. Assumes filtering is <em>disabled</em>.
221 */
222
223 public void printRaw(String value);
224
225 /**
226 * Returns the type of content generated by this response writer, as a MIME type.
227 */
228
229 public String getContentType();
230 }