Package org.apache.tapestry5.http.services

## Interface Request

- All Known Subinterfaces:
    `TestableRequest`
  All Known Implementing Classes:
    `DelegatingRequest`, `RequestImpl`, `TestableRequestImpl`

      public interface Request

  Generic version of `HttpServletRequest`, used to encapsulate the Servlet API version, and to help bridge the differences between Servlet API and Porlet API. The Request service is a shadow of the current thread's request.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `REQUESTED_WITH_HEADER` |
    `static java.lang.String` | `X_FORWARDED_PROTO_HEADER` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.lang.Object` | `getAttribute​(java.lang.String name)` | Returns the value of the named attribute as an `Object`, or `null` if no attribute of the given name exists.
    `java.util.List<java.lang.String>` | `getAttributeNames()` | Returns a sorted list of attribute names.
    `java.lang.String` | `getContextPath()` | Deprecated. in 5.4, inject the value for symbol `SymbolConstants.CONTEXT_PATH` instead
    `long` | `getDateHeader​(java.lang.String name)` | Returns the value of the specified request header as a `long` value that represents a `Date` object.
    `java.lang.String` | `getHeader​(java.lang.String name)` | Returns the named header as a string, or null if not found.
    `java.util.List<java.lang.String>` | `getHeaderNames()` | Returns the names of all headers in the request.
    `java.util.Locale` | `getLocale()` | Returns the locale of the client as determined from the request headers.
    `int` | `getLocalPort()` | Returns the Internet Protocol (IP) port number of the interface on which the request was received.
    `java.lang.String` | `getMethod()` | Returns the name of the HTTP method with which this request was made, for example, GET, POST, or PUT.
    `java.lang.String` | `getParameter​(java.lang.String name)` | Returns the query parameter value for the given name.
    `java.util.List<java.lang.String>` | `getParameterNames()` | Returns a list of query parameter names, in alphabetical order.
    `java.lang.String[]` | `getParameters​(java.lang.String name)` | Returns the parameter values for the given name.
    `java.lang.String` | `getPath()` | Returns the path portion of the request, which starts with a "/" and contains everything up to the start of the query parameters.
    `java.lang.String` | `getRemoteHost()` | Returns the fully qualified name of the client or the last proxy that sent the request.
    `java.lang.String` | `getServerName()` | Returns the host name of the server to which the request was sent.
    `int` | `getServerPort()` | Returns the port number to which the request was sent.
    `Session` | `getSession​(boolean create)` | Gets the `Session`.
    `boolean` | `isRequestedSessionIdValid()` | Checks whether the requested session ID is still valid.
    `boolean` | `isSecure()` | Returns a boolean indicating whether this request was made using a secure channel, such as HTTPS.
    `boolean` | `isSessionInvalidated()` | Returns true if the request specified a session, and that session has been invalidated.
    `boolean` | `isXHR()` | Returns true if the request originated on the client using XmlHttpRequest (the core of any Ajax behavior).
    `void` | `setAttribute​(java.lang.String name, java.lang.Object value)` | Stores an attribute in this request.

- - ### Field Detail

    - #### REQUESTED_WITH_HEADER

          static final java.lang.String REQUESTED_WITH_HEADER

      See Also:
        Constant Field Values

    - #### X_FORWARDED_PROTO_HEADER

          static final java.lang.String X_FORWARDED_PROTO_HEADER

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getSession

          Session getSession​(boolean create)

      Gets the `Session`. If create is false and the session has not be created previously, returns null. Also, if the session is invalidated and create is false, returns null. Invoking this method with true, when the session exists but has been invalidated, will force the creation of a new session.
      Parameters:
        `create` - true to force the creation of the session
      Returns:
        the session (or null if create is false the session has not been previously created)

    - #### getContextPath

          java.lang.String getContextPath()

      Deprecated.
      in 5.4, inject the value for symbol `SymbolConstants.CONTEXT_PATH` instead
      Returns the context path. This always starts with a "/" character and does not end with one, with the exception of servlets in the root context, which return the empty string.

    - #### getParameterNames

          java.util.List<java.lang.String> getParameterNames()

      Returns a list of query parameter names, in alphabetical order.

    - #### getParameter

          java.lang.String getParameter​(java.lang.String name)

      Returns the query parameter value for the given name. Returns null if no such parameter is in the request. For a multi-valued parameter, returns just the first value.

    - #### getParameters

          java.lang.String[] getParameters​(java.lang.String name)

      Returns the parameter values for the given name. Returns null if no such parameter is in the request.

    - #### getPath

          java.lang.String getPath()

      Returns the path portion of the request, which starts with a "/" and contains everything up to the start of the query parameters. It doesn't include the context path.

    - #### getLocale

          java.util.Locale getLocale()

      Returns the locale of the client as determined from the request headers.

    - #### getHeaderNames

          java.util.List<java.lang.String> getHeaderNames()

      Returns the names of all headers in the request.

    - #### getDateHeader

          long getDateHeader​(java.lang.String name)

      Returns the value of the specified request header as a `long` value that represents a `Date` object. Use this method with headers that contain dates, such as `If-Modified-Since` . The date is returned as the number of milliseconds since January 1, 1970 GMT. The header name is case insensitive. If the request did not have a header of the specified name, this method returns -1. If the header can't be converted to a date, the method throws an `IllegalArgumentException`.
      Parameters:
        `name` - a `String` specifying the name of the header
      Returns:
        a `long` value representing the date specified in the header expressed as the number of milliseconds since January 1, 1970 GMT, or -1 if the named header was not included with the reqest
      Throws:
        `java.lang.IllegalArgumentException` - If the header value can't be converted to a date

    - #### getHeader

          java.lang.String getHeader​(java.lang.String name)

      Returns the named header as a string, or null if not found.

    - #### isXHR

          boolean isXHR()

      Returns true if the request originated on the client using XmlHttpRequest (the core of any Ajax behavior). Ajax action requests may behave quite differently than ordinary, page-based requests. This implementation currently depends on the client side setting a header: X-Requested-With=XMLHttpRequest (this is what Prototype does).
      Returns:
        true if the request has an XmlHttpRequest origin

    - #### isSecure

          boolean isSecure()

      Returns a boolean indicating whether this request was made using a secure channel, such as HTTPS.
      Returns:
        a boolean indicating if the request was made using a secure channel

    - #### getServerName

          java.lang.String getServerName()

      Returns the host name of the server to which the request was sent. It is the value of the part before ":" in the `Host` header, if any, or the resolved server name, or the server IP address.
      Returns:
        the name of the server

    - #### isRequestedSessionIdValid

          boolean isRequestedSessionIdValid()

      Checks whether the requested session ID is still valid.
      Returns:
        true if the request included a session id that is still active, false if the included session id has expired

    - #### getAttribute

          java.lang.Object getAttribute​(java.lang.String name)

      Returns the value of the named attribute as an `Object`, or `null` if no attribute of the given name exists. Because this method is a wrapper around `ServletRequest.getAttribute(String)`, it is case sensitive (unlike most of Tapestry).
      Parameters:
        `name` - a `String` specifying the name of the attribute
      Returns:
        an `Object` containing the value of the attribute, or `null` if the attribute does not exist

    - #### getAttributeNames

          java.util.List<java.lang.String> getAttributeNames()

      Returns a sorted list of attribute names.
      Since:
        5.4

    - #### setAttribute

          void setAttribute​(java.lang.String name,
                            java.lang.Object value)

      Stores an attribute in this request. Attributes are reset between requests (and remember that in Tapestry, there is usually two requests per operation: the action request that redirects to a render request).
      Parameters:
        `name` - a `String` specifying the name of the attribute
        `value` - the `Object` to be stored, or null to remove the attribute

    - #### getMethod

          java.lang.String getMethod()

      Returns the name of the HTTP method with which this request was made, for example, GET, POST, or PUT.
      Returns:
        a string specifying the name of the method with which this request was made

    - #### getLocalPort

          int getLocalPort()

      Returns the Internet Protocol (IP) port number of the interface on which the request was received.
      Returns:
        an integer specifying the port number
      Since:
        5.2.0

    - #### getServerPort

          int getServerPort()

      Returns the port number to which the request was sent. It is the value of the part after ":" in the `Host` header, if any, or the server port where the client connection was accepted on.
      Returns:
        an integer specifying the port number
      Since:
        5.2.5

    - #### getRemoteHost

          java.lang.String getRemoteHost()

      Returns the fully qualified name of the client or the last proxy that sent the request. If the engine cannot or chooses not to resolve the hostname (to improve performance), this method returns the dotted-string form of the IP address.
      Returns:
        a `String` containing the fully qualified name of the client
      Since:
        5.3

    - #### isSessionInvalidated

          boolean isSessionInvalidated()

      Returns true if the request specified a session, and that session has been invalidated.
      Returns:
        true if session was invalidated during this request
      Since:
        5.4