[ Team LiB ] Previous Section Next Section

The JspWriter Class

The JspWriter class acts like the PrintWriter class most of the time, except that it is specially tailored to deal with the buffering you need to do in a JSP. If you look at the PrintWriter class, none of the print or println methods throw an IOException. On the other hand, the JspWriter versions of print and println can and will throw an IOException if the buffer fills up and is not automatically flushed.

In addition to the print and println methods, the JspWriter class gives you access to information about buffering. Using this information, you can flush the buffer if necessary or determine how much more you can write to the buffer before it needs to be flushed.

If in Doubt, Use Default Buffering

graphics/bytheway_icon.gif

Don't worry if you don't understand buffering, or if it seems overly complicated. If you use the default settings, you don't have to worry about it at all.


Sending Output Data

Most of the time, you aren't explicitly sending output in your JSP. In other words, you aren't calling the out.print or out.println methods directly. Instead, you put the text that you want to display directly into the JSP. If you look at the servlet generated from your JSP source file, however, you see that the JSP compiler took that text and converted it into an out.print or out.println statement.

Occasionally, you'll need to write to the output stream from within your JSP. For example, you might have a huge block of Java code that loops through some data to extract items that you want to display. Rather than closing the scriptlet and using a JSP expression to display the data, you are much better off calling out.print or out.println.

The print and println methods available in the JspWriter class are


public void print(boolean b) throws IOException
public void print(char c) throws IOException
public void print(char[] s) throws IOexception
public void print(double d) throws IOException
public void print(float f) throws IOException
public void print(int i) throws IOException
public void print(long l) throws IOException
public void print(Object obj) throws IOException
public void print(String s) throws IOException
public void println()throws IOException
public void println(boolean b) throws IOException
public void println(char c) throws IOException
public void println(char[] x) throws IOException
public void println(double d) throws IOException
public void println(float f) throws IOException
public void println(int i) throws IOException
public void println(long l) throws IOException
public void println(Object obj) throws IOException
public void println(String s) throws IOException

Also, instead of calling out.println() to print a blank line, you can call out.newLine().

Because the JspWriter is a subclass of the Writer class, you can also use the write method to write out a string, a single character, or an array of characters:


public void write(String str)
public void write(String str, int offset, int length)
public void write(int singleCharacter)
public void write(char[] charArray)
public void write(char[] charArray, int offset, int length)

Buffer Control

Automatic buffer flushing can be turned off if you want to have more control over when information is sent. It's a simple matter of telling a page that you'll be managing the buffering. You'll learn the details in the next chapter.

If you turn off automatic buffer flushing, the most important method to you, aside from print and println, is the flush method:


public void flush()

If you have a chain of writers set up (that is, if the output of the JspWriter is going to another writer) the flush method flushes all the writers along the output chain. In other words, calling flush ensures that the current contents of the buffer get sent back to the browser, even if they need to go through another writer first.

Rather than flush the buffer, you might need to clear it out, erasing its current contents. The clear or clearBuffer methods empty out the buffer's contents:


public void clear() throws IOException
public void clearBuffer() throws IOException

It might seem strange to have two methods that appear to do the same thing. The clear method, though, throws an IOException if the buffer has been flushed before. The idea is that when you clear the buffer, the chances are good that you meant to clear out the entire page. If the buffer has been flushed, you aren't clearing out the entire page because some of it has already been sent back to the browser. When that happens, you want the system to let you know that it can't do what you want.

If you want to clear the current contents of the buffer, and you don't care whether the buffer has been flushed before, use the clearBuffer method.

The getBufferSize method returns the buffer's size in bytes, and the getRemaining method returns the number of bytes left in the buffer:


public int getBufferSize()
public int getRemaining()

If buffering is turned off, the getBufferSize method returns 0.

The isAutoFlush method returns true if the system is handling the automatic flushing of the buffer:


public boolean isAutoFlush()

In Case of Trouble

graphics/bytheway_icon.gif

If you are having trouble getting the buffering to work correctly, see the "Q&A" section at the end of this hour.


Using a PrintWriter

Sometimes, you need a real PrintWriter object rather than JspWriter. For example, the printStackTrace method in the Throwable class can print a stack trace to a PrintStream or a PrintWriter. Unfortunately, JspWriter is neither of these. You can, however, create a new PrintWriter on top of a Writer object. Thus, if you absolutely need a PrintWriter, just create one around the JspWriter. Listing 8.1 shows a JSP that uses the printStackTrace method to print a stack trace.

Listing 8.1 Source Code for PrintException.jsp
<%@ page language="java" import="java.io.*" %>

<html>
<body bgcolor="#ffffff">
<pre>
<%
    try
    {
        throw new RuntimeException("Print me, please");
    }
    catch (RuntimeException exc)
    {
        PrintWriter pw = new PrintWriter(out);

        exc.printStackTrace(pw);
    }
%>
</pre>
</body>
</html>

Figure 8.1 shows the output from the PrintException JavaServer Page.

Figure 8.1. You can create a PrintWriter to print a stack trace to the browser.

graphics/08fig01.jpg

    [ Team LiB ] Previous Section Next Section