ExternalContext (Java EE 5)

此类使 Faces API 能够忽略所含应用程序环境的特性。具体来说，此类使基于 JavaServer Faces 的应用程序能够在 Servlet 或 Portlet 环境中运行。

在下文的方法描述中，以 Servlet：和 Portlet： 开头的段落表示针对该特定环境的行为。

This class allows the Faces API to be unaware of the nature of its containing application environment. In particular, this class allows JavaServer Faces based appications to run in either a Servlet or a Portlet environment.

In the method descriptions below, paragraphs starting with Servlet: and Portlet: denote behavior that is specific to that particular environment.

英文文档：

BASIC_AUTH

public static final String BASIC_AUTH

String identifier for BASIC authentication.

See Also:

Constant Field Values

英文文档：

CLIENT_CERT_AUTH

public static final String CLIENT_CERT_AUTH

String identifier for CLIENT_CERT authentication.

See Also:

Constant Field Values

英文文档：

DIGEST_AUTH

public static final String DIGEST_AUTH

String identifier for DIGEST authentication.

See Also:

Constant Field Values

英文文档：

FORM_AUTH

public static final String FORM_AUTH

String identifier for FORM authentication.

See Also:

Constant Field Values

public ExternalContext()

英文文档：

ExternalContext

public ExternalContext()

abstract public void dispatch(String path) throws java.io.IOException

将请求分发给指定的资源，以为此响应创建输出。

Servlet：要完成此方法，必须首先调用 javax.servlet.ServletContext 方法 getRequestDispatcher(path)，然后对所得对象调用 forward() 方法。

Portlet：要完成此方法，必须首先调用 javax.portlet.PortletContext 方法 getRequestDispatcher()，然后对所得对象调用 include() 方法。

path	指向指定资源的上下文相对路径，必须以斜杠 ("/") 字符开头
Throws	FacesException: 如果发生 ServletException 或 PortletException，则抛出该异常
Throws	IllegalArgumentException: 如果无法为指定的路径创建请求分发程序
Throws	IllegalStateException: 如果在 portlet 环境中调用此方法，并且当前请求为 ActionRequest，而不是 RenderRequest
Throws	java.io.IOException: 如果发生输入/输出错误
Throws	NullPointerException: 如果 path 为 null

英文文档：

dispatch

public abstract void dispatch(String path)
                       throws IOException

Dispatch a request to the specified resource to create output for this response.

Servlet: This must be accomplished by calling the javax.servlet.ServletContext method getRequestDispatcher(path), and calling the forward() method on the resulting object.

Portlet: This must be accomplished by calling the javax.portlet.PortletContext method getRequestDispatcher(), and calling the include() method on the resulting object.

Parameters:

path - Context relative path to the specified resource, which must start with a slash ("/") character

Throws:

FacesException - thrown if a ServletException or PortletException occurs

IllegalArgumentException - if no request dispatcher can be created for the specified path

IllegalStateException - if this method is called in a portlet environment, and the current request is an ActionRequest instead of a RenderRequest

IOException - if an input/output error occurs

NullPointerException - if path is null

abstract public String encodeActionURL(String url)

执行了任何为确保正确标识当前应用程序中的可寻址操作所需的重写操作之后，返回输入 URL。

Servlet：这必须是 javax.servlet.http.HttpServletResponse 方法 encodeURL(url) 返回的值。

Portlet：这必须是 javax.portlet.PortletResponse 方法 encodeURL(url) 返回的值。

url	要编码的输入 URL
Throws	NullPointerException: 如果 url 为 null

英文文档：

encodeActionURL

public abstract String encodeActionURL(String url)

Return the input URL, after performing any rewriting needed to ensure that it will correctly identify an addressable action in the current application.

Servlet: This must be the value returned by the javax.servlet.http.HttpServletResponse method encodeURL(url).

Portlet: This must be the value returned by the javax.portlet.PortletResponse method encodeURL(url).

Parameters:

url - The input URL to be encoded

Throws:

NullPointerException - if url is null

abstract public String encodeNamespace(String name)

用名称空间作为其前缀以确保它在特定页面上下文中的唯一性之后，返回指定的名称。

Servlet：必须返回未更改的输入值。

Portlet：返回值必须是以 javax.portlet.RenderResponse 方法 getNamespace() 返回的值为前缀的输入值。

name	要编码的名称
Throws	IllegalStateException: 如果在 portlet 环境中调用此方法，并且当前的响应为 ActionResponse，而不是 RenderResponse
Throws	NullPointerException: 如果 name 为 null

英文文档：

encodeNamespace

public abstract String encodeNamespace(String name)

Return the specified name, after prefixing it with a namespace that ensures that it will be unique within the context of a particular page.

Servlet: The input value must be returned unchanged.

Portlet: The returned value must be the input value prefixed by the value returned by the javax.portlet.RenderResponse method getNamespace().

Parameters:

name - Name to be encoded

Throws:

IllegalStateException - if this method is called in a portlet environment, and the current response is an ActionResponse instead of a RenderResponse

NullPointerException - if name is null

abstract public String encodeResourceURL(String url)

执行了任何为确保正确标识当前应用程序中的可寻址资源所需的重写操作之后，返回输入 URL。

Servlet：这必须是 javax.servlet.http.HttpServletResponse 方法 encodeURL(url) 返回的值。

Portlet：这必须是 javax.portlet.PortletResponse 方法 encodeURL(url) 返回的值。

url	要编码的输入 URL
Throws	NullPointerException: 如果 url 为 null

英文文档：

encodeResourceURL

public abstract String encodeResourceURL(String url)

