FacesContext (Java EE 5)

FacesContext 包含与单个 JavaServer Faces 请求的处理以及相应响应的呈现相关的所有每个请求的状态信息。它传递给请求处理生命周期的每个阶段，并且可能被修改。

在请求处理的初始阶段，通过调用与当前 Web 应用程序关联的 FacesContextFactory 实例的 getFacesContext() 方法，可以将 FacesContext 实例与特定请求相关联。在调用其 release() 方法之前，该实例将一直保持活动状态，调用该方法之后将不能再引用此实例。当 FacesContext 实例处于活动状态时，只能从执行此 Web 应用程序的 servlet 容器用来处理此请求的线程中引用该实例。

FacesContext contains all of the per-request state information related to the processing of a single JavaServer Faces request, and the rendering of the corresponding response. It is passed to, and potentially modified by, each phase of the request processing lifecycle.

A FacesContext instance is associated with a particular request at the beginning of request processing, by a call to the getFacesContext() method of the FacesContextFactory instance associated with the current web application. The instance remains active until its release() method is called, after which no further references to this instance are allowed. While a FacesContext instance is active, it must not be referenced from any thread other than the one upon which the servlet container executing this web application utilizes for the processing of this request.

public FacesContext()

英文文档：

FacesContext

public FacesContext()

abstract public Application getApplication()

返回与此 Web 应用程序关联的 Application 实例。

Throws

IllegalStateException: 如果释放此实例后调用此方法

英文文档：

getApplication

public abstract Application getApplication()

Return the Application instance associated with this web application.

Throws:

IllegalStateException - if this method is called after this instance has been released

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

返回一个迭代客户端标识符（至少有一个 javax.faces.application.FacesMessage 加入其队列）的 Iterator。如果不存在这样的客户端标识符，则返回一个空的 Iterator。如果与任何特定客户端标识符无关联的消息加入了队列，则迭代值中将包含一个 null 值。Iterator 中的元素必须按照使用 #addMessage 添加的顺序返回。

Throws

IllegalStateException: 如果释放此实例后调用此方法

英文文档：

getClientIdsWithMessages

public abstract Iterator<String> getClientIdsWithMessages()

Return an Iterator over the client identifiers for which at least one FacesMessage has been queued. If there are no such client identifiers, an empty Iterator is returned. If any messages have been queued that were not associated with any specific client identifier, a null value will be included in the iterated values. The elements in the Iterator must be returned in the order in which they were added with addMessage(java.lang.String, javax.faces.application.FacesMessage).

Throws:

IllegalStateException - if this method is called after this instance has been released

public ELContext getELContext()

返回此 FacesContext 实例的 ELContext 实例。此 ELContext 实例与其关联的 FacesContext 实例具有相同的生命周期和作用域，可以在第一次对给定 FacesContext 实例调用此方法时以延迟方式创建该实例。创建 ELContext 实例时，实现必须执行以下操作：

• 对实例调用 ELContext#putContext 方法，传入 FacesContext.class 以及对 FacesContext 实例本身的 this 引用。

• 如果 javax.faces.application.Application#getELContextListeners 返回的 Collection 非空，则创建 javax.el.ELContextEvent 的一个实例并通过调用 javax.el.ELContextListener#contextCreated 方法将其传递给 Collection 中的每个 javax.el.ELContextListener 实例。

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

Throws	IllegalStateException: 如果释放此实例后调用此方法
since	1.2

英文文档：

getELContext

public ELContext getELContext()

Return the ELContext instance for this FacesContext instance. This ELContext instance has the same lifetime and scope as the FacesContext instance with which it is associated, and may be created lazily the first time this method is called for a given FacesContext instance. Upon creation of the ELContext instance, the implementation must take the following action:

• Call the ELContext.putContext(java.lang.Class, java.lang.Object) method on the instance, passing in FacesContext.class and the this reference for the FacesContext instance itself.

• If the Collection returned by Application.getELContextListeners() is non-empty, create an instance of ELContextEvent and pass it to each ELContextListener instance in the Collection by calling the ELContextListener.contextCreated(javax.el.ELContextEvent) method.

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

