HttpServletRequest (Java EE 5)

Java EE API


javax.servlet.http Interface HttpServletRequest

All Superinterfaces:
ServletRequest
All Known Implementing Classes:
HttpServletRequestWrapper

public interface HttpServletRequest
extends ServletRequest

Implements: ServletRequest

扩展 javax.servlet.ServletRequest 接口,为 HTTP servlet 提供请求信息。

servlet 容器创建 HttpServletRequest 对象,并将该对象作为参数传递给 servlet 的 service 方法(doGetdoPost,等等)。

英文文档:

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

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

Author:
Various

Field Summary
static String
static String
static String
static String
 
Method Summary
 String
 String
 Cookie[]
 long
 String
 Enumeration
 Enumeration
 int
 String
 String
 String
 String
 String
 String
 String
 StringBuffer
 String
 HttpSession
 HttpSession
 Principal
 boolean
 boolean
 boolean
 boolean
 boolean
 
Methods inherited from interface javax.servlet.ServletRequest
 

Field Detail

英文文档:

BASIC_AUTH

static final String BASIC_AUTH
String identifier for Basic authentication. Value "BASIC"

See Also:
Constant Field Values


英文文档:

FORM_AUTH

static final String FORM_AUTH
String identifier for Form authentication. Value "FORM"

See Also:
Constant Field Values


英文文档:

CLIENT_CERT_AUTH

static final String CLIENT_CERT_AUTH
String identifier for Client Certificate authentication. Value "CLIENT_CERT"

See Also:
Constant Field Values


英文文档:

DIGEST_AUTH

static final String DIGEST_AUTH
String identifier for Digest authentication. Value "DIGEST"

See Also:
Constant Field Values

Method Detail

public String getAuthType()
返回用于保护 servlet 的验证方案的名称。所有 servlet 容器都支持 basic、form 和 client certificate 验证,并且可能还支持 digest 验证。如果没有验证 servlet,则返回 null

返回的值与 CGI 变量 AUTH_TYPE 的值相同。

return 返回静态成员 BASIC_AUTH、FORM_AUTH、CLIENT_CERT_AUTH、DIGEST_AUTH 之一(适用于 == 比较)或返回指示验证方案的特定于容器的字符串,如果没有验证请求,则返回 null

英文文档:

getAuthType

String getAuthType()
Returns the name of the authentication scheme used to protect the servlet. All servlet containers support basic, form and client certificate authentication, and may additionally support digest authentication. If the servlet is not authenticated null is returned.

Same as the value of the CGI variable AUTH_TYPE.

Returns:
one of the static members BASIC_AUTH, FORM_AUTH, CLIENT_CERT_AUTH, DIGEST_AUTH (suitable for == comparison) or the container-specific string indicating the authentication scheme, or null if the request was not authenticated.

public Cookie[] getCookies()
返回包含客户端随此请求一起发送的所有 Cookie 对象的数组。如果没有发送任何 cookie,则此方法返回 null
return 此请求中包含的所有 Cookie 的数组,如果该请求没有 cookie,则返回 null
英文文档:

getCookies

Cookie[] getCookies()
Returns an array containing all of the Cookie objects the client sent with this request. This method returns null if no cookies were sent.

Returns:
an array of all the Cookies included with this request, or null if the request has no cookies

public long getDateHeader(String name)
以表示 Date 对象的 long 值的形式返回指定请求头的值。与包含日期的头(比如 If-Modified-Since)一起使用此方法。

返回的日期是自格林威治标准时间 1970 年 1 月 1 日起经过的毫秒数。头名称是不区分大小写的。

如果该请求没有指定名称的头,则此方法返回 -1。如果无法将头转换为日期,则该方法将抛出 IllegalArgumentException

name 指定头名称的 String
return 表示头中指定的日期的 long 值,该日期被表示为自格林威治标准时间 1970 年 1 月 1 日起经过的毫秒数,如果请求中不包含指定的头,则返回 -1
ThrowsIllegalArgumentException: 如果无法将头值转换为日期

英文文档:

getDateHeader

