View Javadoc

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