Package javax.faces.component

Class UIComponentBase

java.lang.Object
javax.faces.component.UIComponent
javax.faces.component.UIComponentBase
All Implemented Interfaces:
EventListener, PartialStateHolder, StateHolder, TransientStateHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder
Direct Known Subclasses:
UIColumn, UICommand, UIData, UIForm, UIGraphic, UIMessage, UIMessages, UINamingContainer, UIOutput, UIPanel, UIParameter, UISelectItem, UISelectItems, UIViewAction, UIViewRoot
public abstract class UIComponentBase extends UIComponent

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.

  • Constructor Details

    • UIComponentBase

      public UIComponentBase()

  • Method Details

    • 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

    • getPassThroughAttributes

      public Map<String,Object> getPassThroughAttributes(boolean create)
      Description copied from class: UIComponent

      This method has the same specification as UIComponent.getPassThroughAttributes() except that it is allowed to return null if and only if the argument create is false and no pass through attribute data structure exists for this instance. The returned Map implementation must support all of the standard and optional Map methods, plus support the following additional requirements. The map must be stored in using UIComponent.getStateHelper().

      The Map implementation must implement java.io.Serializable.

      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 an IllegalArgumentException.

      For backward compatibility with components that extend directly from this class, a default implementation is provided that returns the empty map.

      Overrides:
      getPassThroughAttributes in class UIComponent
      Parameters:
      create - if true, a new Map instance will be created if it does not exist already. If false, and there is no existing Map instance, one will not be created and null will be returned.
      Returns:
      A Map instance, or null.

    • 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

    • 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

    • 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 + UINamingContainer.getSeparatorChar(javax.faces.context.FacesContext) + 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

    • getId

      public String getId()
      Description copied from class: UIComponent

      Return the component identifier of this UIComponent.

      Specified by:
      getId in class UIComponent

    • 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

    • 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

    • setParent

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

      Set the parent UIComponent of this UIComponent. If parent.isInView() returns true, calling this method will first cause a PreRemoveFromViewEvent to be published, for this node, and then the children of this node. Then, once the re-parenting has occurred, a PostAddToViewEvent will be published as well, first for this node, and then for the node's children, but only if any of the following conditions are true.

      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

    • 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

    • 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

    • getRendererType

      public String getRendererType()
      Description copied from class: UIComponent

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

      Specified by:
      getRendererType in class UIComponent

    • 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

    • 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

    • 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:

      Specified by:
      getChildren in class UIComponent

    • 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

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

      WARNING: The found UIComponent instance, if any, is returned without regard for its tree traversal context. Retrieving an EL-bound attribute from the component is not safe. EL expressions can contain implicit objects, such as #{component}, which assume they are being evaluated within the scope of a tree traversal context. Evaluating expressions with these kinds of implicit objects outside of a tree traversal context produces undefined results. See UIComponent.invokeOnComponent(javax.faces.context.FacesContext, java.lang.String, javax.faces.component.ContextCallback) for a method that does correctly account for the tree traversal context when operating on the found UIComponent instance. UIComponent.invokeOnComponent(javax.faces.context.FacesContext, java.lang.String, javax.faces.component.ContextCallback) is also useful to find components given a simple clientId.

      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 UINamingContainer.getSeparatorChar(javax.faces.context.FacesContext) 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

    • 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 UINamingContainer.getSeparatorChar(javax.faces.context.FacesContext) 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, first call UIComponent.pushComponentToEL(javax.faces.context.FacesContext, javax.faces.component.UIComponent), then 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. Then call UIComponent.popComponentFromEL(javax.faces.context.FacesContext). 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 invokeContextCallback(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

    • 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

    • 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

    • 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

    • 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

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

      If the event is an instance of BehaviorEvent and the current component is the source of the event call BehaviorEvent.getBehavior() to get the Behavior for the event. Call Behavior.broadcast(javax.faces.event.BehaviorEvent) on the Behavior instance.

      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

    • 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

    • 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. Call UIComponent.pushComponentToEL(javax.faces.context.FacesContext,javax.faces.component.UIComponent). Call Application.publishEvent(javax.faces.context.FacesContext, java.lang.Class<? extends javax.faces.event.SystemEvent>, java.lang.Object), passing PreRenderComponentEvent.class as the first argument and the component instance to be rendered as the second argument.

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

      If our rendered property is false, call UIComponent.pushComponentToEL(javax.faces.context.FacesContext,javax.faces.component.UIComponent) and return immediately.