UIViewRoot (Java EE 5)

UIViewRoot 是表示 UIComponent 树的根的 UIComponent。此组件没有呈现，它仅作为组件树的根，并作为挂起每个视图 PhaseListener 的地方。

对于下面每个生命周期阶段方法：

• #processDecodes

• #processValidators

• #processUpdates

• #processApplication

• RenderResponse（通过 #encodeBegin 和 #encodeEnd 调用）

采取以下与 PhaseListener 有关的操作。

将状态标志初始化为 false。

如果 #getBeforePhaseListener 返回非 null，则调用该侦听器，同时传入正确的此阶段相应的 PhaseId。

从该侦听器返回时，调用 FacesContext#getResponseComplete 和 FacesContext#getRenderResponse。如果返回 true，则将内部状态标志设置为 true。

如果已通过调用 #addPhaseListener 添加了一个或多个侦听器，则调用其 PhaseListener#getPhaseId 匹配当前 phaseId 的每个侦听器上的 beforePhase 方法，同时传入与上一个步骤中相同的 PhaseId。

从每个侦听器返回时，调用 FacesContext#getResponseComplete 和 FacesContext#getRenderResponse。如果返回 true，则将内部状态标志设置为 true。

如果未设置内部状态标志，则执行此阶段的任何处理。

如果 #getAfterPhaseListener 返回非 null，则调用该侦听器，同时传入正确的此阶段相应的 PhaseId。

如果已通过调用 #addPhaseListener 添加了一个或多个侦听器，则调用其 PhaseListener#getPhaseId 匹配当前 phaseId 的每个侦听器上的 afterPhase 方法，同时传入与上一个步骤中相同的 PhaseId。

UIViewRoot is the UIComponent that represents the root of the UIComponent tree. This component has no rendering, it just serves as the root of the component tree, and as a place to hang per-view PhaseListeners.

For each of the following lifecycle phase methods:

• processDecodes(javax.faces.context.FacesContext)

• processValidators(javax.faces.context.FacesContext)

• processUpdates(javax.faces.context.FacesContext)

• processApplication(javax.faces.context.FacesContext)

• RenderResponse, via encodeBegin(javax.faces.context.FacesContext) and encodeEnd(javax.faces.context.FacesContext)

Take the following action regarding PhaseListeners.

Initialize a state flag to false.

If getBeforePhaseListener() returns non-null, invoke the listener, passing in the correct corresponding PhaseId for this phase.

Upon return from the listener, call FacesContext.getResponseComplete() and FacesContext.getRenderResponse(). If either return true set the internal state flag to true.

If or one or more listeners have been added by a call to addPhaseListener(javax.faces.event.PhaseListener), invoke the beforePhase method on each one whose PhaseListener.getPhaseId() matches the current phaseId, passing in the same PhaseId as in the previous step.

Upon return from each listener, call FacesContext.getResponseComplete() and FacesContext.getRenderResponse(). If either return true set the internal state flag to true.

Execute any processing for this phase if the internal state flag was not set.

If getAfterPhaseListener() returns non-null, invoke the listener, passing in the correct corresponding PhaseId for this phase.

If or one or more listeners have been added by a call to addPhaseListener(javax.faces.event.PhaseListener), invoke the afterPhase method on each one whose PhaseListener.getPhaseId() matches the current phaseId, passing in the same PhaseId as in the previous step.

英文文档：

COMPONENT_TYPE

public static final String COMPONENT_TYPE

The standard component type for this component.

See Also:

Constant Field Values

英文文档：

COMPONENT_FAMILY

public static final String COMPONENT_FAMILY

The standard component family for this component.

See Also:

Constant Field Values

英文文档：

UNIQUE_ID_PREFIX

public static final String UNIQUE_ID_PREFIX

The prefix that will be used for identifiers generated by the createUniqueId() method.

See Also:

Constant Field Values

public UIViewRoot()

使用默认属性值创建新的 UIViewRoot 实例。

英文文档：

UIViewRoot

public UIViewRoot()

Create a new UIViewRoot instance with default property values.

public String getFamily()

英文文档：

getFamily

public String getFamily()

Description copied from class: UIComponent

Return the identifier of the component family to which this component belongs. This identifier, in conjunction with the value of the rendererType property, may be used to select the appropriate Renderer for this component instance.

Specified by:

getFamily in class UIComponent

public String getRenderKitId()

返回与此视图关联的 RenderKit 的呈现工具包标识符。除非显式设置（如在 javax.faces.application.ViewHandler#createView 中），否则返回的值将为 null。

