simple.http
Interface Response

All Superinterfaces:
GenericHeader, StatusLine
All Known Implementing Classes:
FilterResponse

public interface Response
extends StatusLine, GenericHeader

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.

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

Method Summary
 void commit()
          This is used to write the headers that where given to the Response.
 java.lang.Object getAttribute(java.lang.String name)
          This is used as a shortcut for acquiring attributes for the response.
 Attributes getAttributes()
          This can be used to retrieve certain attributes about this Response.
 java.net.InetAddress getInetAddress()
          This can be used to get the I.P address for the browser that the Response goes to.
 java.io.OutputStream getOutputStream()
          Used to write a message body with the Response.
 java.io.OutputStream getOutputStream(int size)
          Used to write a message body with the Response.
 java.io.PrintStream getPrintStream()
          This method is provided for convenience so that the HTTP content can be written using the print methods provided by the PrintStream.
 java.io.PrintStream getPrintStream(int size)
          This method is provided for convenience so that the HTTP content can be written using the print methods provided by the PrintStream.
 boolean isCommitted()
          This can be used to determine whether the Response has been committed.
 void reset()
          The reset method is used to reset the output from an issued OutputStream.
 void setContentLength(int length)
          This should be used when the size of the message body is known.
 java.lang.String toString()
          This constructs the HTTP message header according to the format of RFC 2616.
 
Methods inherited from interface simple.http.StatusLine
getCode, getMajor, getMinor, getText, setCode, setMajor, setMinor, setText
 
Methods inherited from interface simple.http.GenericHeader
add, add, addDate, clear, contains, contains, getDate, getDate, getName, getValue, getValue, getValues, headerCount, indexOf, indexOf, remove, removeAll, set, set, setDate
 

Method Detail

setContentLength

void setContentLength(int length)
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.

Parameters:
length - this is the length of the HTTP message body

getAttributes

Attributes getAttributes()
This can be used to retrieve certain attributes about this Response. The attributes contains certain properties about the Response. For example if this Response goes over a secure line then there may be any arbitrary attributes.

Returns:
the attributes of this Response object

getAttribute

java.lang.Object getAttribute(java.lang.String name)
This is used as a shortcut for acquiring attributes for the response. This avoids acquiring the Attributes in order to retrieve the attribute directly from that object. The attributes contain data specific to the response.

Parameters:
name - this is the name of the attribute to acquire
Returns:
this returns the attribute for the specified name

getInetAddress

java.net.InetAddress getInetAddress()
This can be used to get the I.P address for the browser that the Response goes to. The Attributes shares this information. This method is used to that objects can determine, based on the retrieved I.P address, what type of output is suitable. Statistics such as location can be determined based on the DNS address obtained.

Returns:
returns the source I.P. address of the client

getOutputStream

java.io.OutputStream getOutputStream()
                                     throws java.io.IOException
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. The OutputStream issued must be thread safe so that it can be used in a concurrent environment.

Returns:
an OutputStream with the specified semantics
Throws:
java.io.IOException - this is thrown if there was an I/O error

getOutputStream

java.io.OutputStream getOutputStream(int size)
                                     throws java.io.IOException
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. The OutputStream issued must be thread safe so that it can be used in a concurrent environment.

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.

Parameters:
size - the minimum size that the response buffer must be
Returns:
an OutputStream with the specified semantics
Throws:
java.io.IOException - this is thrown if there was an I/O error

getPrintStream

java.io.PrintStream getPrintStream()
                                   throws java.io.IOException
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.

Returns:
a PrintStream that provides convenience methods to the Response for writing content
Throws:
java.io.IOException - this is thrown if there was an I/O error

getPrintStream

java.io.PrintStream getPrintStream(int size)
                                   throws java.io.IOException
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.

Parameters:
size - the minimum size that the response buffer must be
Returns:
a PrintStream that provides convenience methods to the Response for writing content
Throws:
java.io.IOException - this is thrown if there was an I/O error

commit

void commit()
            throws java.io.IOException
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.

Throws:
java.io.IOException - thrown if there was a problem writing

isCommitted

boolean isCommitted()
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.

Returns:
true if the Response has been committed

reset

void reset()
The reset method is used to reset the output from an issued OutputStream. This will not work is the isCommitted returns true. If the streams byte buffer overflows the response will commit and the reset will fail.


toString

java.lang.String toString()
This constructs the HTTP message header according to the format of RFC 2616. This returns a String that contains each header formatted according to the HTTP/1.1 header format. The header will contain the status line followed by each header and ended with the CRLF.

Overrides:
toString in class java.lang.Object
Returns:
the HTTP response header in string format