Return the input URL, after performing any rewriting needed to ensure that it will correctly identify an addressable resource in the current application.

Servlet: This must be the value returned by the javax.servlet.http.HttpServletResponse method encodeURL(url).

Portlet: This must be the value returned by the javax.portlet.PortletResponse method encodeURL(url).

Parameters:

url - The input URL to be encoded

Throws:

NullPointerException - if url is null

abstract public java.util.Map<K, V> getApplicationMap()

返回一个可变的 Map，它代表当前应用程序的应用程序作用域属性。返回的 Map 必须实现可修改映射的整个协定，这在 java.util.Map 的 JavaDoc 中有详细说明。在 Map 中所进行的修改一定会导致在应用程序作用域属性集中进行相应更改。特别是 clear()、remove()、put()、putAll() 和 get() 操作必须对底层数据库结构采取相应的操作。

对于任何导致元素从底层数据结构中删除的 Map 方法，必须采取以下与托管 Bean 有关的操作。如果移除的元素是托管 Bean，并且它有一个或多个使用 javax.annotation.PreDestroy 注释的公共无参数 void 返回方法，则从底层数据结构移除该元素前，必须调用所有这些方法。对于非托管 Bean，但恰好含有使用该注释的方法的元素，移除时不得调用这些方法。PreDestroy 注释的方法所抛出的任何异常都必须被捕获并重新抛出。可以记录异常。

Servlet：这必须是通过 javax.servlet.ServletContext 方法 getAttribute()、getAttributeNames()、removeAttribute() 和 setAttribute() 获得的属性集。

Portlet：这必须是通过 javax.portlet.PortletContext 方法 getAttribute()、getAttributeNames()、removeAttribute() 和 setAttribute() 获得的属性集。

英文文档：

getApplicationMap

public abstract Map<String,Object> getApplicationMap()

Return a mutable Map representing the application scope attributes for the current application. The returned Map must implement the entire contract for a modifiable map as described in the JavaDocs for java.util.Map. Modifications made in the Map must cause the corresponding changes in the set of application scope attributes. Particularly the clear(), remove(), put(), putAll(), and get() operations must take the appropriate action on the underlying data structure.

For any of the Map methods that cause an element to be removed from the underlying data structure, the following action regarding managed-beans must be taken. If the element to be removed is a managed-bean, and it has one or more public no-argument void return methods annotated with javax.annotation.PreDestroy, each such method must be called before the element is removed from the underlying data structure. Elements that are not managed-beans, but do happen to have methods with that annotation must not have those methods called on removal. Any exception thrown by the PreDestroy annotated methods must by caught and not rethrown. The exception may be logged.

Servlet: This must be the set of attributes available via the javax.servlet.ServletContext methods getAttribute(), getAttributeNames(), removeAttribute(), and setAttribute().

Portlet: This must be the set of attributes available via the javax.portlet.PortletContext methods getAttribute(), getAttributeNames(), removeAttribute(), and setAttribute().

abstract public String getAuthType()

返回用于验证当前用户的验证方案的名称（如果有）；否则返回 null。对于标准验证方案，返回值将是以下常量之一：BASIC_AUTH、CLIENT_CERT_AUTH、DIGEST_AUTH 或 FORM_AUTH。

Servlet：这必须是 javax.servlet.http.HttpServletRequest 方法 getAuthType() 返回的值。

Portlet：这必须是 javax.portlet.http.PortletRequest 方法 getAuthType() 返回的值。

英文文档：

getAuthType

public abstract String getAuthType()

Return the name of the authentication scheme used to authenticate the current user, if any; otherwise, return null. For standard authentication schemes, the returned value will match one of the following constants: BASIC_AUTH, CLIENT_CERT_AUTH, DIGEST_AUTH, or FORM_AUTH.

Servlet: This must be the value returned by the javax.servlet.http.HttpServletRequest method getAuthType().

Portlet: This must be the value returned by the javax.portlet.http.PortletRequest method getAuthType().

abstract public Object getContext()

返回当前应用程序的应用程序环境对象实例。

Servlet：这必须是当前应用程序的 javax.servlet.ServletContext 实例。

Portlet：这必须是当前应用程序的 javax.portlet.PortletContext 实例。

英文文档：

getContext

public abstract Object getContext()

Return the application environment object instance for the current appication.

Servlet: This must be the current application's javax.servlet.ServletContext instance.

Portlet: This must be the current application's javax.portlet.PortletContext instance.

abstract public String getInitParameter(String name)

返回指定应用程序初始化参数的值（如果有）。

Servlet：这必须是 javax.servlet.ServletContext 方法 getInitParameter(name) 的结果。

Portlet：这必须是 javax.portlet.PortletContext 方法 getInitParameter(name) 的结果。

name	请求的初始化参数的名称
Throws	NullPointerException: 如果 name 为 null

英文文档：

getInitParameter

public abstract String getInitParameter(String name)

Return the value of the specified application initialization parameter (if any).

Servlet: This must be the result of the javax.servlet.ServletContext method getInitParameter(name).

Portlet: This must be the result of the javax.portlet.PortletContext method getInitParameter(name).

Parameters:

name - Name of the requested initialization parameter

Throws:

NullPointerException - if name is null

abstract public java.util.Map<K, V> getInitParameterMap()

返回一个不可变的 Map，其键是为此应用程序配置的应用程序初始化参数名称集，其值是相应的参数值。返回的 Map 必须实现不可修改映射的整个协定，这在 java.util.Map 的 JavaDoc 中有详细说明。

Servlet：此方法的结果必须等同于先调用 javax.servlet.ServletContext 方法 getInitParameterNames，然后在结果中放入配置的所有参数名称/值对。