英文文档：

getRenderKitId

public String getRenderKitId()

Return the render kit identifier of the RenderKit associated with this view. Unless explicitly set, as in ViewHandler.createView(javax.faces.context.FacesContext, java.lang.String), the returned value will be null.

public void setRenderKitId(String renderKitId)

设置与此视图关联的 RenderKit 的呈现工具包标识符。可以随时在请求处理生命周期的应用请求值 阶段的末尾（即事件被广播时）和呈现响应 阶段的开始之间调用此方法。

renderKitId

新的 RenderKit 标识符，或为 null 以取消此视图与任何特定 RenderKit 实例的关联

英文文档：

setRenderKitId

public void setRenderKitId(String renderKitId)

Set the render kit identifier of the RenderKit associated with this view. This method may be called at any time between the end of Apply Request Values phase of the request processing lifecycle (i.e. when events are being broadcast) and the beginning of the Render Response phase.

Parameters:

renderKitId - The new RenderKit identifier, or null to disassociate this view with any specific RenderKit instance

public String getViewId()

返回此视图的视图标识符。

英文文档：

getViewId

public String getViewId()

Return the view identifier for this view.

public void setViewId(String viewId)

设置此视图的视图标识符。

viewId

新的视图标识符

英文文档：

setViewId

public void setViewId(String viewId)

Set the view identifier for this view.

Parameters:

viewId - The new view identifier

public MethodExpression getBeforePhaseListener()

return

在呈现此视图前将调用的 MethodExpression。

英文文档：

getBeforePhaseListener

public MethodExpression getBeforePhaseListener()

Returns:

the MethodExpression that will be invoked before this view is rendered.

public void setBeforePhaseListener(MethodExpression newBeforePhase)

当 UIViewRoot 在其生命周期中运行时，允许为 "beforePhase" 事件调用任意方法。将为所有除 PhaseId#RESTORE_VIEW 以外的阶段调用此方法。与实际的 PhaseListener 不同，此方法不允许仅为给定的阶段接收 PhaseEvent。

此方法必须符合 PhaseListener#beforePhase 的签名。

newBeforePhase

在呈现此视图前将调用的 MethodExpression。

英文文档：

setBeforePhaseListener

public void setBeforePhaseListener(MethodExpression newBeforePhase)

Allow an arbitrary method to be called for the "beforePhase" event as the UIViewRoot runs through its lifecycle. This method will be called for all phases except PhaseId.RESTORE_VIEW. Unlike a true PhaseListener, this approach doesn't allow for only receiving PhaseEvents for a given phase.

The method must conform to the signature of PhaseListener.beforePhase(javax.faces.event.PhaseEvent).

Parameters:

newBeforePhase - the MethodExpression that will be invoked before this view is rendered.

public MethodExpression getAfterPhaseListener()

return

在呈现此视图后将调用的 MethodExpression。

英文文档：

getAfterPhaseListener

public MethodExpression getAfterPhaseListener()

Returns:

the MethodExpression that will be invoked after this view is rendered.

public void setAfterPhaseListener(MethodExpression newAfterPhase)

当 UIViewRoot 在其生命周期中运行时，允许为 "afterPhase" 事件调用任意方法。将为所有除 PhaseId#RESTORE_VIEW 以外的阶段调用此方法。与实际的 PhaseListener 不同，此方法不允许仅为给定的阶段接收 PhaseEvent。

此方法必须符合 PhaseListener#afterPhase 的签名。

newAfterPhase

在呈现此视图后将调用的 MethodExpression。

英文文档：

setAfterPhaseListener

public void setAfterPhaseListener(MethodExpression newAfterPhase)

Allow an arbitrary method to be called for the "afterPhase" event as the UIViewRoot runs through its lifecycle. This method will be called for all phases except PhaseId.RESTORE_VIEW. Unlike a true PhaseListener, this approach doesn't allow for only receiving PhaseEvents for a given phase.

The method must conform to the signature of PhaseListener.afterPhase(javax.faces.event.PhaseEvent).

Parameters:

newAfterPhase - the MethodExpression that will be invoked after this view is rendered.

public void removePhaseListener(PhaseListener toRemove)

英文文档：

removePhaseListener

public void removePhaseListener(PhaseListener toRemove)

public void addPhaseListener(PhaseListener newPhaseListener)

英文文档：

addPhaseListener

public void addPhaseListener(PhaseListener newPhaseListener)

public void queueEvent(FacesEvent event)

