UIComponentBase (Java EE 5)

Java EE API


javax.faces.component Class UIComponentBase

java.lang.Object
  extended by javax.faces.component.UIComponent
      extended by javax.faces.component.UIComponentBase
All Implemented Interfaces:
StateHolder
Direct Known Subclasses:
UIColumn, UICommand, UIData, UIForm, UIGraphic, UIMessage, UIMessages, UINamingContainer, UIOutput, UIPanel, UIParameter, UISelectItem, UISelectItems, UIViewRoot

public abstract class UIComponentBase
extends UIComponent

Extends: UIComponent

UIComponentBase 是一个便捷基类,实现 UIComponent 定义的所有方法的默认具体行为。

默认情况下,此类定义 getRendersChildren() 以查找此组件的 renderer 并调用其 getRendersChildren() 方法。Renderer 上的默认实现返回 false。自 JavaServer Faces 规范 1.2 版起,鼓励组件编写者从此方法返回 true,并依赖于此类和 Renderer 中的 #encodeChildren 的实现 (Renderer#encodeChildren)。相反,要管理其子组件呈现的子类应重写此方法以返回 true

英文文档:

UIComponentBase is a convenience base class that implements the default concrete behavior of all methods defined by UIComponent.

By default, this class defines getRendersChildren() to find the renderer for this component and call its getRendersChildren() method. The default implementation on the Renderer 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 the implementation of encodeChildren(javax.faces.context.FacesContext) in this class and in the Renderer (Renderer.encodeChildren(javax.faces.context.FacesContext, javax.faces.component.UIComponent)). Subclasses that wish to manage the rendering of their children should override this method to return true instead.


Field Summary
 
Fields inherited from class javax.faces.component.UIComponent
 
Constructor Summary
 
Method Summary
protected  void
 void
 void
 void
 void
 void
 UIComponent
 Map<String,Object>
 int
 List<UIComponent>
 String
protected  FacesContext
protected  FacesListener[]
 UIComponent
 int
 Map<String,UIComponent>
 Iterator<UIComponent>
 String
 UIComponent
protected  Renderer
 String
 boolean
 ValueBinding
 boolean
 boolean
 boolean
 void
 void
 Object
 void
 void
 void
protected  void
static Object
 void
static Object
 Object
 void
 void
 void
 void
 void
 void
 
Methods inherited from class javax.faces.component.UIComponent
 
Methods inherited from class java.lang.Object
 

Constructor Detail

public UIComponentBase()
英文文档:

UIComponentBase

public UIComponentBase()
Method Detail

public java.util.Map<K, V> getAttributes()
英文文档:

getAttributes

public Map<String,Object> getAttributes()
Description copied from class: UIComponent

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.

Specified by:
getAttributes in class UIComponent

public ValueBinding getValueBinding(String name)
NullPointerException

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

ThrowsNullPointerException: NullPointerException 如果 namenull
deprecated 此方法已由 #getValueExpression 替代。
英文文档:

getValueBinding

public ValueBinding getValueBinding(String name)
Deprecated. This has been replaced by UIComponent.getValueExpression(java.lang.String).

Call through to UIComponent.getValueExpression(java.lang.String) and examine the result. If the result is an instance of the wrapper class mandated in UIComponent.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.

Specified by:
getValueBinding in class UIComponent
Parameters:
name - Name of the attribute or property for which to retrieve a ValueBinding
Throws:
NullPointerException - if name is null

public void setValueBinding(String name, ValueBinding binding)
NullPointerException

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

ThrowsIllegalArgumentException: NullPointerException 如果 nameidparent 之一
ThrowsNullPointerException: NullPointerException 如果 namenull
deprecated 此方法已由 #setValueExpression 替代。
英文文档:

setValueBinding

public void setValueBinding(String name,
                            ValueBinding binding)
Deprecated. This has been replaced by UIComponent.setValueExpression(java.lang.String, javax.el.ValueExpression).

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

