Servlet::Http::HttpServletRequest - HTTP servlet request interface

- NAME
- SYNOPSIS
- DESCRIPTION
- FIELDS
- METHODS
- SEE ALSO
- AUTHOR

# NAME

Servlet::Http::HttpServletRequest - HTTP servlet request interface

# SYNOPSIS

      my $type = $request->getAuthType();

      my $contextpath = $request->getContextPath();

      my @cookies = $request->getCookies();

      my $date = $request->getDateHeader($name);

      for my $name ($request->getHeaderNames()) {
        my $val = $request->getHeader($name);
        # or
        my @vals = $request->getHeaders($name);
      }

      my $method = $request->getMethod();

      my $pathinfo = $request->getPathInfo();

      my $realpath = $request->getPathTranslated();

      my $querystring = $request->getQueryString();

      my $user = $request->getRemoteUser();

      my $sessionid = $request->getRequestedSessionID();

      my $uri = $request->getRequestURI();

      my $url = $request->getRequestURL();

      my $servletpath = $request->getServletPath();

      my $session = $request->getSession($createFlag);

      my $principal = $request->getUserPrincipal();

      my $bool = $request->isRequestedSessionIdFromCookie();
      my $bool = $request->isRequestedSessionIdFromURL();
      my $bool = $request->isRequestedSessionIdValid();

      my $bool = $request->isUserInRole($role);

# DESCRIPTION

Extends the Servlet::ServletRequest interface to provide request information for HTTP servlets.

The servlet container creates this object and passes it as an argument to the servlet's service methods (`doGet()`, `doPost()`, etc).

# FIELDS

BASIC_AUTH
  String identifier for Basic authentication. Value ``BASIC''.

CLIENT_CERT_AUTH
  String identifier for certificate authentication. Value ``CERT-CLIENT''.

DIGEST_AUTH
  String identifier for Digest authentication. Value ``DIGEST''.

FORM_AUTH
  String identifier for form authentication. Value ``FORM''.

# METHODS

`getAuthType()`
  Returns the name of the authentication scheme used to protect the servlet. All servlet containers must support BASIC_AUTH, FORM_AUTH and CLIENT_CERT_AUTH and may support DIGEST_AUTH. If the servlet is not authenticated, undef is returned.

  Same as the CGI variable AUTH_TYPE.

`getContextPath()`
  Returns the portion of the request URI that indicates the context of the request. The context path always comes first in a request URI. The path starts with a ``/'' character but does not end with a ``/'' character. For servlets in the default (root) context, this method returns ``''. The container does not decode this string.

`getCookies()`
  Returns an array containing all of the Servlet::Http::Cookie objects the client sent with this request, or an empty array if no cookies were sent.

`getDateHeader($name)`
  Returns the value of the specified request header as an integer value representing the number of seconds since the epoch. Use this method with headers that contain dates, such as If-Modified-Since.

  Parameters:

  $name
    the header name

`getHeader($name)`
  Returns the value of the specified request header, or undef if the request did not include a header of the specified name. The header name is case insensitive. This method can be used with any request header.

`getHeaderNames()`
  Returns an array of all the header names this request contains, or an empty array if the request has no headers.

  Some servlet containers do not allow servlets to access headers using this method, in which case this method returns undef.

`getHeaders($name)`
  Returns an array of the values of the specified request header, or an empty array if the request did not include a header of the specified name. The header name is case insensitive. This method can be used with any request header.

  Some headers (such as Accept-Language) can be sent by clients as several headers each with a different value rather than sending the header as a comma separated list.

  Parameters:

  $name
    the header name

`getMethod()`
  Returns the name of the HTTP method with which this request was made, for example, GET, POST, or PUT. Same as the value of the CGI variable REQUEST_METHOD.

`getPathInfo()`
  Returns any extra path information associated with the URL the client sent when it made this request, or undef if there was no extra path information. The extra path information follows the servlet path but precedes the query string. Same as the value of the CGI variable PATH_INFO.

`getPathTranslated()`
  Returns any extra path information after the servlet name but before the query string, translated to a real path, or undef if there was no extra path information. The web container does not decode this string. Same as the value of the CGI variable PATH_TRANSLATED.

`getQueryString()`
  Returns the query string that is contained in the request URL after the path, or undef if the URL does not have a query string. Same as the value of the CGI variable QUERY_STRING.

`getRemoteUser()`
  Returns the name of the user making this request, if the user has been authenticated, or undef if the user has not been authenticated. Whether the user name is sent with each subsequent request depends on the client and type of authentication. Same as the value of the CGI variable REMOTE_USER.

`getRequestedSessionId()`
  Returns the session ID specified by the client (or undef if the request did not specify a session ID). This may not be the same as the ID of the actual session in use. For example, if the request specified an old (expired) session ID and the server has started a new session, this method gets a new session with a new ID.

`getRequestURI()`
  Returns the part of this request's URL from the protocol name up to the query string in the first line of the HTTP request. The web container does not decod this string.

  To reconstruct a URL with a scheme and host, use `getRequestURL()`.

`getRequestURL()`
  Reconstructs the URL the client used to make the request. The returned URL contains a protocol, server name, port number, and server path, but it does no tinclude query string parameters.

  This method is useful for creating redirect messages and for reporting errors.

`getServletPath()`
  Returns the part of this request's URL that calls the servlet. This includes either the servlet name or a path to the servlet but does not include any extra path information or a query string. Same as the value of the CGI variable SCRIPT_NAME.

`getSession($boolean)`
  Returns the current session associated with this request, or if the request does not have a session and $create is true, creates one. If $create is false and the request has no valid session, undef is returned.

  To make sure the session is properly maintained, you must call this method before the response is committed.

  Parameters:

  $create
    true to create a new session for this request if necessary; false to return undef if there's no current session.

`getUserPrincipal()`
  Returns a XXX object containing th ename of the current authenticated user, or undef if the user has not been authenticated.

`isRequestedSessionIdFromCookie()`
  Returns true if the requested session ID came in as a cookie, otherwise false.

`isRequestedSessionIdFromURL()`
  Returns true if the requested session ID came in as part of the request URL, otherwise false.

`isRequestedSessionIdValid()`
  Returns true if the requested session ID is still valid, false otherwise.

`isUserInRole($role)`
  Returns true if the authenticated user is included in the specified logical role, or false if the user has not been authenticated or is not included in the role. Roles and role membership can be defined using deployment descriptors.

  Parameters:

  $role
    the name of the role

# SEE ALSO

the Servlet::ServletRequest manpage

# AUTHOR

Brian Moseley, bcm@maz.org