# Class ResponseWrapper

java.lang.Object
org.simpleframework.http.ResponseWrapper

All Implemented Interfaces:
  `Response, ResponseHeader, StatusLine`

public class ResponseWrapper extends Object implements Response
The `ResponseWrapper` object is used so that the original `Response` object can be wrapped in a filtering proxy object. This allows a container to interact with an implementation of this with overridden methods providing specific functionality. the `Response` object in a concurrent environment.

       public void handle(Request req, Response resp) {
          handler.handle(req, new ZipResponse(resp));
       }

The above is an example of how the `ResponseWrapper` can be used to provide extra functionality to a `Response` in a transparent manner. Such an implementation could apply a Content-Encoding header and compress the response for performance over a slow network. Filtering can be applied with the use of layered `Container` objects.

Author:
  Niall Gallagher
See Also:
  - `Container`

## Field Summary

Fields
Modifier and Type
Field
Description
`protected Response`
`response`
This is the response instance that is being wrapped.

## Constructor Summary

Constructors
Constructor
Description
`ResponseWrapper(Response response)`
Constructor for `ResponseWrapper` object.

## Method Summary

Modifier and Type
Method
Description
`void`
`add(String name, int value)`
This can be used to add a HTTP message header to this object.
`void`
`add(String name, String value)`
This can be used to add a HTTP message header to this object.
`void`
`addDate(String name, long date)`
This is used as a convenience method for adding a header that needs to be parsed into a HTTPdate string.
`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`.
`boolean`
`contains(String name)`
This is used to see if there is a HTTP message header with the given name in this container.
`WritableByteChannel`
`getByteChannel()`
Used to write a message body with the `Response`.
`WritableByteChannel`
`getByteChannel(int size)`
Used to write a message body with the `Response`.
`int`
`getCode()`
This represents the status code of the HTTP response.
`int`
`getContentLength()`
This is a convenience method that can be used to determine the length of the message body.
`ContentType`
`getContentType()`
This is a convenience method that can be used to determine the content type of the message body.
`Cookie`
`getCookie(String name)`
This returns the `Cookie` object stored under the specified name.
`List<Cookie>`
`getCookies()`
This returns all `Cookie` objects stored under the specified name.
`long`
`getDate(String name)`
This can be used to get the value of the first message header that has the specified name.
`int`
`getInteger(String name)`
This can be used to get the value of the first message header that has the specified name.
`int`
`getMajor()`
This can be used to get the major number from a HTTP version.
`int`
`getMinor()`
This can be used to get the minor number from a HTTP version.
`List<String>`
`getNames()`
This is used to acquire the names of the of the headers that have been set in the response.
`OutputStream`
`getOutputStream()`
Used to write a message body with the `Response`.
`OutputStream`
`getOutputStream(int size)`
Used to write a message body with the `Response`.
`PrintStream`
`getPrintStream()`
This method is provided for convenience so that the HTTP content can be written using the `print` methods provided by the `PrintStream`.
`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`.
`String`
`getText()`
This can be used to retrieve the text of a HTTP status line.
`String`
`getTransferEncoding()`
This is a convenience method that can be used to determine the content type of the message body.
`String`
`getValue(String name)`
This can be used to get the value of the first message header that has the specified name.
`List<String>`
`getValues(String name)`
This can be used to get the values of HTTP message headers that have the specified name.
`boolean`
`isCommitted()`
This can be used to determine whether the `Response` has been committed.
`void`
`remove(String name)`
This is used to remove the named header from the response.
`void`
`reset()`
This can be used to determine whether the `Response` has been committed.
`void`
`set(String name, int value)`
This can be used to set a HTTP message header to this object.
`void`
`set(String name, String value)`
This can be used to set a HTTP message header to this object.
`void`
`setCode(int code)`
This method allows the status for the response to be changed.
`void`
`setContentLength(int length)`
This should be used when the size of the message body is known.
`Cookie`
`setCookie(String name, String value)`
The `setCookie` method is used to set a cookie value with the cookie name.
`Cookie`
`setCookie(Cookie cookie)`
The `setCookie` method is used to set a cookie value with the cookie name.
`void`
`setDate(String name, long date)`
This is used as a convenience method for adding a header that needs to be parsed into a HTTP date string.
`void`
`setMajor(int major)`
This can be used to set the major number from a HTTP version.
`void`
`setMinor(int minor)`
This can be used to get the minor number from a HTTP version.
`void`
`setText(String text)`
This is used to set the text of the HTTP status line.