Portlet：此方法的结果必须等同于先调用 javax.portlet.PortletContext 方法 getInitParameterNames，然后在结果中放入配置的所有参数名称/值对。

英文文档：

getInitParameterMap

public abstract Map getInitParameterMap()

Return an immutable Map whose keys are the set of application initialization parameter names configured for this application, and whose values are the corresponding parameter values. The returned Map must implement the entire contract for an unmodifiable map as described in the JavaDocs for java.util.Map.

Servlet: This result must be as if it were synthesized by calling the javax.servlet.ServletContext method getInitParameterNames, and putting each configured parameter name/value pair into the result.

Portlet: This result must be as if it were synthesized by calling the javax.portlet.PortletContext method getInitParameterNames, and putting each configured parameter name/value pair into the result.

abstract public String getRemoteUser()

返回作出当前请求的用户的登录名（如果有）；否则返回 null。

Servlet：这必须是 javax.servlet.http.HttpServletRequest 方法 getRemoteUser() 返回的值。

Portlet：这必须是 javax.portlet.http.PortletRequest 方法 getRemoteUser() 返回的值。

英文文档：

getRemoteUser

public abstract String getRemoteUser()

Return the login name of the user making the current request if any; otherwise, return null.

Servlet: This must be the value returned by the javax.servlet.http.HttpServletRequest method getRemoteUser().

Portlet: This must be the value returned by the javax.portlet.http.PortletRequest method getRemoteUser().

abstract public Object getRequest()

返回当前请求的特定于环境的对象实例。

Servlet：这必须是当前请求的 javax.servlet.http.HttpServletRequest 实例。

Portlet：这必须是当前请求的 javax.portlet.PortletRequest 实例 ActionRequest 或 RenderRequest，具体取决于调用此方法的时间。

英文文档：

getRequest

public abstract Object getRequest()

Return the environment-specific object instance for the current request.

Servlet: This must be the current request's javax.servlet.http.HttpServletRequest instance.

Portlet: This must be the current request's javax.portlet.PortletRequest instance, which will be either an ActionRequest or a RenderRequest depending upon when this method is called.

public void setRequest(Object request)

设置后续调用 #getRequest 所返回的特定于环境的请求。此方法可以用来安装用于请求的包装器。

默认实现抛出 UnsupportedOperationException，提供它只有一个目的，即不破坏扩展此类的现有应用程序。

since

1.2

英文文档：

setRequest

public void setRequest(Object request)

Set the environment-specific request to be returned by subsequent calls to getRequest(). This may be used to install a wrapper for the request.

The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

Since:

1.2

public void setRequestCharacterEncoding(String encoding) throws java.io.UnsupportedEncodingException

重写在此请求的正文中使用的字符编码的名称。

访问请求之后调用此方法无效，除非已经从请求中获得了 Reader 或 Stream，这种情况下抛出 IllegalStateException。

Servlet：此方法必须接通 javax.servlet.ServletRequest 方法 setCharacterEncoding()。

Portlet： 此方法必须接通 javax.portlet.ActionRequest 方法 setCharacterEncoding()。

默认实现抛出 UnsupportedOperationException，提供它只有一个目的，即不破坏扩展此类的现有应用程序。

Throws	java.io.UnsupportedEncodingException: 如果这不是有效的编码
since	1.2

英文文档：

setRequestCharacterEncoding

public void setRequestCharacterEncoding(String encoding)
                                 throws UnsupportedEncodingException

Overrides the name of the character encoding used in the body of this request.

Calling this method after the request has been accessed will have no no effect, unless a Reader or Stream has been obtained from the request, in which case an IllegalStateException is thrown.

Servlet: This must call through to the javax.servlet.ServletRequest method setCharacterEncoding().

Portlet: This must call through to the javax.portlet.ActionRequest method setCharacterEncoding().

The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

Throws:

UnsupportedEncodingException - if this is not a valid encoding

Since:

1.2

abstract public String getRequestContextPath()

返回标识此请求的 Web 应用程序上下文的请求 URI 的一部分。

Servlet：这必须是 javax.servlet.http.HttpServletRequest 方法 getContextPath() 返回的值。

Portlet：这必须是 javax.portlet.PortletRequest 方法 getContextPath() 返回的值。

英文文档：

getRequestContextPath

public abstract String getRequestContextPath()

Return the portion of the request URI that identifies the web application context for this request.

Servlet: This must be the value returned by the javax.servlet.http.HttpServletRequest method getContextPath().

Portlet: This must be the value returned by the javax.portlet.PortletRequest method getContextPath().

abstract public java.util.Map<K, V> getRequestCookieMap()

返回一个不可变的 Map，其键是包含于当前请求的 cookie 名称集，其值（类型为 javax.servlet.http.Cookie）是第一个（或唯一一个）对应于底层请求所返回的每个 cookie 名称的 cookie。返回的 Map 必须实现不可修改映射的整个协定，这在 java.util.Map 的 JavaDoc 中有详细说明。

Servlet：这必须是 javax.servlet.http.HttpServletRequest 方法 getCookies() 返回的值，除非返回 null，这种情况下必须是长度为 0 的数组。

Portlet：这必须是空 Map。

英文文档：

getRequestCookieMap

public abstract Map<String,Object> getRequestCookieMap()

Return an immutable Map whose keys are the set of cookie names included in the current request, and whose values (of type javax.servlet.http.Cookie) are the first (or only) cookie for each cookie name returned by the underlying request. The returned Map must implement the entire contract for an unmodifiable map as described in the JavaDocs for java.util.Map.

