UIComponent (Java EE 5)

UIComponent 是 JavaServer Faces 中所有用户界面组件的基类。与特定请求和响应关联的 UIComponent 实例集合被组织成表示整个请求或响应内容的 UIViewRoot 下的组件树。

为了方便组件开发人员使用，UIComponentBase 提供了为 UIComponent 指定的默认行为，并且是所有具体 UIComponent“基本”实现的基类。鼓励组件编写者为 UIComponentBase 创建子类，而不是直接实现此抽象类，以减少将来更改方法签名所带来的影响。

UIComponent is the base class for all user interface components in JavaServer Faces. The set of UIComponent instances associated with a particular request and response are organized into a component tree under a UIViewRoot that represents the entire content of the request or response.

For the convenience of component developers, UIComponentBase provides the default behavior that is specified for a UIComponent, and is the base class for all of the concrete UIComponent "base" implementations. Component writers are encouraged to subclass UIComponentBase, instead of directly implementing this abstract class, to reduce the impact of any future changes to the method signatures.

英文文档：

bindings

protected Map<String,ValueExpression> bindings

public UIComponent()

英文文档：

UIComponent

public UIComponent()

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

返回表示与此 UIComponent 关联的属性（以及特性，参见下文）的可变 Map，以属性名称（必须是 String）作为键。返回的实现必须支持所有标准的和可选的 Map 方法，并支持以下附加要求：

• Map 实现必须实现 java.io.Serializable 接口。
• 任何添加 null 键或值的尝试都必定抛出 NullPointerException。
• 任何添加非 String 键的尝试都必定抛出 ClassCastException。
• 如果指定为键的属性名称与此 UIComponent 实现类的某个属性相匹配，则下列方法将具有特殊行为：
  • containsKey - 返回 false。
  • get() - 如果属性是可读的，则调用获取方法并返回已返回的值（在其相应的包装器类中包装基本值）；否则抛出 IllegalArgumentException。
  • put() - 如果属性是可写的，则调用设置方法以设置相应的值（在其相应包装器类中对基本值解包）。如果属性是不可写的，或尝试将基本类型的属性设置为 null，则抛出 IllegalArgumentException。
  • remove - 抛出 IllegalArgumentException。

英文文档：

getAttributes

public abstract Map<String,Object> getAttributes()

Return a mutable Map representing the attributes (and properties, see below) associated wth this UIComponent, keyed by attribute name (which must be a String). The returned implementation must support all of the standard and optional Map methods, plus support the following additional requirements:

• The Map implementation must implement the java.io.Serializable interface.
• Any attempt to add a null key or value must throw a NullPointerException.
• Any attempt to add a key that is not a String must throw a ClassCastException.
• If the attribute name specified as a key matches a property of this UIComponent's implementation class, the following methods will have special behavior:
  • containsKey - Return false.
  • get() - If the property is readable, call the getter method and return the returned value (wrapping primitive values in their corresponding wrapper classes); otherwise throw IllegalArgumentException.
  • put() - If the property is writeable, call the setter method to set the corresponding value (unwrapping primitive values in their corresponding wrapper classes). If the property is not writeable, or an attempt is made to set a property of primitive type to null, throw IllegalArgumentException.
  • remove - Throw IllegalArgumentException.

abstract public ValueBinding getValueBinding(String name)

调用 #getValueExpression 并检查结果。如果结果是 #setValueBinding 中规定的包装器类的实例，则提取 ValueBinding 实例并将其返回。否则，在 ValueBinding 的实现中包装结果，并将其返回。

name	要为其获取 ValueBinding 的属性的名称
Throws	NullPointerException: 如果 name 为 null
deprecated	此方法已由 #getValueExpression 替代。

英文文档：

getValueBinding

public abstract ValueBinding getValueBinding(String name)

Deprecated. This has been replaced by getValueExpression(java.lang.String).

Call through to getValueExpression(java.lang.String) and examine the result. If the result is an instance of the wrapper class mandated in setValueBinding(java.lang.String, javax.faces.el.ValueBinding), extract the ValueBinding instance and return it. Otherwise, wrap the result in an implementation of ValueBinding, and return it.

Parameters:

name - Name of the attribute or property for which to retrieve a ValueBinding

Throws:

NullPointerException - if name is null

abstract public void setValueBinding(String name, ValueBinding binding)

在 ValueExpression 的实现中包装参数 binding 并调用 #setValueExpression。

name	将为其设置 ValueBinding 的属性的名称
binding	要设置的 ValueBinding，或为 null 以移除任何当前设置的 ValueBinding
Throws	IllegalArgumentException: 如果 name 是 id 或 parent 之一
Throws	NullPointerException: 如果 name 为 null
deprecated	此方法已由 #setValueExpression 替代。

英文文档：

setValueBinding

public abstract void setValueBinding(String name,
                                     ValueBinding binding)

Deprecated. This has been replaced by setValueExpression(java.lang.String, javax.el.ValueExpression).

Wrap the argument binding in an implementation of ValueExpression and call through to setValueExpression(java.lang.String, javax.el.ValueExpression).

Parameters:

name - Name of the attribute or property for which to set a ValueBinding

binding - The ValueBinding to set, or null to remove any currently set ValueBinding

Throws:

IllegalArgumentException - if name is one of id or parent

NullPointerException - if name is null

public ValueExpression getValueExpression(String name)

返回用于计算指定属性名称值的 ValueExpression（如果有）。

必须为遵守 JSF 1.2 及以后规范的组件重写并实现此方法。

since	1.2
name	要为其获取 ValueExpression 的属性的名称
Throws	NullPointerException: 如果 name 为 null

英文文档：

getValueExpression

public ValueExpression getValueExpression(String name)

Return the ValueExpression used to calculate the value for the specified attribute or property name, if any.

