RequestDispatcher.forward()

The following quote is from the RequestDispatcher API:

forward should be called before the response has been committed to the client (before response body output has been flushed). If the response already has been committed, this method throws an IllegalStateException. Uncommitted output in the response buffer is automatically cleared before the forward.

When I run the following code:

import javax.servlet.* ;
import javax.servlet.http.* ;
import java.io.* ;
public class SourceServlet extends HttpServlet
{
    protected void doGet( HttpServletRequest req , HttpServletResponse res )
            throws ServletException , IOException
    {
        res.setContentType( "text/html" );
        PrintWriter out = res.getWriter();
        out.println( "<html><head><title>The Test</title></head>" );
        out.println( "<body>Will you see the source?</body></html>" );
        RequestDispatcher disp = req.getRequestDispatcher( "/servlet/TargetServlet" );
        disp.forward( req , res );
        out.close();
    }
}

import javax.servlet.* ;
import javax.servlet.http.* ;
import java.io.* ;
public class TargetServlet extends HttpServlet
{
    protected void doGet( HttpServletRequest req , HttpServletResponse res )
            throws ServletException , IOException
    {
        res.setContentType( "text/html" );
        PrintWriter out = res.getWriter();
        out.println( "<html><head><title>The Test</title></head>" );
        out.println( "<body>Will you see the target?</body></html>" );
        out.close();
    }
}

I get the following output:
Will you see the source? Will you see the target?
I was expecting to receive either an exception or Will you see the target. Why am I getting the output from both servlets?

The point is that the output from the first servlet has not been flushed from the buffer that out writes to. Your second servlet could call the ServletResponse method resetBuffer() or reset() and thus discard what the first servlet wrote. Thats what is meant by uncommitted output.
Note that you can call the ServletResponse method setBufferSize() before doing any writing if you want your first servlet to be capable of writing more than just a few lines.
Bill

Thank you for your reply. My confusion stems from the fact that the API states that the response buffer will automatically be cleared before forward is called. It does not seem to be doing that.

You are right - that statement in the API contradicts what you observe and other statements in the JavaDocs API!
----- the servlet API in PDF form says:
The forward method of the RequestDispatcher interface may be called by the
calling servlet only when no output has been committed to the client. If output data
exists in the response buffer that has not been committed, the content must be
cleared before the target servlet�s service method is called. If the response has been
committed, an IllegalStateException must be thrown.
The path elements of the request object exposed to the target servlet must
reflect the path used to obtain the RequestDispatcher.
The only exception to this is if the RequestDispatcher was obtained via the
getNamedDispatcher method. In this case, the path elements of the request object
must reflect those of the original request. Before the forward method of the RequestDispatcher interface returns, the
response content must be sent and committed, and closed by the servlet container.
---------
So it looks to me like there is a conflict between the specs and reality.
Bill
[ August 02, 2002: Message edited by: William Brogden ]

Matthew, what container were you using? I remember coding a similar "prove it to myself" servlet pair and it worked as expected (per the API).

Originally posted by Mike Curwen:
Matthew, what container were you using? I remember coding a similar "prove it to myself" servlet pair and it worked as expected (per the API).

It was Orion, but I am not sure of the version at the moment.
[ August 07, 2002: Message edited by: Matthew Phillips ]

TC 4.0.1 behaves as expected, I just double-checked by using your code.

Originally posted by Mike Curwen:
TC 4.0.1 behaves as expected, I just double-checked by using your code.

That's interesting. I will have to try it. I guess Orion doesn't properly implement that behavior. Thanks.