### Methods inherited from class Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### response

protected Response response
This is the response instance that is being wrapped.

## Constructor Details

### ResponseWrapper

public ResponseWrapper(Response response)
Constructor for `ResponseWrapper` object. This allows the original `Response` object to be wrapped so that adjustments to the behavior of a request object handed to the container can be provided by a subclass implementation.

Parameters:
  `response` - the response object that is being wrapped

## Method Details

### getCode

public int getCode()
This represents the status code of the HTTP response. The response code represents the type of message that is being sent to the client. For a description of the codes see RFC 2616 section 10, Status Code Definitions.

Specified by:
  `getCode` in interface `StatusLine`
Returns:
  the status code that this HTTP response has

### setCode

public void setCode(int code)
This method allows the status for the response to be changed. This MUST be reflected the the response content given to the client. For a description of the codes see RFC 2616 section 10, Status Code Definitions.

Specified by:
  `setCode` in interface `StatusLine`
Parameters:
  `code` - the new status code for the HTTP response

### getText

public String getText()
This can be used to retrieve the text of a HTTP status line. This is the text description for the status code. This should match the status code specified by the RFC.

Specified by:
  `getText` in interface `StatusLine`
Returns:
  the message description of the response

### setText

public void setText(String text)
This is used to set the text of the HTTP status line. This should match the status code specified by the RFC.

Specified by:
  `setText` in interface `StatusLine`
Parameters:
  `text` - the descriptive text message of the status

### getMajor

public int getMajor()
This can be used to get the major number from a HTTP version. The major version corresponds to the major type that is the 1 of a HTTP/1.0 version string.

Specified by:
  `getMajor` in interface `StatusLine`
Returns:
  the major version number for the request message

### setMajor

public void setMajor(int major)
This can be used to set the major number from a HTTP version. The major version corresponds to the major type that is the 1 of a HTTP/1.0 version string.

Specified by:
  `setMajor` in interface `StatusLine`
Parameters:
  `major` - the major version number for the request message

### getMinor

public int getMinor()
This can be used to get the minor number from a HTTP version. The minor version corresponds to the major type that is the 0 of a HTTP/1.0 version string. This is used to determine if the request message has keep alive semantics.

Specified by:
  `getMinor` in interface `StatusLine`
Returns:
  the minor version number for the request message

### setMinor

public void setMinor(int minor)
This can be used to get the minor number from a HTTP version. The minor version corresponds to the major type that is the 0 of a HTTP/1.0 version string. This is used to determine if the request message has keep alive semantics.

Specified by:
  `setMinor` in interface `StatusLine`
Parameters:
  `minor` - the minor version number for the request message

### getNames

public List<String> getNames()
This is used to acquire the names of the of the headers that have been set in the response. This can be used to acquire all header values by name that have been set within the response. If no headers have been set this will return an empty list.

Specified by:
  `getNames` in interface `ResponseHeader`
Returns:
  a list of strings representing the set header names

### add

public void add(String name, String value)
This can be used to add a HTTP message header to this object. The name and value of the HTTP message header will be used to create a HTTP message header object which can be retrieved using the `getValue` in combination with the get methods.

Specified by:
  `add` in interface `ResponseHeader`
Parameters:
  `name` - the name of the HTTP message header to be added
  `value` - the value the HTTP message header will have

### add

public void add(String name, int value)
This can be used to add a HTTP message header to this object. The name and value of the HTTP message header will be used to create a HTTP message header object which can be retrieved using the `getInteger` in combination with the get methods.

Specified by:
  `add` in interface `ResponseHeader`
Parameters:
  `name` - the name of the HTTP message header to be added
  `value` - the value the HTTP message header will have

### addDate

public void addDate(String name, long date)
This is used as a convenience method for adding a header that needs to be parsed into a HTTPdate string. This will convert the date given into a date string defined in RFC 2616 sec 3.3.1.

Specified by:
  `addDate` in interface `ResponseHeader`
Parameters:
  `name` - the name of the HTTP message header to be added
  `date` - the value constructed as an RFC 1123 date string

### set

