001 /*
002 * Copyright 2004 The Apache Software Foundation
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017 package javax.servlet.jsp;
018
019 import java.io.IOException;
020
021 /**
022 * <p>
023 * The actions and template data in a JSP page is written using the
024 * JspWriter object that is referenced by the implicit variable out which
025 * is initialized automatically using methods in the PageContext object.
026 *<p>
027 * This abstract class emulates some of the functionality found in the
028 * java.io.BufferedWriter and java.io.PrintWriter classes,
029 * however it differs in that it throws java.io.IOException from the print
030 * methods while PrintWriter does not.
031 * <p><B>Buffering</B>
032 * <p>
033 * The initial JspWriter object is associated with the PrintWriter object
034 * of the ServletResponse in a way that depends on whether the page is or
035 * is not buffered. If the page is not buffered, output written to this
036 * JspWriter object will be written through to the PrintWriter directly,
037 * which will be created if necessary by invoking the getWriter() method
038 * on the response object. But if the page is buffered, the PrintWriter
039 * object will not be created until the buffer is flushed and
040 * operations like setContentType() are legal. Since this flexibility
041 * simplifies programming substantially, buffering is the default for JSP
042 * pages.
043 * <p>
044 * Buffering raises the issue of what to do when the buffer is
045 * exceeded. Two approaches can be taken:
046 * <ul>
047 * <li>
048 * Exceeding the buffer is not a fatal error; when the buffer is
049 * exceeded, just flush the output.
050 * <li>
051 * Exceeding the buffer is a fatal error; when the buffer is exceeded,
052 * raise an exception.
053 * </ul>
054 * <p>
055 * Both approaches are valid, and thus both are supported in the JSP
056 * technology. The behavior of a page is controlled by the autoFlush
057 * attribute, which defaults to true. In general, JSP pages that need to
058 * be sure that correct and complete data has been sent to their client
059 * may want to set autoFlush to false, with a typical case being that
060 * where the client is an application itself. On the other hand, JSP
061 * pages that send data that is meaningful even when partially
062 * constructed may want to set autoFlush to true; such as when the
063 * data is sent for immediate display through a browser. Each application
064 * will need to consider their specific needs.
065 * <p>
066 * An alternative considered was to make the buffer size unbounded; but,
067 * this had the disadvantage that runaway computations would consume an
068 * unbounded amount of resources.
069 * <p>
070 * The "out" implicit variable of a JSP implementation class is of this type.
071 * If the page directive selects autoflush="true" then all the I/O operations
072 * on this class shall automatically flush the contents of the buffer if an
073 * overflow condition would result if the current operation were performed
074 * without a flush. If autoflush="false" then all the I/O operations on this
075 * class shall throw an IOException if performing the current operation would
076 * result in a buffer overflow condition.
077 *
078 * @see java.io.Writer
079 * @see java.io.BufferedWriter
080 * @see java.io.PrintWriter
081 */
082
083 abstract public class JspWriter extends java.io.Writer {
084
085 /**
086 * Constant indicating that the Writer is not buffering output.
087 */
088
089 public static final int NO_BUFFER = 0;
090
091 /**
092 * Constant indicating that the Writer is buffered and is using the
093 * implementation default buffer size.
094 */
095
096 public static final int DEFAULT_BUFFER = -1;
097
098 /**
099 * 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 * Clear the contents of the buffer. If the buffer has been already
351 * been flushed then the clear operation shall throw an IOException
352 * to signal the fact that some data has already been irrevocably
353 * written to the client response stream.
354 *
355 * @throws IOException If an I/O error occurs
356 */
357
358 abstract public void clear() throws IOException;
359
360 /**
361 * Clears the current contents of the buffer. Unlike clear(), this
362 * method will not throw an IOException if the buffer has already been
363 * flushed. It merely clears the current content of the buffer and
364 * returns.
365 *
366 * @throws IOException If an I/O error occurs
367 */
368
369 abstract public void clearBuffer() throws IOException;
370
371 /**
372 * Flush the stream. If the stream has saved any characters from the
373 * various write() methods in a buffer, write them immediately to their
374 * intended destination. Then, if that destination is another character or
375 * byte stream, flush it. Thus one flush() invocation will flush all the
376 * buffers in a chain of Writers and OutputStreams.
377 * <p>
378 * The method may be invoked indirectly if the buffer size is exceeded.
379 * <p>
380 * Once a stream has been closed,
381 * further write() or flush() invocations will cause an IOException to be
382 * thrown.
383 *
384 * @exception IOException If an I/O error occurs
385 */
386
387 abstract public void flush() throws IOException;
388
389 /**
390 * Close the stream, flushing it first.
391 * <p>
392 * This method needs not be invoked explicitly for the initial JspWriter
393 * as the code generated by the JSP container will automatically
394 * include a call to close().
395 * <p>
396 * Closing a previously-closed stream, unlike flush(), has no effect.
397 *
398 * @exception IOException If an I/O error occurs
399 */
400
401 abstract public void close() throws IOException;
402
403 /**
404 * This method returns the size of the buffer used by the JspWriter.
405 *
406 * @return the size of the buffer in bytes, or 0 is unbuffered.
407 */
408
409 public int getBufferSize() {
410 return bufferSize;
411 }
412
413 /**
414 * This method returns the number of unused bytes in the buffer.
415 *
416 * @return the number of bytes unused in the buffer
417 */
418
419 abstract public int getRemaining();
420
421 /**
422 * This method indicates whether the JspWriter is autoFlushing.
423 *
424 * @return if this JspWriter is auto flushing or throwing IOExceptions
425 * on buffer overflow conditions
426 */
427
428 public boolean isAutoFlush() {
429 return autoFlush;
430 }
431
432 /*
433 * fields
434 */
435
436 /**
437 * The size of the buffer used by the JspWriter.
438 */
439 protected int bufferSize;
440
441 /**
442 * Whether the JspWriter is autoflushing.
443 */
444 protected boolean autoFlush;
445 }
|