This method must be overridden and implemented for components that comply with JSF 1.2 and later.

Parameters:

name - Name of the attribute or property for which to retrieve a ValueExpression

Throws:

NullPointerException - if name is null

Since:

1.2

public void setValueExpression(String name, ValueExpression binding)

设置用于计算指定属性名称值的 ValueExpression（如果有）。

实现必须以参数 expression 调用 ValueExpression#isLiteralText。如果 isLiteralText() 返回 true，则以参数 expression 调用 ValueExpression#getValue，并将结果作为 value 参数传入对 this.#getAttributes().put(name, value) 的调用，其中 name 是参数 name。如果调用 ValueExpression#getValue 时抛出异常，则在 javax.faces.FacesException 中包装它并将其重新抛出。如果 isLiteralText() 返回 false，则仅将未求值的 expression 参数存储在参数 name 给定的键下的 ValueExpression 集合中。

必须为遵守 JSF 1.2 及以后规范的组件重写并实现此方法。

since	1.2
name	要为其设置 ValueExpression 的属性的名称
binding	要设置的 ValueExpression，或为 null 以移除任何当前设置的 ValueExpression
Throws	IllegalArgumentException: 如果 name 是 id 或 parent 之一
Throws	NullPointerException: 如果 name 为 null

英文文档：

setValueExpression

public void setValueExpression(String name,
                               ValueExpression binding)

Set the ValueExpression used to calculate the value for the specified attribute or property name, if any.

The implementation must call Expression.isLiteralText() on the argument expression. If isLiteralText() returns true, invoke ValueExpression.getValue(javax.el.ELContext) on the argument expression and pass the result as the value parameter in a call to this.getAttributes().put(name, value) where name is the argument name. If an exception is thrown as a result of calling ValueExpression.getValue(javax.el.ELContext), wrap it in a FacesException and re-throw it. If isLiteralText() returns false, simply store the un-evaluated expression argument in the collection of ValueExpressions under the key given by the argument name.

This method must be overridden and implemented for components that comply with JSF 1.2 and later.

Parameters:

name - Name of the attribute or property for which to set a ValueExpression

binding - The ValueExpression to set, or null to remove any currently set ValueExpression

Throws:

IllegalArgumentException - if name is one of id or parent

NullPointerException - if name is null

Since:

1.2

abstract public String getClientId(FacesContext context)

返回此组件的客户端标识符，如果需要可以生成一个标识符。将会请求关联的 Renderer（如果有）将 clientId 转换为适合传送给客户端的形式。

此方法的返回值必须在实例的整个生命周期中保持一致，除非组件的 id 属性发生改变，或此组件所在的 NamingContainer 的客户端 ID 发生改变（例如，UIData）。但是，即使在这些情况下，对此方法的连续调用也必须总是返回相同的值。实现必须按照以下步骤确定 clientId：

在实现 NamingContainer 的视图层次结构中找到离此组件最近的祖先。调用它的 getContainerClientId() 并将结果保存为局部变量 parentId。调用此组件的 #getId，并将结果保存为局部变量 myId。如果 myId 为 null，则调用 context.getViewRoot().createUniqueId()，并将结果分配给 myId。如果 parentId 为非 null，则使 myId 等于 parentId + NamingContainer.SEPARATOR_CHAR + myId。调用 Renderer#convertClientId，同时传递 myId，并返回结果。

context	当前请求的 FacesContext
Throws	NullPointerException: 如果 context 为 null

英文文档：

getClientId

public abstract String getClientId(FacesContext context)

Return a client-side identifier for this component, generating one if necessary. The associated Renderer, if any, will be asked to convert the clientId to a form suitable for transmission to the client.

The return from this method must be the same value throughout the lifetime of the instance, unless the id property of the component is changed, or the component is placed in a NamingContainer whose client ID changes (for example, UIData). However, even in these cases, consecutive calls to this method must always return the same value. The implementation must follow these steps in determining the clientId:

Find the closest ancestor to this component in the view hierarchy that implements NamingContainer. Call getContainerClientId() on it and save the result as the parentId local variable. Call getId() on this component and save the result as the myId local variable. If myId is null, call context.getViewRoot().createUniqueId() and assign the result to myId. If parentId is non-null, let myId equal parentId + NamingContainer.SEPARATOR_CHAR + myId. Call Renderer.convertClientId(javax.faces.context.FacesContext, java.lang.String), passing myId, and return the result.

Parameters:

context - The FacesContext for the current request

Throws:

NullPointerException - if context is null

public String getContainerClientId(FacesContext context)

通过将前置逻辑分离到一个单独的可调用方法，使实现 NamingContainer 的组件能够有选择地禁用将其 clientId 放到其后代的 clientId 前面的行为。有关用法，请参见 #getClientId。

默认情况下，此方法将调用 #getClientId 并返回结果。

since	1.2
Throws	NullPointerException: 如果 context 为 null

英文文档：

getContainerClientId

public String getContainerClientId(FacesContext context)

Allow components that implement NamingContainer to selectively disable prepending their clientId to their descendent's clientIds by breaking the prepending logic into a seperately callable method. See getClientId(javax.faces.context.FacesContext) for usage.

By default, this method will call through to getClientId(javax.faces.context.FacesContext) and return the result.

Throws:

NullPointerException - if context is null

Since:

1.2

abstract public String getFamily()

返回此组件所属的组件家族的标识符。此标识符（结合 rendererType 属性的值）可用于为此组件实例选择合适的 Renderer。

英文文档：

getFamily

public abstract String getFamily()

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.

abstract public String getId()

返回此 UIComponent 的组件标识符。

英文文档：

getId

public abstract String getId()

Return the component identifier of this UIComponent.

abstract public void setId(String id)

设置此 UIComponent 的组件标识符（如果有）。组件标识符必须符合以下语法限制：

