Source code: javax/servlet/jsp/JspWriter.java
1 /*
2 * Copyright 2004 The Apache Software Foundation
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package javax.servlet.jsp;
18
19 import java.io.IOException;
20
21 /**
22 * <p>
23 * The actions and template data in a JSP page is written using the
24 * JspWriter object that is referenced by the implicit variable out which
25 * is initialized automatically using methods in the PageContext object.
26 *<p>
27 * This abstract class emulates some of the functionality found in the
28 * java.io.BufferedWriter and java.io.PrintWriter classes,
29 * however it differs in that it throws java.io.IOException from the print
30 * methods while PrintWriter does not.
31 * <p><B>Buffering</B>
32 * <p>
33 * The initial JspWriter object is associated with the PrintWriter object
34 * of the ServletResponse in a way that depends on whether the page is or
35 * is not buffered. If the page is not buffered, output written to this
36 * JspWriter object will be written through to the PrintWriter directly,
37 * which will be created if necessary by invoking the getWriter() method
38 * on the response object. But if the page is buffered, the PrintWriter
39 * object will not be created until the buffer is flushed and
40 * operations like setContentType() are legal. Since this flexibility
41 * simplifies programming substantially, buffering is the default for JSP
42 * pages.
43 * <p>
44 * Buffering raises the issue of what to do when the buffer is
45 * exceeded. Two approaches can be taken:
46 * <ul>
47 * <li>
48 * Exceeding the buffer is not a fatal error; when the buffer is
49 * exceeded, just flush the output.
50 * <li>
51 * Exceeding the buffer is a fatal error; when the buffer is exceeded,
52 * raise an exception.
53 * </ul>
54 * <p>
55 * Both approaches are valid, and thus both are supported in the JSP
56 * technology. The behavior of a page is controlled by the autoFlush
57 * attribute, which defaults to true. In general, JSP pages that need to
58 * be sure that correct and complete data has been sent to their client
59 * may want to set autoFlush to false, with a typical case being that
60 * where the client is an application itself. On the other hand, JSP
61 * pages that send data that is meaningful even when partially
62 * constructed may want to set autoFlush to true; such as when the
63 * data is sent for immediate display through a browser. Each application
64 * will need to consider their specific needs.
65 * <p>
66 * An alternative considered was to make the buffer size unbounded; but,
67 * this had the disadvantage that runaway computations would consume an
68 * unbounded amount of resources.
69 * <p>
70 * The "out" implicit variable of a JSP implementation class is of this type.
71 * If the page directive selects autoflush="true" then all the I/O operations
72 * on this class shall automatically flush the contents of the buffer if an
73 * overflow condition would result if the current operation were performed
74 * without a flush. If autoflush="false" then all the I/O operations on this
75 * class shall throw an IOException if performing the current operation would
76 * result in a buffer overflow condition.
77 *
78 * @see java.io.Writer
79 * @see java.io.BufferedWriter
80 * @see java.io.PrintWriter
81 */
82
83 abstract public class JspWriter extends java.io.Writer {
84
85 /**
86 * Constant indicating that the Writer is not buffering output.
87 */
88
89 public static final int NO_BUFFER = 0;
90
91 /**
92 * Constant indicating that the Writer is buffered and is using the
93 * implementation default buffer size.
94 */
95
96 public static final int DEFAULT_BUFFER = -1;
97
98 /**
99 * Constant indicating that the Writer is buffered and is unbounded; this
100 * is used in BodyContent.
101 */
102
103 public static final int UNBOUNDED_BUFFER = -2;
104
105 /**
106 * Protected constructor.
107 *
108 * @param bufferSize the size of the buffer to be used by the JspWriter
109 * @param autoFlush whether the JspWriter should be autoflushing
110 */
111
112 protected JspWriter(int bufferSize, boolean autoFlush) {
113 this.bufferSize = bufferSize;
114 this.autoFlush = autoFlush;
115 }
116
117 /**
118 * Write a line separator. The line separator string is defined by the
119 * system property <tt>line.separator</tt>, and is not necessarily a single
120 * newline ('\n') character.
121 *
122 * @exception IOException If an I/O error occurs
123 */
124
125 abstract public void newLine() throws IOException;
126
127 /**
128 * Print a boolean value. The string produced by <code>{@link
129 * java.lang.String#valueOf(boolean)}</code> is written to the
130 * JspWriter's buffer or, if no buffer is used, directly to the
131 * underlying writer.
132 *
133 * @param b The <code>boolean</code> to be printed
134 * @throws java.io.IOException If an error occured while writing
135 */
136
137 abstract public void print(boolean b) throws IOException;
138
139 /**
140 * Print a character. The character is written to the
141 * JspWriter's buffer or, if no buffer is used, directly to the
142 * underlying writer.
143 *
144 * @param c The <code>char</code> to be printed
145 * @throws java.io.IOException If an error occured while writing
146 */
147
148 abstract public void print(char c) throws IOException;
149
150 /**
151 * Print an integer. The string produced by <code>{@link
152 * java.lang.String#valueOf(int)}</code> is written to the
153 * JspWriter's buffer or, if no buffer is used, directly to the
154 * underlying writer.
155 *
156 * @param i The <code>int</code> to be printed
157 * @see java.lang.Integer#toString(int)
158 * @throws java.io.IOException If an error occured while writing
159 */
160
161 abstract public void print(int i) throws IOException;
162
163 /**
164 * Print a long integer. The string produced by <code>{@link
165 * java.lang.String#valueOf(long)}</code> is written to the
166 * JspWriter's buffer or, if no buffer is used, directly to the
167 * underlying writer.
168 *
169 * @param l The <code>long</code> to be printed
170 * @see java.lang.Long#toString(long)
171 * @throws java.io.IOException If an error occured while writing
172 */
173
174 abstract public void print(long l) throws IOException;
175
176 /**
177 * Print a floating-point number. The string produced by <code>{@link
178 * java.lang.String#valueOf(float)}</code> is written to the
179 * JspWriter's buffer or, if no buffer is used, directly to the
180 * underlying writer.
181 *
182 * @param f The <code>float</code> to be printed
183 * @see java.lang.Float#toString(float)
184 * @throws java.io.IOException If an error occured while writing
185 */
186
187 abstract public void print(float f) throws IOException;
188
189 /**
190 * Print a double-precision floating-point number. The string produced by
191 * <code>{@link java.lang.String#valueOf(double)}</code> is written to
192 * the JspWriter's buffer or, if no buffer is used, directly to the
193 * underlying writer.
194 *
195 * @param d The <code>double</code> to be printed
196 * @see java.lang.Double#toString(double)
197 * @throws java.io.IOException If an error occured while writing
198 */
199
200 abstract public void print(double d) throws IOException;
201
202 /**
203 * Print an array of characters. The characters are written to the
204 * JspWriter's buffer or, if no buffer is used, directly to the
205 * underlying writer.
206 *
207 * @param s The array of chars to be printed
208 *
209 * @throws NullPointerException If <code>s</code> is <code>null</code>
210 * @throws java.io.IOException If an error occured while writing
211 */
212
213 abstract public void print(char s[]) throws IOException;
214
215 /**
216 * Print a string. If the argument is <code>null</code> then the string
217 * <code>"null"</code> is printed. Otherwise, the string's characters are
218 * written to the JspWriter's buffer or, if no buffer is used, directly
219 * to the underlying writer.
220 *
221 * @param s The <code>String</code> to be printed
222 * @throws java.io.IOException If an error occured while writing
223 */
224
225 abstract public void print(String s) throws IOException;
226
227 /**
228 * Print an object. The string produced by the <code>{@link
229 * java.lang.String#valueOf(Object)}</code> method is written to the
230 * JspWriter's buffer or, if no buffer is used, directly to the
231 * underlying writer.
232 *
233 * @param obj The <code>Object</code> to be printed
234 * @see java.lang.Object#toString()
235 * @throws java.io.IOException If an error occured while writing
236 */
237
238 abstract public void print(Object obj) throws IOException;
239
240 /**
241 * Terminate the current line by writing the line separator string. The
242 * line separator string is defined by the system property
243 * <code>line.separator</code>, and is not necessarily a single newline
244 * character (<code>'\n'</code>).
245 * @throws java.io.IOException If an error occured while writing
246 */
247
248 abstract public void println() throws IOException;
249
250 /**
251 * Print a boolean value and then terminate the line. This method behaves
252 * as though it invokes <code>{@link #print(boolean)}</code> and then
253 * <code>{@link #println()}</code>.
254 *
255 * @param x the boolean to write
256 * @throws java.io.IOException If an error occured while writing
257 */
258
259 abstract public void println(boolean x) throws IOException;
260
261 /**
262 * Print a character and then terminate the line. This method behaves as
263 * though it invokes <code>{@link #print(char)}</code> and then <code>{@link
264 * #println()}</code>.
265 *
266 * @param x the char to write
267 * @throws java.io.IOException If an error occured while writing
268 */
269
270 abstract public void println(char x) throws IOException;
271
272 /**
273 * Print an integer and then terminate the line. This method behaves as
274 * though it invokes <code>{@link #print(int)}</code> and then <code>{@link
275 * #println()}</code>.
276 *
277 * @param x the int to write
278 * @throws java.io.IOException If an error occured while writing
279 */
280
281 abstract public void println(int x) throws IOException;
282
283 /**
284 * Print a long integer and then terminate the line. This method behaves
285 * as though it invokes <code>{@link #print(long)}</code> and then
286 * <code>{@link #println()}</code>.
287 *
288 * @param x the long to write
289 * @throws java.io.IOException If an error occured while writing
290 */
291
292 abstract public void println(long x) throws IOException;
293
294 /**
295 * Print a floating-point number and then terminate the line. This method
296 * behaves as though it invokes <code>{@link #print(float)}</code> and then
297 * <code>{@link #println()}</code>.
298 *
299 * @param x the float to write
300 * @throws java.io.IOException If an error occured while writing
301 */
302
303 abstract public void println(float x) throws IOException;
304
305 /**
306 * Print a double-precision floating-point number and then terminate the
307 * line. This method behaves as though it invokes <code>{@link
308 * #print(double)}</code> and then <code>{@link #println()}</code>.
309 *
310 * @param x the double to write
311 * @throws java.io.IOException If an error occured while writing
312 */
313
314 abstract public void println(double x) throws IOException;
315
316 /**
317 * Print an array of characters and then terminate the line. This method
318 * behaves as though it invokes <code>print(char[])</code> and then
319 * <code>println()</code>.
320 *
321 * @param x the char[] to write
322 * @throws java.io.IOException If an error occured while writing
323 */
324
325 abstract public void println(char x[]) throws IOException;
326
327 /**
328 * Print a String and then terminate the line. This method behaves as
329 * though it invokes <code>{@link #print(String)}</code> and then
330 * <code>{@link #println()}</code>.
331 *
332 * @param x the String to write
333 * @throws java.io.IOException If an error occured while writing
334 */
335
336 abstract public void println(String x) throws IOException;
337
338 /**
339 * Print an Object and then terminate the line. This method behaves as
340 * though it invokes <code>{@link #print(Object)}</code> and then
341 * <code>{@link #println()}</code>.
342 *
343 * @param x the Object to write
344 * @throws java.io.IOException If an error occured while writing
345 */
346
347 abstract public void println(Object x) throws IOException;
348
349
350 /**
351 * Clear the contents of the buffer. If the buffer has been already
352 * been flushed then the clear operation shall throw an IOException
353 * to signal the fact that some data has already been irrevocably
354 * written to the client response stream.
355 *
356 * @throws IOException If an I/O error occurs
357 */
358
359 abstract public void clear() throws IOException;
360
361 /**
362 * Clears the current contents of the buffer. Unlike clear(), this
363 * method will not throw an IOException if the buffer has already been
364 * flushed. It merely clears the current content of the buffer and
365 * returns.
366 *
367 * @throws IOException If an I/O error occurs
368 */
369
370 abstract public void clearBuffer() throws IOException;
371
372 /**
373 * Flush the stream. If the stream has saved any characters from the
374 * various write() methods in a buffer, write them immediately to their
375 * intended destination. Then, if that destination is another character or
376 * byte stream, flush it. Thus one flush() invocation will flush all the
377 * buffers in a chain of Writers and OutputStreams.
378 * <p>
379 * The method may be invoked indirectly if the buffer size is exceeded.
380 * <p>
381 * Once a stream has been closed,
382 * further write() or flush() invocations will cause an IOException to be
383 * thrown.
384 *
385 * @exception IOException If an I/O error occurs
386 */
387
388 abstract public void flush() throws IOException;
389
390 /**
391 * Close the stream, flushing it first.
392 * <p>
393 * This method needs not be invoked explicitly for the initial JspWriter
394 * as the code generated by the JSP container will automatically
395 * include a call to close().
396 * <p>
397 * Closing a previously-closed stream, unlike flush(), has no effect.
398 *
399 * @exception IOException If an I/O error occurs
400 */
401
402 abstract public void close() throws IOException;
403
404 /**
405 * This method returns the size of the buffer used by the JspWriter.
406 *
407 * @return the size of the buffer in bytes, or 0 is unbuffered.
408 */
409
410 public int getBufferSize() { return bufferSize; }
411
412 /**
413 * This method returns the number of unused bytes in the buffer.
414 *
415 * @return the number of bytes unused in the buffer
416 */
417
418 abstract public int getRemaining();
419
420 /**
421 * This method indicates whether the JspWriter is autoFlushing.
422 *
423 * @return if this JspWriter is auto flushing or throwing IOExceptions
424 * on buffer overflow conditions
425 */
426
427 public boolean isAutoFlush() { return autoFlush; }
428
429 /*
430 * fields
431 */
432
433 /**
434 * The size of the buffer used by the JspWriter.
435 */
436 protected int bufferSize;
437
438 /**
439 * Whether the JspWriter is autoflushing.
440 */
441 protected boolean autoFlush;
442 }