Throws:

IllegalStateException - if this method is called after this instance has been released

Since:

1.2

abstract public ExternalContext getExternalContext()

返回此 FacesContext 实例的 ExternalContext 实例。

Throws

IllegalStateException: 如果释放此实例后调用此方法

英文文档：

getExternalContext

public abstract ExternalContext getExternalContext()

Return the ExternalContext instance for this FacesContext instance.

Throws:

IllegalStateException - if this method is called after this instance has been released

abstract public FacesMessage.Severity getMaximumSeverity()

返回已加入队列的所有 javax.faces.application.FacesMessage（无论它们是否与某个特定的 UIComponent 关联）上记录的最大严重性级别。如果队列中不存在这样的消息，则返回 null。

Throws

IllegalStateException: 如果释放此实例后调用此方法

英文文档：

getMaximumSeverity

public abstract FacesMessage.Severity getMaximumSeverity()

Return the maximum severity level recorded on any FacesMessages that has been queued, whether or not they are associated with any specific UIComponent. If no such messages have been queued, return null.

Throws:

IllegalStateException - if this method is called after this instance has been released

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

返回迭代已加入队列的 javax.faces.application.FacesMessage（无论它们是否与某个特定的客户端标识符关联）的 Iterator。如果队列中不存在这样的消息，则返回空 Iterator。Iterator 的元素必须按照使用 #addMessage 调用添加的顺序返回。

Throws

IllegalStateException: 如果释放此实例后调用此方法

英文文档：

getMessages

public abstract Iterator<FacesMessage> getMessages()

Return an Iterator over the FacesMessages that have been queued, whether or not they are associated with any specific client identifier. If no such messages have been queued, return an empty Iterator. The elements of the Iterator must be returned in the order in which they were added with calls to addMessage(java.lang.String, javax.faces.application.FacesMessage).

Throws:

IllegalStateException - if this method is called after this instance has been released

abstract public java.util.Iterator<E> getMessages(String clientId)

返回迭代已经加入队列且与指定客户端标识符关联（如果 clientId 不为 null）的 javax.faces.application.FacesMessage，或者迭代已经加入队列且不与任何特定客户端标识符关联（如果 clientId 为 null）的 javax.faces.application.FacesMessage 的 Iterator。如果队列中不存在这样的消息，则返回空 Iterator。Iterator 的元素必须按照使用 #addMessage 调用添加的顺序返回。

clientId	请求的消息的客户端标识符；如果消息不与任何客户端标识符关联，则为 null
Throws	IllegalStateException: 如果释放此实例后调用此方法

英文文档：

getMessages

public abstract Iterator<FacesMessage> getMessages(String clientId)

Return an Iterator over the FacesMessages that have been queued that are associated with the specified client identifier (if clientId is not null), or over the FacesMessages that have been queued that are not associated with any specific client identifier (if clientId is null). If no such messages have been queued, return an empty Iterator. The elements of the Iterator must be returned in the order in which they were added with calls to addMessage(java.lang.String, javax.faces.application.FacesMessage).

Parameters:

clientId - The client identifier for which messages are requested, or null for messages not associated with any client identifier

Throws:

IllegalStateException - if this method is called after this instance has been released

abstract public RenderKit getRenderKit()

返回在我们的 UIViewRoot 上指定的呈现工具包标识符的 RenderKit 实例（如果有）。如果没有当前的 UIViewRoot，或者 UIViewRoot 没有指定的 renderKitId，或者指定的标识符没有 RenderKit，则返回 null。

英文文档：

getRenderKit

public abstract RenderKit getRenderKit()

Return the RenderKit instance for the render kit identifier specified on our UIViewRoot, if there is one. If there is no current UIViewRoot, if the UIViewRoot does not have a specified renderKitId, or if there is no RenderKit for the specified identifier, return null instead.

abstract public boolean getRenderResponse()

如果已经对当前请求调用了 renderResponse() 方法，则返回 true。

Throws