• 不得为长度为 0 的 String。
• 第一个字符必须为字母或下划线 ('_')。
• 后续字符必须为字母、数字、下划线 ('_') 或短划线 ('-')。

组件标识符还必须遵守下列语义限制（请注意，setId() 实现不执行此限制）：

• 指定的标识符必须在所有组件（包括 facet）之间是唯一的，这些组件是距离最近的 NamingContainer 祖先 UIComponent 的后代；如果不存在这样一个 NamingContainer 祖先，则它必须在整个组件树范围内是唯一的。

id	新组件标识符，或为 null 以指示此 UIComponent 没有组件标识符
Throws	IllegalArgumentException: 如果 id 语法无效

英文文档：

setId

public abstract void setId(String id)

Set the component identifier of this UIComponent (if any). Component identifiers must obey the following syntax restrictions:

• Must not be a zero-length String.
• First character must be a letter or an underscore ('_').
• Subsequent characters must be a letter, a digit, an underscore ('_'), or a dash ('-').

Component identifiers must also obey the following semantic restrictions (note that this restriction is NOT enforced by the setId() implementation):

• The specified identifier must be unique among all the components (including facets) that are descendents of the nearest ancestor UIComponent that is a NamingContainer, or within the scope of the entire component tree if there is no such ancestor that is a NamingContainer.

Parameters:

id - The new component identifier, or null to indicate that this UIComponent does not have a component identifier

Throws:

IllegalArgumentException - if id is not syntactically valid

abstract public UIComponent getParent()

返回此 UIComponent 的父 UIComponent（如果有）。组件必须允许将子组件添加到此组件的子组件列表中，或从该列表中将其移除，即使子组件从 getParent( ) 返回 null。

英文文档：

getParent

public abstract UIComponent getParent()

Return the parent UIComponent of this UIComponent, if any. A component must allow child components to be added to and removed from the list of children of this component, even though the child component returns null from getParent( ).

abstract public void setParent(UIComponent parent)

设置此 UIComponent 的父 UIComponent。此方法绝不能由开发人员调用；在将组件添加到父组件的子 List 或 facet Map 中，或从中移除组件时，UIComponent 的内部实现会调用它。

parent

新父组件，或对于组件树的根节点而言，为 null

英文文档：

setParent

public abstract void setParent(UIComponent parent)

Set the parent UIComponent of this UIComponent. This method must never be called by developers; a UIComponent's internal implementation will call it as components are added to or removed from a parent's child List or facet Map.

Parameters:

parent - The new parent, or null for the root node of a component tree

abstract public boolean isRendered()

如果应在请求处理生命周期的呈现响应 阶段呈现此组件（及其子组件），则返回 true。

英文文档：

isRendered

public abstract boolean isRendered()

Return true if this component (and its children) should be rendered during the Render Response phase of the request processing lifecycle.

abstract public void setRendered(boolean rendered)

设置此 UIComponent 的 rendered 属性。

rendered

如果为 true，则呈现此组件；否则不呈现此组件。

英文文档：

setRendered

public abstract void setRendered(boolean rendered)

Set the rendered property of this UIComponent.

Parameters:

rendered - If true render this component; otherwise, do not render this component

abstract public String getRendererType()

返回此 UIComponent 的 Renderer 类型（如果有）。

英文文档：

getRendererType

public abstract String getRendererType()

Return the Renderer type for this UIComponent (if any).

abstract public void setRendererType(String rendererType)

设置此 UIComponent 的 Renderer 类型，或对于自呈现组件而言，为 null。

rendererType

要使用的 Renderer 类型的逻辑标识符，或对于自呈现组件而言，为 null

英文文档：

setRendererType

public abstract void setRendererType(String rendererType)

Set the Renderer type for this UIComponent, or null for components that render themselves.

Parameters:

rendererType - Logical identifier of the type of Renderer to use, or null for components that render themselves

abstract public boolean getRendersChildren()

返回一个标志，指示此组件是否负责呈现其子组件。UIComponentBase#getRendersChildren 的默认实现会尝试查找此组件的 renderer。如果找到，它将调用 Renderer#getRendersChildren 并返回结果。如果未找到，它将返回 false。自 JavaServer Faces 规范 1.2 版起，鼓励组件编写者通过此方法返回 true，并依靠 UIComponentBase#encodeChildren。

英文文档：

getRendersChildren

public abstract boolean getRendersChildren()

Return a flag indicating whether this component is responsible for rendering its child components. The default implementation in UIComponentBase.getRendersChildren() tries to find the renderer for this component. If it does, it calls Renderer.getRendersChildren() and returns the result. If it doesn't, it returns false. As of version 1.2 of the JavaServer Faces Specification, component authors are encouraged to return true from this method and rely on UIComponentBase.encodeChildren(javax.faces.context.FacesContext).

abstract public java.util.List<E> getChildren()

返回表示与此组件关联的子 UIComponent 的可变 List。返回的实现必须支持所有标准的和可选的 List 方法，并支持以下附加要求：

• List 实现必须实现 java.io.Serializable 接口。
• 任何添加 null 的尝试都必定抛出 NullPointerException。
• 任何添加未实现 UIComponent 的对象的尝试都必定抛出 ClassCastException。
• 只要添加新的子组件，该子组件的 parent 属性就必须设置为此组件实例。如果子组件的 parent 属性已经是非 null，则必须首先从此组件以前的父组件中移除此子组件（在该父组件中它可能已经是子组件或 facet）。
• 只要移除现有的子组件，该子组件的 parent 属性就必须设置为 null。

英文文档：

getChildren

public abstract List<UIComponent> getChildren()

Return a mutable List representing the child UIComponents associated with this component. The returned implementation must support all of the standard and optional List methods, plus support the following additional requirements:

