Synopsis
Interface Name: javax.servlet.http.HttpServletRequest
Superinterface: javax.servlet.ServletRequest
Immediate Subinterfaces: None
Implemented By: None
Availability: Servlet API 1.0 and later
Description
HttpServletRequest extends the basic ServletRequest class, providing additional functionality for HTTP (World Wide Web) servlets. It includes support for cookies and session tracking and access to HTTP header information. HttpServletRequest also parses incoming HTTP form data and stores it as servlet parameters. The server passes an HttpServletRequest object to the service method of an HttpServlet.
Certain methods in this interface have suffered from documentation and implementation inconsistencies. Discrepancies have been noted where possible.
Interface Declaration
public interface HttpServletRequest extends javax.servlet.ServletRequest { // Methods public abstract String getAuthType(); public abstract String getContextPath(); // New in 2.2 public abstract Cookie[] getCookies(); // New in 2.0 public abstract long getDateHeader(String name); public abstract String getHeader(String name); public abstract Enumeration getHeaderNames(); public abstract Enumeration getHeaders(String name); // New in 2.2 public abstract int getIntHeader(String name); public abstract String getMethod(); public abstract String getPathInfo(); public abstract String getPathTranslated(); public abstract String getQueryString(); public abstract String getRemoteUser(); public abstract String getRequestedSessionId(); // New in 2.0 public abstract String getRequestURI(); public abstract String getServletPath(); public abstract HttpSession getSession(); // New in 2.1 public abstract HttpSession getSession(boolean create); // New in 2.0 public abstract java.security.Principal getUserPrincipal(); // New in 2.2 public abstract boolean isRequestedSessionIdFromCookie(); // New in 2.0 public abstract boolean isRequestedSessionIdFromUrl(); // Deprecated public abstract boolean isRequestedSessionIdFromURL(); // New in 2.1 public abstract boolean isRequestedSessionIdValid(); // New in 2.0 public abstract boolean isUserInRole(String role); // New in 2.2 } Methods
getAuthType()
public abstract String getAuthType()
- Description
-
Returns the servlet's authentication scheme or null if the servlet was not protected by an access control mechanism. Possible schemes are BASIC, DIGEST, FORM, and CLIENT-CERT. Same as the CGI variable AUTH_TYPE.
getContextPath()
public abstract String getContextPath()
- Description
-
Returns the portion of the request URI that indicates the context (web application) 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 and is returned directly without being URL-decoded. For servlets in the default (root) context, this method returns an empty string. This method was introduced in Servlet API 2.2.
getCookies()
public abstract Cookie[] getCookies()
- Description
-
Returns an array of Cookie objects that contains all the cookies sent by the browser as part of the request or null if no cookies were sent. This method was introduced in Servlet API 2.0.
getDateHeader()
public abstract long getDateHeader(String name)
- Description
-
Returns the value of the named header as a long value that represents a Date (the number of milliseconds since midnight, January 1, 1970, GMT) or -1 if the header was not sent as part of the request. The name is case insensitive. Throws an IllegalArgumentException when called on a header whose value cannot be converted to a Date. This method is useful for handling headers like Last-Modified and If-Modified-Since.
getHeader()
public abstract String getHeader(String name)
- Description
-
Returns the value of the named header as a String or null if the header was not sent as part of the request. The name is case insensitive. This method can retrieve all header types.
getHeaderNames()
public abstract Enumeration getHeaderNames()
- Description
-
Returns the names of all the headers a servlet can access as an Enumeration of String objects or an empty Enumeration if there were no headers. Some servlet implementations may not allow headers to be accessed in this way, in which case this method returns null.
getHeaders()
public abstract Enumeration getHeaders(String name)
- Description
-
Returns all the values of the named header as an Enumeration of String objects. Some headers, such as Accept-Language, can be sent by clients as several headers, each with a different value. This method allows all values to be retrieved. If the request did not include any headers of the specified name, this method returns an empty Enumeration. The name is case insensitive. This method can retrieve all header types. This method was introduced in Servlet API 2.2.
getIntHeader()
public abstract int getIntHeader(String name)
- Description
-
Returns the value of the named header as an int or -1 if the header was not sent as part of the request. The name is case insensitive. Throws a NumberFormatException when called on a header with a value that cannot be converted to an int.
getMethod()
public abstract String getMethod()
- Description
-
Returns the HTTP method used to make the request. Example methods include GET, POST, and HEAD. The same as the CGI variable REQUEST_METHOD. The HttpServlet implementation of service( ) uses this method when dispatching requests.
getPathInfo()
public abstract String getPathInfo()
- Description
-
Returns the extra path information associated with the request or null if none was provided. The path is URL-decoded before being returned. The same as the CGI variable PATH_INFO.
getPathTranslated()
public abstract String getPathTranslated()
- Description
-
Returns the extra path information translated to a filesystem path or null if there was no extra path information or if the servlet container cannot create a valid file path (such as when the file is on a remote filesystem or is found only inside a .war archive). The path returned does not necessarily point to an existing file or directory. The path is URL-decoded before being returned. The call is similar to the CGI variable PATH_TRANSLATED. Also the same as getServletContext().getRealPath(req.getPathInfo( )).
getQueryString()
public abstract String getQueryString()
- Description
-
Returns the query string from the request's URL. This value is the same as the CGI variable QUERY_STRING. Because HttpServletRequest parses this string into a set of servlet parameters available through getParameter( ), most servlets can ignore this method.
getRemoteUser()
public abstract String getRemoteUser()
- Description
-
Returns the name of the user making the request as a String or null if access to the servlet was not restricted. The same as the CGI variable REMOTE_USER. This generally requires that the user has logged in using HTTP authentication. There is no comparable method to directly retrieve the remote user's password.
getRequestedSessionId()
public abstract String getRequestedSessionId()
- Description
-
This method returns the session ID specified by the client. This may not be the actual session identifier currently in use for example, if the session expired before the request occurred, the server creates a new session ID and uses that one instead. This method was introduced in Servlet API 2.0.
getRequestURI()
public abstract String getRequestURI()
- Description
-
Returns the Universal Resource Identifier (URI) of the request. This is the resource requested by the client in the first line of its HTTP request, everything after the protocol and before the query string. For normal HTTP servlets, the request URI is the request URL minus the scheme, host, port, and query string but including extra path information. The path is returned directly, without being URL-decoded. Early versions of the Servlet API defined and implemented this method in different ways. When writing code that depends on this method, make sure you know what you're actually getting.
getServletPath()
public abstract String getServletPath()
- Description
-
Returns the part of the URI that refers to the servlet. The path is URL-decoded before being returned and does not include any extra path information or the query string. For file extension matches the path does include the extension. This is the same as the CGI variable SCRIPT_NAME.
getSession()
public abstract HttpSession getSession() public abstract HttpSession getSession(boolean create)
- Description
-
Returns the current session associated with the user making the request. If the user has no current valid session, this method creates one if create is true or returns null if create is false. The no-argument version has create set implicitly to true. To ensure the session is properly maintained, this method should be called at least once before any output is written to the response. Servlets not using session tracking may ignore this method. This method was introduced in Servlet API 2.0. The no-argument version was introduced in Servlet API 2.1.
getUserPrincipal()
public abstract java.security.Principal getUserPrincipal()
- Description
-
Returns a java.security.Principal object containing the name of the current authenticated user. If the user has not been authenticated, the method returns null. This method was introduced in Servlet API 2.2.
isRequestedSessionIdFromCookie()
public abstract boolean isRequestedSessionIdFromCookie()
- Description
-
Returns true if the client submitted a session identifier via a cookie, false otherwise. This method was introduced in Servlet API 2.0.
isRequestedSessionIdFromURL()
public abstract boolean isRequestedSessionIdFromUrl() public abstract boolean isRequestedSessionIdFromURL()
- Description
-
Returns true if the requested session ID was submitted via a rewritten URL, false otherwise. The isRequestedSessionIdFromUrl( ) method was introduced in Servlet API 2.0, then deprecated in Servlet API 2.1 with the introduction of the more standardly named isRequestedSessionIdFromURL( ) method.
isRequestedSessionIdValid()
public abstract boolean isRequestedSessionIdValid()
- Description
-
Returns true if the session requested by the client is a valid session and is therefore the session currently in use. For new sessions and expired sessions, it returns false. This method was introduced in Servlet API 2.0.
isUserInRole()
public abstract boolean isUserInRole(String role)
- Description
-
Returns a boolean indicating whether the authenticated user is included in the specified logical "role." Roles and role membership can be defined using deployment descriptors, and roles can be mapped to users and groups using server administration tools. If the user has not been authenticated, the method always returns false. This method was introduced in Servlet API 2.2.
