simple.http
Class FilterRequest

java.lang.Object
  extended by simple.http.FilterRequest
All Implemented Interfaces:
GenericHeader, Request, RequestLine

public class FilterRequest
extends java.lang.Object
implements Request

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

Author:
Niall Gallagher

Field Summary
protected  Request req
          This is the object that is being wrapped.
 
Constructor Summary
FilterRequest(Request req)
          Constructor for FilterRequest allows the original Request object to be wrapped so that adjustments to the behavior of a Request 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.
 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 request.
 Attributes getAttributes()
          This can be used to retrieve certain attributes about this Request.
 int getContentLength()
          This is a convenience method that can be used to determine the length of the message body.
 ContentType getContentType()
          This is used to acquire the Content-Type for any HTTP message body that may be sent with the request.
 Cookie getCookie(java.lang.String name)
          This method can be used to retrieve cookies from the header.
 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()
          Used to get the address from which this Request came from.
 java.io.InputStream getInputStream()
          This is used to read the content body.
 java.util.Locale getLanguage()
          This provides Locale for the Accept-Language value.
 int getMajor()
          This can be used to get the major number from a HTTP version.
 java.lang.String getMethod()
          This can be used to get the HTTP method for this request.
 int getMinor()
          This can be used to get the major 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.lang.String getParameter(java.lang.String name)
          This is used to provide quick access to the parameters.
 Parameters getParameters()
          This provides access to HTML form and query parameters.
 Path getPath()
          This method is used to acquire the normalized path part of the HTTP request URI.
 Principal getPrincipal()
          This is a convenience method that is used to retrieve the client authorized to this server.
 Session getSession()
          This method is used to acquire a Session for the request.
 State getState()
          The State represents the collection of cookies sent with this HTTP request.
 java.lang.String getURI()
          This can be used to get the URI specified for this HTTP request.
 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 isKeepAlive()
          This is a convenience method that is used to determine whether or not this message has the Connection: close header.
 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 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 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 for the HTTP request.
 void setMethod(java.lang.String method)
          This is used to set the method for this HTTP request object.
 void setMinor(int minor)
          This can be used to specify the minor version for the HTTP request.
 void setURI(java.lang.String target)
          This can be used to set the URI for this HTTP request.
 java.lang.String toString()
          This method is used so that the original HTTP header can be reconstructed This returns a String that contains each header formatted according to the HTTP/1.1 header format.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

req

protected Request req
This is the object that is being wrapped.

Constructor Detail

FilterRequest

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

Parameters:
req - the Request object being wrapped
Method Detail

getURI

public java.lang.String getURI()
This can be used to get the URI specified for this HTTP request. This corresponds to the /index part of a http://www.domain.com/index URL but may contain the full URL. This can be set using setURI.

Specified by:
getURI in interface RequestLine
Returns:
the URI that this HTTP request is targeting

setURI

public void setURI(java.lang.String target)
This can be used to set the URI for this HTTP request. The getURI will return the String entered which can be a full HTTP URL or a relative path URL.

Specified by:
setURI in interface RequestLine
Parameters:
target - the URI that this HTTP request is to use

getMethod

public java.lang.String getMethod()
This can be used to get the HTTP method for this request. The HTTP specification RFC 2616 specifies the HTTP request methods in section 9, Method Definitions.

Specified by:
getMethod in interface RequestLine
Returns:
the request method for this request

setMethod

public void setMethod(java.lang.String method)
This is used to set the method for this HTTP request object. For a list of possible string values that can be used see RFC 2616 section 9, Method Definitions.

Specified by:
setMethod in interface RequestLine
Parameters:
method - the desired method for this

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 RequestLine
Returns:
the major version number for the request

setMajor

public void setMajor(int major)
This can be used to specify the major version for the HTTP request. Specifying the major version has little effect on the semantics of the request.

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

getMinor

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

Specified by:
getMinor in interface RequestLine
Returns:
the major version number

setMinor

public void setMinor(int minor)
This can be used to specify the minor version for the HTTP request. Specifying the minor version will effect the manner in which the request is processed.

Specified by:
setMinor in interface RequestLine
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

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

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

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.io.IOException
This is used to read the content body. The specifics of the data that is read from this InputStream can be determined by the getContentLength method. If the data sent by the client is chunked then it is decoded, any footers sent are ignored as they provide optional meta-data, see RFC 2616 section 3.6. The InputStream must be so that multiple threads can use the stream.

Specified by:
getInputStream in interface Request
Returns:
an InputStream containing the bytes
Throws:
java.io.IOException - thrown if there is an I/O error

getParameters

public Parameters getParameters()
                         throws java.io.IOException
