simple.http
Interface Request

All Superinterfaces:
GenericHeader, RequestLine
All Known Implementing Classes:
FilterRequest

public interface Request
extends RequestLine, GenericHeader

This interface is used to represent a HTTP request. This defines the attributes that a HTTP request has such as a request line and the headers that come with the message header.

The Request is used to provide an interface to the HTTP InputStream and message header. The stream can have certain characteristics, these characteristics are available by this object. The Request provides methods that allow the InputStream's semantics to be known, for example if the stream is keep-alive or if the stream has a length.

The Request origin is also retrievable from the Request as is the Attributes object which defines specific connection attributes.

It is important to note that the Request controls the processing of the HTTP pipeline. The next HTTP request is not processed until the request has read all of the content body within the InputStream. The stream must be fully read or closed for the next request to be processed.

Author:
Niall Gallagher

Method Summary
 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.
 java.net.InetAddress getInetAddress()
          Used to get the address from where 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.
 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.
 boolean isKeepAlive()
          This is a convenience method that is used to determine whether or not this message has the Connection: close header.
 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 interface simple.http.RequestLine
getMajor, getMethod, getMinor, getURI, setMajor, setMethod, setMinor, setURI
 
Methods inherited from interface simple.http.GenericHeader
add, add, addDate, clear, contains, contains, getDate, getDate, getName, getValue, getValue, getValues, headerCount, indexOf, indexOf, remove, removeAll, set, set, setDate
 

Method Detail

getInputStream

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, see RFC 2616 section 3.6. The InputStream must be synchronized so that multiple threads can use the stream in a concurrent environment.

Returns:
InputStream containing the message body
Throws:
java.io.IOException - signifies that there is an I/O problem

getParameters

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.

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

getParameter

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.

Parameters:
name - this is the name of the parameter value
Throws:
java.io.IOException - thrown if there is an I/O problem

getPath

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.

Returns:
this returns information regarding the URI path

getContentType

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.

Returns:
this returns the Content-Type value if it exists

getLanguage

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.

Returns:
the Locale preference of the client

getCookie

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.

Parameters:
name - this is the name of the cookie to be retrieved
Returns:
returns a simple.util.net.Cookie object

getState

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

Returns:
this returns a State for the client

getPrincipal

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.

Returns:
this returns a HTTP authorized client if one exists

getAttributes

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.

Returns:
attributes of this Request object

getAttribute

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.

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

getSession

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.

Returns:
returns an active Session object

isKeepAlive

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.

Returns:
returns true if this has a keep-alive stream

getInetAddress

java.net.InetAddress getInetAddress()
Used to get the address from where 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.

Returns:
the I.P. address this Request came from

getContentLength

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.

Returns:
the content length, or -1 if it cannot be determined

toString

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.

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