SRV.6.1 Buffering

In order to improve efficiency, a servlet container is allowed, but not required by default, to buffer output going to the client. The following methods are provided via the ServletResponse interface to allow a servlet access to, and the setting of, buffering information:

• getBufferSize

• setBufferSize

• isCommitted

• reset

• flushBuffer

These methods are provided on the ServletResponse interface to allow buffering operations to be performed whether the servlet is using a ServletOutputStream or a Writer .

The getBufferSize method returns the size of the underlying buffer being used. If no buffering is being used for this response, this method must return the int value of 0 (zero) .

The servlet can request a preferred buffer size for the response by using the set BufferSize method. The actual buffer assigned to this request is not required to be the same size as requested by the servlet, but must be at least as large as the buffer size requested. This allows the container to reuse a set of fixed size buffers, provid-ing a larger buffer than requested , if appropriate. This method must be called before any content is written using a ServletOutputStream or Writer . If any content has been written, this method must throw an IllegalStateException .

The isCommitted method returns a boolean value indicating whether or not any bytes from the response have yet been returned to the client. The flushBuffer method forces any content in the buffer to be written to the client.

The reset method clears any data that exists in the buffer as long as the response is not considered to be committed. All headers and the status code set by the servlet previous to the reset called must be cleared as well.

If the response is committed and the reset method is called, an IllegalStateException must be thrown. In this case, the response and its associated buffer will be unchanged.

When the buffer in use is filled, the container must immediatly flush the contents of the buffer to the client. If this is the first time for this request that data is sent to the client, the response is considered to be committed at this point.