Servlet: This must be the value returned by the javax.servlet.http.HttpServletRequest method getCookies(), unless null was returned, in which case this must be a zero-length array.

Portlet: Ths must be an empty Map.

abstract public java.util.Map<K, V> getRequestHeaderMap()

返回一个不可变的 Map，其键是包含于当前请求的请求头名称集，其值（类型为 String）是第一个（或唯一一个）对应于底层请求所返回的每个头名称的值。返回的 Map 必须实现不可修改映射的整个协定，这在 java.util.Map 的 JavaDoc 中有详细说明。此外，必须以大小写无关的方式执行键比较。

Servlet：这必须是通过 javax.servlet.http.HttpServletRequest 方法 getHeader() 和 getHeaderNames() 获得的头集合。

Portlet：这必须是通过 javax.portlet.PortletRequest 方法 getProperty() 和 getPropertyNames() 获得的属性集。因此，将仅包含 HTTP 头（如果 portlet 容器提供了头）和 portlet 容器提供的其他属性。

英文文档：

getRequestHeaderMap

public abstract Map<String,String> getRequestHeaderMap()

Return an immutable Map whose keys are the set of request header names included in the current request, and whose values (of type String) are the first (or only) value for each header name returned by the underlying request. The returned Map must implement the entire contract for an unmodifiable map as described in the JavaDocs for java.util.Map. In addition, key comparisons must be performed in a case insensitive manner.

Servlet: This must be the set of headers available via the javax.servlet.http.HttpServletRequest methods getHeader() and getHeaderNames().

Portlet: This must be the set of properties available via the javax.portlet.PortletRequest methods getProperty() and getPropertyNames(). As such, HTTP headers will only be included if they were provided by the portlet container, and additional properties provided by the portlet container may also be included.

abstract public java.util.Map<K, V> getRequestHeaderValuesMap()

返回一个不可变的 Map，其键是包含于当前请求的请求头名称集，其值（类型为 String[]）是对应于底层请求所返回的每个头名称的所有值。返回的 Map 必须实现不可修改映射的整个协定，这在 java.util.Map 的 JavaDoc 中有详细说明。此外，必须以大小写无关的方式执行键比较。

Servlet：这必须是通过 javax.servlet.http.HttpServletRequest 方法 getHeaders() 和 getHeaderNames() 获得的头集合。

Portlet：这必须是通过 javax.portlet.PortletRequest 方法 getProperties() 和 getPropertyNames() 获得的属性集。因此，将仅包含 HTTP 头（如果 portlet 容器提供了头）和 portlet 容器提供的其他属性。

英文文档：

getRequestHeaderValuesMap

public abstract Map<String,String[]> getRequestHeaderValuesMap()

Return an immutable Map whose keys are the set of request header names included in the current request, and whose values (of type String[]) are all of the value for each header name returned by the underlying request. The returned Map must implement the entire contract for an unmodifiable map as described in the JavaDocs for java.util.Map. In addition, key comparisons must be performed in a case insensitive manner.

Servlet: This must be the set of headers available via the javax.servlet.http.HttpServletRequest methods getHeaders() and getHeaderNames().

Portlet: This must be the set of properties available via the javax.portlet.PortletRequest methods getProperties() and getPropertyNames(). As such, HTTP headers will only be included if they were provided by the portlet container, and additional properties provided by the portlet container may also be included.

abstract public java.util.Locale getRequestLocale()

返回客户端将用于接收内容的首选 Locale。

Servlet：这必须是 javax.servlet.ServletRequest 方法 getLocale() 返回的值。

Portlet：这必须是 javax.portlet.PortletRequest 方法 getLocale() 返回的值。

英文文档：

getRequestLocale

public abstract Locale getRequestLocale()

Return the preferred Locale in which the client will accept content.

Servlet: This must be the value returned by the javax.servlet.ServletRequest method getLocale().

Portlet: This must be the value returned by the javax.portlet.PortletRequest method getLocale().

abstract public java.util.Iterator<E> getRequestLocales()

返回迭代请求中指定首选 Locale 的 Iterator，以递减顺序对首选项进行排序。

Servlet：这必须是一个迭代 javax.servlet.ServletRequest 方法 getLocales() 所返回值的 Iterator。

Portlet：这必须是一个迭代 javax.portlet.PortletRequest 方法 getLocales() 所返回值的 Iterator。

英文文档：

getRequestLocales

public abstract Iterator<Locale> getRequestLocales()

Return an Iterator over the preferred Locales specified in the request, in decreasing order of preference.

Servlet: This must be an Iterator over the values returned by the javax.servlet.ServletRequest method getLocales().

Portlet: This must be an Iterator over the values returned by the javax.portlet.PortletRequest method getLocales().

abstract public java.util.Map<K, V> getRequestMap()

返回一个可变的 Map，它代表当前应用程序的请求作用域属性。返回的 Map 必须实现可修改映射的整个协定，这在 java.util.Map 的 JavaDoc 中有详细说明。在 Map 中所进行的修改一定会导致在请求作用域属性集中进行相应更改。特别是 clear()、remove()、put()、putAll() 和 get() 操作必须对底层数据库结构采取相应的操作。

对于任何导致元素从底层数据结构中删除的 Map 方法，必须采取以下与托管 Bean 有关的操作。如果移除的元素是托管 Bean，并且它有一个或多个使用 javax.annotation.PreDestroy 注释的公共无参数 void 返回方法，则从底层数据结构移除该元素前，必须调用所有这些方法。对于非托管 Bean，但恰好含有使用该注释的方法的元素，移除时不得调用这些方法。PreDestroy 注释的方法所抛出的任何异常都必须被捕获并重新抛出。可以记录异常。

