Class UIComponentBase

    • Constructor Detail

      • UIComponentBase

        public UIComponentBase​()
    • Method Detail

      • getAttributes

        public java.util.Map<java.lang.String,java.lang.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
        Returns:
        the component attribute map.
      • getPassThroughAttributes

        public java.util.Map<java.lang.String,java.lang.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.
      • getClientId

        public java.lang.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
        Returns:
        the client id.
        Throws:
        java.lang.NullPointerException - if context is null
      • getId

        public java.lang.String getId​()
        Description copied from class: UIComponent

        Return the component identifier of this UIComponent.

        Specified by:
        getId in class UIComponent
        Returns:
        the component identifier.
      • setId

        public void setId​(java.lang.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:
        java.lang.IllegalArgumentException - if id is not syntactically valid
        java.lang.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
        Returns:
        the parent component.
      • 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
        Returns:
        true if the component should be rendered, false otherwise.
      • 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
      • setRendererType

        public void setRendererType​(java.lang.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
        Returns:
        true if the component renders its children, false otherwise.
      • 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
        Returns:
        the number of child components.
      • findComponent

        public UIComponent findComponent​(java.lang.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:
        java.lang.NullPointerException - if expr is null
      • getFacets

        public java.util.Map<java.lang.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
        Returns:
        the map of facets.
      • 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
        Returns:
        the number of facets.
      • getFacet

        public UIComponent getFacet​(java.lang.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
        Returns:
        the component, or null.
      • getFacetsAndChildren

        public java.util.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
        Returns:
        the facets and children iterator.
      • 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:
        java.lang.NullPointerException - if context is null
      • 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:
        java.lang.NullPointerException - if listener is null
      • getFacesListeners

        protected FacesListener[] getFacesListeners​(java.lang.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
        Returns:
        the Faces listeners, or a zero-length array.
        Throws:
        java.lang.IllegalArgumentException - if class is not, and does not implement, FacesListener
        java.lang.NullPointerException - if clazz is null
      • 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:
        java.lang.IllegalStateException - if this component is not a descendant of a UIViewRoot
        java.lang.NullPointerException - if event is null
      • unsubscribeFromEvent

        public void unsubscribeFromEvent​(java.lang.Class<? extends SystemEvent> eventClass,
                                         ComponentSystemEventListener componentListener)

        Remove the listener instance referenced by argument componentListener as a listener for events of type eventClass originating from this specific instance of UIComponent. When doing the comparison to determine if an existing listener is equal to the argument componentListener (and thus must be removed), the equals() method on the existing listener must be invoked, passing the argument componentListener, rather than the other way around.

        Overrides:
        unsubscribeFromEvent in class UIComponent
        Parameters:
        eventClass - the Class of event for which listener must be removed.
        componentListener - the implementation of ComponentSystemEventListener whose ComponentSystemEventListener.processEvent(javax.faces.event.ComponentSystemEvent) method must no longer be called when events of type eventClass are fired.
        Throws:
        java.lang.NullPointerException - if any of the arguments are null.
        Since:
        2.1
      • getListenersForEventClass

        public java.util.List<SystemEventListener> getListenersForEventClass​(java.lang.Class<? extends SystemEvent> eventClass)

        Return the SystemEventListener instances registered on this UIComponent instance that are interested in events of type eventClass.

        Specified by:
        getListenersForEventClass in interface SystemEventListenerHolder
        Overrides:
        getListenersForEventClass in class UIComponent
        Parameters:
        eventClass - the Class of event for which the listeners must be returned.
        Returns:
        the list of listeners.
        Throws:
        java.lang.NullPointerException - if argument eventClass is null.
        Since:
        2.1
      • processSaveState

        public java.lang.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.

        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
        Returns:
        the saved state.
        Throws:
        java.lang.NullPointerException - if context is null
      • 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
        Returns:
        the renderer, or null.
      • saveState

        public java.lang.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

        Parameters:
        context - the Faces context.
        Returns:
        the saved state.
      • restoreState

        public void restoreState​(FacesContext context,
                                 java.lang.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.

        If the state argument is null, take no action and return.

        Parameters:
        context - the Faces context.
        state - the state.
      • isTransient

        public boolean isTransient​()
        Description copied from interface: StateHolder

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

        Returns:
        true if transient, false otherwise.
      • 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 not participate in state saving or restoring, otherwise pass false.
      • saveAttachedState

        public static java.lang.Object saveAttachedState​(FacesContext context,
                                                         java.lang.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 Collections of these objects. If any contained objects are not Collections 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.
        Returns:
        The state object to be saved.
        Throws:
        java.lang.NullPointerException - if the context argument is null.
      • getEventNames

        public java.util.Collection<java.lang.String> getEventNames​()

        This is a default implementation of ClientBehaviorHolder.getEventNames(). UIComponent does not implement the ClientBehaviorHolder interface, but provides default implementations for the methods defined by ClientBehaviorHolder to simplify subclass implementations. Subclasses that wish to support the ClientBehaviorHolder contract must declare that the subclass implements ClientBehaviorHolder, and must override this method to return a non-Empty Collection of the client event names that the component supports.

        Returns:
        the collection of event names.
        Since:
        2.0