This provides access to HTML form and query parameters. This is used to provide access to parameters by reading the parameters from the InputStream. If the data cannot be read from the stream then an IOException is thrown. If the data on the stream is not of the correct MIME type then an empty parameters object is returned. The MIME type for the parameters is application/x-www-form-urlenoded.

Specified by:
getParameters in interface Request
Returns:
this returns all HTML form and query parameter data
Throws:
java.io.IOException - thrown if there is an I/O problem

getParameter

public java.lang.String getParameter(java.lang.String name)
                              throws java.io.IOException
This is used to provide quick access to the parameters. This avoids having to acquire the Parameters object. This basically acquires the parameters object and invokes the getParameters method with the given name.

Specified by:
getParameter in interface Request
Parameters:
name - this is the name of the parameter value
Throws:
java.io.IOException - thrown if there is an I/O problem

getPath

public Path getPath()
This method is used to acquire the normalized path part of the HTTP request URI. This will contain provide a convinient means to examine the path without the query. It also allows the target directory to be acquired as well as the file name and the file locale. The acquired Path object is read only, so changes will not affect the request header.

Specified by:
getPath in interface Request
Returns:
this returns information regarding the URI path

getContentType

public ContentType getContentType()
This is used to acquire the Content-Type for any HTTP message body that may be sent with the request. If the header is not sent with the HTTP message header this returns null. This should be used with a contains invocation to see if the Content-Type header is in the HTTP header. The MIME type is returned is a ContentType object.

Specified by:
getContentType in interface Request
Returns:
this returns the Content-Type value if it exists

getLanguage

public java.util.Locale getLanguage()
This provides Locale for the Accept-Language value. This returns the first language preference from the header. If the set of values are required the LanguageParser from the simple.util.parse package can be used. If the header does not exist this will return the default Locale from Local.getDefault.

Specified by:
getLanguage in interface Request
Returns:
the Locale preference of the client

getCookie

public Cookie getCookie(java.lang.String name)
This method can be used to retrieve cookies from the header. This is a convenience method that avoids having to parse the Cookie header values. This will basically call the getState method and from the State invoke get using the specified name.

Specified by:
getCookie in interface Request
Parameters:
name - this is the name of the cookie to be retrieved
Returns:
returns a simple.util.net.Cookie object to to represent the cookie of that name within the header

getState

public State getState()
The State represents the collection of cookies sent with this HTTP request. This represents the cookie state established between the server and client using either domain of path values see RFC 2109, HTTP State Management Mechanism.

The state is shared with the Response which will write each cookie set in the state as a Set-Cookie value once the response has committed. This enables simple management of state with the browser by using the state.

Specified by:
getState in interface Request
Returns:
this returns a State which represents the state maintained with the client application

getPrincipal

public Principal getPrincipal()
This is a convenience method that is used to retrieve the client authorized to this server. This is used to that the HTTP Basic authorization scheme could be used. This will check to see if the Authorization header is present, if it is then this will return a simple.util.net.Principal that identifies the client without having to decode the header.

Specified by:
getPrincipal in interface Request
Returns:
this returns the authorized client as retrieved from the HTTP Authorization header

getAttributes

public Attributes getAttributes()
This can be used to retrieve certain attributes about this Request. The Attributes contains certain properties about the Request. For example if this Request came over a secure line then there may be security attributes.

Specified by:
getAttributes in interface Request
Returns:
returns attributes of this Request object

getAttribute

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

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

getSession

public Session getSession()
This method is used to acquire a Session for the request. The object retrieved provides a container for data associated to the connected client. This allows the request to perform more complex operations based on knowledge that is built up through a series of requests. The session is known to the system using a Cookie, which contains the session reference. This cookie value should not be modified as it used to reference the active session object.

Specified by:
getSession in interface Request
Returns:
returns an active Session object

getInetAddress

public java.net.InetAddress getInetAddress()
Used to get the address from which this Request came from. This information can be retrieved from Attributes object using the getAttributes method. This can be used to log HTTP requests for the server. This can also provide security, where requests from specific locations are denied.

Specified by:
getInetAddress in interface Request
Returns:
the I.P. address this Request came from

isKeepAlive

public boolean isKeepAlive()
This is a convenience method that is used to determine whether or not this message has the Connection: close header. If the close token is present then this stream is not a keep-alive connection. If this has no Connection header then the keep-alive status is determined by the HTTP version, that is, HTTP/1.1 is keep-alive by default, HTTP/1.0 is not keep-alive by default.

Specified by:
isKeepAlive in interface Request
Returns:
returns true if this has a keep-alive stream

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. This will return a -1 if there is no length.

Specified by:
getContentLength in interface Request
Returns:
returns -1 if the length cannot be determined

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 method is used so that the original HTTP header can be reconstructed This returns a String that contains each header formatted according to the HTTP/1.1 header format. The header will contain the request line followed by each header and ended with the CRLF.

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