javax.servlet.http

Interface HttpServletRequest

All Superinterfaces:

ServletRequest

All Known Implementing Classes:

HttpServletRequestWrapper

public interface HttpServletRequest
extends ServletRequest

Contains all the client's request information. Implementation note: all the headername matching in this class should be caseinsensitive.

Since:

1.0

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	BASIC_AUTH Identifier for a request using basic authentication.
static java.lang.String	CLIENT_CERT_AUTH Indentifier for a request using client certificate authentication value is "CLIENT_CERT"
static java.lang.String	DIGEST_AUTH Indentifier for a request using digest authentication value is "DIGEST"
static java.lang.String	FORM_AUTH Identifier for a request using form authentication.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	authenticate(HttpServletResponse response) Authenticate the user making this request.
java.lang.String	getAuthType() Gets the authorization scheme of this request.
java.lang.String	getContextPath() Returns the part of the request path used to identify the servlet context.
Cookie[]	getCookies() Gets all the Cookies present in the request.
long	getDateHeader(java.lang.String name) Converts a given header parameter name to a date in the form of the number of milliseconds since 1 january 1970 midnight GMT.
java.lang.String	getHeader(java.lang.String name) Gets a named header.
java.util.Enumeration	getHeaderNames() Gets an Enumeration with all the headernames.
java.util.Enumeration	getHeaders(java.lang.String name) Returns the values of the specified header as an enumeration of String.
int	getIntHeader(java.lang.String name) Gets a named header and returns it in the shape of an int.
java.lang.String	getMethod() Gets the method the client used.
Part	getPart(java.lang.String name) Returns the part with the specified name.
java.util.Collection<Part>	getParts() Returns all of the Part components of this multipart/form-data request.
java.lang.String	getPathInfo() Extra path info.
java.lang.String	getPathTranslated() The filesystem path to the path info.
java.lang.String	getQueryString() Gets the request's query string.
java.lang.String	getRemoteUser() Gets the username of the person sending the request.
java.lang.String	getRequestedSessionId() Gets the session Id of this request that the client wanted.
java.lang.String	getRequestURI() Gets the requested URI.
java.lang.StringBuffer	getRequestURL() Contains the URL that the client used to make the request without the query string.
java.lang.String	getServletPath() Gets the part of the URI up to and including the servlet name.
HttpSession	getSession() Gets the HttpSession connected with the client sending the request.
HttpSession	getSession(boolean create) Gets the HttpSession connected with the client sending the request.
java.security.Principal	getUserPrincipal() get the principal associated with the user tied to this request.
boolean	isRequestedSessionIdFromCookie() was the session id in the request passed via a Cookie.
boolean	isRequestedSessionIdFromUrl() Deprecated. Use isRequestedSessionIdFromURL()
boolean	isRequestedSessionIdFromURL() was the session id in the request passed via encoding of the request URI.
boolean	isRequestedSessionIdValid() is the session connected with the id in the request valid? A session id is valid if it came in with the current request and the session associated with it exists and is valid.
boolean	isUserInRole(java.lang.String role) is the user in the specified HTTP role?
void	login(java.lang.String username, java.lang.String password) Validate the specified username and password against the realm for this context.
void	logout() Remove userPrincipal, remoteUser, and authType from the request.

Methods inherited from interface javax.servlet.ServletRequest

getAsyncContext, getAttribute, getAttributeNames, getCharacterEncoding, getContentLength, getContentType, getDispatcherType, getInputStream, getLocalAddr, getLocale, getLocales, getLocalName, getLocalPort, getParameter, getParameterMap, getParameterNames, getParameterValues, getProtocol, getReader, getRealPath, getRemoteAddr, getRemoteHost, getRemotePort, getRequestDispatcher, getScheme, getServerName, getServerPort, getServletContext, isAsyncStarted, isAsyncSupported, isSecure, removeAttribute, setAttribute, setCharacterEncoding, startAsync, startAsync

Field Detail

BASIC_AUTH

static final java.lang.String BASIC_AUTH

Identifier for a request using basic authentication. Value is "BASIC"

See Also:

Constant Field Values

FORM_AUTH

static final java.lang.String FORM_AUTH

