Analysis and Resolution of 'getOutputStream() has already been called for this response' Error in JSP

Problem Background and Error Analysis

In Java Web development, particularly when using JSP (JavaServer Pages) technology, developers may encounter the java.lang.IllegalStateException: getOutputStream() has already been called for this response exception. This error typically occurs when directly manipulating the HTTP response output stream in a JSP page, conflicting with the JSP engine's default behavior.

In-depth Mechanism Analysis

From the provided error stack trace, the exception occurs in the org.apache.catalina.connector.Response.getWriter() method. This is because, according to the Servlet specification, each HTTP response object can only call getOutputStream() or getWriter() once, and they cannot be mixed. The JSP engine implicitly calls getWriter() during page rendering to output HTML content, while the developer explicitly calls response.getOutputStream() in the code to output PDF binary data, creating a conflict.

Specifically, in the example code:

<%
    response.setContentType("application/pdf");
    Document document = new Document();
    try{
        ByteArrayOutputStream buffer = new ByteArrayOutputStream();
        PdfWriter.getInstance(document, buffer);
        document.open();
        PdfPTable table = new PdfPTable(2);
        table.addCell("1");
        table.addCell("2");
        table.addCell("3");
        table.addCell("4");
        table.addCell("5");
        table.addCell("6");
        document.add(table);
        document.close();
        DataOutput dataOutput = new DataOutputStream(response.getOutputStream());
        byte[] bytes = buffer.toByteArray();
        response.setContentLength(bytes.length);
        for(int i = 0; i &lt; bytes.length; i++)
        {
        dataOutput.writeByte(bytes[i]);
        }
    }catch(DocumentException e){
        e.printStackTrace();
    }
%>

After calling response.getOutputStream(), the JSP engine attempts to clean up resources at the end of the page and calls getWriter(), which then throws the IllegalStateException.

Solutions and Best Practices

Solution 1: Using the trimDirectiveWhitespaces Directive

Adding the following directive at the top of the JSP page can eliminate whitespace around directives, reducing unnecessary output:

<%@ page trimDirectiveWhitespaces="true" %>

Or configure it globally in web.xml:

<jsp-config>
  <jsp-property-group>
    <url-pattern>*.jsp</url-pattern>
    <trim-directive-whitespaces>true</trim-directive-whitespaces>
  </jsp-property-group>
</jsp-config>

Solution 2: Improving Output Stream Management

After completing data writing, properly close and flush the output stream, and return immediately to avoid subsequent JSP processing:

dataOutput.flush();
dataOutput.close();
return;

Solution 3: Using Servlet Instead of JSP

For scenarios generating binary content (like PDF), it is more recommended to use Servlet instead of JSP. Servlet is specifically designed for handling HTTP requests and responses and does not cause implicit output conflicts like JSP.

Technical Details and Considerations

When dealing with similar issues, it is important to pay attention to HTML escaping rules. For example, in code examples, < represents the escaped form of the less-than symbol < to prevent it from being parsed as an HTML tag. Similarly, when describing HTML tags, such as discussing the semantics of the <br> tag, appropriate escaping is necessary.

By understanding how JSP and Servlet work, and correctly managing the HTTP response output stream, developers can effectively avoid such errors and improve the stability and performance of web applications.