重写默认的 UIComponentBase#queueEvent 行为以累积排队事件供以后广播。

event	要排队的 FacesEvent
Throws	IllegalStateException: 如果此组件不是 UIViewRoot 的后代
Throws	NullPointerException: 如果 event 为 null

英文文档：

queueEvent

public void queueEvent(FacesEvent event)

Override the default UIComponentBase.queueEvent(javax.faces.event.FacesEvent) behavior to accumulate the queued events for later broadcasting.

Overrides:

queueEvent in class UIComponentBase

Parameters:

event - FacesEvent to be queued

Throws:

IllegalStateException - if this component is not a descendant of a UIViewRoot

NullPointerException - if event is null

public void processDecodes(FacesContext context)

如果此阶段的事件处理导致调用了 FacesContext#renderResponse 或 FacesContext#responseComplete，则重写默认的 UIComponentBase#processDecodes 行为，以便在默认处理完成后广播任何排队事件，并清除后面阶段的任何事件。

context	要处理的请求的 FacesContext
Throws	NullPointerException: 如果 context 为 null

英文文档：

processDecodes

public void processDecodes(FacesContext context)

Override the default UIComponentBase.processDecodes(javax.faces.context.FacesContext) behavior to broadcast any queued events after the default processing has been completed and to clear out any events for later phases if the event processing for this phase caused FacesContext.renderResponse() or FacesContext.responseComplete() to be called.

Overrides:

processDecodes in class UIComponentBase

Parameters:

context - FacesContext for the request we are processing

Throws:

NullPointerException - if context is null

public void encodeBegin(FacesContext context) throws java.io.IOException

重写默认的 UIComponentBase#encodeBegin 行为。如果 #getBeforePhaseListener 返回非 null，则调用它，同时传递 PhaseId#RENDER_RESPONSE 阶段的 PhaseEvent。如果通过调用 #addPhaseListener 填充的内部列表为非空，则该列表中的任何侦听器都必须调用其 PhaseListener#beforePhase 方法，同时传递 PhaseEvent。调用任何 beforePhase 侦听器期间发生的任何错误都必须被记录和抑制。调用侦听器后，调用超类处理。

英文文档：

encodeBegin

public void encodeBegin(FacesContext context)
                 throws IOException

Override the default UIComponentBase.encodeBegin(javax.faces.context.FacesContext) behavior. If getBeforePhaseListener() returns non-null, invoke it, passing a PhaseEvent for the PhaseId.RENDER_RESPONSE phase. If the internal list populated by calls to addPhaseListener(javax.faces.event.PhaseListener) is non-empty, any listeners in that list must have their PhaseListener.beforePhase(javax.faces.event.PhaseEvent) method called, passing the PhaseEvent. Any errors that occur during invocation of any of the the beforePhase listeners must be logged and swallowed. After listeners are invoked call superclass processing.

Overrides:

encodeBegin in class UIComponentBase

Parameters:

context - FacesContext for the response we are creating

Throws:

IOException - if an input/output error occurs while rendering

public void encodeEnd(FacesContext context) throws java.io.IOException

重写默认的 UIComponentBase#encodeEnd 行为。如果 #getAfterPhaseListener 返回非 null，则调用它，同时传递 PhaseId#RENDER_RESPONSE 阶段的 PhaseEvent。调用 afterPhase 侦听器期间发生的任何错误都必须被记录和抑制。

英文文档：

encodeEnd

public void encodeEnd(FacesContext context)
               throws IOException

Override the default UIComponentBase.encodeEnd(javax.faces.context.FacesContext) behavior. If getAfterPhaseListener() returns non-null, invoke it, passing a PhaseEvent for the PhaseId.RENDER_RESPONSE phase. Any errors that occur during invocation of the afterPhase listener must be logged and swallowed.

Overrides:

encodeEnd in class UIComponentBase

Parameters:

context - FacesContext for the response we are creating

Throws:

IOException - if an input/output error occurs while rendering

public void processValidators(FacesContext context)

如果此阶段的事件处理导致调用了 FacesContext#renderResponse 或 FacesContext#responseComplete，则重写默认的 UIComponentBase#processValidators 行为，以便在默认处理完成后广播任何排队事件，并清除后面阶段的任何事件。

context	要处理的请求的 FacesContext
Throws	NullPointerException: 如果 context 为 null

英文文档：

processValidators

public void processValidators(FacesContext context)