IllegalStateException: 如果释放此实例后调用此方法

英文文档：

getRenderResponse

public abstract boolean getRenderResponse()

Return true if the renderResponse() method has been called for the current request.

Throws:

IllegalStateException - if this method is called after this instance has been released

abstract public boolean getResponseComplete()

如果已经对当前请求调用了 responseComplete() 方法，则返回 true。

Throws

IllegalStateException: 如果释放此实例后调用此方法

英文文档：

getResponseComplete

public abstract boolean getResponseComplete()

Return true if the responseComplete() method has been called for the current request.

Throws:

IllegalStateException - if this method is called after this instance has been released

abstract public ResponseStream getResponseStream()

返回应该接收组件二进制输出的 ResponseStream。在给定的响应中，组件可以使用 ResponseStream 或 ResponseWriter，但不能同时使用两者。

Throws

IllegalStateException: 如果释放此实例后调用此方法

英文文档：

getResponseStream

public abstract ResponseStream getResponseStream()

Return the ResponseStream to which components should direct their binary output. Within a given response, components can use either the ResponseStream or the ResponseWriter, but not both.

Throws:

IllegalStateException - if this method is called after this instance has been released

abstract public void setResponseStream(ResponseStream responseStream)

设置应该接收组件二进制输出的 ResponseStream。

responseStream	此响应的新 ResponseStream
Throws	NullPointerException: 如果 responseStream 为 null
Throws	IllegalStateException: 如果释放此实例后调用此方法

英文文档：

setResponseStream

public abstract void setResponseStream(ResponseStream responseStream)

Set the ResponseStream to which components should direct their binary output.

Parameters:

responseStream - The new ResponseStream for this response

Throws:

NullPointerException - if responseStream is null

IllegalStateException - if this method is called after this instance has been released

abstract public ResponseWriter getResponseWriter()

返回应该接收组件基于字符的输出的 ResponseWriter。在给定的响应中，组件可以使用 ResponseStream 或 ResponseWriter，但不能同时使用两者。

Throws

IllegalStateException: 如果释放此实例后调用此方法

英文文档：

getResponseWriter

public abstract ResponseWriter getResponseWriter()

Return the ResponseWriter to which components should direct their character-based output. Within a given response, components can use either the ResponseStream or the ResponseWriter, but not both.

Throws:

IllegalStateException - if this method is called after this instance has been released

abstract public void setResponseWriter(ResponseWriter responseWriter)

设置应该接收组件基于字符的输出的 ResponseWriter。

responseWriter	此响应的新 ResponseWriter
Throws	IllegalStateException: 如果释放此实例后调用此方法
Throws	NullPointerException: 如果 responseWriter 为 null

英文文档：

setResponseWriter

public abstract void setResponseWriter(ResponseWriter responseWriter)

Set the ResponseWriter to which components should direct their character-based output.

Parameters:

responseWriter - The new ResponseWriter for this response

Throws:

IllegalStateException - if this method is called after this instance has been released

NullPointerException - if responseWriter is null

abstract public UIViewRoot getViewRoot()

返回与此请求关联的根组件。

Throws

IllegalStateException: 如果释放此实例后调用此方法

英文文档：

getViewRoot

public abstract UIViewRoot getViewRoot()

Return the root component that is associated with the this request.

Throws:

IllegalStateException - if this method is called after this instance has been released

abstract public void setViewRoot(UIViewRoot root)

设置与此请求关联的根组件。此方法只能由应用程序处理程序（或处理程序调用的类）在请求处理生命周期的调用应用程序 阶段调用。

root	新的 UIViewRoot 组件
Throws	IllegalStateException: 如果释放此实例后调用此方法
Throws	NullPointerException: 如果 root 为 null

英文文档：

setViewRoot

public abstract void setViewRoot(UIViewRoot root)

Set the root component that is associated with this request. This method can only be called by the application handler (or a class that the handler calls), and only during the Invoke Application phase of the request processing lifecycle.

Parameters:

root - The new component UIViewRoot component

Throws:

