Package org.simpleframework.http

## Class RequestWrapper

- java.lang.Object
- - org.simpleframework.http.RequestWrapper

- All Implemented Interfaces:
    `Request`, `RequestHeader`, `RequestLine`

      public class RequestWrapper
      extends java.lang.Object
      implements Request

  The `RequestWrapper` object is used so that the original `Request` object can be wrapped in a filtering proxy object. This allows a `Container` that interacts with a modified request object. To add functionality to the request it can be wrapped in a subclass of this and the overridden methods can provide modified functionality to the standard request.
  Author:
    Niall Gallagher

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected Request` | `request` | This is the request instance that is being wrapped.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `RequestWrapper​(Request request)` | Constructor for `RequestWrapper` object.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `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.
    `Address` | `getAddress()` | This is used to acquire the address from the request line.
    `java.lang.Object` | `getAttribute​(java.lang.Object key)` | This is used as a shortcut for acquiring attributes for the response.
    `java.util.Map` | `getAttributes()` | This can be used to retrieve the response attributes.
    `java.nio.channels.ReadableByteChannel` | `getByteChannel()` | This is used to read the content body.
    `java.net.InetSocketAddress` | `getClientAddress()` | This is used to acquire the remote client address.
    `java.lang.String` | `getContent()` | This is used to get the content body.
    `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​(java.lang.String name)` | This is used to acquire a cookie usiing the name of that cookie.
    `java.util.List<Cookie>` | `getCookies()` | This is used to acquire all cookies that were sent in the header.
    `long` | `getDate​(java.lang.String name)` | This can be used to get the date of the first message header that has the specified name.
    `Form` | `getForm()` | This is used to acquire all the form parameters from the HTTP request.
    `java.io.InputStream` | `getInputStream()` | This is used to read the content body.
    `int` | `getInteger​(java.lang.String name)` | This can be used to get the integer of the first message header that has the specified name.
    `java.util.List<java.util.Locale>` | `getLocales()` | This is used to acquire the locales from the request header.
    `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.util.List<java.lang.String>` | `getNames()` | This method is used to get a `List` of the names for the headers.
    `java.lang.String` | `getParameter​(java.lang.String name)` | This is used to provide quick access to the parameters.
    `Part` | `getPart​(java.lang.String name)` | This method is used to acquire a `Part` from the form using a known name for the part.
    `Path` | `getPath()` | This is used to acquire the path as extracted from the HTTP request URI.
    `Query` | `getQuery()` | This method is used to acquire the query part from the HTTP request URI target.
    `Session` | `getSession()` | This method is used to acquire a `Session` for the request.
    `Session` | `getSession​(boolean create)` | This method is used to acquire a `Session` for the request.
    `java.lang.String` | `getTarget()` | This can be used to get the URI specified for this HTTP request.
    `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.util.List<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.
    `boolean` | `isKeepAlive()` | This is a convenience method that is used to determine whether or not this message has the `Connection: close` header.
    `boolean` | `isSecure()` | This is used to determine if the request has been transferred over a secure connection.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### request

          protected Request request

      This is the request instance that is being wrapped.

  - ### Constructor Detail

    - #### RequestWrapper

          public RequestWrapper​(Request request)

      Constructor for `RequestWrapper` object. This allows the original `Request` 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:
        `request` - the request object that is being wrapped

  - ### Method Detail

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

    - #### 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. This is used to determine if the request message has keep alive semantics.
      Specified by:
        `getMinor` in interface `RequestLine`
      Returns:
        the major version number for the request message

    - #### 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. Typically this will be a GET, POST or a HEAD method, although any string is possible.
      Specified by:
        `getMethod` in interface `RequestLine`
      Returns:
        the request method for this request message

    - #### getTarget

          public java.lang.String getTarget()

      This can be used to get the URI specified for this HTTP request. This corresponds to the either the full HTTP URI or the path part of the URI depending on how the client sends the request.
      Specified by:
        `getTarget` in interface `RequestLine`
      Returns:
        the URI address that this HTTP request is targeting

    - #### getAddress

          public Address getAddress()

      This is used to acquire the address from the request line. An address is the full URI including the scheme, domain, port and the query parts. This allows various parameters to be acquired without having to parse the raw request target URI.
      Specified by:
        `getAddress` in interface `RequestLine`
      Returns:
        this returns the address of the request line

    - #### getPath

          public Path getPath()

      This is used to acquire the path as extracted from the HTTP request URI. The `Path` object that is provided by this method is immutable, it represents the normalized path only part from the request uniform resource identifier.
      Specified by:
        `getPath` in interface `RequestLine`
      Returns:
        this returns the normalized path for the request

    - #### getQuery

          public Query getQuery()

      This method is used to acquire the query part from the HTTP request URI target. This will return only the values that have been extracted from the request URI target.
      Specified by:
        `getQuery` in interface `RequestLine`
      Returns:
        the query associated with the HTTP target URI

    - #### getNames

          public java.util.List<java.lang.String> getNames()

      This method is used to get a `List` of the names for the headers. This will provide the original names for the HTTP headers for the message. Modifications to the provided list will not affect the header, the list is a simple copy.
      Specified by:
        `getNames` in interface `RequestHeader`
      Returns:
        this returns a list of the names within the header

    - #### getInteger

          public int getInteger​(java.lang.String name)

      This can be used to get the integer 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 returns -1 if theres no HTTP header value for the specified name.
      Specified by:
        `getInteger` in interface `RequestHeader`
      Parameters:
        `name` - the HTTP message header to get the value from
      Returns:
        this returns the date as a long from the header value

    - #### 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 returns -1 if theres no HTTP header value for the specified name.
      Specified by:
        `getDate` in interface `RequestHeader`
      Parameters:
        `name` - the HTTP message header to get the value from
      Returns:
        this returns the date as a long from the header value

    - #### getCookie

          public Cookie getCookie​(java.lang.String name)

      This is used to acquire a cookie usiing the name of that cookie. If the cookie exists within the HTTP header then it is returned as a `Cookie` object. Otherwise this method will return null. Each cookie object will contain the name, value and path of the cookie as well as the optional domain part.
      Specified by:
        `getCookie` in interface `RequestHeader`
      Parameters:
        `name` - this is the name of the cookie object to acquire
      Returns:
        this returns a cookie object from the header or null

    - #### getCookies

          public java.util.List<Cookie> getCookies()

      This is used to acquire all cookies that were sent in the header. If any cookies exists within the HTTP header they are returned as `Cookie` objects. Otherwise this method will an empty list. Each cookie object will contain the name, value and path of the cookie as well as the optional domain part.
      Specified by:
        `getCookies` in interface `RequestHeader`
      Returns:
        this returns all cookie objects from the HTTP 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. The value provided from this will be trimmed so there is no need to modify the value, also if the header name specified refers to a comma seperated list of values the value returned is the first value in that list. This returns null if theres no HTTP message header.
      Specified by:
        `getValue` in interface `RequestHeader`
      Parameters:
        `name` - the HTTP message header to get the value from
      Returns:
        this returns the value that the HTTP message header

    - #### getValues

          public java.util.List<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 will present that values as tokens extracted from the header. This has obvious performance benifits 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 appearence.

      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 higest preference.

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

    - #### getLocales

          public java.util.List<java.util.Locale> getLocales()

      This is used to acquire the locales from the request header. The locales are provided in the `Accept-Language` header. This provides an indication as to the languages that the client accepts. It provides the locales in preference order.
      Specified by:
        `getLocales` in interface `RequestHeader`
      Returns:
        this returns the locales preferred by the client

    - #### 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 `RequestHeader`
      Parameters:
        `name` - the HTTP message header to get the value from
      Returns:
        this returns true if the HTTP message header exists

    - #### 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 `RequestHeader`
      Returns:
        this returns the content type 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 `RequestHeader`
      Returns:
        the content length, or -1 if it cannot be determined

    - #### isSecure

          public boolean isSecure()

      This is used to determine if the request has been transferred over a secure connection. If the protocol is HTTPS and the content is delivered over SSL then the request is considered to be secure. Also the associated response will be secure.
      Specified by:
        `isSecure` in interface `Request`
      Returns:
        true if the request is transferred securely

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

    - #### getAttributes

          public java.util.Map getAttributes()

      This can be used to retrieve the response attributes. These can be used to keep state with the response when it is passed to other systems for processing. Attributes act as a convenient model for storing objects associated with the response. This also inherits attributes associated with the client connection.
      Specified by:
        `getAttributes` in interface `Request`
      Returns:
        the attributes that have been set on this response

    - #### getAttribute

          public java.lang.Object getAttribute​(java.lang.Object key)

      This is used as a shortcut for acquiring attributes for the response. This avoids acquiring the attribute `Map` in order to retrieve the attribute directly from that object. The attributes contain data specific to the response.
      Specified by:
        `getAttribute` in interface `Request`
      Parameters:
        `key` - this is the key of the attribute to acquire
      Returns:
        this returns the attribute for the specified name

    - #### getClientAddress

          public java.net.InetSocketAddress getClientAddress()

      This is used to acquire the remote client address. This can be used to acquire both the port and the I.P address for the client. It allows the connected clients to be logged and if require it can be used to perform course grained security.
      Specified by:
        `getClientAddress` in interface `Request`
      Returns:
        this returns the client address for this request

    - #### getContent

          public java.lang.String getContent()
                                      throws java.io.IOException

      This is used to get the content body. This will essentially get the content from the body and present it as a single string. The encoding of the string is determined from the content type charset value. If the charset is not supported this will throw an exception. Typically only text values should be extracted using this method if there is a need to parse that content.
      Specified by:
        `getContent` in interface `Request`
      Returns:
        the body content as an encoded string value
      Throws:
        `java.io.IOException` - signifies that there is an I/O problem

    - #### 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, see RFC 2616 section 3.6. Also multipart data is available as `Part` objects however the raw content of the multipart body is still available.
      Specified by:
        `getInputStream` in interface `Request`
      Returns:
        returns the input stream containing the message body
      Throws:
        `java.lang.Exception` - signifies that there is an I/O problem
        `java.io.IOException`

    - #### getByteChannel

          public java.nio.channels.ReadableByteChannel getByteChannel()
                                                               throws java.io.IOException

      This is used to read the content body. The specifics of the data that is read from this `ReadableByteChannel` 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. This stream will never provide empty reads as the content is internally buffered, so this can do a full read.
      Specified by:
        `getByteChannel` in interface `Request`
      Returns:
        this returns the byte channel used to read the content
      Throws:
        `java.io.IOException`

    - #### getSession

          public Session getSession()
                             throws LeaseException

      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 for the associated client
      Throws:
        `LeaseException`

    - #### getSession

          public Session getSession​(boolean create)
                             throws LeaseException

      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`
      Parameters:
        `create` - creates the session if it does not exist
      Returns:
        returns an active session for the associated client
      Throws:
        `LeaseException`

    - #### getForm

          public Form getForm()
                       throws java.io.IOException

      This is used to acquire all the form parameters from the HTTP request. This includes the query and POST data values as well as the parts of a multipart request. The form is a convenience object enabling easy access to state.
      Specified by:
        `getForm` in interface `Request`
      Returns:
        this returns the form containing the state
      Throws:
        `java.io.IOException` - thrown if it could not be acquired

    - #### 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 request `Form` 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

    - #### getPart

          public Part getPart​(java.lang.String name)
                       throws java.io.IOException

      This method is used to acquire a `Part` from the form using a known name for the part. This is typically used when there is a file upload with a multipart POST request. All parts that are not files are added to the query values as strings so that they can be used in a convenient way.
      Specified by:
        `getPart` in interface `Request`
      Parameters:
        `name` - this is the name of the part to acquire
      Returns:
        the named part or null if the part does not exist
      Throws:
        `java.io.IOException`