ServletRequest (Java EE 5)

ServletRequest 对象提供包括参数名称、参数值、属性和输入流的数据。扩展 ServletRequest 的接口可提供其他特定于协议的数据，例如 javax.servlet.http.HttpServletRequest 提供的 HTTP 数据。

Defines an object to provide client request information to a servlet. The servlet container creates a ServletRequest object and passes it as an argument to the servlet's service method.

A ServletRequest object provides data including parameter name and values, attributes, and an input stream. Interfaces that extend ServletRequest can provide additional protocol-specific data (for example, HTTP data is provided by HttpServletRequest.

Author:

Various

See Also:

HttpServletRequest

public Object getAttribute(String name)
以 Object 形式返回指定属性的值，如果不存在给定名称的属性，则返回 null。

可以以两种方式设置属性。servlet 容器可设置属性，使有关请求的自定义信息可用。例如，对于使用 HTTPS 发出的请求，可使用属性 javax.servlet.request.X509Certificate 获取有关客户端证书的信息。还可以使用 ServletRequest#setAttribute 以编程方式设置属性。这允许在调用 RequestDispatcher 之前将信息嵌入请求。

属性名称应遵守与包名称相同的命名约定。此规范保留匹配 java.*、javax.* 和 sun.* 的名称。

name	指定属性名称的 String
return	包含属性值的 Object，如果属性不存在，则返回 null

英文文档：

getAttribute

Object getAttribute(String name)

Returns the value of the named attribute as an Object, or null if no attribute of the given name exists.

Attributes can be set two ways. The servlet container may set attributes to make available custom information about a request. For example, for requests made using HTTPS, the attribute javax.servlet.request.X509Certificate can be used to retrieve information on the certificate of the client. Attributes can also be set programatically using setAttribute(java.lang.String, java.lang.Object). This allows information to be embedded into a request before a RequestDispatcher call.

Attribute names should follow the same conventions as package names. This specification reserves names matching java.*, javax.*, and sun.*.

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

public java.util.Enumeration<E> getAttributeNames()
返回包含此请求可用属性的名称的 Enumeration。如果该请求没有可用的属性，则此方法返回一个空的 Enumeration。

return

包含请求的属性名称的字符串的 Enumeration

英文文档：

getAttributeNames

Enumeration getAttributeNames()

Returns an Enumeration containing the names of the attributes available to this request. This method returns an empty Enumeration if the request has no attributes available to it.

Returns:

an Enumeration of strings containing the names of the request's attributes

public String getCharacterEncoding()
返回此请求正文中使用的字符编码的名称。如果该请求未指定字符编码，则此方法返回 null

return

包含字符编码的名称的 String，如果该请求未指定字符编码，则返回 null

英文文档：

getCharacterEncoding

String getCharacterEncoding()

Returns the name of the character encoding used in the body of this request. This method returns null if the request does not specify a character encoding

Returns:

a String containing the name of the character encoding, or null if the request does not specify a character encoding

public void setCharacterEncoding(String env) throws java.io.UnsupportedEncodingException
重写此请求正文中使用的字符编码的名称。必须在使用 getReader() 读取请求参数或读取输入之前调用此方法。否则，此方法没有任何效果。

env	包含字符编码名称的 String。
Throws	java.io.UnsupportedEncodingException: 如果此 ServletRequest 仍然处于可以设置字符编码的状态，但指定编码无效

英文文档：

setCharacterEncoding

void setCharacterEncoding(String env)
                          throws UnsupportedEncodingException

Overrides the name of the character encoding used in the body of this request. This method must be called prior to reading request parameters or reading input using getReader(). Otherwise, it has no effect.

Parameters:

env - String containing the name of the character encoding.

Throws:

UnsupportedEncodingException - if this ServletRequest is still in a state where a character encoding may be set, but the specified encoding is invalid

public int getContentLength()
返回请求正文的长度（以字节为单位），并使输入流可以使用它，如果长度未知，则返回 -1。对于 HTTP servlet，返回的值与 CGI 变量 CONTENT_LENGTH 的值相同。

return

包含请求正文长度的整数，如果长度未知，则返回 -1

英文文档：

getContentLength

int getContentLength()

Returns the length, in bytes, of the request body and made available by the input stream, or -1 if the length is not known. For HTTP servlets, same as the value of the CGI variable CONTENT_LENGTH.

Returns:

an integer containing the length of the request body or -1 if the length is not known

public String getContentType()
返回请求正文的 MIME 类型，如果该类型未知，则返回 null。对于 HTTP servlet，返回的值与 CGI 变量 CONTENT_TYPE 的值相同。

return

包含请求的 MIME 类型名称的 String，如果该类型未知，则返回 null

英文文档：

getContentType

String getContentType()

Returns the MIME type of the body of the request, or null if the type is not known. For HTTP servlets, same as the value of the CGI variable CONTENT_TYPE.

Returns:

a String containing the name of the MIME type of the request, or null if the type is not known

public ServletInputStream getInputStream() throws java.io.IOException
使用 ServletInputStream 以二进制数据形式获取请求正文。可调用此方法或 #getReader 读取正文，而不是两种方法都调用。

return	包含请求正文的 ServletInputStream 对象
Throws	IllegalStateException: 如果已经为此请求调用 #getReader 方法
Throws	java.io.IOException: 如果发生输入或输出异常

英文文档：

getInputStream

ServletInputStream getInputStream()
                                  throws IOException

Retrieves the body of the request as binary data using a ServletInputStream. Either this method or getReader() may be called to read the body, not both.

Returns:

a ServletInputStream object containing the body of the request

Throws:

IllegalStateException - if the getReader() method has already been called for this request

IOException - if an input or output exception occurred

public String getParameter(String name)
以 String 形式返回请求参数的值，如果该参数不存在，则返回 null。请求参数是与请求一起发送的额外信息。对于 HTTP servlet，参数包含在查询字符串或发送的表单数据中。

只有在确定参数只有一个值时，才应该使用此方法。如果参数可能拥有一个以上的值，则使用 #getParameterValues。

如果将此方法用于一个有多个值的参数，则返回的值等于 getParameterValues 返回的数组中的第一个值。

如果参数数据是在请求正文中发送的，比如发生在 HTTP POST 请求中，则通过 #getInputStream 或 #getReader 直接读取正文可能妨碍此方法的执行。

name	指定参数名称的 String
return	表示单个参数值的 String
See also	getParameterValues

英文文档：

getParameter

String getParameter(String name)

Returns the value of a request parameter as a String, or null if the parameter does not exist. Request parameters are extra information sent with the request. For HTTP servlets, parameters are contained in the query string or posted form data.

You should only use this method when you are sure the parameter has only one value. If the parameter might have more than one value, use getParameterValues(java.lang.String).

If you use this method with a multivalued parameter, the value returned is equal to the first value in the array returned by getParameterValues.

If the parameter data was sent in the request body, such as occurs with an HTTP POST request, then reading the body directly via getInputStream() or getReader() can interfere with the execution of this method.

Parameters:

name - a String specifying the name of the parameter

Returns:

a String representing the single value of the parameter

See Also:

getParameterValues(java.lang.String)

public java.util.Enumeration<E> getParameterNames()
返回包含此请求中所包含参数的名称的 String 对象的 Enumeration。如果该请求没有参数，则此方法返回一个空的 Enumeration。

return

String 对象的 Enumeration，每个 String 都包含一个请求参数的名称；如果该请求没有参数，则返回一个空的 Enumeration

英文文档：

getParameterNames

Enumeration getParameterNames()

Returns an Enumeration of String objects containing the names of the parameters contained in this request. If the request has no parameters, the method returns an empty Enumeration.

Returns:

an Enumeration of String objects, each String containing the name of a request parameter; or an empty Enumeration if the request has no parameters

public String[] getParameterValues(String name)
返回包含给定请求参数拥有的所有值的 String 对象数组，如果该参数不存在，则返回 null。

如果该参数只有一个值，则数组的长度为 1。

name	包含请求其值的参数的名称的 String
return	包含参数值的 String 对象数组
See also	getParameter

英文文档：

getParameterValues

String[] getParameterValues(String name)

Returns an array of String objects containing all of the values the given request parameter has, or null if the parameter does not exist.

If the parameter has a single value, the array has a length of 1.

Parameters:

name - a String containing the name of the parameter whose value is requested

Returns:

an array of String objects containing the parameter's values

See Also:

getParameter(java.lang.String)

public java.util.Map<K, V> getParameterMap()
返回此请求的参数的 java.util.Map。请求参数是与请求一起发送的额外信息。对于 HTTP servlet，参数包含在查询字符串或发送的表单数据中。

return

将参数名称作为键、参数值作为映射值的不可变 java.util.Map。参数映射中的键的类型为 String。参数映射中的值的类型为 String 数组。

英文文档：

getParameterMap

Map getParameterMap()

Returns a java.util.Map of the parameters of this request. Request parameters are extra information sent with the request. For HTTP servlets, parameters are contained in the query string or posted form data.

Returns:

an immutable java.util.Map containing parameter names as keys and parameter values as map values. The keys in the parameter map are of type String. The values in the parameter map are of type String array.

public String getProtocol()
以 protocol/majorVersion.minorVersion 的形式（例如 HTTP/1.1）返回请求使用的协议的名称和版本。对于 HTTP servlet，返回的值与 CGI 变量 SERVER_PROTOCOL 的值相同。

return

包含协议名称和版本号的 String

英文文档：

getProtocol

String getProtocol()

Returns the name and version of the protocol the request uses in the form protocol/majorVersion.minorVersion, for example, HTTP/1.1. For HTTP servlets, the value returned is the same as the value of the CGI variable SERVER_PROTOCOL.

Returns:

a String containing the protocol name and version number

public String getScheme()
返回用于发出此请求的方案的名称，例如 http、https 或 ftp。不同方案具有不同的构造 URL 的规则，这一点已在 RFC 1738 中注明。

return

包含用于发出此请求的方案的名称的 String

英文文档：

getScheme

String getScheme()

Returns the name of the scheme used to make this request, for example, http, https, or ftp. Different schemes have different rules for constructing URLs, as noted in RFC 1738.

Returns:

a String containing the name of the scheme used to make this request

public String getServerName()
返回请求被发送到的服务器的主机名。它是 Host 头值 ":"（如果有）之前的那部分的值，或者解析的服务器名称或服务器 IP 地址。

return

包含服务器名称的 String

英文文档：

getServerName

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 value, if any, or the resolved server name, or the server IP address.

Returns:

a String containing the name of the server

public int getServerPort()
返回请求被发送到的端口号。它是 Host 头值 ":"（如果有）之后的那部分的值，或者接受客户端连接的服务器端口。

return

指定端口号的整数

英文文档：

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 value, if any, or the server port where the client connection was accepted on.

Returns:

an integer specifying the port number

public java.io.BufferedReader getReader() throws java.io.IOException
使用 BufferedReader 以字符数据形式获取请求正文。读取器根据正文上使用的字符编码转换字符数据。可调用此方法或 #getInputStream 读取正文，而不是两种方法都调用。

return	包含请求正文的 BufferedReader
Throws	UnsupportedEncodingException: 如果使用的字符集编码不受支持，并且无法对文本进行解码
Throws	IllegalStateException: 如果已对此请求调用 #getInputStream 方法
Throws	java.io.IOException: 如果发生输入或输出异常
See also	getInputStream

英文文档：

getReader

BufferedReader getReader()
                         throws IOException

Retrieves the body of the request as character data using a BufferedReader. The reader translates the character data according to the character encoding used on the body. Either this method or getInputStream() may be called to read the body, not both.

Returns:

a BufferedReader containing the body of the request

Throws:

UnsupportedEncodingException - if the character set encoding used is not supported and the text cannot be decoded

IllegalStateException - if getInputStream() method has been called on this request

IOException - if an input or output exception occurred

See Also:

getInputStream()

public String getRemoteAddr()
返回发送请求的客户端或最后一个代理的 Internet Protocol (IP) 地址。对于 HTTP servlet，返回的值与 CGI 变量 REMOTE_ADDR 的值相同。

return

包含发送请求的客户端的 IP 地址的 String

英文文档：

getRemoteAddr

String getRemoteAddr()

Returns the Internet Protocol (IP) address of the client or last proxy that sent the request. For HTTP servlets, same as the value of the CGI variable REMOTE_ADDR.

Returns:

a String containing the IP address of the client that sent the request

public String getRemoteHost()
返回发送请求的客户端或最后一个代理的完全限定名称。如果引擎无法或没有选择解析主机名（为了提高性能），则此方法返回以点分隔的字符串形式的 IP 地址。对于 HTTP servlet，返回的值与 CGI 变量 REMOTE_HOST 的值相同。

return

包含客户端的完全限定名称的 String

英文文档：

getRemoteHost

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. For HTTP servlets, same as the value of the CGI variable REMOTE_HOST.

Returns:

a String containing the fully qualified name of the client

public void setAttribute(String name, Object o)
存储此请求中的属性。在请求之间重置属性。此方法常常与 RequestDispatcher 一起使用。

属性名称应遵守与包名称相同的命名约定。以 java.*、javax.* 和 com.sun.* 开头的名称保留给 Sun Microsystems 使用。
如果传入的对象为 null，则效果将与调用 #removeAttribute 相同。
警告，当通过 RequestDispatcher 从驻留在另一个 Web 应用程序中的 servlet 分发请求时，可能无法在调用者 servlet 中正确获取通过此方法设置的对象。

name	指定属性名称的 String
o	要存储的 Object

英文文档：

setAttribute

void setAttribute(String name,
                  Object o)

Stores an attribute in this request. Attributes are reset between requests. This method is most often used in conjunction with RequestDispatcher.

Attribute names should follow the same conventions as package names. Names beginning with java.*, javax.*, and com.sun.*, are reserved for use by Sun Microsystems.
If the object passed in is null, the effect is the same as calling removeAttribute(java.lang.String).
It is warned that when the request is dispatched from the servlet resides in a different web application by RequestDispatcher, the object set by this method may not be correctly retrieved in the caller servlet.

Parameters:

name - a String specifying the name of the attribute

o - the Object to be stored

public void removeAttribute(String name)
从此请求中移除属性。此方法不是普遍需要的，因为属性只在处理请求期间保留。

属性名称应遵守与包名称相同的命名约定。以 java.*、javax.* 和 com.sun.* 开头的名称保留给 Sun Microsystems 使用。

name	指定要移除属性的名称的 String

英文文档：

removeAttribute

void removeAttribute(String name)

Removes an attribute from this request. This method is not generally needed as attributes only persist as long as the request is being handled.

Attribute names should follow the same conventions as package names. Names beginning with java.*, javax.*, and com.sun.*, are reserved for use by Sun Microsystems.

Parameters:

name - a String specifying the name of the attribute to remove

public java.util.Locale getLocale()
基于 Accept-Language 头，返回客户端将用来接受内容的首选 Locale。如果客户端请求没有提供 Accept-Language 头，则此方法返回服务器的默认语言环境。

return

客户端的首选 Locale

英文文档：

getLocale

Locale getLocale()

Returns the preferred Locale that the client will accept content in, based on the Accept-Language header. If the client request doesn't provide an Accept-Language header, this method returns the default locale for the server.

Returns:

the preferred Locale for the client

public java.util.Enumeration<E> getLocales()
返回 Locale 对象的 Enumeration，这些对象以首选语言环境开头，按递减顺序排列，指示基于 Accept-Language 头客户端可接受的语言环境。如果客户端请求没有提供 Accept-Language 头，则此方法返回包含一个 Locale 的 Enumeration，即服务器的默认语言环境。

return

客户端首选 Locale 对象的 Enumeration

英文文档：

getLocales

Enumeration getLocales()

Returns an Enumeration of Locale objects indicating, in decreasing order starting with the preferred locale, the locales that are acceptable to the client based on the Accept-Language header. If the client request doesn't provide an Accept-Language header, this method returns an Enumeration containing one Locale, the default locale for the server.

Returns:

an Enumeration of preferred Locale objects for the client

public boolean isSecure()
返回一个 boolean 值，指示此请求是否是使用安全通道（比如 HTTPS）发出的。

return

指示请求是否是使用安全通道发出的 boolean 值

英文文档：

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

public RequestDispatcher getRequestDispatcher(String path)
返回一个 RequestDispatcher 对象，它充当位于给定路径上的资源的包装器。可以使用 RequestDispatcher 对象将请求转发给资源，或者在响应中包含资源。资源可以是动态的，也可以是静态的。

指定的路径名可以是相对的，尽管它无法扩展到当前 servlet 上下文之外。如果该路径以 "/" 开头，那么可以相对于当前上下文根解释它。如果 servlet 容器无法返回 RequestDispatcher，则此方法将返回 null。

此方法与 ServletContext#getRequestDispatcher 的不同在于此方法可以采用相对路径。

path	指定指向资源的路径名的 String。如果该路径名是相对的，那么它必须是相对于当前 servlet 的。
return	充当位于给定路径上的资源的包装器的 RequestDispatcher 对象，如果 servlet 容器无法返回 RequestDispatcher，则返回 null
See also	javax.servlet.RequestDispatcher, getRequestDispatcher

英文文档：

getRequestDispatcher

RequestDispatcher getRequestDispatcher(String path)

Returns a RequestDispatcher object that acts as a wrapper for the resource located at the given path. A RequestDispatcher object can be used to forward a request to the resource or to include the resource in a response. The resource can be dynamic or static.

The pathname specified may be relative, although it cannot extend outside the current servlet context. If the path begins with a "/" it is interpreted as relative to the current context root. This method returns null if the servlet container cannot return a RequestDispatcher.

The difference between this method and ServletContext.getRequestDispatcher(java.lang.String) is that this method can take a relative path.

Parameters:

path - a String specifying the pathname to the resource. If it is relative, it must be relative against the current servlet.

Returns:

a RequestDispatcher object that acts as a wrapper for the resource at the specified path, or null if the servlet container cannot return a RequestDispatcher

See Also:

RequestDispatcher, ServletContext.getRequestDispatcher(java.lang.String)

public String getRealPath(String path)

deprecated

从 Java Servlet API 的版本 2.1 起，请改用 ServletContext#getRealPath。

英文文档：

getRealPath

String getRealPath(String path)

Deprecated. As of Version 2.1 of the Java Servlet API, use ServletContext.getRealPath(java.lang.String) instead.

public int getRemotePort()
返回发送请求的客户端或最后一个代理的 Internet Protocol (IP) 源端口。

return	指定端口号的整数
since	2.4

英文文档：

getRemotePort

int getRemotePort()

Returns the Internet Protocol (IP) source port of the client or last proxy that sent the request.

Returns:

an integer specifying the port number

Since:

2.4

public String getLocalName()
返回接收请求的 Internet Protocol (IP) 接口的主机名。

return	包含接收请求的 IP 的主机名的 String。
since	2.4

英文文档：

getLocalName

String getLocalName()

Returns the host name of the Internet Protocol (IP) interface on which the request was received.

Returns:

a String containing the host name of the IP on which the request was received.

Since:

2.4

public String getLocalAddr()
返回接收请求的接口的 Internet Protocol (IP) 地址。

return	包含接收请求的 IP 地址的 String。
since	2.4

英文文档：

getLocalAddr

String getLocalAddr()

Returns the Internet Protocol (IP) address of the interface on which the request was received.

Returns:

a String containing the IP address on which the request was received.

Since:

2.4

public int getLocalPort()
返回接收请求的接口的 Internet Protocol (IP) 端口号。

return	指定端口号的整数
since	2.4

英文文档：

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:

2.4

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