IllegalStateException - if this method is called after this instance has been released

NullPointerException - if root is null

abstract public void addMessage(String clientId, FacesMessage message)

如果 clientId 不为 null，则向与指定客户端标识符关联的消息集添加一个 javax.faces.application.FacesMessage。如果 clientId 为 null，则认为此 javax.faces.application.FacesMessage 不与任何特定组件实例关联。

clientId	与此消息关联的客户端标识符（如果有）
message	将添加的消息
Throws	IllegalStateException: 如果释放此实例后调用此方法
Throws	NullPointerException: 如果 message 为 null

英文文档：

addMessage

public abstract void addMessage(String clientId,
                                FacesMessage message)

Append a FacesMessage to the set of messages associated with the specified client identifier, if clientId is not null. If clientId is null, this FacesMessage is assumed to not be associated with any specific component instance.

Parameters:

clientId - The client identifier with which this message is associated (if any)

message - The message to be appended

Throws:

IllegalStateException - if this method is called after this instance has been released

NullPointerException - if message is null

abstract public void release()

释放与此 FacesContext 实例关联的所有资源。Faces 实现可以选择在关联的 FacesContextFactory 中将实例入池，以避免重复创建对象和垃圾回收。对 FacesContext 实例调用 release() 之后（直到实现回收 FacesContext 实例以便重复使用时），调用任何其他方法将导致抛出 IllegalStateException。

实现必须调用 #setCurrentInstance 并传递 null，以移除此线程和此停用的 FacesContext 实例之间的关联。

Throws

IllegalStateException: 如果释放此实例后调用此方法

英文文档：

release

public abstract void release()

Release any resources associated with this FacesContext instance. Faces implementations may choose to pool instances in the associated FacesContextFactory to avoid repeated object creation and garbage collection. After release() is called on a FacesContext instance (until the FacesContext instance has been recycled by the implementation for re-use), calling any other methods will cause an IllegalStateException to be thrown.

The implementation must call setCurrentInstance(javax.faces.context.FacesContext) passing null to remove the association between this thread and this dead FacesContext instance.

Throws:

IllegalStateException - if this method is called after this instance has been released

abstract public void renderResponse()

通知 JavaServer faces 实现，完成请求处理生命周期的当前阶段后，应该立即进入呈现响应 阶段，忽略尚未执行的任何阶段。

Throws

IllegalStateException: 如果释放此实例后调用此方法

英文文档：

renderResponse

public abstract void renderResponse()

Signal the JavaServer faces implementation that, as soon as the current phase of the request processing lifecycle has been completed, control should be passed to the Render Response phase, bypassing any phases that have not been executed yet.

Throws:

IllegalStateException - if this method is called after this instance has been released

abstract public void responseComplete()

通知 JavaServer Faces 实现，已经生成了此请求的 HTTP 响应（如 HTTP 重定向），完成当前阶段后，应该立即终止请求处理生命周期。

Throws

IllegalStateException: 如果释放此实例后调用此方法

英文文档：

responseComplete

public abstract void responseComplete()

Signal the JavaServer Faces implementation that the HTTP response for this request has already been generated (such as an HTTP redirect), and that the request processing lifecycle should be terminated as soon as the current phase is completed.

Throws:

IllegalStateException - if this method is called after this instance has been released

public static FacesContext getCurrentInstance()

返回当前线程正在处理的请求的 FacesContext 实例（如果有）。

英文文档：

getCurrentInstance

public static FacesContext getCurrentInstance()

Return the FacesContext instance for the request that is being processed by the current thread, if any.

protected static void setCurrentInstance(FacesContext context)

设置当前线程正在处理的请求的 FacesContext 实例。

context

当前线程的 FacesContext 实例；如果此线程不再拥有 FacesContext 实例，则为 null。

英文文档：

setCurrentInstance

protected static void setCurrentInstance(FacesContext context)

Set the FacesContext instance for the request that is being processed by the current thread.

Parameters:

context - The FacesContext instance for the current thread, or null if this thread no longer has a FacesContext instance.

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