public void set(String name, String value)
This can be used to set a HTTP message header to this object. The name and value of the HTTP message header will be used to create a HTTP message header object which can be retrieved using the `getValue` in combination with the get methods. This will perform a `remove` using the issued header name before the header value is set.

Specified by:
  `set` in interface `ResponseHeader`
Parameters:
  `name` - the name of the HTTP message header to be added
  `value` - the value the HTTP message header will have

### set

public void set(String name, int value)
This can be used to set a HTTP message header to this object. The name and value of the HTTP message header will be used to create a HTTP message header object which can be retrieved using the `getValue` in combination with the get methods. This will perform a `remove` using the issued header name before the header value is set.

Specified by:
  `set` in interface `ResponseHeader`
Parameters:
  `name` - the name of the HTTP message header to be added
  `value` - the value the HTTP message header will have

### setDate

public void setDate(String name, long date)
This is used as a convenience method for adding a header that needs to be parsed into a HTTP date string. This will convert the date given into a date string defined in RFC 2616 sec 3.3.1. This will perform a `remove` using the issued header name before the header value is set.

Specified by:
  `setDate` in interface `ResponseHeader`
Parameters:
  `name` - the name of the HTTP message header to be added
  `date` - the value constructed as an RFC 1123 date string

### remove

public void remove(String name)
This is used to remove the named header from the response. This removes all header values assigned to the specified name. If it does not exist then this will return without modifying the HTTP response. Headers names removed are case insensitive.

Specified by:
  `remove` in interface `ResponseHeader`
Parameters:
  `name` - the HTTP message header to remove from the response

### contains

public boolean contains(String name)
This is used to see if there is a HTTP message header with the given name in this container. If there is a HTTP message header with the specified name then this returns true otherwise false.

Specified by:
  `contains` in interface `ResponseHeader`
Parameters:
  `name` - the HTTP message header to get the value from
Returns:
  this returns true if the HTTP message header exists

### getValue

public String getValue(String name)
This can be used to get the value of the first message header that has the specified name. This will return the full string representing the named header value. If the named header does not exist then this will return a null value.

Specified by:
  `getValue` in interface `ResponseHeader`
Parameters:
  `name` - the HTTP message header to get the value from
Returns:
  this returns the value that the HTTP message header

### getInteger

public int getInteger(String name)
This can be used to get the value of the first message header that has the specified name. This will return the integer representing the named header value. If the named header does not exist then this will return a value of minus one, -1.

Specified by:
  `getInteger` in interface `ResponseHeader`
Parameters:
  `name` - the HTTP message header to get the value from
Returns:
  this returns the value that the HTTP message header

### getDate

public long getDate(String name)
This can be used to get the value of the first message header that has the specified name. This will return the long value representing the named header value. If the named header does not exist then this will return a value of minus one, -1.

Specified by:
  `getDate` in interface `ResponseHeader`
Parameters:
  `name` - the HTTP message header to get the value from
Returns:
  this returns the value that the HTTP message header

### getValues

public List<String> getValues(String name)
This can be used to get the values of HTTP message headers that have the specified name. This is a convenience method that will present that values as tokens extracted from the header. This has obvious performance benefits as it avoids having to deal with `substring` and `trim` calls.

The tokens returned by this method are ordered according to there HTTP quality values, or "q" values, see RFC 2616 section 3.9. This also strips out the quality parameter from tokens returned. So "image/html; q=0.9" results in "image/html". If there are no "q" values present then order is by appearance.

The result from this is either the trimmed header value, that is, the header value with no leading or trailing whitespace or an array of trimmed tokens ordered with the most preferred in the lower indexes, so index 0 is has highest preference.

Specified by:
  `getValues` in interface `ResponseHeader`
Parameters:
  `name` - the name of the headers that are to be retrieved
Returns:
  ordered list of tokens extracted from the header(s)

### setCookie

public Cookie setCookie(Cookie cookie)
The `setCookie` method is used to set a cookie value with the cookie name. This will add a cookie to the response stored under the name of the cookie, when this is committed it will be added as a Set-Cookie header to the resulting response.

Specified by:
  `setCookie` in interface `ResponseHeader`
Parameters:
  `cookie` - this is the cookie to be added to the response
Returns:
  returns the cookie that has been set in the response

### setCookie

public Cookie setCookie(String name, String value)
The `setCookie` method is used to set a cookie value with the cookie name. This will add a cookie to the response stored under the name of the cookie, when this is committed it will be added as a Set-Cookie header to the resulting response. This is a convenience method that avoids cookie creation.