• The List implementation must implement the java.io.Serializable interface.
• Any attempt to add a null must throw a NullPointerException
• Any attempt to add an object that does not implement UIComponent must throw a ClassCastException.
• Whenever a new child component is added, the parent property of the child must be set to this component instance. If the parent property of the child was already non-null, the child must first be removed from its previous parent (where it may have been either a child or a facet).
• Whenever an existing child component is removed, the parent property of the child must be set to null.

abstract public int getChildCount()

返回与此 UIComponent 关联的子 UIComponent 的数量。如果不存在子组件，则此方法必须返回 0。此方法不得导致创建子组件列表。

英文文档：

getChildCount

public abstract int getChildCount()

Return the number of child UIComponents that are associated with this UIComponent. If there are no children, this method must return 0. The method must not cause the creation of a child component list.

abstract public UIComponent findComponent(String expr)

按照如下所述的算法，搜索并返回带有与指定搜索表达式相匹配的 id 的 UIComponent（如果有）。

有关给定一个简单的 clientId 查找组件的方法，请参见 #invokeOnComponent。

要求组件标识符在包含此组件的距离最近的祖先 NamingContainer （可能是此组件本身）范围内是唯一的。如果此组件的祖先中不存在 NamingContainer 组件，则树的根组件将被视为 NamingContainer，不论其类是否实际实现 NamingContainer 接口。

搜索表达式 由一个标识符（该标识符与 UIComponent 的 id 属性完全匹配），或者一组通过 NamingContainer#SEPARATOR_CHAR 字符值链接的此类标识符组成。搜索算法应按照下列过程操作，尽管只要最终结果相同，也可以使用备用算法：

• 标识作为搜索基本组件的 UIComponent，当满足下列条件之一时停止：
  • 如果搜索表达式以分隔符字符开头（称为“绝对”搜索表达式），基本组件将是组件树的根 UIComponent。前导分隔符字符将会被去掉，搜索表达式的其余部分将被视为下文所述的“相对”搜索表达式。
  • 否则，如果此 UIComponent 是 NamingContainer，它将作为基本组件。
  • 否则，向上搜索此组件的父组件。如果遇到 NamingContainer，它将作为基本组件。
  • 否则（如果没有遇到 NamingContainer），则将根 UIComponent 作为基本组件。
• 现在搜索表达式（可能在前面的步骤中修改过）是“相对”搜索表达式，将用于在基本组件范围内查找具有匹配 id 的组件（如果有）。匹配按照以下过程操作：
  • 如果搜索表达式是简单标识符，则将该值与 id 属性比较，然后在基本 UIComponent 的 facet 和子组件中递归（除非找到了后代 NamingContainer 才不搜索其自身的 facet 和子组件）。
  • 如果搜索表达式包含由分隔符字符分隔的多个标识符，则使用第一个标识符按上一条规则来查找 NamingContainer。然后，将调用此 NamingContainer 的 findComponent() 方法，同时传递搜索表达式的其余部分。

expr	标识要返回的 UIComponent 的搜索表达式
return	找到的 UIComponent；如果未找到组件，则返回 null。
Throws	IllegalArgumentException: 如果搜索表达式的中间标识符标识了非 NamingContainer 的 UIComponent
Throws	NullPointerException: 如果 expr 为 null

英文文档：

findComponent

public abstract UIComponent findComponent(String expr)

Search for and return the UIComponent with an id that matches the specified search expression (if any), according to the algorithm described below.

For a method to find a component given a simple clientId, see invokeOnComponent(javax.faces.context.FacesContext, java.lang.String, javax.faces.component.ContextCallback).

Component identifiers are required to be unique within the scope of the closest ancestor NamingContainer that encloses this component (which might be this component itself). If there are no NamingContainer components in the ancestry of this component, the root component in the tree is treated as if it were a NamingContainer, whether or not its class actually implements the NamingContainer interface.

