ServletResponse object and
* passes it as an argument to the servlet's service method.
*
* To send binary data in a MIME body response, use
* the {@link ServletOutputStream} returned by {@link #getOutputStream}.
* To send character data, use the PrintWriter object
* returned by {@link #getWriter}. To mix binary and text data,
* for example, to create a multipart response, use a
* ServletOutputStream and manage the character sections
* manually.
*
*
The charset for the MIME body response can be specified with
* {@link #setContentType}. For example, "text/html; charset=Shift_JIS".
* The charset can alternately be set using {@link #setLocale}.
* If no charset is specified, ISO-8859-1 will be used.
* The setContentType or setLocale method
* must be called before getWriter for the charset to
* affect the construction of the writer.
*
*
See the Internet RFCs such as * * RFC 2045 for more information on MIME. Protocols such as SMTP * and HTTP define profiles of MIME, and those standards * are still evolving. * * @author Various * @version $Version$ * * @see ServletOutputStream * */ public interface ServletResponse { /** * Returns the name of the charset used for * the MIME body sent in this response. * *
If no charset has been assigned, it is implicitly
* set to ISO-8859-1 (Latin-1).
*
*
See RFC 2047 (http://ds.internic.net/rfc/rfc2045.txt)
* for more information about character encoding and MIME.
*
* @return a String specifying the
* name of the charset, for
* example, ISO-8859-1
*
*/
public String getCharacterEncoding();
/**
* Returns a {@link ServletOutputStream} suitable for writing binary
* data in the response. The servlet container does not encode the
* binary data.
*
Calling flush() on the ServletOutputStream commits the response.
* Either this method or {@link #getWriter} may
* be called to write the body, not both.
*
* @return a {@link ServletOutputStream} for writing binary data
*
* @exception IllegalStateException if the getWriter method
* has been called on this response
*
* @exception IOException if an input or output exception occurred
*
* @see #getWriter
*
*/
public ServletOutputStream getOutputStream() throws IOException;
/**
* Returns a PrintWriter object that
* can send character text to the client.
* The character encoding used is the one specified
* in the charset= property of the
* {@link #setContentType} method, which must be called
* before calling this method for the charset to take effect.
*
*
If necessary, the MIME type of the response is * modified to reflect the character encoding used. * *
Calling flush() on the PrintWriter commits the response. * *
Either this method or {@link #getOutputStream} may be called
* to write the body, not both.
*
*
* @return a PrintWriter object that
* can return character data to the client
*
* @exception UnsupportedEncodingException if the charset specified in
* setContentType cannot be
* used
*
* @exception IllegalStateException if the getOutputStream
* method has already been called for this
* response object
*
* @exception IOException if an input or output exception occurred
*
* @see #getOutputStream
* @see #setContentType
*
*/
public PrintWriter getWriter() throws IOException;
/**
* Sets the length of the content body in the response
* In HTTP servlets, this method sets the HTTP Content-Length header.
*
*
* @param len an integer specifying the length of the
* content being returned to the client; sets
* the Content-Length header
*
*/
public void setContentLength(int len);
/**
* Sets the content type of the response being sent to
* the client. The content type may include the type of character
* encoding used, for example, text/html; charset=ISO-8859-4.
*
*
If obtaining a PrintWriter, this method should be
* called first.
*
*
* @param type a String specifying the MIME
* type of the content
*
* @see #getOutputStream
* @see #getWriter
*
*/
public void setContentType(String type);
/**
* Sets the preferred buffer size for the body of the response.
* The servlet container will use a buffer at least as large as
* the size requested. The actual buffer size used can be found
* using getBufferSize.
*
*
A larger buffer allows more content to be written before anything is * actually sent, thus providing the servlet with more time to set * appropriate status codes and headers. A smaller buffer decreases * server memory load and allows the client to start receiving data more * quickly. * *
This method must be called before any response body content is
* written; if content has been written, this method throws an
* IllegalStateException.
*
* @param size the preferred buffer size
*
* @exception IllegalStateException if this method is called after
* content has been written
*
* @see #getBufferSize
* @see #flushBuffer
* @see #isCommitted
* @see #reset
*
*/
public void setBufferSize(int size);
/**
* Returns the actual buffer size used for the response. If no buffering
* is used, this method returns 0.
*
* @return the actual buffer size used
*
* @see #setBufferSize
* @see #flushBuffer
* @see #isCommitted
* @see #reset
*
*/
public int getBufferSize();
/**
* Forces any content in the buffer to be written to the client. A call
* to this method automatically commits the response, meaning the status
* code and headers will be written.
*
* @see #setBufferSize
* @see #getBufferSize
* @see #isCommitted
* @see #reset
*
*/
public void flushBuffer() throws IOException;
/**
* Clears the content of the underlying buffer in the response without
* clearing headers or status code. If the
* response has been committed, this method throws an
* IllegalStateException.
*
* @see #setBufferSize
* @see #getBufferSize
* @see #isCommitted
* @see #reset
*
* @since 2.3
*/
public void resetBuffer();
/**
* Returns a boolean indicating if the response has been
* committed. A commited response has already had its status
* code and headers written.
*
* @return a boolean indicating if the response has been
* committed
*
* @see #setBufferSize
* @see #getBufferSize
* @see #flushBuffer
* @see #reset
*
*/
public boolean isCommitted();
/**
* Clears any data that exists in the buffer as well as the status code and
* headers. If the response has been committed, this method throws an
* IllegalStateException.
*
* @exception IllegalStateException if the response has already been
* committed
*
* @see #setBufferSize
* @see #getBufferSize
* @see #flushBuffer
* @see #isCommitted
*
*/
public void reset();
/**
* Sets the locale of the response, setting the headers (including the
* Content-Type's charset) as appropriate. This method should be called
* before a call to {@link #getWriter}. By default, the response locale
* is the default locale for the server.
*
* @param loc the locale of the response
*
* @see #getLocale
*
*/
public void setLocale(Locale loc);
/**
* Returns the locale assigned to the response.
*
*
* @see #setLocale
*
*/
public Locale getLocale();
}