Override the default UIComponentBase.processValidators(javax.faces.context.FacesContext) behavior to broadcast any queued events after the default processing has been completed and to clear out any events for later phases if the event processing for this phase caused FacesContext.renderResponse() or FacesContext.responseComplete() to be called.

Overrides:

processValidators in class UIComponentBase

Parameters:

context - FacesContext for the request we are processing

Throws:

NullPointerException - if context is null

public void processUpdates(FacesContext context)

如果此阶段的事件处理导致调用了 FacesContext#renderResponse 或 FacesContext#responseComplete，则重写默认的 UIComponentBase 行为，以便在默认处理完成后广播任何排队事件，并清除后面阶段的任何事件。

context	要处理的请求的 FacesContext
Throws	NullPointerException: 如果 context 为 null

英文文档：

processUpdates

public void processUpdates(FacesContext context)

Override the default UIComponentBase behavior to broadcast any queued events after the default processing has been completed and to clear out any events for later phases if the event processing for this phase caused FacesContext.renderResponse() or FacesContext.responseComplete() to be called.

Overrides:

processUpdates in class UIComponentBase

Parameters:

context - FacesContext for the request we are processing

Throws:

NullPointerException - if context is null

public void processApplication(FacesContext context)

如果此阶段的事件处理导致调用了 FacesContext#renderResponse 或 FacesContext#responseComplete，则广播任何已为请求处理生命周期的调用应用程序 阶段排队的事件并清除后面阶段的任何事件。

context	要处理的请求的 FacesContext
Throws	NullPointerException: 如果 context 为 null

英文文档：

processApplication

public void processApplication(FacesContext context)

Broadcast any events that have been queued for the Invoke Application phase of the request processing lifecycle and to clear out any events for later phases if the event processing for this phase caused FacesContext.renderResponse() or FacesContext.responseComplete() to be called.

Parameters:

context - FacesContext for the request we are processing

Throws:

NullPointerException - if context is null

public String createUniqueId()

生成组件的标识符。该标识符将带有前缀 UNIQUE_ID_PREFIX，且在此 UIViewRoot 内是唯一的。

英文文档：

createUniqueId

public String createUniqueId()

Generate an identifier for a component. The identifier will be prefixed with UNIQUE_ID_PREFIX, and will be unique within this UIViewRoot.

public java.util.Locale getLocale()

返回在本地化为此视图创建的响应中使用的 Locale。

算法：

如果有 locale ivar，则将其返回。如果有 "locale" 的值表达式，则获取其值。如果该值为 null，则返回调用 javax.faces.application.ViewHandler#calculateLocale 的结果。如果值是 java.util.Locale 的实例，则将其返回。如果该值是 String，则将其转换为 java.util.Locale 并将其返回。如果没有 "locale" 的值表达式，则返回调用 javax.faces.application.ViewHandler#calculateLocale 的结果。

return

通过执行上述算法获取的当前 Locale。

英文文档：

getLocale

public Locale getLocale()

Return the Locale to be used in localizing the response being created for this view.

Algorithm:

If we have a locale ivar, return it. If we have a value expression for "locale", get its value. If the value is null, return the result of calling ViewHandler.calculateLocale(javax.faces.context.FacesContext). If the value is an instance of java.util.Locale return it. If the value is a String, convert it to a java.util.Locale and return it. If there is no value expression for "locale", return the result of calling ViewHandler.calculateLocale(javax.faces.context.FacesContext).

Returns:

The current Locale obtained by executing the above algorithm.

public void setLocale(java.util.Locale locale)

设置在本地化为此视图创建的响应中使用的 Locale。

locale

新的本地化 Locale

英文文档：

setLocale

public void setLocale(Locale locale)

Set the Locale to be used in localizing the response being created for this view.

Parameters:

locale - The new localization Locale

public Object saveState(FacesContext context)

英文文档：

saveState

public Object saveState(FacesContext context)

Description copied from interface: StateHolder

Gets the state of the instance as a Serializable Object.

If the class that implements this interface has references to instances that implement StateHolder (such as a UIComponent with event handlers, validators, etc.) this method must call the StateHolder.saveState(javax.faces.context.FacesContext) method on all those instances as well. This method must not save the state of children and facets. That is done via the StateManager

This method must not alter the state of the implementing object. In other words, after executing this code:

 Object state = component.saveState(facesContext);
 

component should be the same as before executing it.

The return from this method must be Serializable

Specified by:

saveState in interface StateHolder

Overrides:

saveState in class UIComponentBase

public void restoreState(FacesContext context,
                         Object state)