Identifier for a request using form authentication. Value is "FORM"

See Also:

Constant Field Values

CLIENT_CERT_AUTH

static final java.lang.String CLIENT_CERT_AUTH

Indentifier for a request using client certificate authentication value is "CLIENT_CERT"

See Also:

Constant Field Values

DIGEST_AUTH

static final java.lang.String DIGEST_AUTH

Indentifier for a request using digest authentication value is "DIGEST"

See Also:

Constant Field Values

Method Detail

getAuthType

java.lang.String getAuthType()

Gets the authorization scheme of this request. This is the same as the CGI request metadata AUTH_TYPE. See also section 11 of the HTTP/1.1 specification (RFC 2068).

Returns:

Authorization scheme or null if not set

getCookies

Cookie[] getCookies()

Gets all the Cookies present in the request.

Returns:

an array containing all the Cookies or an empty array if there are no cookies

Since:

2.0

getDateHeader

long getDateHeader(java.lang.String name)

Converts a given header parameter name to a date in the form of the number of milliseconds since 1 january 1970 midnight GMT. If the headername doesn't exist it returns -1; If the header can not be converted to a date it throws an IllegalArgumentException.

Parameters:

name - the name of the header field (case insensitive)

Returns:

milliseconds since January 1, 1970, 00:00:00 GMT or -1 if the header does not exist.

Throws:

java.lang.IllegalArgumentException - if the value is not a date

getHeader

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

Gets a named header. returns null if the headername doesn't exist.

Parameters:

name - the name of the header field (case insensitive)

Returns:

The value of the header or null if the header does not exist

getHeaders

java.util.Enumeration getHeaders(java.lang.String name)

Returns the values of the specified header as an enumeration of String.

Since:

2.2

getHeaderNames

java.util.Enumeration getHeaderNames()

Gets an Enumeration with all the headernames. Note that the Servlet API 2.1 Specification says that if an implementation does not support this operation an empty enumeration should be returned, but the Servlet API documentation says that the implementation will return null.

Returns:

Enumeration of all the header names or when this operation is not supported an empty Enumeration or null.

getIntHeader

int getIntHeader(java.lang.String name)

Gets a named header and returns it in the shape of an int. returns -1 if the headername doesn't exist.

Parameters:

name - the name of the header field (case insensitive)

Returns:

the value of the header field or -1 if the header does not exist

Throws:

java.lang.NumberFormatException - if the headervalue can't be converted to an int.

getMethod

java.lang.String getMethod()

Gets the method the client used. This is the same as the CGI request metadata REQUEST_METHOD. Possible return values are "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS", "TRACE".

Returns:

The method in question

getPathInfo

java.lang.String getPathInfo()

Extra path info. Everything after the actual Servlet except the query data. This is the same as the CGI request metadata PATH_INFO and identifies the source or sub-resource to be returned by the Servlet.

The function of this method could best be explained using an example. Client requests: www.foo_bar.com/servlets/myServlet/more/path?id=paul (where myServlet is a servlet)
In this case this method would return "/more/path".

[MJW] Note that the Servlet 2.1 Spec says that the path info must be URL decoded although this was not required before 2.1 and I am not sure if that is the behaviour of the CGI request metadata PATH_INFO.

Returns:

The path info or null when there is no path information.

getPathTranslated

java.lang.String getPathTranslated()

The filesystem path to the path info. Does the same as getPathInfo, but translates the result to a real path. This is the same as the CGI request metadata PATH_TRANSLATED.

[MJW] Can this be different from calling ServletContext.getRealPath() on the urldecoded result of getPathInfo()?

Returns:

The filesystem path to the file indicated by the path info or null if there is no path info

getContextPath

java.lang.String getContextPath()

Returns the part of the request path used to identify the servlet context.

Since:

2.2

getQueryString

java.lang.String getQueryString()

Gets the request's query string. The query string is the part of the request that follows the '?'.
This is the same as the CGI request metadata QUERY_STRING.

Returns:

the query string or null if there is no such part

getRemoteUser

java.lang.String getRemoteUser()

Gets the username of the person sending the request. This is the same as the CGI request metadata REMOTE_USER.

