001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 */ 019 020 // 021 // This source code implements specifications defined by the Java 022 // Community Process. In order to remain compliant with the specification 023 // DO NOT add / change / or delete method signatures! 024 // 025 026 package javax.servlet.jsp; 027 028 import java.io.IOException; 029 030 /** 031 * <p> 032 * The actions and template data in a JSP page is written using the 033 * JspWriter object that is referenced by the implicit variable out which 034 * is initialized automatically using methods in the PageContext object. 035 *<p> 036 * This abstract class emulates some of the functionality found in the 037 * java.io.BufferedWriter and java.io.PrintWriter classes, 038 * however it differs in that it throws java.io.IOException from the print 039 * methods while PrintWriter does not. 040 * <p><B>Buffering</B> 041 * <p> 042 * The initial JspWriter object is associated with the PrintWriter object 043 * of the ServletResponse in a way that depends on whether the page is or 044 * is not buffered. If the page is not buffered, output written to this 045 * JspWriter object will be written through to the PrintWriter directly, 046 * which will be created if necessary by invoking the getWriter() method 047 * on the response object. But if the page is buffered, the PrintWriter 048 * object will not be created until the buffer is flushed and 049 * operations like setContentType() are legal. Since this flexibility 050 * simplifies programming substantially, buffering is the default for JSP 051 * pages. 052 * <p> 053 * Buffering raises the issue of what to do when the buffer is 054 * exceeded. Two approaches can be taken: 055 * <ul> 056 * <li> 057 * Exceeding the buffer is not a fatal error; when the buffer is 058 * exceeded, just flush the output. 059 * <li> 060 * Exceeding the buffer is a fatal error; when the buffer is exceeded, 061 * raise an exception. 062 * </ul> 063 * <p> 064 * Both approaches are valid, and thus both are supported in the JSP 065 * technology. The behavior of a page is controlled by the autoFlush 066 * attribute, which defaults to true. In general, JSP pages that need to 067 * be sure that correct and complete data has been sent to their client 068 * may want to set autoFlush to false, with a typical case being that 069 * where the client is an application itself. On the other hand, JSP 070 * pages that send data that is meaningful even when partially 071 * constructed may want to set autoFlush to true; such as when the 072 * data is sent for immediate display through a browser. Each application 073 * will need to consider their specific needs. 074 * <p> 075 * An alternative considered was to make the buffer size unbounded; but, 076 * this had the disadvantage that runaway computations would consume an 077 * unbounded amount of resources. 078 * <p> 079 * The "out" implicit variable of a JSP implementation class is of this type. 080 * If the page directive selects autoflush="true" then all the I/O operations 081 * on this class shall automatically flush the contents of the buffer if an 082 * overflow condition would result if the current operation were performed 083 * without a flush. If autoflush="false" then all the I/O operations on this 084 * class shall throw an IOException if performing the current operation would 085 * result in a buffer overflow condition. 086 * 087 * @see java.io.Writer 088 * @see java.io.BufferedWriter 089 * @see java.io.PrintWriter 090 */ 091 092 abstract public class JspWriter extends java.io.Writer { 093 094 /** 095 * Constant indicating that the Writer is not buffering output. 096 */ 097 098 public static final int NO_BUFFER = 0; 099 100 /** 101 * Constant indicating that the Writer is buffered and is using the 102 * implementation default buffer size. 103 */ 104 105 public static final int DEFAULT_BUFFER = -1; 106 107 /** 108 * Constant indicating that the Writer is buffered and is unbounded; this 109 * is used in BodyContent. 110 */ 111 112 public static final int UNBOUNDED_BUFFER = -2; 113 114 /** 115 * Protected constructor. 116 * 117 * @param bufferSize the size of the buffer to be used by the JspWriter 118 * @param autoFlush whether the JspWriter should be autoflushing 119 */ 120 121 protected JspWriter(int bufferSize, boolean autoFlush) { 122 this.bufferSize = bufferSize; 123 this.autoFlush = autoFlush; 124 } 125 126 /** 127 * Write a line separator. The line separator string is defined by the 128 * system property <tt>line.separator</tt>, and is not necessarily a single 129 * newline ('\n') character. 130 * 131 * @exception IOException If an I/O error occurs 132 */ 133 134 abstract public void newLine() throws IOException; 135 136 /** 137 * Print a boolean value. The string produced by <code>{@link 138 * java.lang.String#valueOf(boolean)}</code> is written to the 139 * JspWriter's buffer or, if no buffer is used, directly to the 140 * underlying writer. 141 * 142 * @param b The <code>boolean</code> to be printed 143 * @throws java.io.IOException If an error occured while writing 144 */ 145 146 abstract public void print(boolean b) throws IOException; 147 148 /** 149 * Print a character. The character is written to the 150 * JspWriter's buffer or, if no buffer is used, directly to the 151 * underlying writer. 152 * 153 * @param c The <code>char</code> to be printed 154 * @throws java.io.IOException If an error occured while writing 155 */ 156 157 abstract public void print(char c) throws IOException; 158 159 /** 160 * Print an integer. The string produced by <code>{@link 161 * java.lang.String#valueOf(int)}</code> is written to the 162 * JspWriter's buffer or, if no buffer is used, directly to the 163 * underlying writer. 164 * 165 * @param i The <code>int</code> to be printed 166 * @see java.lang.Integer#toString(int) 167 * @throws java.io.IOException If an error occured while writing 168 */ 169 170 abstract public void print(int i) throws IOException; 171 172 /** 173 * Print a long integer. The string produced by <code>{@link 174 * java.lang.String#valueOf(long)}</code> is written to the 175 * JspWriter's buffer or, if no buffer is used, directly to the 176 * underlying writer. 177 * 178 * @param l The <code>long</code> to be printed 179 * @see java.lang.Long#toString(long) 180 * @throws java.io.IOException If an error occured while writing 181 */ 182 183 abstract public void print(long l) throws IOException; 184 185 /** 186 * Print a floating-point number. The string produced by <code>{@link 187 * java.lang.String#valueOf(float)}</code> is written to the 188 * JspWriter's buffer or, if no buffer is used, directly to the 189 * underlying writer. 190 * 191 * @param f The <code>float</code> to be printed 192 * @see java.lang.Float#toString(float) 193 * @throws java.io.IOException If an error occured while writing 194 */ 195 196 abstract public void print(float f) throws IOException; 197 198 /** 199 * Print a double-precision floating-point number. The string produced by 200 * <code>{@link java.lang.String#valueOf(double)}</code> is written to 201 * the JspWriter's buffer or, if no buffer is used, directly to the 202 * underlying writer. 203 * 204 * @param d The <code>double</code> to be printed 205 * @see java.lang.Double#toString(double) 206 * @throws java.io.IOException If an error occured while writing 207 */ 208 209 abstract public void print(double d) throws IOException; 210 211 /** 212 * Print an array of characters. The characters are written to the 213 * JspWriter's buffer or, if no buffer is used, directly to the 214 * underlying writer. 215 * 216 * @param s The array of chars to be printed 217 * 218 * @throws NullPointerException If <code>s</code> is <code>null</code> 219 * @throws java.io.IOException If an error occured while writing 220 */ 221 222 abstract public void print(char s[]) throws IOException; 223 224 /** 225 * Print a string. If the argument is <code>null</code> then the string 226 * <code>"null"</code> is printed. Otherwise, the string's characters are 227 * written to the JspWriter's buffer or, if no buffer is used, directly 228 * to the underlying writer. 229 * 230 * @param s The <code>String</code> to be printed 231 * @throws java.io.IOException If an error occured while writing 232 */ 233 234 abstract public void print(String s) throws IOException; 235 236 /** 237 * Print an object. The string produced by the <code>{@link 238 * java.lang.String#valueOf(Object)}</code> method is written to the 239 * JspWriter's buffer or, if no buffer is used, directly to the 240 * underlying writer. 241 * 242 * @param obj The <code>Object</code> to be printed 243 * @see java.lang.Object#toString() 244 * @throws java.io.IOException If an error occured while writing 245 */ 246 247 abstract public void print(Object obj) throws IOException; 248 249 /** 250 * Terminate the current line by writing the line separator string. The 251 * line separator string is defined by the system property 252 * <code>line.separator</code>, and is not necessarily a single newline 253 * character (<code>'\n'</code>). 254 * @throws java.io.IOException If an error occured while writing 255 */ 256 257 abstract public void println() throws IOException; 258 259 /** 260 * Print a boolean value and then terminate the line. This method behaves 261 * as though it invokes <code>{@link #print(boolean)}</code> and then 262 * <code>{@link #println()}</code>. 263 * 264 * @param x the boolean to write 265 * @throws java.io.IOException If an error occured while writing 266 */ 267 268 abstract public void println(boolean x) throws IOException; 269 270 /** 271 * Print a character and then terminate the line. This method behaves as 272 * though it invokes <code>{@link #print(char)}</code> and then <code>{@link 273 * #println()}</code>. 274 * 275 * @param x the char to write 276 * @throws java.io.IOException If an error occured while writing 277 */ 278 279 abstract public void println(char x) throws IOException; 280 281 /** 282 * Print an integer and then terminate the line. This method behaves as 283 * though it invokes <code>{@link #print(int)}</code> and then <code>{@link 284 * #println()}</code>. 285 * 286 * @param x the int to write 287 * @throws java.io.IOException If an error occured while writing 288 */ 289 290 abstract public void println(int x) throws IOException; 291 292 /** 293 * Print a long integer and then terminate the line. This method behaves 294 * as though it invokes <code>{@link #print(long)}</code> and then 295 * <code>{@link #println()}</code>. 296 * 297 * @param x the long to write 298 * @throws java.io.IOException If an error occured while writing 299 */ 300 301 abstract public void println(long x) throws IOException; 302 303 /** 304 * Print a floating-point number and then terminate the line. This method 305 * behaves as though it invokes <code>{@link #print(float)}</code> and then 306 * <code>{@link #println()}</code>. 307 * 308 * @param x the float to write 309 * @throws java.io.IOException If an error occured while writing 310 */ 311 312 abstract public void println(float x) throws IOException; 313 314 /** 315 * Print a double-precision floating-point number and then terminate the 316 * line. This method behaves as though it invokes <code>{@link 317 * #print(double)}</code> and then <code>{@link #println()}</code>. 318 * 319 * @param x the double to write 320 * @throws java.io.IOException If an error occured while writing 321 */ 322 323 abstract public void println(double x) throws IOException; 324 325 /** 326 * Print an array of characters and then terminate the line. This method 327 * behaves as though it invokes <code>print(char[])</code> and then 328 * <code>println()</code>. 329 * 330 * @param x the char[] to write 331 * @throws java.io.IOException If an error occured while writing 332 */ 333 334 abstract public void println(char x[]) throws IOException; 335 336 /** 337 * Print a String and then terminate the line. This method behaves as 338 * though it invokes <code>{@link #print(String)}</code> and then 339 * <code>{@link #println()}</code>. 340 * 341 * @param x the String to write 342 * @throws java.io.IOException If an error occured while writing 343 */ 344 345 abstract public void println(String x) throws IOException; 346 347 /** 348 * Print an Object and then terminate the line. This method behaves as 349 * though it invokes <code>{@link #print(Object)}</code> and then 350 * <code>{@link #println()}</code>. 351 * 352 * @param x the Object to write 353 * @throws java.io.IOException If an error occured while writing 354 */ 355 356 abstract public void println(Object x) throws IOException; 357 358 359 /** 360 * Clear the contents of the buffer. If the buffer has been already 361 * been flushed then the clear operation shall throw an IOException 362 * to signal the fact that some data has already been irrevocably 363 * written to the client response stream. 364 * 365 * @throws IOException If an I/O error occurs 366 */ 367 368 abstract public void clear() throws IOException; 369 370 /** 371 * Clears the current contents of the buffer. Unlike clear(), this 372 * method will not throw an IOException if the buffer has already been 373 * flushed. It merely clears the current content of the buffer and 374 * returns. 375 * 376 * @throws IOException If an I/O error occurs 377 */ 378 379 abstract public void clearBuffer() throws IOException; 380 381 /** 382 * Flush the stream. If the stream has saved any characters from the 383 * various write() methods in a buffer, write them immediately to their 384 * intended destination. Then, if that destination is another character or 385 * byte stream, flush it. Thus one flush() invocation will flush all the 386 * buffers in a chain of Writers and OutputStreams. 387 * <p> 388 * The method may be invoked indirectly if the buffer size is exceeded. 389 * <p> 390 * Once a stream has been closed, 391 * further write() or flush() invocations will cause an IOException to be 392 * thrown. 393 * 394 * @exception IOException If an I/O error occurs 395 */ 396 397 abstract public void flush() throws IOException; 398 399 /** 400 * Close the stream, flushing it first. 401 * <p> 402 * This method needs not be invoked explicitly for the initial JspWriter 403 * as the code generated by the JSP container will automatically 404 * include a call to close(). 405 * <p> 406 * Closing a previously-closed stream, unlike flush(), has no effect. 407 * 408 * @exception IOException If an I/O error occurs 409 */ 410 411 abstract public void close() throws IOException; 412 413 /** 414 * This method returns the size of the buffer used by the JspWriter. 415 * 416 * @return the size of the buffer in bytes, or 0 is unbuffered. 417 */ 418 419 public int getBufferSize() { return bufferSize; } 420 421 /** 422 * This method returns the number of unused bytes in the buffer. 423 * 424 * @return the number of bytes unused in the buffer 425 */ 426 427 abstract public int getRemaining(); 428 429 /** 430 * This method indicates whether the JspWriter is autoFlushing. 431 * 432 * @return if this JspWriter is auto flushing or throwing IOExceptions 433 * on buffer overflow conditions 434 */ 435 436 public boolean isAutoFlush() { return autoFlush; } 437 438 /* 439 * fields 440 */ 441 442 /** 443 * The size of the buffer used by the JspWriter. 444 */ 445 protected int bufferSize; 446 447 /** 448 * Whether the JspWriter is autoflushing. 449 */ 450 protected boolean autoFlush; 451 }