Specified by:
setValueBinding in class UIComponent
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 String getClientId(FacesContext context)
ThrowsNullPointerException: NullPointerException 如果 contextnull
英文文档:

getClientId

public String getClientId(FacesContext context)
Description copied from class: UIComponent

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 UIComponent.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.

Specified by:
getClientId in class UIComponent
Parameters:
context - The FacesContext for the current request
Throws:
NullPointerException - if context is null

public String getId()
英文文档:

getId

public String getId()
Description copied from class: UIComponent

Return the component identifier of this UIComponent.

Specified by:
getId in class UIComponent

public void setId(String id)
ThrowsIllegalArgumentException: NullPointerException 如果 id 语法无效
ThrowsIllegalStateException: NullPointerException
英文文档:

setId

public void setId(String id)
Description copied from class: UIComponent

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.

Specified by:
setId in class UIComponent
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
IllegalStateException

public UIComponent getParent()
英文文档:

getParent

public UIComponent getParent()
Description copied from class: UIComponent

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( ).

Specified by:
getParent in class UIComponent

public void setParent(UIComponent parent)
英文文档:

setParent

public void setParent(UIComponent parent)
Description copied from class: UIComponent

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.

Specified by:
setParent in class UIComponent
Parameters:
parent - The new parent, or null for the root node of a component tree

public boolean isRendered()
英文文档:

isRendered

public boolean isRendered()
Description copied from class: UIComponent

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

Specified by:
isRendered in class UIComponent

public void setRendered(boolean rendered)
英文文档:

setRendered

public void setRendered(boolean rendered)
Description copied from class: UIComponent

Set the rendered property of this UIComponent.

Specified by:
setRendered in class UIComponent
Parameters:
rendered - If true render this component; otherwise, do not render this component

public String getRendererType()
英文文档:

getRendererType

public String getRendererType()
Description copied from class: UIComponent

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

Specified by:
getRendererType in class UIComponent

public void setRendererType(String rendererType)
英文文档:

setRendererType

public void setRendererType(String rendererType)
Description copied from class: UIComponent

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

Specified by:
setRendererType in class UIComponent
Parameters:
rendererType - Logical identifier of the type of Renderer to use, or null for components that render themselves

public boolean getRendersChildren()
英文文档:

getRendersChildren

public boolean getRendersChildren()
Description copied from class: UIComponent

Return a flag indicating whether this component is responsible for rendering its child components. The default implementation in 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 encodeChildren(javax.faces.context.FacesContext).

Specified by:
getRendersChildren in class UIComponent

public java.util.List<E> getChildren()
英文文档:

getChildren

public List<UIComponent> getChildren()
Description copied from class: UIComponent

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.

Specified by:
getChildren in class UIComponent

public int getChildCount()
英文文档:

getChildCount

public int getChildCount()
Description copied from class: UIComponent

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.

Specified by:
getChildCount in class UIComponent

public UIComponent findComponent(String expr)
ThrowsNullPointerException: NullPointerException 如果 exprnull
英文文档:

findComponent

public UIComponent findComponent(String expr)
Description copied from class: UIComponent

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 UIComponent.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.

Specified by:
findComponent in class UIComponent
Parameters:
expr - Search expression identifying the UIComponent to be returned
Returns:
the found UIComponent, or null if the component was not found.
Throws:
NullPointerException - if expr is null

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

在视图层次结构中从此组件开始,搜索 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;
         }
      });
}
 
since1.2
ThrowsNullPointerException: NullPointerException 如果任何参数为 null
ThrowsFacesException: NullPointerException 如果参数 Callback 抛出 Exception,则将在 FacesException 中包装它并将其重新抛出。
英文文档:

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 UIComponent.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 UIComponent.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 UIComponent.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;
         }
      });
}
 

Overrides:
invokeOnComponent in class UIComponent
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

public java.util.Map<K, V> getFacets()
英文文档:

getFacets