long getDateHeader(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 request
Throws:
IllegalArgumentException - If the header value can't be converted to a date

public String getHeader(String name)
String 的形式返回指定请求头的值。如果该请求不包含指定名称的头,则此方法返回 null。如果有多个具有相同名称的头,则此方法返回请求中的第一个头。头名称是不区分大小写的。可以将此方法与任何请求头一起使用。
name 指定头名称的 String
return 包含请求头的值的 String,如果该请求没有该名称的头,则返回 null
英文文档:

getHeader

String getHeader(String name)
Returns the value of the specified request header as a String. If the request did not include a header of the specified name, this method returns null. If there are multiple headers with the same name, this method returns the first head in the request. The header name is case insensitive. You can use this method with any request header.

Parameters:
name - a String specifying the header name
Returns:
a String containing the value of the requested header, or null if the request does not have a header of that name

public java.util.Enumeration<E> getHeaders(String name)
String 对象的 Enumeration 的形式返回指定请求头的所有值。

一些头(比如 Accept-Language)能够以具有不同值的几个头的形式由客户端发送,而不采用以逗号分隔的列表的形式发送该头。

如果该请求不包含任何指定名称的头,则此方法返回一个空的 Enumeration。头名称是不区分大小写的。可以将此方法与任何请求头一起使用。

name 指定头名称的 String
return 包含请求头的值的 Enumeration。如果该请求不包含任何具有该名称的头,则返回一个空枚举。如果容器不允许访问头信息,则返回 null

英文文档:

getHeaders

Enumeration getHeaders(String name)
Returns all the values of the specified request 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 rather than sending the header as a comma separated list.

If the request did not include any headers of the specified name, this method returns an empty Enumeration. The header name is case insensitive. You can use this method with any request header.

Parameters:
name - a String specifying the header name
Returns:
an Enumeration containing the values of the requested header. If the request does not have any headers of that name return an empty enumeration. If the container does not allow access to header information, return null

public java.util.Enumeration<E> getHeaderNames()
返回此请求包含的所有头名称的枚举。如果该请求没有头,则此方法返回一个空枚举。

一些 servlet 容器不允许 servlet 使用此方法访问头,在这种情况下,此方法返回 null

return 随此请求一起发送的所有头名称的枚举;如果该请求没有头,则返回一个空枚举;如果 servlet 容器不允许 servlet 使用此方法,则返回 null

英文文档:

getHeaderNames

Enumeration getHeaderNames()
Returns an enumeration of all the header names this request contains. If the request has no headers, this method returns an empty enumeration.

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

Returns:
an enumeration of all the header names sent with this request; if the request has no headers, an empty enumeration; if the servlet container does not allow servlets to use this method, null

public int getIntHeader(String name)
int 的形式返回指定请求头的值。如果该请求没有指定名称的头,则此方法返回 -1。如果无法将头转换为整数,则此方法抛出 NumberFormatException

头名称是不区分大小写的。

name 指定请求头名称的 String
return 表示请求头的值的整数,如果该请求没有此名称的头,则返回 -1
ThrowsNumberFormatException: 如果无法将头值转换为 int

英文文档:

getIntHeader

int getIntHeader(String name)
Returns the value of the specified request header as an int. If the request does not have a header of the specified name, this method returns -1. If the header cannot be converted to an integer, this method throws a NumberFormatException.

The header name is case insensitive.

Parameters:
name - a String specifying the name of a request header
Returns:
an integer expressing the value of the request header or -1 if the request doesn't have a header of this name
Throws:
NumberFormatException - If the header value can't be converted to an int

public String getMethod()
返回用于发出此请求的 HTTP 方法的名称,例如 GET、POST 或 PUT。返回的值与 CGI 变量 REQUEST_METHOD 的值相同。
return 指定用于发出此请求的方法名称的 String
英文文档:

getMethod

String 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.

Returns:
a String specifying the name of the method with which this request was made

public String getPathInfo()
返回与客户端发出此请求时发送的 URL 相关联的额外路径信息。额外路径信息位于 servlet 路径之后但在查询字符串之前,并且将以 "/" 字符开头。

如果没有额外路径信息,则此方法返回 null

返回的值与 CGI 变量 PATH_INFO 的值相同。

return 由 Web 容器解码的 String,用于指定额外路径信息,这些信息在请求 URL 中跟随在 servlet 路径之后但在查询字符串之前;如果该 URL 没有任何额外路径信息,则返回 null

英文文档:

getPathInfo

String getPathInfo()
Returns any extra path information associated with the URL the client sent when it made this request. The extra path information follows the servlet path but precedes the query string and will start with a "/" character.

This method returns null if there was no extra path information.

Same as the value of the CGI variable PATH_INFO.

Returns:
a String, decoded by the web container, specifying extra path information that comes after the servlet path but before the query string in the request URL; or null if the URL does not have any extra path information

public String getPathTranslated()
返回在 servlet 名称之后但在查询字符串之前的额外路径信息,并将它转换为实际路径。返回的值与 CGI 变量 PATH_TRANSLATED 的值相同。

如果 URL 没有任何额外路径信息,则此方法返回 null,或者 servlet 容器因为某种原因(比如当从归档文件执行 Web 应用程序时)无法将虚拟路径转换为实际路径。 Web 容器不会解码此字符串。

return 指定实际路径的 String,如果 URL 没有额外路径信息,则返回 null

英文文档:

getPathTranslated

String getPathTranslated()
Returns any extra path information after the servlet name but before the query string, and translates it to a real path. Same as the value of the CGI variable PATH_TRANSLATED.

If the URL does not have any extra path information, this method returns null or the servlet container cannot translate the virtual path to a real path for any reason (such as when the web application is executed from an archive). The web container does not decode this string.

Returns:
a String specifying the real path, or null if the URL does not have any extra path information

public String getContextPath()
返回请求 URI 指示请求上下文的那一部分。请求 URI 中首先出现的总是上下文路径。路径以 "/" 字符开头但不以 "/" 字符结束。对于默认(根)上下文中的 servlet,此方法返回 ""。容器不会解码此字符串。

servlet 容器可能通过多个上下文路径匹配一个上下文。在这种情况下,此方法将返回该请求使用的实际上下文路径,该路径可能不同于 getContextPath() 方法返回的路径。getContextPath() 返回的上下文路径应该被认为是应用程序的主要或首选上下文路径。

return 指定请求 URI 指示请求上下文的那一部分的 String
See also getContextPath()

英文文档:

getContextPath

String 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.

It is possible that a servlet container may match a context by more than one context path. In such cases this method will return the actual context path used by the request and it may differ from the path returned by the ServletContext.getContextPath() method. The context path returned by ServletContext.getContextPath() should be considered as the prime or preferred context path of the application.

Returns:
a String specifying the portion of the request URI that indicates the context of the request
See Also:
ServletContext.getContextPath()

public String getQueryString()
返回包含在请求 URL 中路径后面的查询字符串。如果 URL 没有查询字符串,则此方法返回 null。返回的值与 CGI 变量 QUERY_STRING 的值相同。
return 包含查询字符串的 String,如果 URL 不包含任何查询字符串,则返回 null。该值不由容器解码。
英文文档:

getQueryString

String getQueryString()
Returns the query string that is contained in the request URL after the path. This method returns null if the URL does not have a query string. Same as the value of the CGI variable QUERY_STRING.

Returns:
a String containing the query string or null if the URL contains no query string. The value is not decoded by the container.

public String getRemoteUser()
如果用户已经过验证,则返回发出此请求的用户的登录信息,如果用户未经过验证,则返回 null。用户名是否随每个后续请求发送取决于浏览器和验证类型。返回的值与 CGI 变量 REMOTE_USER 的值相同。
return 指定发出此请求的用户的登录信息的 String,如果用户登录信息未知,则返回 null
英文文档:

getRemoteUser

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

Returns:
a String specifying the login of the user making this request, or null if the user login is not known

public boolean isUserInRole(String role)
返回一个 boolean 值,指示指定的逻辑“角色”中是否包含经过验证的用户。角色和角色成员关系可使用部署描述符定义。如果用户没有经过验证,则该方法返回 false
role 指定角色名称的 String
return 一个 boolean 值,指示发出此请求的用户是否属于给定角色;如果用户未经过验证,则返回 false
英文文档:

isUserInRole

boolean isUserInRole(String role)
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. If the user has not been authenticated, the method returns false.

Parameters:
role - a String specifying the name of the role
Returns:
a boolean indicating whether the user making this request belongs to a given role; false if the user has not been authenticated

public java.security.Principal getUserPrincipal()
返回包含当前已经过验证的用户的名称的 java.security.Principal 对象。如果用户没有经过验证,则该方法返回 null
return 包含发出此请求的用户的名称的 java.security.Principal;如果用户没有经过验证,则返回 null
英文文档:

getUserPrincipal

Principal getUserPrincipal()
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.

Returns:
a java.security.Principal containing the name of the user making this request; null if the user has not been authenticated

public String getRequestedSessionId()
返回客户端指定的会话 ID。此值可能不同于此请求的当前有效会话的 ID。如果客户端没有指定会话 ID,则此方法返回 null
return 指定会话 ID 的 String,如果该请求没有指定会话 ID,则返回 null
See also isRequestedSessionIdValid
英文文档:

getRequestedSessionId

String getRequestedSessionId()
Returns the session ID specified by the client. This may not be the same as the ID of the current valid session for this request. If the client did not specify a session ID, this method returns null.

Returns:
a String specifying the session ID, or null if the request did not specify a session ID
See Also:
isRequestedSessionIdValid()

public String getRequestURI()
返回此请求的 URL 的一部分,从协议名称一直到 HTTP 请求的第一行中的查询字符串。Web 容器不会解码此 String。例如:
HTTP 请求的第一行 返回的值
POST /some/path.html HTTP/1.1/some/path.html
GET http://foo.bar/a.html HTTP/1.0 /a.html
HEAD /xyz?a=b HTTP/1.1/xyz

要使用某个方案和主机重新构造 URL,可使用 HttpUtils#getRequestURL

return 包含 URL 从协议名称一直到查询字符串的那一部分的 String
See also getRequestURL

英文文档:

getRequestURI

String 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 decode this String. For example:
First line of HTTP request Returned Value

To reconstruct an URL with a scheme and host, use HttpUtils.getRequestURL(javax.servlet.http.HttpServletRequest).

Returns:
a String containing the part of the URL from the protocol name up to the query string
See Also:
HttpUtils.getRequestURL(javax.servlet.http.HttpServletRequest)

public StringBuffer getRequestURL()
重新构造客户端用于发出请求的 URL。返回的 URL 包含一个协议、服务器名称、端口号、服务器路径,但是不包含查询字符串参数。

如果已经使用 javax.servlet.RequestDispatcher#forward 转发了此请求,则重新构造的 URL 中的服务器路径必须反映用于获取 RequestDispatcher 的路径,而不是客户端指定的服务器路径。

因为此方法返回 StringBuffer 而不是字符串,所以可以轻松地修改 URL,例如,可以追加查询参数。

此方法对于创建重定向消息和报告错误很有用。

return 包含重新构造的 URL 的 StringBuffer 对象

英文文档:

getRequestURL

StringBuffer 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 not include query string parameters.

If this request has been forwarded using RequestDispatcher.forward(javax.servlet.ServletRequest, javax.servlet.ServletResponse), the server path in the reconstructed URL must reflect the path used to obtain the RequestDispatcher, and not the server path specified by the client.

Because this method returns a StringBuffer, not a string, you can modify the URL easily, for example, to append query parameters.

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

Returns:
a StringBuffer object containing the reconstructed URL

public String getServletPath()
返回此请求调用 servlet 的 URL 部分。此路径以 "/" 字符开头,包括 servlet 名称或到 servlet 的路径,但不包括任何额外路径信息或查询字符串。返回的值与 CGI 变量 SCRIPT_NAME 的值相同。

如果用于处理此请求的 servlet 使用 "/*" 模式实现匹配,则此方法将返回一个空字符串 ("")。

return 包含将被调用或解码的 servlet 的名称或路径的 String(如请求 URL 中指定的那样),如果用于处理请求的 servlet 使用 "/*" 模式实现匹配,则返回一个空字符串。

英文文档:

getServletPath

String getServletPath()
Returns the part of this request's URL that calls the servlet. This path starts with a "/" character and 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.

This method will return an empty string ("") if the servlet used to process this request was matched using the "/*" pattern.

Returns:
a String containing the name or path of the servlet being called, as specified in the request URL, decoded, or an empty string if the servlet used to process the request is matched using the "/*" pattern.

public HttpSession getSession(boolean create)
返回与此请求关联的当前 HttpSession,如果没有当前会话并且 create 为 true,则返回一个新会话。

如果 createfalse 并且该请求没有有效的 HttpSession,则此方法返回 null

要确保会话得到适当维护,必须在提交响应之前调用此方法。如果容器正使用 cookie 维护会话完整性,并被要求在提交响应时创建新会话,则抛出 IllegalStateException。

create true 表示为此请求创建一个新会话(如有必要);false 表示返回 null(如果没有当前会话)
return 与此请求关联的 HttpSession,如果 createfalse,并且该请求没有有效会话,则返回 null
See also getSession()

英文文档:

getSession

HttpSession getSession(boolean create)
Returns the current HttpSession associated with this request or, if there is no current session and create is true, returns a new session.

If create is false and the request has no valid HttpSession, this method returns null.

To make sure the session is properly maintained, you must call this method before the response is committed. If the container is using cookies to maintain session integrity and is asked to create a new session when the response is committed, an IllegalStateException is thrown.

Parameters:
create - true to create a new session for this request if necessary; false to return null if there's no current session
Returns:
the HttpSession associated with this request or null if create is false and the request has no valid session
See Also:
getSession()

public HttpSession getSession()
返回与此请求关联的当前会话,如果该请求没有会话,则创建一个会话。
return 与此请求关联的 HttpSession
See also getSession(boolean)
英文文档:

getSession

HttpSession getSession()
Returns the current session associated with this request, or if the request does not have a session, creates one.

Returns:
the HttpSession associated with this request
See Also:
getSession(boolean)

public boolean isRequestedSessionIdValid()
检查请求的会话 ID 是否仍然有效。

如果客户端没有指定任何会话 ID,则此方法返回 false

return 如果此请求在当前会话上下文中有一个有效会话 id,则返回 true;否则返回 false
See also getRequestedSessionId, getSession, javax.servlet.http.HttpSessionContext

英文文档:

isRequestedSessionIdValid

boolean isRequestedSessionIdValid()
Checks whether the requested session ID is still valid.

If the client did not specify any session ID, this method returns false.

Returns:
true if this request has an id for a valid session in the current session context; false otherwise
See Also:
getRequestedSessionId(), getSession(boolean), HttpSessionContext

public boolean isRequestedSessionIdFromCookie()
检查请求的会话 ID 是否是作为 cookie 进入的。
return 如果会话 ID 是作为 cookie 进入的,则返回 true;否则返回 false
See also getSession
英文文档:

isRequestedSessionIdFromCookie

boolean isRequestedSessionIdFromCookie()
Checks whether the requested session ID came in as a cookie.

Returns:
true if the session ID came in as a cookie; otherwise, false
See Also:
getSession(boolean)

public boolean isRequestedSessionIdFromURL()
检查请求的会话 ID 是否是作为请求 URL 的一部分进入的。
return 如果会话 ID 是作为 URL 的一部分进入的,则返回 true;否则返回 false
See also getSession
英文文档:

isRequestedSessionIdFromURL

boolean isRequestedSessionIdFromURL()
Checks whether the requested session ID came in as part of the request URL.

Returns:
true if the session ID came in as part of a URL; otherwise, false
See Also:
getSession(boolean)

public boolean isRequestedSessionIdFromUrl()
deprecated 从 Java Servlet API 的版本 2.1 起,请改用 #isRequestedSessionIdFromURL
英文文档:

isRequestedSessionIdFromUrl

boolean isRequestedSessionIdFromUrl()
Deprecated. As of Version 2.1 of the Java Servlet API, use isRequestedSessionIdFromURL() instead.



Submit a bug or feature

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.

一看就知道只有菜鸟才干这么无知的事啦。

PS : 未经我党受权你也可自由散发此文档。 如有任何错误请自行修正;若因此而造成任何损失请直接找人民主席,请勿与本人联系。谢谢!