Returns:

User name or null if the username wasn't in the HTTP authentication.

isUserInRole

boolean isUserInRole(java.lang.String role)

is the user in the specified HTTP role?

Since:

2.2

getUserPrincipal

java.security.Principal getUserPrincipal()

get the principal associated with the user tied to this request.

Since:

2.2

getRequestedSessionId

java.lang.String getRequestedSessionId()

Gets the session Id of this request that the client wanted. This id can differ from the id in the current session if the client recently had gotten a new session id for whatver reason.

Returns:

The requested session id

Since:

2.0

getRequestURI

java.lang.String getRequestURI()

Gets the requested URI. This includes both the path to the servlet and everything after that except the '?' and the query_string.

Note that the Servlet 2.1 Spec says that the URI must be decoded before being returned, but this was not required before the Servlet 2.1 API and normally all URIs are encoded.

Returns:

The requested URI

getRequestURL

java.lang.StringBuffer getRequestURL()

Contains the URL that the client used to make the request without the query string. This includes protocol,server,port, and path information.

Returns:

a StringBuffer containing the request URL. this Stringbuffer can be easily appended to, to add the query string if needed.

Since:

2.3

getServletPath

java.lang.String getServletPath()

Gets the part of the URI up to and including the servlet name. No path info or query string segments are included. This is the same as the CGI request metadata SCRIPT_NAME.

getSession

HttpSession getSession()

Gets the HttpSession connected with the client sending the request. If the client didn't have a session connected with him then a new HttpSession will be created. To maintain a session this method must be called before the connection is flushed or closed. Same as calling getSession(true).

Returns:

The HttpSession connected with the client sending the request.

Since:

2.1

getSession

HttpSession getSession(boolean create)

Gets the HttpSession connected with the client sending the request. If the client didn't have a session connected with him, and create is true then a new HttpSession will be created. If create is false then null is returned. To maintain a session this method must be called before the connection is flushed or closed.

Returns:

The HttpSession connected with the client sending the request.

Since:

2.0

isRequestedSessionIdValid

boolean isRequestedSessionIdValid()

is the session connected with the id in the request valid? A session id is valid if it came in with the current request and the session associated with it exists and is valid.

Note: there is no other way to test session validity than using this method.

Since:

2.0

isRequestedSessionIdFromCookie

boolean isRequestedSessionIdFromCookie()

was the session id in the request passed via a Cookie.

Since:

2.0

isRequestedSessionIdFromURL

boolean isRequestedSessionIdFromURL()

was the session id in the request passed via encoding of the request URI.

Since:

2.1

isRequestedSessionIdFromUrl

boolean isRequestedSessionIdFromUrl()

Deprecated. Use isRequestedSessionIdFromURL()

Returns whether the session id in the request was encoded in the request URI.

Since:

2.0

authenticate

boolean authenticate(HttpServletResponse response)
                     throws java.io.IOException,
                            ServletException

Authenticate the user making this request.

Returns:

true if userPrincipal, remoteUser, and authType values have been established correctly on the request

Throws:

java.io.IOException

ServletException

Since:

3.0

login

void login(java.lang.String username,
         java.lang.String password)
           throws ServletException

Validate the specified username and password against the realm for this context.

Throws:

ServletException - on login failure

Since:

3.0

logout

void logout()
            throws ServletException

Remove userPrincipal, remoteUser, and authType from the request.

Throws:

ServletException

Since:

3.0

getParts

java.util.Collection<Part> getParts()
                                    throws java.io.IOException,
                                           ServletException

Returns all of the Part components of this multipart/form-data request.

Throws:

ServletException - if this request is not of type multipart/form-data

java.lang.IllegalArgumentException - if the request body is larger than maxRequestSize or any part body is larger than maxFileSize

java.io.IOException

Since:

3.0

getPart

Part getPart(java.lang.String name)
             throws java.io.IOException,
                    ServletException

Returns the part with the specified name.

Throws:

ServletException - if this request is not of type multipart/form-data

java.lang.IllegalArgumentException - if the request body is larger than maxRequestSize or the part body is larger than maxFileSize

java.io.IOException

Since:

3.0