| |
|
| java.lang.Object
 java.io.Writer
javax.servlet.jsp.JspWriter
All known Subclasses: javax.servlet.jsp.tagext.BodyContent,
| JspWriter | | abstract public class JspWriter extends java.io.Writer (Code) | |
The actions and template data in a JSP page is written using the
JspWriter object that is referenced by the implicit variable out which
is initialized automatically using methods in the PageContext object.
This abstract class emulates some of the functionality found in the
java.io.BufferedWriter and java.io.PrintWriter classes,
however it differs in that it throws java.io.IOException from the print
methods while PrintWriter does not.
Buffering
The initial JspWriter object is associated with the PrintWriter object
of the ServletResponse in a way that depends on whether the page is or
is not buffered. If the page is not buffered, output written to this
JspWriter object will be written through to the PrintWriter directly,
which will be created if necessary by invoking the getWriter() method
on the response object. But if the page is buffered, the PrintWriter
object will not be created until the buffer is flushed and
operations like setContentType() are legal. Since this flexibility
simplifies programming substantially, buffering is the default for JSP
pages.
Buffering raises the issue of what to do when the buffer is
exceeded. Two approaches can be taken:
-
Exceeding the buffer is not a fatal error; when the buffer is
exceeded, just flush the output.
-
Exceeding the buffer is a fatal error; when the buffer is exceeded,
raise an exception.
Both approaches are valid, and thus both are supported in the JSP
technology. The behavior of a page is controlled by the autoFlush
attribute, which defaults to true. In general, JSP pages that need to
be sure that correct and complete data has been sent to their client
may want to set autoFlush to false, with a typical case being that
where the client is an application itself. On the other hand, JSP
pages that send data that is meaningful even when partially
constructed may want to set autoFlush to true; such as when the
data is sent for immediate display through a browser. Each application
will need to consider their specific needs.
An alternative considered was to make the buffer size unbounded; but,
this had the disadvantage that runaway computations would consume an
unbounded amount of resources.
The "out" implicit variable of a JSP implementation class is of this type.
If the page directive selects autoflush="true" then all the I/O operations
on this class shall automatically flush the contents of the buffer if an
overflow condition would result if the current operation were performed
without a flush. If autoflush="false" then all the I/O operations on this
class shall throw an IOException if performing the current operation would
result in a buffer overflow condition.
See Also: java.io.Writer
See Also: java.io.BufferedWriter
See Also: java.io.PrintWriter |
| Field Summary | |
| final public static int | DEFAULT_BUFFER
Constant indicating that the Writer is buffered and is using the
implementation default buffer size. | | final public static int | NO_BUFFER
Constant indicating that the Writer is not buffering output. | | final public static int | UNBOUNDED_BUFFER
Constant indicating that the Writer is buffered and is unbounded; this
is used in BodyContent. | | protected boolean | autoFlush
Whether the JspWriter is autoflushing. | | protected int | bufferSize
The size of the buffer used by the JspWriter. |
| Constructor Summary | |
| protected | JspWriter(int bufferSize, boolean autoFlush)
Protected constructor. |
| Method Summary | |
| abstract public void | clear()
Clear the contents of the buffer. | | abstract public void | clearBuffer()
Clears the current contents of the buffer. | | abstract public void | close()
Close the stream, flushing it first. | | abstract public void | flush()
Flush the stream. | | public int | getBufferSize()
This method returns the size of the buffer used by the JspWriter. | | abstract public int | getRemaining()
This method returns the number of unused bytes in the buffer. | | public boolean | isAutoFlush()
This method indicates whether the JspWriter is autoFlushing. | | abstract public void | newLine()
Write a line separator. | | abstract public void | print(boolean b)
Print a boolean value. | | abstract public void | print(char c)
Print a character. | | abstract public void | print(int i)
Print an integer. | | abstract public void | print(long l)
Print a long integer. | | abstract public void | print(float f)
Print a floating-point number. | | abstract public void | print(double d)
Print a double-precision floating-point number. | | abstract public void | print(char s)
Print an array of characters. | | abstract public void | print(String s)
Print a string. | | abstract public void | print(Object obj)
Print an object. | | abstract public void | println()
Terminate the current line by writing the line separator string. | | abstract public void | println(boolean x)
Print a boolean value and then terminate the line. | | abstract public void | println(char x)
Print a character and then terminate the line. | | abstract public void | println(int x)
Print an integer and then terminate the line. | | abstract public void | println(long x)
Print a long integer and then terminate the line. | | abstract public void | println(float x)
Print a floating-point number and then terminate the line. | | abstract public void | println(double x)
Print a double-precision floating-point number and then terminate the
line. | | abstract public void | println(char x)
Print an array of characters and then terminate the line. | | abstract public void | println(String x)
Print a String and then terminate the line. | | abstract public void | println(Object x)
Print an Object and then terminate the line. |
| DEFAULT_BUFFER | | final public static int DEFAULT_BUFFER(Code) | | Constant indicating that the Writer is buffered and is using the
implementation default buffer size.
|
| NO_BUFFER | | final public static int NO_BUFFER(Code) | | Constant indicating that the Writer is not buffering output.
|
| UNBOUNDED_BUFFER | | final public static int UNBOUNDED_BUFFER(Code) | | Constant indicating that the Writer is buffered and is unbounded; this
is used in BodyContent.
|
| autoFlush | | protected boolean autoFlush(Code) | | Whether the JspWriter is autoflushing.
|
| bufferSize | | protected int bufferSize(Code) | | The size of the buffer used by the JspWriter.
|
| JspWriter | | protected JspWriter(int bufferSize, boolean autoFlush)(Code) | | Protected constructor.
Parameters:
bufferSize - the size of the buffer to be used by the JspWriter
Parameters:
autoFlush - whether the JspWriter should be autoflushing |
| clear | | abstract public void clear() throws IOException(Code) | | Clear the contents of the buffer. If the buffer has been already
been flushed then the clear operation shall throw an IOException
to signal the fact that some data has already been irrevocably
written to the client response stream.
throws:
IOException - If an I/O error occurs |
| clearBuffer | | abstract public void clearBuffer() throws IOException(Code) | | Clears the current contents of the buffer. Unlike clear(), this
method will not throw an IOException if the buffer has already been
flushed. It merely clears the current content of the buffer and
returns.
throws:
IOException - If an I/O error occurs |
| close | | abstract public void close() throws IOException(Code) | | Close the stream, flushing it first.
This method needs not be invoked explicitly for the initial JspWriter
as the code generated by the JSP container will automatically
include a call to close().
Closing a previously-closed stream, unlike flush(), has no effect.
exception:
IOException - If an I/O error occurs |
| flush | | abstract public void flush() throws IOException(Code) | | Flush the stream. If the stream has saved any characters from the
various write() methods in a buffer, write them immediately to their
intended destination. Then, if that destination is another character or
byte stream, flush it. Thus one flush() invocation will flush all the
buffers in a chain of Writers and OutputStreams.
The method may be invoked indirectly if the buffer size is exceeded.
Once a stream has been closed,
further write() or flush() invocations will cause an IOException to be
thrown.
exception:
IOException - If an I/O error occurs |
| getBufferSize | | public int getBufferSize()(Code) | | This method returns the size of the buffer used by the JspWriter.
the size of the buffer in bytes, or 0 is unbuffered. |
| getRemaining | | abstract public int getRemaining()(Code) | | This method returns the number of unused bytes in the buffer.
the number of bytes unused in the buffer |
| isAutoFlush | | public boolean isAutoFlush()(Code) | | This method indicates whether the JspWriter is autoFlushing.
if this JspWriter is auto flushing or throwing IOExceptions on buffer overflow conditions |
| newLine | | abstract public void newLine() throws IOException(Code) | | Write a line separator. The line separator string is defined by the
system property line.separator, and is not necessarily a single
newline ('\n') character.
exception:
IOException - If an I/O error occurs |
| print | | abstract public void print(boolean b) throws IOException(Code) | | Print a boolean value. The string produced by
java.lang.String.valueOf(boolean) is written to the
JspWriter's buffer or, if no buffer is used, directly to the
underlying writer.
Parameters:
b - The boolean to be printed
throws:
java.io.IOException - If an error occured while writing |
| print | | abstract public void print(char c) throws IOException(Code) | | Print a character. The character is written to the
JspWriter's buffer or, if no buffer is used, directly to the
underlying writer.
Parameters:
c - The char to be printed
throws:
java.io.IOException - If an error occured while writing |
| print | | abstract public void print(char s) throws IOException(Code) | | Print an array of characters. The characters are written to the
JspWriter's buffer or, if no buffer is used, directly to the
underlying writer.
Parameters:
s - The array of chars to be printed
throws:
NullPointerException - If s is null
throws:
java.io.IOException - If an error occured while writing |
| print | | abstract public void print(String s) throws IOException(Code) | | Print a string. If the argument is null then the string
"null" is printed. Otherwise, the string's characters are
written to the JspWriter's buffer or, if no buffer is used, directly
to the underlying writer.
Parameters:
s - The String to be printed
throws:
java.io.IOException - If an error occured while writing |
| println | | abstract public void println() throws IOException(Code) | | Terminate the current line by writing the line separator string. The
line separator string is defined by the system property
line.separator, and is not necessarily a single newline
character ('\n').
throws:
java.io.IOException - If an error occured while writing |
| println | | abstract public void println(char x) throws IOException(Code) | | Print an array of characters and then terminate the line. This method
behaves as though it invokes print(char[]) and then
println().
Parameters:
x - the char[] to write
throws:
java.io.IOException - If an error occured while writing |
|
|
|