org.simpleframework.http.Response Maven / Gradle / Ivy
/*
* Response.java February 2001
*
* Copyright (C) 2001, Niall Gallagher
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General
* Public License along with this library; if not, write to the
* Free Software Foundation, Inc., 59 Temple Place, Suite 330,
* Boston, MA 02111-1307 USA
*/
package org.simpleframework.http;
import java.io.OutputStream;
import java.io.PrintStream;
import java.nio.channels.WritableByteChannel;
/**
* This is used to represent the HTTP response. This provides methods
* that can be used to set various characteristics of the response.
* The OutputStream of the Response can be
* retrieved from this interface as can the I.P address of the client
* that will be receiving the Response. The attributes
* of the connection can be retrieved also. This provides a set of
* methods that can be used to set the attributes of the stream so
* the Response can be transported properly. The headers
* can be set and will be sent once a commit is made, or when there
* is content sent over the output stream.
*
* This should never allow the message body be sent if it should not
* be sent with the headers as of RFC 2616 rules for the presence of
* a message body. A message body must not be included with a HEAD
* request or with a 304 or a 204 response. A proper implementation
* of this will prevent a message body being sent if the response
* is to a HEAD request of if there is a 304 or 204 response code.
*
* It is important to note that the Response controls
* the processing of the HTTP pipeline. The next HTTP request is
* not processed until the response has committed. The response is
* committed once the commit method is invoked if there
* is NO content body. Committing with a content body is done only if
* correct content is given. The OutputStream acts as
* a client and commits the response once the specified content has
* been written to the issued OutputStream.
*
* @author Niall Gallagher
*/
public interface Response extends ResponseHeader {
/**
* This should be used when the size of the message body is known. For
* performance reasons this should be used so the length of the output
* is known. This ensures that Persistent HTTP (PHTTP) connections
* can be maintained for both HTTP/1.0 and HTTP/1.1 clients. If the
* length of the output is not known HTTP/1.0 clients will require a
* connection close, which reduces performance (see RFC 2616).
*
* This removes any previous Content-Length headers from the message
* header. This will then set the appropriate Content-Length header with
* the correct length. If a the Connection header is set with the close
* token then the semantics of the connection are such that the server
* will close it once the OutputStream.close is used.
*
* @param length this is the length of the HTTP message body
*/
public void setContentLength(int length);
/**
* Used to write a message body with the Response. The
* semantics of this OutputStream will be determined
* by the HTTP version of the client, and whether or not the content
* length has been set, through the setContentLength
* method. If the length of the output is not known then the output
* is chunked for HTTP/1.1 clients and closed for HTTP/1.0 clients.
*
* @return an output stream object with the specified semantics
*/
public OutputStream getOutputStream() throws Exception;
/**
* Used to write a message body with the Response. The
* semantics of this OutputStream will be determined
* by the HTTP version of the client, and whether or not the content
* length has been set, through the setContentLength
* method. If the length of the output is not known then the output
* is chunked for HTTP/1.1 clients and closed for HTTP/1.0 clients.
*
* This will ensure that there is buffering done so that the output
* can be reset using the reset method. This will
* enable the specified number of bytes to be written without
* committing the response. This specified size is the minimum size
* that the response buffer must be.
*
* @return an output stream object with the specified semantics
*/
public OutputStream getOutputStream(int size) throws Exception;
/**
* This method is provided for convenience so that the HTTP content
* can be written using the print methods provided by
* the PrintStream. This will basically wrap the
* getOutputStream with a buffer size of zero.
*
* The retrieved PrintStream uses the charset used to
* describe the content, with the Content-Type header. This will
* check the charset parameter of the contents MIME type. So if
* the Content-Type was text/plain; charset=UTF-8 the
* resulting PrintStream would encode the written data
* using the UTF-8 encoding scheme. Care must be taken to ensure
* that bytes written to the stream are correctly encoded.
*
* Implementations of the Response must guarantee
* that this can be invoked repeatedly without effecting any issued
* OutputStream or PrintStream object.
*
* @return a PrintStream that provides convenience
* methods to the Response for writing content
*
* @exception Exception this is thrown if there was an I/O error
*/
public PrintStream getPrintStream() throws Exception;
/**
* This method is provided for convenience so that the HTTP content
* can be written using the print methods provided by
* the PrintStream. This will basically wrap the
* getOutputStream with a specified buffer size.
*
* The retrieved PrintStream uses the charset used to
* describe the content, with the Content-Type header. This will
* check the charset parameter of the contents MIME type. So if
* the Content-Type was text/plain; charset=UTF-8 the
* resulting PrintStream would encode the written data
* using the UTF-8 encoding scheme. Care must be taken to ensure
* that bytes written to the stream are correctly encoded.
*
* Implementations of the Response must guarantee
* that this can be invoked repeatedly without effecting any issued
* OutputStream or PrintStream object.
*
* @param size the minimum size that the response buffer must be
*
* @return a PrintStream that provides convenience
* methods to the Response for writing content
*
* @exception Exception this is thrown if there was an I/O error
*/
public PrintStream getPrintStream(int size) throws Exception;
/**
* Used to write a message body with the Response. The
* semantics of this WritableByteChannel are determined
* by the HTTP version of the client, and whether or not the content
* length has been set, through the setContentLength
* method. If the length of the output is not known then the output
* is chunked for HTTP/1.1 clients and closed for HTTP/1.0 clients.
*
* @return a writable byte channel used to write the message body
*/
public WritableByteChannel getByteChannel() throws Exception;
/**
* Used to write a message body with the Response. The
* semantics of this WritableByteChannel are determined
* by the HTTP version of the client, and whether or not the content
* length has been set, through the setContentLength
* method. If the length of the output is not known then the output
* is chunked for HTTP/1.1 clients and closed for HTTP/1.0 clients.
*
* This will ensure that there is buffering done so that the output
* can be reset using the reset method. This will
* enable the specified number of bytes to be written without
* committing the response. This specified size is the minimum size
* that the response buffer must be.
*
* @param size the minimum size that the response buffer must be
*
* @return a writable byte channel used to write the message body
*/
public WritableByteChannel getByteChannel(int size) throws Exception;
/**
* This can be used to determine whether the Response
* has been committed. This is true if the Response
* was committed, either due to an explicit invocation of the
* commit method or due to the writing of content. If
* the Response has committed the reset
* method will not work in resetting content already written.
*
* @return true if the Response has been committed
*/
public boolean isCommitted();
/**
* This is used to write the headers that where given to the
* Response. Any further attempts to give headers
* to the Response will be futile as only the headers
* that were given at the time of the first commit will be used
* in the message header.
*
* This also performs some final checks on the headers submitted.
* This is done to determine the optimal performance of the
* output. If no specific Connection header has been specified
* this will set the connection so that HTTP/1.0 closes by default.
*
* @exception Exception thrown if there was a problem writing
*/
public void commit() throws Exception;
/**
* This can be used to determine whether the Response
* has been committed. This is true if the Response
* was committed, either due to an explicit invocation of the
* commit method or due to the writing of content. If
* the Response has committed the reset
* method will not work in resetting content already written.
*
* @throws Exception thrown if there is a problem resetting
*/
public void reset() throws Exception;
/**
* This is used to close the connection and commit the request.
* This provides the same semantics as closing the output stream
* and ensures that the HTTP response is committed. This will
* throw an exception if the response can not be committed.
*
* @throws Exception thrown if there is a problem writing
*/
public void close() throws Exception;
}