simple.http
Class FilterResponse

java.lang.Object
  extended by simple.http.FilterResponse
All Implemented Interfaces:
GenericHeader, Response, StatusLine

public class FilterResponse
extends java.lang.Object
implements Response

The FilterResponse object is used so that the original Response object can be wrapped in a filtering proxy object. This allows a ProtocolHandler to interact with the Response object in a concurrent environment. This is also useful if any special behavior is need when a HTTP header with special significance is added.


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

 
The above is an example of how the FilterResponse 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 ProtocolHandler objects, an example of such layering is the simple.http.serve.DomainHandler.

Author:
Niall Gallagher

Field Summary
protected  Response resp
          This is the object that is being wrapped.
 
Constructor Summary
FilterResponse(Response resp)
          Constructor for FilterResponse allows the original Response object to be wrapped so that adjustments to the behavior of a Response object handed to a specialized ProtocolHandler can be done simply.
 
Method Summary
 void add(java.lang.String name, int value)
          This can be used to add a HTTP message header to this object.
 void add(java.lang.String name, java.lang.String value)
          This can be used to add a HTTP message header to this object.
 void addDate(java.lang.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 clear()
          This is used to clear all HTTP message headers from the message header.
 void commit()
          This is used to write the headers that where given to the Response.
 boolean contains(java.lang.String name)
          This is used to see if there is a HTTP message header with the given name in this container.
 boolean contains(java.lang.String name, java.lang.String value)
          This is used to see if there is a HTTP message header with the given name in this container, if it exists this will check to see if the provided value exists.
 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.
 int getCode()
          This represents the status code of the HTTP response.
 long getDate(int off)
          This can be used to get the value of the HTTP message header at the specified index.
 long getDate(java.lang.String name)
          This can be used to get the date of the first message header that has the specified name.
 java.net.InetAddress getInetAddress()
          This can be used to get the I.P address for the browser that the Response goes to.
 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.
 java.lang.String getName(int off)
          This is used to get the name value of the HTTP message header at the specified index.
 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.
 java.lang.String getText()
          This can be used to retrieve the text of a HTTP status line.
 java.lang.String getValue(int off)
          This is used to get the date value of the HTTP message header at the specified index.
 java.lang.String getValue(java.lang.String name)
          This can be used to get the value of the first message header that has the specified name.
 java.lang.String[] getValues(java.lang.String name)
          This can be used to get the values of HTTP message headers that have the specified name.
 int headerCount()
          This can be used to determine how many HTTP message headers this object contains.
 int indexOf(java.lang.String name)
          This can be used to find the first occurrence of the specified HTTP message header.
 int indexOf(java.lang.String name, int from)
          This can be used to find the first occurrence of the specified HTTP message header from a given index.
 boolean isCommitted()
          This can be used to determine whether the Response has been committed.
 void remove(int off)
          This can be used to remove the HTTP message header at the specified index.
 void removeAll(java.lang.String name)
          This can be used to remove all HTTP message headers with the specified name.
 void reset()
          The reset method is used to reset the output from an issued OutputStream.
 void set(java.lang.String name, int value)
          This can be used to set a HTTP message header to this object.
 void set(java.lang.String name, java.lang.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.
 void setDate(java.lang.String name, long date)
          This is used as a convenience method for setting a header that needs to be parsed into a HTTP-date string.
 void setMajor(int major)
          This can be used to specify the major version.
 void setMinor(int minor)
          This can be used to specify the minor version.
 void setText(java.lang.String text)
          This is used to set the text of the HTTP status line.
 java.lang.String toString()
          This constructs the HTTP message header according to the format of RFC 2616.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

resp

protected Response resp
This is the object that is being wrapped.

Constructor Detail

FilterResponse

public FilterResponse(Response resp)
Constructor for FilterResponse allows the original Response object to be wrapped so that adjustments to the behavior of a Response object handed to a specialized ProtocolHandler can be done simply.

Parameters:
resp - the Response object being wrapped
Method Detail

getCode

public int getCode()
This represents the status code of the HTTP response. The HTTP 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 java.lang.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(java.lang.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 response

setMajor

public void setMajor(int major)
This can be used to specify the major version. This should be the major version of the HTTP request.

Specified by:
setMajor in interface StatusLine
Parameters:
major - this is the major number desired

getMinor

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

Specified by:
getMinor in interface StatusLine
Returns:
the major version number for the response

setMinor

public void setMinor(int minor)
This can be used to specify the minor version. This should not be set to zero if the HTTP request was for HTTP/1.1. The response must be equal or higher.

Specified by:
setMinor in interface StatusLine
Parameters:
minor - this is the minor number desired

headerCount

public int headerCount()
This can be used to determine how many HTTP message headers this object contains. The headerCount represents the number of individual HTTP message headers that this has.

Specified by:
headerCount in interface GenericHeader
Returns:
returns the number of HTTP message headers this has

indexOf

public int indexOf(java.lang.String name)
This can be used to find the first occurrence of the specified HTTP message header. This will search through the list of HTTP message headers that this contains and when it encounters a HTTP message header with the name specified it returns the index of that HTTP message header. The index will change when a remove is used. So the index is valid only for the until the next remove method or possible the next add method.

Specified by:
indexOf in interface GenericHeader
Parameters:
name - name of the HTTP message header being searched for
Returns:
returns the position of the first HTTP message header

indexOf

public int indexOf(java.lang.String name,
                   int from)
This can be used to find the first occurrence of the specified HTTP message header from a given index. This will search through the list of HTTP message headers that occur after the index. When it encounters a HTTP message header with the name specified it returns the index of that HTTP message header. The index will change when a remove is used. So the index is valid only until a remove or add method is used.

Specified by:
indexOf in interface GenericHeader
Parameters:
name - name of the HTTP message header being searched for
from - the index from which the search will start
Returns:
this returns the position of the HTTP message header

add

public void add(java.lang.String name,
                java.lang.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 indexOf in combination with the get methods.

Specified by:
add in interface GenericHeader
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(java.lang.String name,
                java.lang.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 indexOf in combination with the get methods. This will perform a removeAll using the issued header name before the header value is set.

Specified by:
set in interface GenericHeader
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(java.lang.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 indexOf in combination with the get methods.

Specified by:
add in interface GenericHeader
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(java.lang.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 indexOf in combination with the get methods. This will perform a removeAll using the issued header name before the header value is set.

Specified by:
set in interface GenericHeader
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(java.lang.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.

Specified by:
addDate in interface GenericHeader
Parameters:
name - the name of the HTTP message header to be added
date - the value the HTTP message header will have when parsed into RFC 1123 format

setDate

public void setDate(java.lang.String name,
                    long date)
This is used as a convenience method for setting 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 removeAll using the issued header name before the header value is set.

Specified by:
setDate in interface GenericHeader
Parameters:
name - the name of the HTTP message header to be added
date - the value the HTTP message header will have when parsed into RFC 1123 format

remove

public void remove(int off)
This can be used to remove the HTTP message header at the specified index. This will invalidate any value received by an indexOf method previous to this. If the index specified is not valid then an IndexOutOfBoundsException may be thrown.

Specified by:
remove in interface GenericHeader
Parameters:
off - index of the HTTP message header to be removed

removeAll

public void removeAll(java.lang.String name)
This can be used to remove all HTTP message headers with the specified name. This will search through the list of HTTP message header an remove the HTTP message headers from the list. This will invalidate any previous indexes received.

Specified by:
removeAll in interface GenericHeader
Parameters:
name - name of the message headers to be removed

getValue

public java.lang.String getValue(int off)
This is used to get the date value of the HTTP message header at the specified index. This is a convenience method that avoids having to deal with a HTTP message header object. If the offset used specified is invalid then an exception may be thrown.

Specified by:
getValue in interface GenericHeader
Parameters:
off - the offset of the HTTP message header value
Returns:
this returns the date value value that the header

getName

public java.lang.String getName(int off)
This is used to get the name value of the HTTP message header at the specified index. This is used in conjunction with the getValue(int) method so that the contents of the HTTP message header can be fully examined.

Specified by:
getName in interface GenericHeader
Parameters:
off - the offset of the HTTP message header name value
Returns:
this returns the name of the header at that index

getValues

public java.lang.String[] getValues(java.lang.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 avoids having to deal with the indexOf methods. This will return an empty array if there are no headers of the specified name within this list.

Specified by:
getValues in interface GenericHeader
Parameters:
name - the name of the headers that are to be retrieved
Returns:
this returns and array of values that correspond to the headers in the list

getDate

public long getDate(int off)
This can be used to get the value of the HTTP message header at the specified index. This is a convenience method that avoids having to deal with a HTTP message header object. If the offset used specified is invalid then an exception may be thrown.

Specified by:
getDate in interface GenericHeader
Parameters:
off - the offset of the date HTTP message header value
Returns:
this returns the date as a long from the parsed value of that HTTP message header

getValue

public java.lang.String getValue(java.lang.String name)
This can be used to get the value of the first message header that has the specified name. This is a convenience method that avoids having to deal with a HTTP message header object and the indexOf methods. This returns null if theres not a HTTP message header.

Specified by:
getValue in interface GenericHeader
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(java.lang.String name)
This can be used to get the date of the first message header that has the specified name. This is a convenience method that avoids having to deal with parsing the value of the requested HTTP message header. This also avoids having to deal with the indexOf methods. This returns -1 if theres not a HTTP message header.

Specified by:
getDate in interface GenericHeader
Parameters:
name - the HTTP message header to get the value from
Returns:
this returns the date as a long from the parsed value of that HTTP message header

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 is 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 method 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

getAttributes

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

Specified by:
getAttributes in interface Response
Returns:
the attributes of this Response object

getAttribute

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

Specified by:
getAttribute in interface Response
Parameters:
name - this is the name of the attribute to acquire
Returns:
this returns the attribute for the specified name

getInetAddress

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

Specified by:
getInetAddress in interface Response
Returns:
returns the source I.P. address of the client

getOutputStream

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

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

getOutputStream

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

Specified by:
getOutputStream in interface Response
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

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

Specified by:
getPrintStream in interface Response
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

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

Specified by:
getPrintStream in interface Response
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

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

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

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 committed

reset

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

Specified by:
reset in interface Response

contains

public boolean contains(java.lang.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 GenericHeader
Parameters:
name - the HTTP message header to get the value from
Returns:
this returns true if the HTTP message header exists

contains

public boolean contains(java.lang.String name,
                        java.lang.String value)
This is used to see if there is a HTTP message header with the given name in this container, if it exists this will check to see if the provided value exists. This is used for a comma seperated list of values found within the HTTP header value. If the header and token exits this returns true otherwise false.

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

clear

public void clear()
This is used to clear all HTTP message headers from the message header. This will leave no data remaining, i.e. headerCount is zero after this method is invoked, this is a convenience method.

Specified by:
clear in interface GenericHeader

toString

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

Specified by:
toString in interface Response
Overrides:
toString in class java.lang.Object
Returns:
the HTTP response header as a string object