Servlet：这必须是通过 javax.servlet.ServletRequest 方法 getAttribute()、getAttributeNames()、removeAttribute() 和 setAttribute() 获得的属性集。

Portlet：这必须是通过 javax.portlet.PortletRequest 方法 getAttribute()、getAttributeNames()、removeAttribute() 和 setAttribute() 获得的属性集。

英文文档：

getRequestMap

public abstract Map<String,Object> getRequestMap()

Return a mutable Map representing the request scope attributes for the current application. The returned Map must implement the entire contract for a modifiable map as described in the JavaDocs for java.util.Map. Modifications made in the Map must cause the corresponding changes in the set of request scope attributes. Particularly the clear(), remove(), put(), putAll(), and get() operations must take the appropriate action on the underlying data structure.

For any of the Map methods that cause an element to be removed from the underlying data structure, the following action regarding managed-beans must be taken. If the element to be removed is a managed-bean, and it has one or more public no-argument void return methods annotated with javax.annotation.PreDestroy, each such method must be called before the element is removed from the underlying data structure. Elements that are not managed-beans, but do happen to have methods with that annotation must not have those methods called on removal. Any exception thrown by the PreDestroy annotated methods must by caught and not rethrown. The exception may be logged.

Servlet: This must be the set of attributes available via the javax.servlet.ServletRequest methods getAttribute(), getAttributeNames(), removeAttribute(), and setAttribute().

Portlet: This must be the set of attributes available via the javax.portlet.PortletRequest methods getAttribute(), getAttributeNames(), removeAttribute(), and setAttribute().

abstract public java.util.Map<K, V> getRequestParameterMap()

返回一个不可变的 Map，其键是包含于当前请求的请求参数名称集，其值（类型为 String）是第一个（或唯一一个）对应于底层请求所返回的每个参数名称的值。返回的 Map 必须实现不可修改映射的整个协定，这在 java.util.Map 的 JavaDoc 中有详细说明。

Servlet：这必须是通过 javax.servlet.ServletRequest 方法 getParameter() 和 getParameterNames() 获得的参数集。

Portlet：这必须是通过 javax.portlet.PortletRequest 方法 getParameter() 和 getParameterNames() 获得的参数集。

英文文档：

getRequestParameterMap

public abstract Map<String,String> getRequestParameterMap()

Return an immutable Map whose keys are the set of request parameters names included in the current request, and whose values (of type String) are the first (or only) value for each parameter name returned by the underlying request. The returned Map must implement the entire contract for an unmodifiable map as described in the JavaDocs for java.util.Map.

Servlet: This must be the set of parameters available via the javax.servlet.ServletRequest methods getParameter() and getParameterNames().

Portlet: This must be the set of parameters available via the javax.portlet.PortletRequest methods getParameter() and getParameterNames().

abstract public java.util.Iterator<E> getRequestParameterNames()

返回迭代当前请求中所含所有请求参数名称的 Iterator。

Servlet：这必须是一个迭代 javax.servlet.ServletRequest 方法 getParameterNames() 所返回值的 Iterator。

Portlet：这必须是一个迭代 javax.portlet.PortletRequest 方法 getParameterNames() 所返回值的 Iterator。

英文文档：

getRequestParameterNames

public abstract Iterator<String> getRequestParameterNames()

Return an Iterator over the names of all request parameters included in the current request.

Servlet: This must be an Iterator over the values returned by the javax.servlet.ServletRequest method getParameterNames().

Portlet: This must be an Iterator over the values returned by the javax.portlet.PortletRequest method getParameterNames().

abstract public java.util.Map<K, V> getRequestParameterValuesMap()

返回一个不可变的 Map，其键是包含于当前请求的请求参数名称集，其值（类型为 String[]）是对应于底层请求所返回的每个参数名称的所有值。返回的 Map 必须实现不可修改映射的整个协定，这在 java.util.Map 的 JavaDoc 中有详细说明。

Servlet：这必须是通过 javax.servlet.ServletRequest 方法 getParameterValues() 和 getParameterNames() 获得的参数集。

Portlet：这必须是通过 javax.portlet.PortletRequest 方法 getParameterValues() 和 getParameterNames() 获得的参数集。

英文文档：

getRequestParameterValuesMap

public abstract Map<String,String[]> getRequestParameterValuesMap()

Return an immutable Map whose keys are the set of request parameters names included in the current request, and whose values (of type String[]) are all of the values for each parameter name returned by the underlying request. The returned Map must implement the entire contract for an unmodifiable map as described in the JavaDocs for java.util.Map.

Servlet: This must be the set of parameters available via the javax.servlet.ServletRequest methods getParameterValues() and getParameterNames().

Portlet: This must be the set of parameters available via the javax.portlet.PortletRequest methods getParameterValues() and getParameterNames().

abstract public String getRequestPathInfo()

返回包含于请求 URI 的额外路径信息（如果有）；否则返回 null。

Servlet：这必须是 javax.servlet.http.HttpServletRequest 方法 getPathInfo() 返回的值。

Portlet：这必须为 null。

英文文档：

getRequestPathInfo

public abstract String getRequestPathInfo()

Return the extra path information (if any) included in the request URI; otherwise, return null.

Servlet: This must be the value returned by the javax.servlet.http.HttpServletRequest method getPathInfo().

Portlet: This must be null.

abstract public String getRequestServletPath()

返回包含于请求 URI 的 servlet 路径信息（如果有）；否则返回 null。