public Map<String,UIComponent> getFacets()
Description copied from class: UIComponent

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.

Specified by:
getFacets in class UIComponent

public int getFacetCount()
英文文档:

getFacetCount

public int getFacetCount()
Description copied from class: UIComponent

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 UIComponent.getFacets() and then calls the size() method on the returned Map. A more optimized version of this method is provided in getFacetCount().

Overrides:
getFacetCount in class UIComponent

public UIComponent getFacet(String name)
英文文档:

getFacet

public UIComponent getFacet(String name)
Description copied from class: UIComponent

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.

Specified by:
getFacet in class UIComponent
Parameters:
name - Name of the desired facet

public java.util.Iterator<E> getFacetsAndChildren()
英文文档:

getFacetsAndChildren

public Iterator<UIComponent> getFacetsAndChildren()
Description copied from class: UIComponent

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.

Specified by:
getFacetsAndChildren in class UIComponent

public void broadcast(FacesEvent event) throws AbortProcessingException
ThrowsAbortProcessingException: NullPointerException 通知 JavaServer Face 实现不应该继续处理当前事件
ThrowsIllegalStateException: NullPointerException
ThrowsNullPointerException: NullPointerException 如果 eventnull
英文文档:

broadcast

public void broadcast(FacesEvent event)
               throws AbortProcessingException
Description copied from class: UIComponent

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.

Specified by:
broadcast in class UIComponent
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
IllegalStateException
NullPointerException - if event is null

public void decode(FacesContext context)
ThrowsNullPointerException: NullPointerException 如果 contextnull
英文文档:

decode

public void decode(FacesContext context)
Description copied from class: UIComponent

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().

Specified by:
decode in class UIComponent
Parameters:
context - FacesContext for the request we are processing
Throws:
NullPointerException - if context is null

public void encodeBegin(FacesContext context) throws java.io.IOException
ThrowsNullPointerException: NullPointerException 如果 contextnull
英文文档:

encodeBegin

public void encodeBegin(FacesContext context)
                 throws IOException
Description copied from class: UIComponent

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).

Specified by:
encodeBegin in class UIComponent
Parameters:
context - FacesContext for the response we are creating
Throws:
NullPointerException - if context is null
IOException - if an input/output error occurs while rendering

public void encodeChildren(FacesContext context) throws java.io.IOException
ThrowsNullPointerException: NullPointerException 如果 contextnull
英文文档:

encodeChildren

public void encodeChildren(FacesContext context)
                    throws IOException
Description copied from class: UIComponent

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).

Specified by:
encodeChildren in class UIComponent
Parameters:
context - FacesContext for the response we are creating
Throws:
NullPointerException - if context is null
IOException - if an input/output error occurs while rendering

public void encodeEnd(FacesContext context) throws java.io.IOException
Throwsjava.io.IOException: NullPointerException 如果呈现期间发生输入/输出错误
ThrowsNullPointerException: NullPointerException 如果 contextnull
英文文档:

encodeEnd

public void encodeEnd(FacesContext context)
               throws IOException
Description copied from class: UIComponent

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).

Specified by:
encodeEnd in class 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

protected void addFacesListener(FacesListener listener)

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

public class FooEvent extends FacesEvent {
   ...
protected boolean isAppropriateListener(FacesListener listener) {
return (listener instanceof FooListener);
   }
protected void processListener(FacesListener listener) {
((FooListener) listener).processFoo(this);
   }
   ...
 }

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
ThrowsNullPointerException: 如果 listenernull
英文文档:

addFacesListener

protected 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 {
   ...
   protected boolean isAppropriateListener(FacesListener listener) {
     return (listener instanceof FooListener);
   }
   protected void processListener(FacesListener listener) {
     ((FooListener) listener).processFoo(this);
   }
   ...
 }

 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);
   }
   ...
 }
 

Specified by:
addFacesListener in class UIComponent
Parameters:
listener - The FacesListener to be registered
Throws:
NullPointerException - if listener is null

