Save This Page
1 /*
2 * $Id: ResponseWriter.java,v 1.19 2007/04/27 22:00:06 ofung Exp $
3 */
4
5 /*
6 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
7 *
8 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
9 *
10 * The contents of this file are subject to the terms of either the GNU
11 * General Public License Version 2 only ("GPL") or the Common Development
12 * and Distribution License("CDDL") (collectively, the "License"). You
13 * may not use this file except in compliance with the License. You can obtain
14 * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
15 * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
16 * language governing permissions and limitations under the License.
17 *
18 * When distributing the software, include this License Header Notice in each
19 * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
20 * Sun designates this particular file as subject to the "Classpath" exception
21 * as provided by Sun in the GPL Version 2 section of the License file that
22 * accompanied this code. If applicable, add the following below the License
23 * Header, with the fields enclosed by brackets [] replaced by your own
24 * identifying information: "Portions Copyrighted [year]
25 * [name of copyright owner]"
26 *
27 * Contributor(s):
28 *
29 * If you wish your version of this file to be governed by only the CDDL or
30 * only the GPL Version 2, indicate your decision by adding "[Contributor]
31 * elects to include this software in this distribution under the [CDDL or GPL
32 * Version 2] license." If you don't indicate a single choice of license, a
33 * recipient has the option to distribute your version of this file under
34 * either the CDDL, the GPL Version 2 or to extend the choice of license to
35 * its licensees as provided above. However, if you add GPL Version 2 code
36 * and therefore, elected the GPL Version 2 license, then the option applies
37 * only if the new code is made subject to such option by the copyright
38 * holder.
39 */
40
41 package javax.faces.context;
42
43
44 import java.io.IOException;
45 import java.io.Writer;
46
47 import javax.faces.component.UIComponent;
48
49
50 /**
51 * <p><strong>ResponseWriter</strong> is an abstract class describing an
52 * adapter to an underlying output mechanism for character-based output.
53 * In addition to the low-level <code>write()</code> methods inherited from
54 * <code>java.io.Writer</code>, this class provides utility methods
55 * that are useful in producing elements and attributes for markup languages
56 * like HTML and XML.</p>
57 */
58
59 public abstract class ResponseWriter extends Writer {
60
61
62 /**
63 * <p>Return the content type (such as "text/html") for this {@link
64 * ResponseWriter}. Note: this must not include the "charset="
65 * suffix.</p>
66 */
67 public abstract String getContentType();
68
69
70 /**
71 * <p>Return the character encoding (such as "ISO-8859-1") for this
72 * {@link ResponseWriter}. Please see <a
73 * href="http://www.iana.org/assignments/character-sets">the
74 * IANA</a> for a list of character encodings.</p>
75 */
76 public abstract String getCharacterEncoding();
77
78
79 /**
80 * <p>Flush any ouput buffered by the output method to the
81 * underlying Writer or OutputStream. This method
82 * will not flush the underlying Writer or OutputStream; it
83 * simply clears any values buffered by this {@link ResponseWriter}.</p>
84 */
85 public abstract void flush() throws IOException;
86
87
88 /**
89 * <p>Write whatever text should begin a response.</p>
90 *
91 * @throws IOException if an input/output error occurs
92 */
93 public abstract void startDocument() throws IOException;
94
95
96 /**
97 * <p>Write whatever text should end a response. If there is an open
98 * element that has been created by a call to <code>startElement()</code>,
99 * that element will be closed first.</p>
100 *
101 * @throws IOException if an input/output error occurs
102 */
103 public abstract void endDocument() throws IOException;
104
105
106 /**
107 * <p>Write the start of an element, up to and including the
108 * element name. Once this method has been called, clients can
109 * call the <code>writeAttribute()</code> or
110 * <code>writeURIAttribute()</code> methods to add attributes and
111 * corresponding values. The starting element will be closed
112 * (that is, the trailing '>' character added)
113 * on any subsequent call to <code>startElement()</code>,
114 * <code>writeComment()</code>,
115 * <code>writeText()</code>, <code>endElement()</code>,
116 * <code>endDocument()</code>, <code>close()</code>,
117 * <code>flush()</code>, or <code>write()</code>.</p>
118 *
119 * @param name Name of the element to be started
120 * @param component The {@link UIComponent} (if any) to which
121 * this element corresponds
122 *
123 * @throws IOException if an input/output error occurs
124 * @throws NullPointerException if <code>name</code>
125 * is <code>null</code>
126 */
127 public abstract void startElement(String name, UIComponent component)
128 throws IOException;
129
130
131 /**
132 * <p>Write the end of an element, after closing any open element
133 * created by a call to <code>startElement()</code>. Elements must be
134 * closed in the inverse order from which they were opened; it is an
135 * error to do otherwise.</p>
136 *
137 * @param name Name of the element to be ended
138 *
139 * @throws IOException if an input/output error occurs
140 * @throws NullPointerException if <code>name</code>
141 * is <code>null</code>
142 */
143 public abstract void endElement(String name) throws IOException;
144
145
146 /**
147 * <p>Write an attribute name and corresponding value, after converting
148 * that text to a String (if necessary), and after performing any escaping
149 * appropriate for the markup language being rendered.
150 * This method may only be called after a call to
151 * <code>startElement()</code>, and before the opened element has been
152 * closed.</p>
153 *
154 * @param name Attribute name to be added
155 * @param value Attribute value to be added
156 * @param property Name of the property or attribute (if any) of the
157 * {@link UIComponent} associated with the containing element,
158 * to which this generated attribute corresponds
159 *
160 * @throws IllegalStateException if this method is called when there
161 * is no currently open element
162 * @throws IOException if an input/output error occurs
163 * @throws NullPointerException if <code>name</code> is
164 * <code>null</code>
165 */
166 public abstract void writeAttribute(String name, Object value,
167 String property)
168 throws IOException;
169
170
171 /**
172 * <p>Write a URI attribute name and corresponding value, after converting
173 * that text to a String (if necessary), and after performing any encoding
174 * appropriate to the markup language being rendered.
175 * This method may only be called after a call to
176 * <code>startElement()</code>, and before the opened element has been
177 * closed.</p>
178 *
179 * @param name Attribute name to be added
180 * @param value Attribute value to be added
181 * @param property Name of the property or attribute (if any) of the
182 * {@link UIComponent} associated with the containing element,
183 * to which this generated attribute corresponds
184 *
185 * @throws IllegalStateException if this method is called when there
186 * is no currently open element
187 * @throws IOException if an input/output error occurs
188 * @throws NullPointerException if <code>name</code> is
189 * <code>null</code>
190 */
191 public abstract void writeURIAttribute(String name, Object value,
192 String property)
193 throws IOException;
194
195
196 /**
197 * <p>Write a comment containing the specified text, after converting
198 * that text to a String (if necessary), and after performing any escaping
199 * appropriate for the markup language being rendered. If there is
200 * an open element that has been created by a call to
201 * <code>startElement()</code>, that element will be closed first.</p>
202 *
203 * @param comment Text content of the comment
204 *
205 * @throws IOException if an input/output error occurs
206 * @throws NullPointerException if <code>comment</code>
207 * is <code>null</code>
208 */
209 public abstract void writeComment(Object comment) throws IOException;
210
211
212 /**
213 * <p>Write an object, after converting it to a String (if necessary),
214 * and after performing any escaping appropriate for the markup language
215 * being rendered. If there is an open element that has been created
216 * by a call to <code>startElement()</code>, that element will be closed
217 * first.</p>
218 *
219 * @param text Text to be written
220 * @param property Name of the property or attribute (if any) of the
221 * {@link UIComponent} associated with the containing element,
222 * to which this generated text corresponds
223 *
224 * @throws IOException if an input/output error occurs
225 * @throws NullPointerException if <code>text</code>
226 * is <code>null</code>
227 */
228 public abstract void writeText(Object text, String property)
229 throws IOException;
230
231 /**
232 * <p>Write an object, after converting it to a String (if
233 * necessary), and after performing any escaping appropriate for the
234 * markup language being rendered. This method is equivalent to
235 * {@link #writeText(java.lang.Object,java.lang.String)} but adds a
236 * <code>component</code> property to allow custom
237 * <code>ResponseWriter</code> implementations to associate a
238 * component with an arbitrary portion of text.</p>
239 *
240 * <p>The default implementation simply ignores the
241 * <code>component</code> argument and calls through to {@link
242 * #writeText(java.lang.Object,java.lang.String)}</p>
243 *
244 * @param text Text to be written
245 * @param component The {@link UIComponent} (if any) to which
246 * this element corresponds
247 * @param property Name of the property or attribute (if any) of the
248 * {@link UIComponent} associated with the containing element,
249 * to which this generated text corresponds
250 *
251 * @throws IOException if an input/output error occurs
252 * @throws NullPointerException if <code>text</code>
253 * is <code>null</code>
254 *
255 * @since 1.2
256 */
257 public void writeText(Object text, UIComponent component, String property)
258 throws IOException {
259 writeText(text, property);
260 }
261
262
263 /**
264 * <p>Write text from a character array, after any performing any
265 * escaping appropriate for the markup language being rendered.
266 * If there is an open element that has been created by a call to
267 * <code>startElement()</code>, that element will be closed first.</p>
268 *
269 * @param text Text to be written
270 * @param off Starting offset (zero-relative)
271 * @param len Number of characters to be written
272 *
273 * @throws IndexOutOfBoundsException if the calculated starting or
274 * ending position is outside the bounds of the character array
275 * @throws IOException if an input/output error occurs
276 * @throws NullPointerException if <code>text</code>
277 * is <code>null</code>
278 */
279 public abstract void writeText(char text[], int off, int len)
280 throws IOException;
281
282
283 /**
284 * <p>Create and return a new instance of this {@link ResponseWriter},
285 * using the specified <code>Writer</code> as the output destination.</p>
286 *
287 * @param writer The <code>Writer</code> that is the output destination
288 */
289 public abstract ResponseWriter cloneWithWriter(Writer writer);
290
291
292 }