Specified by:
  `setCookie` in interface `ResponseHeader`
Parameters:
  `name` - this is the cookie to be added to the response
  `value` - this is the cookie value that is to be used
Returns:
  returns the cookie that has been set in the response

### getCookie

public Cookie getCookie(String name)
This returns the `Cookie` object stored under the specified name. This is used to retrieve cookies that have been set with the `setCookie` methods. If the cookie does not exist under the specified name this will return null.

Specified by:
  `getCookie` in interface `ResponseHeader`
Parameters:
  `name` - this is the name of the cookie to be retrieved
Returns:
  returns the cookie object send with the request

### getCookies

public List<Cookie> getCookies()
This returns all `Cookie` objects stored under the specified name. This is used to retrieve cookies that have been set with the `setCookie` methods. If there are no cookies then this will return an empty list.

Specified by:
  `getCookies` in interface `ResponseHeader`
Returns:
  returns all the cookie objects for this response

### getContentType

public ContentType getContentType()
This is a convenience method that can be used to determine the content type of the message body. This will determine whether there is a `Content-Type` header, if there is then this will parse that header and represent it as a typed object which will expose the various parts of the HTTP header.

Specified by:
  `getContentType` in interface `ResponseHeader`
Returns:
  this returns the content type value if it exists

### getTransferEncoding

public String getTransferEncoding()
This is a convenience method that can be used to determine the content type of the message body. This will determine whether there is a `Transfer-Encoding` header, if there is then this will parse that header and return the first token in the comma separated list of values, which is the primary value.

Specified by:
  `getTransferEncoding` in interface `ResponseHeader`
Returns:
  this returns the transfer encoding value if it exists

### getContentLength

public int getContentLength()
This is a convenience method that can be used to determine the length of the message body. This will determine if there is a `Content-Length` header, if it does then the length can be determined, if not then this returns -1.

Specified by:
  `getContentLength` in interface `ResponseHeader`
Returns:
  content length, or -1 if it cannot be determined

### setContentLength

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

Specified by:
  `setContentLength` in interface `Response`
Parameters:
  `length` - this is the length of the HTTP message body

### getOutputStream

public OutputStream getOutputStream() throws 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.

Specified by:
  `getOutputStream` in interface `Response`
Returns:
  an output stream used to write the response body
Throws:
  `IOException` - this is thrown if there was an I/O error

### getOutputStream

public OutputStream getOutputStream(int size) throws 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.

Specified by:
  `getOutputStream` in interface `Response`
Parameters:
  `size` - the minimum size that the response buffer must be
Returns:
  an output stream used to write the response body
Throws:
  `IOException` - this is thrown if there was an I/O error

### getPrintStream

public PrintStream getPrintStream() throws 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.

Specified by:
  `getPrintStream` in interface `Response`
Returns:
  a print stream used for writing the response body
Throws:
  `IOException` - this is thrown if there was an I/O error

### getPrintStream

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

Specified by:
  `getPrintStream` in interface `Response`
Parameters:
  `size` - the minimum size that the response buffer must be
Returns:
  a print stream used for writing the response body
Throws:
  `IOException` - this is thrown if there was an I/O error

### getByteChannel

public WritableByteChannel getByteChannel() throws 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.

Specified by:
  `getByteChannel` in interface `Response`
Returns:
  a writable byte channel used to write the message body
Throws:
  `IOException`

### getByteChannel

public WritableByteChannel getByteChannel(int size) throws 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.

Specified by:
  `getByteChannel` in interface `Response`
Parameters:
  `size` - the minimum size that the response buffer must be
Returns:
  a writable byte channel used to write the message body
Throws:
  `IOException`

### isCommitted

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

Specified by:
  `isCommitted` in interface `Response`
Returns:
  true if the response has been fully committed

### commit

public void commit() throws 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.

Specified by:
  `commit` in interface `Response`
Throws:
  `IOException` - thrown if there was a problem writing

### reset

public void reset() throws 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.

Specified by:
  `reset` in interface `Response`
Throws:
  `IOException` - thrown if there is a problem resetting

### close

public void close() throws 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.

Specified by:
  `close` in interface `Response`
Throws:
  `IOException` - thrown if there is a problem writing