protected FacesListener[] getFacesListeners(Class<T> clazz)
ThrowsIllegalArgumentException: NullPointerException 如果 clazz 不是 FacesListener 并且未实现 FacesListener
ThrowsNullPointerException: NullPointerException 如果 clazznull
英文文档:

getFacesListeners

protected FacesListener[] getFacesListeners(Class clazz)
Description copied from class: UIComponent

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.

Specified by:
getFacesListeners in class UIComponent
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

protected void removeFacesListener(FacesListener listener)

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

listener 要取消注册的 FacesListener
ThrowsNullPointerException: 如果 listenernull

英文文档:

removeFacesListener

protected void removeFacesListener(FacesListener listener)

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

Specified by:
removeFacesListener in class UIComponent
Parameters:
listener - The FacesListener to be deregistered
Throws:
NullPointerException - if listener is null

public void queueEvent(FacesEvent event)
ThrowsIllegalStateException: NullPointerException 如果此组件不是 UIViewRoot 的后代
ThrowsNullPointerException: NullPointerException 如果 eventnull
英文文档:

queueEvent

public void queueEvent(FacesEvent event)
Description copied from class: UIComponent

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.

Specified by:
queueEvent in class UIComponent
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)
ThrowsNullPointerException: NullPointerException 如果 contextnull
英文文档:

processDecodes

public void processDecodes(FacesContext context)
Description copied from class: UIComponent

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.

Specified by:
processDecodes in class UIComponent
Parameters:
context - FacesContext for the request we are processing
Throws:
NullPointerException - if context is null

public void processValidators(FacesContext context)
ThrowsNullPointerException: NullPointerException 如果 contextnull
英文文档:

processValidators

public void processValidators(FacesContext context)
Description copied from class: UIComponent

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().

Specified by:
processValidators in class UIComponent
Parameters:
context - FacesContext for the request we are processing
Throws:
NullPointerException - if context is null

public void processUpdates(FacesContext context)
ThrowsNullPointerException: NullPointerException 如果 contextnull
英文文档:

processUpdates

public void processUpdates(FacesContext context)
Description copied from class: UIComponent

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().

Specified by:
processUpdates in class UIComponent
Parameters:
context - FacesContext for the request we are processing
Throws:
NullPointerException - if context is null

public Object processSaveState(FacesContext context)
ThrowsNullPointerException: NullPointerException 如果 contextnull
英文文档:

processSaveState

public Object processSaveState(FacesContext context)
Description copied from class: UIComponent

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.

Specified by:
processSaveState in class UIComponent
Parameters:
context - FacesContext for the request we are processing
Throws:
NullPointerException - if context is null

public void processRestoreState(FacesContext context, Object state)
ThrowsNullPointerException: NullPointerException 如果 contextnull
英文文档:

processRestoreState

public void processRestoreState(FacesContext context,
                                Object state)
Description copied from class: UIComponent

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.

Specified by:
processRestoreState in class UIComponent
Parameters:
context - FacesContext for the request we are processing
Throws:
NullPointerException - if context is null

protected FacesContext getFacesContext()
英文文档:

getFacesContext

protected FacesContext getFacesContext()
Description copied from class: UIComponent

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

Specified by:
getFacesContext in class UIComponent

protected Renderer getRenderer(FacesContext context)
英文文档:

getRenderer

protected Renderer getRenderer(FacesContext context)
Description copied from class: UIComponent

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

Specified by:
getRenderer in class UIComponent
Parameters:
context - FacesContext for the current request

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


public void restoreState(FacesContext context, Object state)
英文文档:

restoreState

public void restoreState(FacesContext context,
                         Object state)
Description copied from interface: StateHolder

Perform any processing required to restore the state from the entries in the state Object.

If the class that implements this interface has references to instances that also implement StateHolder (such as a UIComponent with event handlers, validators, etc.) this method must call the StateHolder.restoreState(javax.faces.context.FacesContext, java.lang.Object) method on all those instances as well.