Servlet：这必须是 javax.servlet.http.HttpServletRequest 方法 getServletPath() 返回的值。

Portlet：这必须为 null。

英文文档：

getRequestServletPath

public abstract String getRequestServletPath()

Return the servlet path information (if any) included in the request URI; otherwise, return null.

Servlet: This must be the value returned by the javax.servlet.http.HttpServletRequest method getServletPath().

Portlet: This must be null.

public String getRequestCharacterEncoding()

返回当前用来解释此请求的字符编码。

Servlet：此方法必须返回 javax.servlet.ServletRequest 方法 getCharacterEncoding() 返回的值。

Portlet：此方法必须返回 javax.portlet.ActionRequest 方法 getCharacterEncoding() 返回的值。

默认实现抛出 UnsupportedOperationException，提供它只有一个目的，即不破坏扩展此类的现有应用程序。

since

1.2

英文文档：

getRequestCharacterEncoding

public String getRequestCharacterEncoding()

Return the character encoding currently being used to interpret this request.

Servlet: This must return the value returned by the javax.servlet.ServletRequest method getCharacterEncoding().

Portlet: This must return the value returned by the javax.portlet.ActionRequest method getCharacterEncoding().

The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

Since:

1.2

public String getRequestContentType()

返回此请求的 MIME 内容类型。如果不可用，则返回 null。

Servlet：此方法必须返回 javax.servlet.ServletRequest 方法 getContentType() 返回的值。

Portlet：此方法必须返回 null。

默认实现抛出 UnsupportedOperationException，提供它只有一个目的，即不破坏扩展此类的现有应用程序。

since

1.2

英文文档：

getRequestContentType

public String getRequestContentType()

Return the MIME Content-Type for this request. If not available, return null.

Servlet: This must return the value returned by the javax.servlet.ServletRequest method getContentType().

Portlet: This must return null.

The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

Since:

1.2

public String getResponseCharacterEncoding()

返回用于此响应中发送的正文的字符编码（MIME 字符集）名称。

Servlet：此方法必须返回 javax.servlet.ServletResponse 方法 getCharacterEncoding() 返回的值。

Portlet：此方法必须返回 null。

默认实现抛出 UnsupportedOperationException，提供它只有一个目的，即不破坏扩展此类的现有应用程序。

since

1.2

英文文档：

getResponseCharacterEncoding

public String getResponseCharacterEncoding()

Returns the name of the character encoding (MIME charset) used for the body sent in this response.

Servlet: This must return the value returned by the javax.servlet.ServletResponse method getCharacterEncoding().

Portlet: This must return null.

The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

Since:

1.2

public String getResponseContentType()

返回此响应的 MIME 内容类型。如果不可用，则返回 null。

Servlet：此方法必须返回 javax.servlet.ServletResponse 方法 getContentType() 返回的值。

Portlet：此方法必须返回 null。

默认实现抛出 UnsupportedOperationException，提供它只有一个目的，即不破坏扩展此类的现有应用程序。

since

1.2

英文文档：

getResponseContentType

public String getResponseContentType()

Return the MIME Content-Type for this response. If not available, return null.

Servlet: This must return the value returned by the javax.servlet.ServletResponse method getContentType().

Portlet: This must return null.

The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

Since:

1.2

abstract public java.net.URL getResource(String path) throws java.net.MalformedURLException

返回映射到指定路径的应用程序资源的 URL（如果存在）；否则返回 null。

Servlet：这必须是 javax.servlet.ServletContext 方法 getResource(path) 返回的值。

Portlet：这必须是 javax.portlet.PortletContext 方法 getResource(path) 返回的值。

path	指向请求资源的路径，必须以斜杠 ("/") 字符开始
Throws	java.net.MalformedURLException: 如果指定路径的格式不正确
Throws	NullPointerException: 如果 path 为 null

英文文档：

getResource

public abstract URL getResource(String path)
                         throws MalformedURLException

Return a URL for the application resource mapped to the specified path, if it exists; otherwise, return null.

Servlet: This must be the value returned by the javax.servlet.ServletContext method getResource(path).

Portlet: This must be the value returned by the javax.portlet.PortletContext method getResource(path).

Parameters:

path - The path to the requested resource, which must start with a slash ("/" character

Throws:

MalformedURLException - if the specified path is not in the correct form

NullPointerException - if path is null

abstract public java.io.InputStream getResourceAsStream(String path)

返回映射到指定路径的应用程序资源的 InputStream（如果存在）；否则返回 null。

Servlet：这必须是 javax.servlet.ServletContext 方法 getResourceAsStream(path) 返回的值。

Portlet：这必须是 javax.portlet.PortletContext 方法 getResourceAsStream(path) 返回的值。

path	指向请求资源的路径，必须以斜杠 ("/") 字符开始
Throws	NullPointerException: 如果 path 为 null

英文文档：

getResourceAsStream

public abstract InputStream getResourceAsStream(String path)

Return an InputStream for an application resource mapped to the specified path, if it exists; otherwise, return null.

Servlet: This must be the value returned by the javax.servlet.ServletContext method getResourceAsStream(path).

Portlet: This must be the value returned by the javax.portlet.PortletContext method getResourceAsStream(path).

Parameters:

path - The path to the requested resource, which must start with a slash ("/" character

Throws:

NullPointerException - if path is null

abstract public java.util.Set<E> getResourcePaths(String path)

返回资源路径以指定参数开头的所有应用程序资源的资源路径所组成的 Set。

Servlet：这必须是 javax.servlet.ServletContext 方法 getResourcePaths(path) 返回的值。

Portlet：这必须是 javax.portlet.PortletContext 方法 getResourcePaths(path) 返回的值。

path	用于匹配资源的部分路径，必须以斜杠 ("/") 字符开头
Throws	NullPointerException: 如果 path 为 null

英文文档：

getResourcePaths

public abstract Set<String> getResourcePaths(String path)

Return the Set of resource paths for all application resources whose resource path starts with the specified argument.

Servlet: This must be the value returned by the javax.servlet.ServletContext method getResourcePaths(path).

Portlet: This must be the value returned by the javax.portlet.PortletContext method getResourcePaths(path).

Parameters:

path - Partial path used to match resources, which must start with a slash ("/") character

Throws:

NullPointerException - if path is null

abstract public Object getResponse()

返回当前响应的特定于环境的对象实例。

Servlet：这是当前请求的 javax.servlet.http.HttpServletResponse 实例。

Portlet：这是当前请求的 javax.portlet.PortletResponse 实例 ActionResponse 或 RenderResponse，具体取决于调用此方法的时间。

英文文档：

getResponse

public abstract Object getResponse()

Return the environment-specific object instance for the current response.

Servlet: This is the current request's javax.servlet.http.HttpServletResponse instance.

Portlet: This is the current request's javax.portlet.PortletResponse instance, which will be either an ActionResponse or a RenderResponse depending upon when this method is called.

public void setResponse(Object response)

设置后续调用 #getResponse 所返回的特定于环境的响应。此方法可以用于安装响应的包装器。

默认实现抛出 UnsupportedOperationException，提供它只有一个目的，即不破坏扩展此类的现有应用程序。

since

1.2

英文文档：

setResponse

public void setResponse(Object response)

Set the environment-specific response to be returned by subsequent calls to getResponse(). This may be used to install a wrapper for the response.

The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

Since:

1.2

public void setResponseCharacterEncoding(String encoding)

设置将发送到客户端的响应的字符编码（MIME 字符集），例如，设置为 UTF-8。

Servlet：此方法必须接通 javax.servlet.ServletResponse 方法 setCharacterEncoding()。

Portlet：此方法不得执行任何操作。

默认实现抛出 UnsupportedOperationException，提供它只有一个目的，即不破坏扩展此类的现有应用程序。

since

1.2

英文文档：

setResponseCharacterEncoding

public void setResponseCharacterEncoding(String encoding)

Sets the character encoding (MIME charset) of the response being sent to the client, for example, to UTF-8.

Servlet: This must call through to the javax.servlet.ServletResponse method setCharacterEncoding().

Portlet: This method must take no action.

The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

Since:

1.2

abstract public Object getSession(boolean create)

如果 create 参数为 true，则创建（如有必要）并返回一个与当前请求关联的会话实例。如果 create 参数为 false，则返回与当前请求关联的任何现有会话实例；如果没有这样的会话，则返回 null。

Servlet：此方法必须返回对底层 javax.servlet.http.HttpServletRequest 实例调用 getSession(create) 的结果。

Portlet：此方法必须返回对底层 javax.portlet.PortletRequest 实例调用 getPortletSession(create) 的结果。

create

指出没有会话与当前请求关联时是否应该创建一个新会话的标志。

英文文档：

getSession

public abstract Object getSession(boolean create)

If the create parameter is true, create (if necessary) and return a session instance associated with the current request. If the create parameter is false return any existing session instance associated with the current request, or return null if there is no such session.

Servlet: This must return the result of calling getSession(create) on the underlying javax.servlet.http.HttpServletRequest instance.

em>Portlet: This must return the result of calling getPortletSession(create) on the underlying javax.portlet.PortletRequest instance.

Parameters:

create - Flag indicating whether or not a new session should be created if there is no session associated with the current request

abstract public java.util.Map<K, V> getSessionMap()

返回一个可变的 Map，它代表当前应用程序的会话作用域属性。返回的 Map 必须实现可修改映射的整个协定，这在 java.util.Map 的 JavaDoc 中有详细说明。在 Map 中所进行的修改一定会导致在会话作用域属性集中进行相应更改。特别是 clear()、remove()、put() 和 get() 操作必须对底层数据库结构采取相应的操作。通过此 Map 访问属性必定导致创建与当前请求关联的会话（如果不存在这样的会话）。

对于任何导致元素从底层数据结构中删除的 Map 方法，必须采取以下与托管 Bean 有关的操作。如果移除的元素是托管 Bean，并且它有一个或多个使用 javax.annotation.PreDestroy 注释的公共无参数 void 返回方法，则从底层数据结构移除该元素前，必须调用所有这些方法。对于非托管 Bean，但恰好含有使用该注释的方法的元素，移除时不得调用这些方法。PreDestroy 注释的方法所抛出的任何异常都必须被捕获并重新抛出。可以记录异常。

Servlet：这必须是通过 javax.servlet.http.HttpServletSession 方法 getAttribute()、getAttributeNames()、removeAttribute() 和 setAttribute() 获得的属性集。

Portlet：这必须是通过 javax.portlet.PortletSession 方法 getAttribute()、getAttributeNames()、removeAttribute() 和 setAttribute() 获得的属性集。所有会话属性访问必须出现在会话的 PORTLET_SCOPE 作用域。

英文文档：

getSessionMap

public abstract Map<String,Object> getSessionMap()

Return a mutable Map representing the session scope attributes for the current application. The returned Map must implement the entire contract for a modifiable map as described in the JavaDocs for java.util.Map. Modifications made in the Map must cause the corresponding changes in the set of session scope attributes. Particularly the clear(), remove(), put(), and get() operations must take the appropriate action on the underlying data structure. Accessing attributes via this Map must cause the creation of a session associated with the current request, if such a session does not already exist.

For any of the Map methods that cause an element to be removed from the underlying data structure, the following action regarding managed-beans must be taken. If the element to be removed is a managed-bean, and it has one or more public no-argument void return methods annotated with javax.annotation.PreDestroy, each such method must be called before the element is removed from the underlying data structure. Elements that are not managed-beans, but do happen to have methods with that annotation must not have those methods called on removal. Any exception thrown by the PreDestroy annotated methods must by caught and not rethrown. The exception may be logged.

Servlet: This must be the set of attributes available via the javax.servlet.http.HttpServletSession methods getAttribute(), getAttributeNames(), removeAttribute(), and setAttribute().

Portlet: This must be the set of attributes available via the javax.portlet.PortletSession methods getAttribute(), getAttributeNames(), removeAttribute(), and setAttribute(). All session attribute access must occur in PORTLET_SCOPE scope within the session.

abstract public java.security.Principal getUserPrincipal()

返回包含当前验证的用户名称的 Principal 对象（如果有）；否则返回 null。

Servlet：这必须是 javax.servlet.http.HttpServletRequest 方法 getUserPrincipal() 返回的值。

Portlet：这必须是 javax.portlet.http.PortletRequest 方法 getUserPrincipal() 返回的值。

英文文档：

getUserPrincipal

public abstract Principal getUserPrincipal()

Return the Principal object containing the name of the current authenticated user, if any; otherwise, return null.

Servlet: This must be the value returned by the javax.servlet.http.HttpServletRequest method getUserPrincipal().

Portlet: This must be the value returned by the javax.portlet.http.PortletRequest method getUserPrincipal().

abstract public boolean isUserInRole(String role)

如果当前验证的用户包含在指定的角色中，则返回 true。否则返回 false。

Servlet：这必须是 javax.servlet.http.HttpServletRequest 方法 isUserInRole(role) 返回的值。

Portlet：这必须是 javax.portlet.http.PortletRequest 方法 isUserInRole(role) 返回的值。

role	要检查的逻辑角色名称
Throws	NullPointerException: 如果 role 为 null

英文文档：

isUserInRole

public abstract boolean isUserInRole(String role)

Return true if the currently authenticated user is included in the specified role. Otherwise, return false.

Servlet: This must be the value returned by the javax.servlet.http.HttpServletRequest method isUserInRole(role).

Portlet: This must be the value returned by the javax.portlet.http.PortletRequest method isUserInRole(role).

Parameters:

role - Logical role name to be checked

Throws:

NullPointerException - if role is null

abstract public void log(String message)

将指定的消息记录到应用程序对象。

Servlet：此方法必须通过调用 javax.servlet.ServletContext 方法 log(String) 来执行。

Portlet：此方法必须通过调用 javax.portlet.PortletContext 方法 log(String) 来执行。

message	要记录的消息
Throws	NullPointerException: 如果 message 为 null

英文文档：

log

public abstract void log(String message)

Log the specified message to the application object.

Servlet: This must be performed by calling the javax.servlet.ServletContext method log(String).

Portlet: This must be performed by calling the javax.portlet.PortletContext method log(String).

Parameters:

message - Message to be logged

Throws:

NullPointerException - if message is null

abstract public void log(String message, Throwable exception)

将指定的消息和异常记录到应用程序对象。

Servlet：此方法必须通过调用 javax.servlet.ServletContext 方法 log(String,Throwable) 来执行。

Portlet：此方法必须通过调用 javax.portlet.PortletContext 方法 log(String,Throwable) 来执行。

message	要记录的消息
exception	要记录的异常
Throws	NullPointerException: 如果 message 或 exception 为 null

英文文档：

log

public abstract void log(String message,
                         Throwable exception)

Log the specified message and exception to the application object.

Servlet: This must be performed by calling the javax.servlet.ServletContext method log(String,Throwable).

Portlet: This must be performed by calling the javax.portlet.PortletContext method log(String,Throwable).

Parameters:

message - Message to be logged

exception - Exception to be logged

Throws:

NullPointerException - if message or exception is null

abstract public void redirect(String url) throws java.io.IOException

将请求重定向到指定的 URL，并导致对当前请求的 FacesContext 实例调用 responseComplete() 方法。

Servlet：此方法必须通过调用 javax.servlet.http.HttpServletResponse 方法 sendRedirect() 来完成。

Portlet：此方法必须通过调用 javax.portlet.ActionResponse 方法 sendRedirect() 来完成。

url	客户端应该重定向到的绝对 URL
Throws	IllegalArgumentException: 如果指定的 url 是相对的
Throws	IllegalStateException: 如果当前对象是 RenderResponse，而不是 ActionResponse（在 portlet 环境中）
Throws	IllegalStateException: 如果当前响应已被提交（在 servlet 环境中）
Throws	java.io.IOException: 如果发生输入/输出错误

英文文档：

redirect

public abstract void redirect(String url)
                       throws IOException

Redirect a request to the specified URL, and cause the responseComplete() method to be called on the FacesContext instance for the current request.

Servlet: This must be accomplished by calling the javax.servlet.http.HttpServletResponse method sendRedirect().

Portlet: This must be accomplished by calling the javax.portlet.ActionResponse method sendRedirect().

Parameters:

url - Absolute URL to which the client should be redirected

Throws:

IllegalArgumentException - if the specified url is relative

IllegalStateException - if, in a portlet environment, the current response object is a RenderResponse instead of an ActionResponse

IllegalStateException - if, in a servlet environment, the current response has already been committed

IOException - if an input/output error occurs

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