A search expression consists of either an identifier (which is matched exactly against the id property of a UIComponent, or a series of such identifiers linked by the NamingContainer.SEPARATOR_CHAR character value. The search algorithm should operates as follows, though alternate alogrithms may be used as long as the end result is the same:

• Identify the UIComponent that will be the base for searching, by stopping as soon as one of the following conditions is met:
  • If the search expression begins with the the separator character (called an "absolute" search expression), the base will be the root UIComponent of the component tree. The leading separator character will be stripped off, and the remainder of the search expression will be treated as a "relative" search expression as described below.
  • Otherwise, if this UIComponent is a NamingContainer it will serve as the basis.
  • Otherwise, search up the parents of this component. If a NamingContainer is encountered, it will be the base.
  • Otherwise (if no NamingContainer is encountered) the root UIComponent will be the base.
• The search expression (possibly modified in the previous step) is now a "relative" search expression that will be used to locate the component (if any) that has an id that matches, within the scope of the base component. The match is performed as follows:
  • If the search expression is a simple identifier, this value is compared to the id property, and then recursively through the facets and children of the base UIComponent (except that if a descendant NamingContainer is found, its own facets and children are not searched).
  • If the search expression includes more than one identifier separated by the separator character, the first identifier is used to locate a NamingContainer by the rules in the previous bullet point. Then, the findComponent() method of this NamingContainer will be called, passing the remainder of the search expression.

Parameters:

expr - Search expression identifying the UIComponent to be returned

Returns:

the found UIComponent, or null if the component was not found.

Throws:

IllegalArgumentException - if an intermediate identifier in a search expression identifies a UIComponent that is not a NamingContainer

NullPointerException - if expr is null

public boolean invokeOnComponent(FacesContext context, String clientId, ContextCallback callback) throws FacesException

在视图层次结构中从此组件开始，搜索 clientId 等于参数 clientId 的组件；如果找到，则以参数 callback 调用 ContextCallback#invokeContextCallback 方法，同时将当前 FacesContext 和找到的组件作为参数传递。此方法与 #findComponent 类似，但它不支持前导 NamingContainer#SEPARATOR_CHAR 语法用于从视图的根进行搜索。

默认实现将首先检查 this.getClientId() 是否等于参数 clientId。如果等于，以参数 callback 调用 ContextCallback#invokeContextCallback 方法，同时传递 FacesContext 参数并将此 clientId 作为组件参数传递。如果回调抛出 Exception，则在 FacesException 中包装它并将其重新抛出。否则，返回 true。

否则，对 #getFacetsAndChildren 返回的每个组件，调用 invokeOnComponent()，同时按顺序将参数传递给此方法。invokeOnComponent() 首次返回 true 时，将中止遍历 Iterator 的其余部分并返回 true。

对于在参数 clientId 中找到的任何状态，当调用 ContextCallback#invokeContextCallback 时，此方法的实现必须保证传递给回调的组件状态正确反映组件在视图层次结构中的位置。例如，像 UIData 之类的迭代组件将需要设置其行索引，以正确反映参数 clientId，然后再查找正确行支持的相应子组件。当回调正常返回或抛出 Exception 时，此方法的实现必须将视图状态恢复到调用回调前的状态。

如果 #getFacetsAndChildren 的任何一个元素都没有从 invokeOnComponent() 中返回 true，则返回 false。

一个简单的用法示例是通过 clientId 查找组件。

private UIComponent found = null;

private void doFind(FacesContext context, String clientId) {
  context.getViewRoot().invokeOnComponent(context, clientId,
      new ContextCallback() {
         public void invokeOnComponent(FacesContext context,
                                       UIComponent component) {
           found = component;
         }
      });
}
 

since	1.2
context	当前请求的 FacesContext
clientId	要传递给参数 callback 的组件的客户端标识符。
callback	Callback 接口的实现。
Throws	NullPointerException: 如果任何参数为 null
Throws	FacesException: 如果参数 Callback 抛出 Exception，则将在 FacesException 中包装它并将其重新抛出。
return	如果找到了具有给定 clientId 的组件，成功调用了回调方法，同时将该组件作为参数传递，而且未抛出 Exception，则返回 true。如果未找到具有给定 clientId 的组件，则返回 false。

英文文档：

invokeOnComponent

public boolean invokeOnComponent(FacesContext context,
                                 String clientId,
                                 ContextCallback callback)
                          throws FacesException

Starting at this component in the View hierarchy, search for a component with a clientId equal to the argument clientId and, if found, call the ContextCallback.invokeContextCallback(javax.faces.context.FacesContext, javax.faces.component.UIComponent) method on the argument callback, passing the current FacesContext and the found component as arguments. This method is similar to findComponent(java.lang.String) but it does not support the leading NamingContainer.SEPARATOR_CHAR syntax for searching from the root of the View.

The default implementation will first check if this.getClientId() is equal to the argument clientId. If so, call the ContextCallback.invokeContextCallback(javax.faces.context.FacesContext, javax.faces.component.UIComponent) method on the argument callback, passing through the FacesContext argument and passing this as the component argument. If an Exception is thrown by the callback, wrap it in a FacesException and re-throw it. Otherwise, return true.

Otherwise, for each component returned by getFacetsAndChildren(), call invokeOnComponent() passing the arguments to this method, in order. The first time invokeOnComponent() returns true, abort traversing the rest of the Iterator and return true.

When calling ContextCallback.invokeContextCallback(javax.faces.context.FacesContext, javax.faces.component.UIComponent) the implementation of this method must guarantee that the state of the component passed to the callback correctly reflects the component's position in the View hierarchy with respect to any state found in the argument clientId. For example, an iterating component such as UIData will need to set its row index to correctly reflect the argument clientId before finding the appropriate child component backed by the correct row. When the callback returns, either normally or by throwing an Exception the implementation of this method must restore the state of the view to the way it was before invoking the callback.

If none of the elements from getFacetsAndChildren() returned true from invokeOnComponent(), return false.

Simple usage example to find a component by clientId.

private UIComponent found = null;

private void doFind(FacesContext context, String clientId) {
  context.getViewRoot().invokeOnComponent(context, clientId,
      new ContextCallback() {
         public void invokeOnComponent(FacesContext context,
                                       UIComponent component) {
           found = component;
         }
      });
}
 

Parameters:

context - the FacesContext for the current request

clientId - the client identifier of the component to be passed to the argument callback.

callback - an implementation of the Callback interface.

Returns:

true if the a component with the given clientId is found, the callback method was successfully invoked passing that component as an argument, and no Exception was thrown. Returns false if no component with the given clientId is found.

Throws:

NullPointerException - if any of the arguments are null

FacesException - if the argument Callback throws an Exception, it is wrapped in a FacesException and re-thrown.

Since:

1.2

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

返回表示与此 UIComponent 关联的 facet UIComponent 的可变 Map，以 facet 名称（必须是 String）作为键。返回的实现必须支持所有标准的和可选的 Map 方法，并支持以下附加要求：

• Map 实现必须实现 java.io.Serializable 接口。
• 任何添加 null 键或值的尝试都必定抛出 NullPointerException。
• 任何添加非 String 键的尝试都必定抛出 ClassCastException。
• 任何添加非 UIComponent 的尝试都必定抛出 ClassCastException。
• 只要添加新 facet UIComponent：
  • 组件的 parent 属性就必须设置为此组件实例。
  • 如果组件的 parent 属性已经是非 null，则必须首先从此组件以前的父组件中移除此组件（在该父组件中它可能已经是子组件或 facet）。
• 只要移除现有的 facet UIComponent：
  • facet 的 parent 属性就必须设置为 null。

英文文档：

getFacets

public abstract Map<String,UIComponent> getFacets()

Return a mutable Map representing the facet UIComponents associated with this UIComponent, keyed by facet name (which must be a String). The returned implementation must support all of the standard and optional Map methods, plus support the following additional requirements:

• The Map implementation must implement the java.io.Serializable interface.
• Any attempt to add a null key or value must throw a NullPointerException.
• Any attempt to add a key that is not a String must throw a ClassCastException.
• Any attempt to add a value that is not a UIComponent must throw a ClassCastException.
• Whenever a new facet UIComponent is added:
  • The parent property of the component must be set to this component instance.
  • If the parent property of the component was already non-null, the component must first be removed from its previous parent (where it may have been either a child or a facet).
• Whenever an existing facet UIComponent is removed:
  • The parent property of the facet must be set to null.

public int getFacetCount()

返回与此 UIComponent 关联的 facet UIComponent 的数量。如果不存在 facet，则此方法必须返回 0。此方法不得导致创建 facet 组件映射。

为了与直接扩展 UIComponent 的类向后兼容，提供了默认实现，只需调用 #getFacets，然后对返回的 Map 调用 size() 方法即可。UIComponentBase#getFacetCount 中提供了此方法的更优化版本。

since

1.2

英文文档：

getFacetCount

public int getFacetCount()

Return the number of facet UIComponents that are associated with this UIComponent. If there are no facets, this method must return 0. The method must not cause the creation of a facet component map.

For backwards compatability with classes that extend UIComponent directly, a default implementation is provided that simply calls getFacets() and then calls the size() method on the returned Map. A more optimized version of this method is provided in UIComponentBase.getFacetCount().

Since:

1.2

abstract public UIComponent getFacet(String name)

一个便捷方法，如果指定的 facet 存在，则返回指定的 facet，否则返回 null。如果请求的 facet 不存在，则不得创建 facet Map。

name	所需 facet 的名称

英文文档：

getFacet

public abstract UIComponent getFacet(String name)

Convenience method to return the named facet, if it exists, or null otherwise. If the requested facet does not exist, the facets Map must not be created.

Parameters:

name - Name of the desired facet

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

返回 facet 上的 Iterator，该 facet 后跟此 UIComponent 的子 UIComponent。返回的 facet 没有固定的顺序，所有子组件按其在子组件列表中存储的顺序跟在 facet 后面。如果此组件没有 facet 或子组件，则返回空 Iterator。

返回的 Iterator 不得支持 remove() 操作。

英文文档：

getFacetsAndChildren

public abstract Iterator<UIComponent> getFacetsAndChildren()

Return an Iterator over the facet followed by child UIComponents of this UIComponent. Facets are returned in an undefined order, followed by all the children in the order they are stored in the child list. If this component has no facets or children, an empty Iterator is returned.

The returned Iterator must not support the remove() operation.

abstract public void broadcast(FacesEvent event) throws AbortProcessingException

将指定的 FacesEvent 广播到表示关注此类型事件的所有注册的事件侦听器。侦听器按其添加的顺序调用。

event	要广播的 FacesEvent
Throws	AbortProcessingException: 通知 JavaServer Face 实现不应该继续处理当前事件
Throws	IllegalArgumentException: 如果此组件不支持此 FacesEvent 的实现类
Throws	NullPointerException: 如果 event 为 null

英文文档：

broadcast

public abstract void broadcast(FacesEvent event)
                        throws AbortProcessingException

Broadcast the specified FacesEvent to all registered event listeners who have expressed an interest in events of this type. Listeners are called in the order in which they were added.

Parameters:

event - The FacesEvent to be broadcast

Throws:

AbortProcessingException - Signal the JavaServer Faces implementation that no further processing on the current event should be performed

IllegalArgumentException - if the implementation class of this FacesEvent is not supported by this component

NullPointerException - if event is null

abstract public void decode(FacesContext context)

从指定 FacesContext 包含的请求中对此 UIComponent 的任何新状态解码，并在需要时存储此状态。

在解码过程中，通过调用 queueEvent()，可将事件排队，以便稍后处理（由已注册关注此事件的事件侦听器处理）。

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

英文文档：

decode

public abstract void decode(FacesContext context)

Decode any new state of this UIComponent from the request contained in the specified FacesContext, and store this state as needed.

During decoding, events may be enqueued for later processing (by event listeners who have registered an interest), by calling queueEvent().

Parameters:

context - FacesContext for the request we are processing

Throws:

NullPointerException - if context is null

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

如果 rendered 属性为 true，则将此 UIComponent 的当前状态的开头呈现给指定 FacesContext 中包含的响应。

如果 Renderer 与此 UIComponent 关联，则实际编码操作将委托给 encodeBegin(FacesContext, UIComponent)。

context	要创建的响应的 FacesContext
Throws	java.io.IOException: 如果呈现期间发生输入/输出错误
Throws	NullPointerException: 如果 context 为 null

英文文档：

encodeBegin

public abstract void encodeBegin(FacesContext context)
                          throws IOException

If our rendered property is true, render the beginning of the current state of this UIComponent to the response contained in the specified FacesContext.

If a Renderer is associated with this UIComponent, the actual encoding will be delegated to Renderer.encodeBegin(FacesContext, UIComponent).

Parameters:

context - FacesContext for the response we are creating

Throws:

IOException - if an input/output error occurs while rendering

NullPointerException - if context is null

abstract public void encodeChildren(FacesContext context) throws java.io.IOException

如果 rendered 属性为 true，则呈现此 UIComponent 的子 UIComponent。仅当 rendersChildren 属性为 true 时才调用此方法。

如果 Renderer 与此 UIComponent 关联，则实际编码操作将委托给 encodeChildren(FacesContext, UIComponent)。

context	要创建的响应的 FacesContext
Throws	java.io.IOException: 如果呈现期间发生输入/输出错误
Throws	NullPointerException: 如果 context 为 null

英文文档：

encodeChildren

public abstract void encodeChildren(FacesContext context)
                             throws IOException

If our rendered property is true, render the child UIComponents of this UIComponent. This method will only be called if the rendersChildren property is true.

If a Renderer is associated with this UIComponent, the actual encoding will be delegated to Renderer.encodeChildren(FacesContext, UIComponent).

Parameters:

context - FacesContext for the response we are creating

Throws:

IOException - if an input/output error occurs while rendering

NullPointerException - if context is null

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

如果 rendered 属性为 true，则呈现此 UIComponent 的当前状态的末尾。

如果 Renderer 与此 UIComponent 关联，则实际编码操作将委托给 encodeEnd(FacesContext, UIComponent)。

context	要创建的响应的 FacesContext
Throws	java.io.IOException: 如果呈现期间发生输入/输出错误
Throws	NullPointerException: 如果 context 为 null

英文文档：

encodeEnd

public abstract void encodeEnd(FacesContext context)
                        throws IOException

If our rendered property is true, render the ending of the current state of this UIComponent.

If a Renderer is associated with this UIComponent, the actual encoding will be delegated to Renderer.encodeEnd(FacesContext, UIComponent).

Parameters:

context - FacesContext for the response we are creating

Throws:

IOException - if an input/output error occurs while rendering

NullPointerException - if context is null

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

如果此组件从 #isRendered 返回 true，则呈现此组件及其从 isRendered() 返回 true 的所有子组件，不考虑 #getRendersChildren 标志的值。

since	1.2
Throws	java.io.IOException: 如果呈现期间发生输入/输出错误
Throws	NullPointerException: 如果 context 为 null

英文文档：

encodeAll

public void encodeAll(FacesContext context)
               throws IOException

If this component returns true from isRendered(), render this component and all its children that return true from isRendered(), regardless of the value of the getRendersChildren() flag.

Throws:

IOException - if an input/output error occurs while rendering

NullPointerException - if context is null

Since:

1.2

abstract protected void addFacesListener(FacesListener listener)

将指定的 FacesListener 添加到注册了接收此 UIComponent 事件通知的侦听器集合。预计作为事件源的 UIComponent 类将具有相应的类型安全 API 用于注册所需类型的侦听器，并且这些注册方法的实现将委托给此方法。例如：

public class FooEvent extends FacesEvent { ... }

public interface FooListener extends FacesListener {
public void processFoo(FooEvent event);
 }

public class FooComponent extends UIComponentBase {
   ...
public void addFooListener(FooListener listener) {
addFacesListener(listener);
   }
public void removeFooListener(FooListener listener) {
removeFacesListener(listener);
   }
   ...
 }
 

listener	要注册的 FacesListener
Throws	NullPointerException: 如果 listener 为 null

英文文档：

addFacesListener

protected abstract void addFacesListener(FacesListener listener)

Add the specified FacesListener to the set of listeners registered to receive event notifications from this UIComponent. It is expected that UIComponent classes acting as event sources will have corresponding typesafe APIs for registering listeners of the required type, and the implementation of those registration methods will delegate to this method. For example:

 public class FooEvent extends FacesEvent { ... }

 public interface FooListener extends FacesListener {
   public void processFoo(FooEvent event);
 }

 public class FooComponent extends UIComponentBase {
   ...
   public void addFooListener(FooListener listener) {
     addFacesListener(listener);
   }
   public void removeFooListener(FooListener listener) {
     removeFacesListener(listener);
   }
   ...
 }
 

Parameters:

listener - The FacesListener to be registered

Throws:

NullPointerException - if listener is null

abstract protected FacesListener[] getFacesListeners(Class<T> clazz)

返回作为指定类实例的已注册 FacesListener 的数组。如果不存在此类已注册侦听器，则返回一个长度为 0 的数组。返回的数组可以安全地强制转换为 clazz 元素类型的强制类型数组。

clazz	必须由其要返回的 FacesListener 实现的类
Throws	IllegalArgumentException: 如果 clazz 不是 FacesListener 并且未实现 FacesListener
Throws	NullPointerException: 如果 clazz 为 null

英文文档：

getFacesListeners

protected abstract FacesListener[] getFacesListeners(Class clazz)

Return an array of registered FacesListeners that are instances of the specified class. If there are no such registered listeners, a zero-length array is returned. The returned array can be safely be cast to an array strongly typed to an element type of clazz.

Parameters:

clazz - Class that must be implemented by a FacesListener for it to be returned

Throws:

IllegalArgumentException - if class is not, and does not implement, FacesListener

NullPointerException - if clazz is null

abstract protected void removeFacesListener(FacesListener listener)

从注册接收此 UIComponent 事件通知的侦听器集合中移除指定的 FacesListener。

listener	要取消注册的 FacesListener
Throws	NullPointerException: 如果 listener 为 null

英文文档：

removeFacesListener

protected abstract void removeFacesListener(FacesListener listener)

Remove the specified FacesListener from the set of listeners registered to receive event notifications from this UIComponent.

Parameters:

listener - The FacesListener to be deregistered

Throws:

NullPointerException - if listener is null

abstract public void queueEvent(FacesEvent event)

将事件排队，以便在当前请求处理生命周期阶段结束时广播。UIComponentBase 中的默认实现必须将此调用委托给父 UIComponent 的 queueEvent() 方法。

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

英文文档：

queueEvent

public abstract void queueEvent(FacesEvent event)

Queue an event for broadcast at the end of the current request processing lifecycle phase. The default implementation in UIComponentBase must delegate this call to the queueEvent() method of the parent UIComponent.

Parameters:

event - FacesEvent to be queued

Throws:

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

NullPointerException - if event is null

abstract public void processRestoreState(FacesContext context, Object state)

按如下操作，对此组件的所有 facet、此组件的所有子组件和此组件本身执行请求处理生命周期的恢复视图 阶段所需的组件树处理。

• 按照调用 getFacetsAndChildren() 所确定的顺序，调用此 UIComponent 的所有 facet 和子组件的 processRestoreState() 方法。
• 调用此组件的 restoreState() 方法。

如果状态保存方法被设置为服务器，则可能不能调用此方法。

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

英文文档：

processRestoreState

public abstract void processRestoreState(FacesContext context,
                                         Object state)

Perform the component tree processing required by the Restore View phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.

• Call the processRestoreState() method of all facets and children of this UIComponent in the order determined by a call to getFacetsAndChildren().
• Call the restoreState() method of this component.

This method may not be called if the state saving method is set to server.

Parameters:

context - FacesContext for the request we are processing

Throws:

NullPointerException - if context is null

abstract public void processDecodes(FacesContext context)

按如下操作，对此组件的所有 facet、此组件的所有子组件和此组件本身执行请求处理生命周期的应用请求值 阶段所需的组件树处理。

• 如果此 UIComponent 的 rendered 属性为 false，则跳过进一步的处理。
• 按照调用 getFacetsAndChildren() 所确定的顺序，调用此 UIComponent 的所有 facet 和子组件的 processDecodes() 方法。
• 调用此组件的 decode() 方法。
• 如果在解码处理期间抛出 RuntimeException，则调用 FacesContext#renderResponse 并重新抛出该异常。

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

英文文档：

processDecodes

public abstract void processDecodes(FacesContext context)

Perform the component tree processing required by the Apply Request Values phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.

• If the rendered property of this UIComponent is false, skip further processing.
• Call the processDecodes() method of all facets and children of this UIComponent, in the order determined by a call to getFacetsAndChildren().
• Call the decode() method of this component.
• If a RuntimeException is thrown during decode processing, call FacesContext.renderResponse() and re-throw the exception.

Parameters:

context - FacesContext for the request we are processing

Throws:

NullPointerException - if context is null

abstract public void processValidators(FacesContext context)

按如下操作，对此组件的所有 facet、此组件的所有子组件和此组件本身执行请求处理生命周期的处理验证 阶段所需的组件树处理。

• 如果此 UIComponent 的 rendered 属性为 false，则跳过进一步的处理。
• 按照调用 getFacetsAndChildren() 所确定的顺序，调用此 UIComponent 的所有 facet 和子组件的 processValidators() 方法。

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

英文文档：

processValidators

public abstract void processValidators(FacesContext context)

Perform the component tree processing required by the Process Validations phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.

• If the rendered property of this UIComponent is false, skip further processing.
• Call the processValidators() method of all facets and children of this UIComponent, in the order determined by a call to getFacetsAndChildren().

Parameters:

context - FacesContext for the request we are processing

Throws:

NullPointerException - if context is null

abstract public void processUpdates(FacesContext context)

按如下操作，对此组件的所有 facet、此组件的所有子组件和此组件本身执行请求处理生命周期的更新模型值 阶段所需的组件树处理。

• 如果此 UIComponent 的 rendered 属性为 false，则跳过进一步的处理。
• 按照调用 getFacetsAndChildren() 所确定的顺序，调用此 UIComponent 的所有 facet 和子组件的 processUpdates() 方法。

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

英文文档：

processUpdates

public abstract void processUpdates(FacesContext context)

Perform the component tree processing required by the Update Model Values phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.

• If the rendered property of this UIComponent is false, skip further processing.
• Call the processUpdates() method of all facets and children of this UIComponent, in the order determined by a call to getFacetsAndChildren().

Parameters:

context - FacesContext for the request we are processing

Throws:

NullPointerException - if context is null

abstract public Object processSaveState(FacesContext context)

按如下操作，对此组件的所有 facet、此组件的所有子组件和此组件本身执行请求处理生命周期的呈现响应 阶段的状态保存部分所需的组件树处理。

• 参考此组件的 transient 属性。如果为 true，则仅返回 null。
• 按照调用 getFacetsAndChildren() 所确定的顺序，调用此 UIComponent 的所有 facet 和子组件的 processSaveState() 方法，跳过瞬态的子组件和 facet。
• 调用此组件的 saveState() 方法。
• 将子状态和所处状态封装到 Serializable Object 中并将其返回。

如果状态保存方法被设置为服务器，则可能不能调用此方法。

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

英文文档：

processSaveState

public abstract Object processSaveState(FacesContext context)

Perform the component tree processing required by the state saving portion of the Render Response phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.

• consult the transient property of this component. If true, just return null.
• Call the processSaveState() method of all facets and children of this UIComponent in the order determined by a call to getFacetsAndChildren(), skipping children and facets that are transient.
• Call the saveState() method of this component.
• Encapsulate the child state and your state into a Serializable Object and return it.

This method may not be called if the state saving method is set to server.

Parameters:

context - FacesContext for the request we are processing

Throws:

NullPointerException - if context is null

abstract protected FacesContext getFacesContext()

一个便捷方法，返回当前请求的 FacesContext 实例。

英文文档：

getFacesContext

protected abstract FacesContext getFacesContext()

Convenience method to return the FacesContext instance for the current request.

abstract protected Renderer getRenderer(FacesContext context)

一个便捷方法，返回与此组件关联的 Renderer 实例（如果有）；否则返回 null。

context

当前请求的 FacesContext

英文文档：

getRenderer

protected abstract Renderer getRenderer(FacesContext context)

Convenience method to return the Renderer instance associated with this component, if any; otherwise, return null.

Parameters:

context - FacesContext for the current request

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