public boolean isTransient()
英文文档:

isTransient

public boolean isTransient()
Description copied from interface: StateHolder

If true, the Object implementing this interface must not participate in state saving or restoring.


public void setTransient(boolean transientFlag)
英文文档:

setTransient

public void setTransient(boolean transientFlag)
Description copied from interface: StateHolder

Denotes whether or not the Object implementing this interface must or must not participate in state saving or restoring.

Parameters:
transientFlag - boolean pass true if this Object will participate in state saving or restoring, otherwise pass false.

public static Object saveAttachedState(FacesContext context, Object attachedObject)

此方法由要保存一个或多个连接对象的 UIComponent 子类调用。这是个便捷方法,完成保存可能实现也可能不实现 StateHolder 接口的连接对象的工作。使用此方法意味着使用 #restoreAttachedState 恢复连接对象。

此方法支持保存下列类型的连接对象:这些对象的 Objectnull 值和 Lists。如果任何包含的对象不是 Lists 且没有实现 StateHolder,则它们必须有不带参数的公共构造方法。返回对象的确切结构是未定义和透明的,但可进行序列化。

context 此请求的 FacesContext
attachedObject 对象,可能是 List 实例或 Object。attachedObject(或包含 attachedObject 的元素)可以实现 StateHolder
ThrowsNullPointerException: 如果上下文参数为 null。
英文文档:

saveAttachedState

public static Object saveAttachedState(FacesContext context,
                                       Object attachedObject)

This method is called by UIComponent subclasses that want to save one or more attached objects. It is a convenience method that does the work of saving attached objects that may or may not implement the StateHolder interface. Using this method implies the use of restoreAttachedState(javax.faces.context.FacesContext, java.lang.Object) to restore the attached objects.

This method supports saving attached objects of the following type: Objects, null values, and Lists of these objects. If any contained objects are not Lists and do not implement StateHolder, they must have zero-argument public constructors. The exact structure of the returned object is undefined and opaque, but will be serializable.

Parameters:
context - the FacesContext for this request.
attachedObject - the object, which may be a List instance, or an Object. The attachedObject (or the elements that comprise attachedObject may implement StateHolder.
Throws:
NullPointerException - if the context argument is null.

public static Object restoreAttachedState(FacesContext context, Object stateObj) throws IllegalStateException

此方法由 UIComponent 子类调用,该子类需要恢复它们使用 #saveAttachedState 保存的对象。此方法与 #saveAttachedState 紧密耦合。

此方法支持恢复 #saveAttachedState 支持的所有连接对象类型。

context 此请求的 FacesContext
stateObj#saveAttachedState 返回的透明对象
ThrowsNullPointerException: 如果 context 为 null。
ThrowsIllegalStateException: 如果该对象不是以前由 #saveAttachedState 返回的。
英文文档:

restoreAttachedState

public static Object restoreAttachedState(FacesContext context,
                                          Object stateObj)
                                   throws IllegalStateException

This method is called by UIComponent subclasses that need to restore the objects they saved using saveAttachedState(javax.faces.context.FacesContext, java.lang.Object). This method is tightly coupled with saveAttachedState(javax.faces.context.FacesContext, java.lang.Object).

This method supports restoring all attached objects types supported by saveAttachedState(javax.faces.context.FacesContext, java.lang.Object).

Parameters:
context - the FacesContext for this request
stateObj - the opaque object returned from saveAttachedState(javax.faces.context.FacesContext, java.lang.Object)
Throws:
NullPointerException - if context is null.
IllegalStateException - if the object is not previously returned by saveAttachedState(javax.faces.context.FacesContext, java.lang.Object).


Submit a bug or feature

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

一看就知道只有菜鸟才干这么无知的事啦。

PS : 未经我党受权你也可自由散发此文档。 如有任何错误请自行修正;若因此而造成任何损失请直接找人民主席,请勿与本人联系。谢谢!