org.simpleframework.http

## Interface Response

All Superinterfaces:
  ResponseHeader, StatusLine

All Known Implementing Classes:
  ResponseWrapper

    public interface Response
    extends ResponseHeader

This is used to represent the HTTP response. This provides methods that can be used to set various characteristics of the response. An `OutputStream` can be acquired via this interface which can be used to write the response body. A buffer size can be specified when acquiring the output stream which allows data to be buffered until it over flows or is flushed explicitly. This buffering allows a partially written response body to be reset.

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 been sent. To ensure that the response is sent the `close` method of the response or the output stream should be used. This will notify the server to dispatch the next request in the pipeline for processing.

Author:
  Niall Gallagher

### Method Summary

Methods
`void` `close()` This is used to close the connection and commit the request.
`void` `commit()` This is used to write the headers that where given to the `Response`.
`java.nio.channels.WritableByteChannel` `getByteChannel()` Used to write a message body with the `Response`.
`java.nio.channels.WritableByteChannel` `getByteChannel(int size)` Used to write a message body with the `Response`.
`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()` This can be used to determine whether the `Response` has been committed.
`void` `setContentLength(int length)` This should be used when the size of the message body is known.

### Methods inherited from interface org.simpleframework.http.ResponseHeader

`add, add, addDate, contains, getContentLength, getContentType, getCookie, getCookies, getDate, getInteger, getNames, getTransferEncoding, getValue, getValues, remove, set, set, setCookie, setCookie, setDate`

### Methods inherited from interface org.simpleframework.http.StatusLine

`getCode, getMajor, getMinor, getText, setCode, setMajor, setMinor, setText`

### Method Detail

#### setContentLength

    void setContentLength(int length)

This should be used when the size of the message body 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 output stream or request is closed.

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

#### 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.

Returns:
  an output stream object with the specified semantics
Throws:
  `java.io.IOException`

#### 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.

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.

Returns:
  an output stream object with the specified semantics
Throws:
  `java.io.IOException`

#### 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 print stream that provides convenience writing
Throws:
  `java.io.IOException`

#### 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 print stream that provides convenience writing
Throws:
  `java.io.IOException`

#### getByteChannel

    java.nio.channels.WritableByteChannel getByteChannel()
                                                         throws java.io.IOException

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.

Returns:
  a writable byte channel used to write the message body
Throws:
  `java.io.IOException`

#### getByteChannel

    java.nio.channels.WritableByteChannel getByteChannel(int size)
                                                         throws java.io.IOException

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.

Parameters:
  `size` - the minimum size that the response buffer must be
Returns:
  a writable byte channel used to write the message body
Throws:
  `java.io.IOException`

#### 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 headers have been committed

#### 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

#### reset

    void reset()
               throws java.io.IOException

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:
  `java.io.IOException` - thrown if there is a problem resetting

#### close

    void close()
               throws java.io.IOException

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:
  `java.io.IOException` - thrown if there is a problem writing