javax.faces.component

## Class UIComponent

- java.lang.Object
- - javax.faces.component.UIComponent

- All Implemented Interfaces:
    EventListener, PartialStateHolder, StateHolder, TransientStateHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder
  Direct Known Subclasses:
    UIComponentBase

      public abstract class UIComponent
      extends Object
      implements PartialStateHolder, TransientStateHolder, SystemEventListenerHolder, ComponentSystemEventListener

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

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

  If the `ListenerFor` annotation is attached to the class definition of a `Component`, that class must also implement `ComponentSystemEventListener`.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `ATTRS_WITH_DECLARED_DEFAULT_VALUES` This constant enables one to quickly discover the names of the declared composite component attributes that have been given default values by the composite component author.
    `static String` | `BEANINFO_KEY` The value of this constant is used as the key in the component attribute map, the value for which is a `java.beans.BeanInfo` implementation describing the composite component.
    `protected Map<String,ValueExpression>` | `bindings` Deprecated.
    `static String` | `COMPOSITE_COMPONENT_TYPE_KEY` The value of this constant is used as the key in the composite component BeanDescriptor for a `ValueExpression` that evaluates to the `component-type` of the composite component root `UIComponent` for this composite component, if one was declared by the composite component author.
    `static String` | `COMPOSITE_FACET_NAME` The value of this constant is used as the key in the `Map` returned as described in `FACETS_KEY` for the `PropertyDescriptor` describing the composite component facet.
    `static String` | `CURRENT_COMPONENT` Deprecated.
    `static String` | `CURRENT_COMPOSITE_COMPONENT` Deprecated.
    `static String` | `FACETS_KEY` The value of this constant is used as the key in the composite component BeanDescriptor for the `Map<PropertyDescriptor>` that contains meta-information for the declared facets for this composite component.
    `static String` | `HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME` The `ServletContext` init parameter consulted by the `UIComponent` to tell whether or not the `CURRENT_COMPONENT` and `CURRENT_COMPOSITE_COMPONENT` attribute keys should be honored as specified.
    `static String` | `VIEW_LOCATION_KEY` The value of this constant is used as the key in the component attributes `Map` for the `Location` in the view at which this component instance resides.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `UIComponent()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected abstract void` | `addFacesListener(FacesListener listener)` Add the specified `FacesListener` to the set of listeners registered to receive event notifications from this `UIComponent`.
    `abstract void` | `broadcast(FacesEvent event)` Broadcast the specified `FacesEvent` to all registered event listeners who have expressed an interest in events of this type.
    `void` | `clearInitialState()` An implementation of `PartialStateHolder.clearInitialState()`, this method is called by the runtime to tell the instance to stop tracking state changes.
    `abstract void` | `decode(FacesContext context)` Decode any new state of this `UIComponent` from the request contained in the specified `FacesContext`, and store this state as needed.
    `void` | `encodeAll(FacesContext context)` If this component returns `true` from `isRendered()`, take the following action.
    `abstract void` | `encodeBegin(FacesContext context)` If our `rendered` property is `true`, render the beginning of the current state of this `UIComponent` to the response contained in the specified `FacesContext`.
    `abstract void` | `encodeChildren(FacesContext context)` If our `rendered` property is `true`, render the child `UIComponent`s of this `UIComponent`.
    `abstract void` | `encodeEnd(FacesContext context)` If our `rendered` property is `true`, render the ending of the current state of this `UIComponent`.
    `abstract UIComponent` | `findComponent(String expr)` Search for and return the `UIComponent` with an `id` that matches the specified search expression (if any), according to the algorithm described below.
    `abstract Map<String,Object>` | `getAttributes()` Return a mutable `Map` representing the attributes (and properties, see below) associated wth this `UIComponent`, keyed by attribute name (which must be a String).
    `abstract int` | `getChildCount()` Return the number of child `UIComponent`s that are associated with this `UIComponent`.
    `abstract List<UIComponent>` | `getChildren()` Return a mutable `List` representing the child `UIComponent`s associated with this component.
    `String` | `getClientId()` Enable EL to access the `clientId` of a component.
    `abstract String` | `getClientId(FacesContext context)` Return a client-side identifier for this component, generating one if necessary.
    `static UIComponent` | `getCompositeComponentParent(UIComponent component)` Finds the nearest composite component parent of the specified component.
    `String` | `getContainerClientId(FacesContext context)` Allow components that implement `NamingContainer` to selectively disable prepending their clientId to their descendent's clientIds by breaking the prepending logic into a seperately callable method.
    `static UIComponent` | `getCurrentComponent(FacesContext context)` Return the `UIComponent` instance that is currently processing.
    `static UIComponent` | `getCurrentCompositeComponent(FacesContext context)` Return the closest ancestor component, relative to the component returned from `getCurrentComponent(javax.faces.context.FacesContext)`, that is a composite component, or `null` if no such component exists.
    `protected abstract FacesContext` | `getFacesContext()` Convenience method to return the `FacesContext` instance for the current request.
    `protected abstract FacesListener[]` | `getFacesListeners(Class clazz)` Return an array of registered `FacesListener`s that are instances of the specified class.
    `abstract UIComponent` | `getFacet(String name)` Convenience method to return the named facet, if it exists, or `null` otherwise.
    `int` | `getFacetCount()` Return the number of facet `UIComponent`s that are associated with this `UIComponent`.
    `abstract Map<String,UIComponent>` | `getFacets()` Return a mutable `Map` representing the facet `UIComponent`s associated with this `UIComponent`, keyed by facet name (which must be a String).
    `abstract Iterator<UIComponent>` | `getFacetsAndChildren()` Return an `Iterator` over the facet followed by child `UIComponent`s of this `UIComponent`.
    `abstract String` | `getFamily()` Return the identifier of the component family to which this component belongs.
    `abstract String` | `getId()` Return the component identifier of this `UIComponent`.
    `List<SystemEventListener>` | `getListenersForEventClass(Class<? extends SystemEvent> eventClass)` This implementation throws `UnsupportedOperationException` and is provided for the sole purpose of not breaking existing applications that extend this class.
    `UIComponent` | `getNamingContainer()` Starting with "this", return the closest component in the ancestry that is a `NamingContainer` or `null` if none can be found.
    `abstract UIComponent` | `getParent()` Return the parent `UIComponent` of this `UIComponent`, if any.
    `Map<String,Object>` | `getPassThroughAttributes()` This is a convenience method that simply calls `getPassThroughAttributes(boolean)`, passing `true` as the argument.
    `Map<String,Object>` | `getPassThroughAttributes(boolean create)` This method has the same specification as `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.
    `protected abstract Renderer` | `getRenderer(FacesContext context)` Convenience method to return the `Renderer` instance associated with this component, if any; otherwise, return `null`.
    `abstract String` | `getRendererType()` Return the `Renderer` type for this `UIComponent` (if any).
    `abstract boolean` | `getRendersChildren()` Return a flag indicating whether this component is responsible for rendering its child components.
    `Map<String,String>` | `getResourceBundleMap()` Return a `Map<String,String>` of the `ResourceBundle` for this component.
    `protected StateHelper` | `getStateHelper()` Return the `StateHelper` instance used to help this component implement `PartialStateHolder`.
    `protected StateHelper` | `getStateHelper(boolean create)` Like `getStateHelper()`, but only create a state helper instance if the argument `creat` is `true`.
    `TransientStateHelper` | `getTransientStateHelper()` Return the `TransientStateHelper` instance for this `UIComponent` instance.
    `TransientStateHelper` | `getTransientStateHelper(boolean create)` Return the `TransientStateHelper` instance for this `UIComponent` instance.
    `abstract ValueBinding` | `getValueBinding(String name)` Deprecated. This has been replaced by `getValueExpression(java.lang.String)`.
    `ValueExpression` | `getValueExpression(String name)` Return the `ValueExpression` used to calculate the value for the specified attribute or property name, if any.
    `boolean` | `initialStateMarked()` An implementation of `PartialStateHolder.initialStateMarked()`, this method is called by the runtime to test if the `PartialStateHolder.markInitialState()` method was called.
    `boolean` | `invokeOnComponent(FacesContext context, String clientId, ContextCallback callback)` 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.
    `static boolean` | `isCompositeComponent(UIComponent component)` Return `true` if `component` is a composite component, otherwise `false`.
    `boolean` | `isInView()` Return `true` if this component is within the view hierarchy otherwise `false`
    `abstract boolean` | `isRendered()` Return `true` if this component (and its children) should be rendered during the Render Response phase of the request processing lifecycle.
    `protected boolean` | `isVisitable(VisitContext context)` Return `true` if this component should be visited, `false` otherwise.
    `void` | `markInitialState()` An implementation of `PartialStateHolder.markInitialState()`, this method is called by the runtime to indicate that the instance should start tracking changes to its state.
    `void` | `popComponentFromEL(FacesContext context)` Pop the current `UIComponent` from the `FacesContext` attributes map so that the previous `UIComponent`, if any, becomes the current component.
    `abstract void` | `processDecodes(FacesContext context)` Perform the component tree processing required by the Apply Request Values phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
    `void` | `processEvent(ComponentSystemEvent event)` The default implementation performs the following action.
    `abstract void` | `processRestoreState(FacesContext context, Object state)` Perform the component tree processing required by the Restore View phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
    `abstract Object` | `processSaveState(FacesContext context)` Perform the component tree processing required by the state saving portion of the Render Response phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
    `abstract void` | `processUpdates(FacesContext context)` Perform the component tree processing required by the Update Model Values phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
    `abstract void` | `processValidators(FacesContext context)` Perform the component tree processing required by the Process Validations phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
    `void` | `pushComponentToEL(FacesContext context, UIComponent component)` Push the current `UIComponent` `this` to the `FacesContext` attribute map using the key `CURRENT_COMPONENT` saving the previous `UIComponent` associated with `CURRENT_COMPONENT` for a subsequent call to `popComponentFromEL(javax.faces.context.FacesContext)`.
    `abstract void` | `queueEvent(FacesEvent event)` Queue an event for broadcast at the end of the current request processing lifecycle phase.
    `protected abstract void` | `removeFacesListener(FacesListener listener)` Remove the specified `FacesListener` from the set of listeners registered to receive event notifications from this `UIComponent`.
    `void` | `restoreTransientState(FacesContext context, Object state)` For components that need to support the concept of transient state, this method will restore any state saved on a prior call to `saveTransientState(javax.faces.context.FacesContext)`.
    `Object` | `saveTransientState(FacesContext context)` For components that need to support the concept of transient state, this method will save any state that is known to be transient in nature.
    `abstract void` | `setId(String id)` Set the component identifier of this `UIComponent` (if any).
    `void` | `setInView(boolean isInView)` Updates the status as to whether or not this component is currently within the view hierarchy.
    `abstract void` | `setParent(UIComponent parent)` Set the parent `UIComponent` of this `UIComponent`.
    `abstract void` | `setRendered(boolean rendered)` Set the `rendered` property of this `UIComponent`.
    `abstract void` | `setRendererType(String rendererType)` Set the `Renderer` type for this `UIComponent`, or `null` for components that render themselves.
    `abstract void` | `setValueBinding(String name, ValueBinding binding)` Deprecated. This has been replaced by `setValueExpression(java.lang.String, javax.el.ValueExpression)`.
    `void` | `setValueExpression(String name, ValueExpression binding)` Set the `ValueExpression` used to calculate the value for the specified attribute or property name, if any.
    `void` | `subscribeToEvent(Class<? extends SystemEvent> eventClass, ComponentSystemEventListener componentListener)` This implementation throws `UnsupportedOperationException` and is provided for the sole purpose of not breaking existing applications that extend this class.
    `void` | `unsubscribeFromEvent(Class<? extends SystemEvent> eventClass, ComponentSystemEventListener componentListener)` This implementation throws `UnsupportedOperationException` and is provided for the sole purpose of not breaking existing applications that extend this class.
    `boolean` | `visitTree(VisitContext context, VisitCallback callback)` Perform a tree visit starting at this node in the tree.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface javax.faces.component.StateHolder

      `isTransient, restoreState, saveState, setTransient`

- - ### Field Detail

    - #### HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME

          public static final String HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME

      The `ServletContext` init parameter consulted by the `UIComponent` to tell whether or not the `CURRENT_COMPONENT` and `CURRENT_COMPOSITE_COMPONENT` attribute keys should be honored as specified.

      If this parameter is not specified, or is set to false, the contract specified by the `CURRENT_COMPONENT` and `CURRENT_COMPOSITE_COMPONENT` method is not honored. If this parameter is set to true, the contract is honored.

      See Also:
        Constant Field Values

    - #### CURRENT_COMPONENT

          public static final String CURRENT_COMPONENT

      Deprecated.

      The key to which the `UIComponent` currently being processed will be associated with within the `FacesContext` attributes map. The use of this constant is deprecated. Please see `HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME` to enable its use.

      Since:
        2.0
      See Also:
        `FacesContext.getAttributes()`, Constant Field Values

    - #### CURRENT_COMPOSITE_COMPONENT

          public static final String CURRENT_COMPOSITE_COMPONENT

      Deprecated.

      The key to which the composite `UIComponent` currently being processed will be associated with within the `FacesContext` attributes map. The use of this constant is deprecated. Please see `HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME` to enable its use.

      Since:
        2.0
      See Also:
        `FacesContext.getAttributes()`, Constant Field Values

    - #### BEANINFO_KEY

          public static final String BEANINFO_KEY

      The value of this constant is used as the key in the component attribute map, the value for which is a `java.beans.BeanInfo` implementation describing the composite component. This `BeanInfo` is known as the composite component BeanInfo.

      Since:
        2.0
      See Also:
        Constant Field Values

    - #### FACETS_KEY

          public static final String FACETS_KEY

      The value of this constant is used as the key in the composite component BeanDescriptor for the `Map<PropertyDescriptor>` that contains meta-information for the declared facets for this composite component. This map must contain an entry under the key `COMPOSITE_FACET_NAME`, even if no facets were explicitly declared. See `COMPOSITE_FACET_NAME`.

      Since:
        2.0
      See Also:
        Constant Field Values

    - #### VIEW_LOCATION_KEY

          public static final String VIEW_LOCATION_KEY

      The value of this constant is used as the key in the component attributes `Map` for the `Location` in the view at which this component instance resides.

      Since:
        2.0
      See Also:
        Constant Field Values

    - #### COMPOSITE_COMPONENT_TYPE_KEY

          public static final String COMPOSITE_COMPONENT_TYPE_KEY

      The value of this constant is used as the key in the composite component BeanDescriptor for a `ValueExpression` that evaluates to the `component-type` of the composite component root `UIComponent` for this composite component, if one was declared by the composite component author.

      Since:
        2.0
      See Also:
        Constant Field Values

    - #### COMPOSITE_FACET_NAME

          public static final String COMPOSITE_FACET_NAME

      The value of this constant is used as the key in the `Map` returned as described in `FACETS_KEY` for the `PropertyDescriptor` describing the composite component facet. The value of this constant is also used as the key in the `Map` returned from `getFacets()`. In this case, it refers to the actual facet that is the `UIPanel` that is the parent of the all of the components in the `<composite:implementation>` section of the composite component VDL file.

      Since:
        2.0
      See Also:
        Constant Field Values

    - #### ATTRS_WITH_DECLARED_DEFAULT_VALUES

          public static final String ATTRS_WITH_DECLARED_DEFAULT_VALUES

      This constant enables one to quickly discover the names of the declared composite component attributes that have been given default values by the composite component author. The information is exposed as a `Collection<String>` returned from the `getValue()` method on the composite component BeanDescriptor, when this constant is passed as the argument.

      Since:
        2.1
      See Also:
        Constant Field Values

    - #### bindings

          @Deprecated
          protected Map<String,ValueExpression> bindings

      Deprecated.

  - ### Constructor Detail

    - #### UIComponent

          public UIComponent()

  - ### Method Detail

    - #### getAttributes

          public abstract Map<String,Object> getAttributes()

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

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

    - #### getPassThroughAttributes

          public final Map<String,Object> getPassThroughAttributes()

      This is a convenience method that simply calls `getPassThroughAttributes(boolean)`, passing `true` as the argument. This method must never return `null`.

      Since:
        2.2

    - #### getPassThroughAttributes

          public Map<String,Object> getPassThroughAttributes(boolean create)

      This method has the same specification as `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 `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.

      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`.
      Since:
        2.2

    - #### getValueBinding

          public abstract ValueBinding getValueBinding(String name)

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

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

      Parameters:
        `name` - Name of the attribute or property for which to retrieve a `ValueBinding`
      Throws:
        `NullPointerException` - if `name` is `null`

    - #### setValueBinding

          public abstract void setValueBinding(String name,
                             ValueBinding binding)

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

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

      Parameters:
        `name` - Name of the attribute or property for which to set a `ValueBinding`
        `binding` - The `ValueBinding` to set, or `null` to remove any currently set `ValueBinding`
      Throws:
        `IllegalArgumentException` - if `name` is one of `id` or `parent`
        `NullPointerException` - if `name` is `null`

    - #### getValueExpression

          public ValueExpression getValueExpression(String name)

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

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

      Parameters:
        `name` - Name of the attribute or property for which to retrieve a `ValueExpression`
      Throws:
        `NullPointerException` - if `name` is `null`
      Since:
        1.2

    - #### setValueExpression

          public void setValueExpression(String name,
                                ValueExpression binding)

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

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

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

      Parameters:
        `name` - Name of the attribute or property for which to set a `ValueExpression`
        `binding` - The `ValueExpression` to set, or `null` to remove any currently set `ValueExpression`
      Throws:
        `IllegalArgumentException` - if `name` is one of `id` or `parent`
        `NullPointerException` - if `name` is `null`
      Since:
        1.2

    - #### markInitialState

          public void markInitialState()

      An implementation of `PartialStateHolder.markInitialState()`, this method is called by the runtime to indicate that the instance should start tracking changes to its state.

      Specified by:
        `markInitialState` in interface `PartialStateHolder`
      Since:
        2.0

    - #### initialStateMarked

          public boolean initialStateMarked()

      An implementation of `PartialStateHolder.initialStateMarked()`, this method is called by the runtime to test if the `PartialStateHolder.markInitialState()` method was called.

      Specified by:
        `initialStateMarked` in interface `PartialStateHolder`
      Since:
        2.0

    - #### clearInitialState

          public void clearInitialState()

      An implementation of `PartialStateHolder.clearInitialState()`, this method is called by the runtime to tell the instance to stop tracking state changes.

      Specified by:
        `clearInitialState` in interface `PartialStateHolder`
      Since:
        2.0

    - #### getStateHelper

          protected StateHelper getStateHelper()

      Return the `StateHelper` instance used to help this component implement `PartialStateHolder`.

      Since:
        2.0

    - #### getStateHelper

          protected StateHelper getStateHelper(boolean create)

      Like `getStateHelper()`, but only create a state helper instance if the argument `creat` is `true`.

      Parameters:
        `create` - if `true`, a new `StateHelper` instance will be created if it does not exist already. If `false`, and there is no existing `StateHelper` instance, one will not be created and `null` will be returned.
      Since:
        2.0

    - #### getTransientStateHelper

          public final TransientStateHelper getTransientStateHelper()

      Return the `TransientStateHelper` instance for this `UIComponent` instance. The default implementation simply calls through to `getTransientStateHelper(boolean)` passing `true` as the argument.

      Since:
        2.1

    - #### getTransientStateHelper

          public TransientStateHelper getTransientStateHelper(boolean create)

      Return the `TransientStateHelper` instance for this `UIComponent` instance.

      Parameters:
        `create` - if `true` create, if necessary, any internal data structures. If `false`, do not create any instances. In this case, it is possible for this method to return `null`.
      Since:
        2.1

    - #### restoreTransientState

          public void restoreTransientState(FacesContext context,
                                   Object state)

      For components that need to support the concept of transient state, this method will restore any state saved on a prior call to `saveTransientState(javax.faces.context.FacesContext)`.

      Specified by:
        `restoreTransientState` in interface `TransientStateHolder`
        `state` - the object containing transient values
      Since:
        2.1

    - #### saveTransientState

          public Object saveTransientState(FacesContext context)

      For components that need to support the concept of transient state, this method will save any state that is known to be transient in nature.

      Specified by:
        `saveTransientState` in interface `TransientStateHolder`
      Returns:
        object containing transient values
      Since:
        2.1

    - #### isInView

          public boolean isInView()

      Return `true` if this component is within the view hierarchy otherwise `false`

      Since:
        2.0

    - #### setInView

          public void setInView(boolean isInView)

      Updates the status as to whether or not this component is currently within the view hierarchy. This method must never be called by developers; a `UIComponent`'s internal implementation will call it as components are added to or removed from a parent's child `List` or facet `Map`.

      Parameters:
        `isInView` - flag indicating whether or not this component is within the view hierachy
      Since:
        2.0

    - #### getClientId

          public String getClientId()

      Enable EL to access the `clientId` of a component. This is particularly useful in combination with the `component` and `cc` implicit objects. A default implementation is provided that simply calls `FacesContext.getCurrentInstance()` and then calls through to `getClientId(FacesContext)`.

      Since:
        2.0

    - #### getClientId

          public abstract String getClientId(FacesContext context)

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

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

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

      Parameters:
        `context` - The `FacesContext` for the current request
      Throws:
        `NullPointerException` - if `context` is `null`

    - #### getContainerClientId

          public String getContainerClientId(FacesContext context)

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

      By default, this method will call through to `getClientId()` and return the result.

      Throws:
        `NullPointerException` - if `context` is `null`
      Since:
        1.2

    - #### getFamily

          public abstract String getFamily()

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

    - #### getId

          public abstract String getId()

      Return the component identifier of this `UIComponent`.

    - #### setId

          public abstract void setId(String id)

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

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

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

      - The specified identifier must be unique among all the components (including facets) that are descendents of the nearest ancestor `UIComponent` that is a `NamingContainer`, or within the scope of the entire component tree if there is no such ancestor that is a `NamingContainer`.
      Parameters:
        `id` - The new component identifier, or `null` to indicate that this `UIComponent` does not have a component identifier
      Throws:
        `IllegalArgumentException` - if `id` is not syntactically valid

    - #### getParent

          public abstract UIComponent getParent()

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

    - #### setParent

          public abstract void setParent(UIComponent parent)

      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.

      - `FacesContext.getCurrentPhaseId()` returns `PhaseId.RESTORE_VIEW` and partial state saving is enabled.

      - `FacesContext.isPostback()` returns `false` and `FacesContext.getCurrentPhaseId()` returns something other than `PhaseId.RESTORE_VIEW`

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

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

    - #### isRendered

          public abstract boolean isRendered()

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

    - #### setRendered

          public abstract void setRendered(boolean rendered)

      Set the `rendered` property of this `UIComponent`.

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

    - #### getRendererType

          public abstract String getRendererType()

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

    - #### setRendererType

          public abstract void setRendererType(String rendererType)

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

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

    - #### getRendersChildren

          public abstract boolean getRendersChildren()

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

    - #### getResourceBundleMap

          public Map<String,String> getResourceBundleMap()

      Return a `Map<String,String>` of the `ResourceBundle` for this component. A component may have a `ResourceBundle` associated with it. This bundle may contain localized properties relating to instances of this component. The default implementation first looks for a `ResourceBundle` with a base name equal to the fully qualified class name of the current `UIComponent this` and `Locale` equal to the `Locale` of the current `UIViewRoot`. If no such bundle is found, and the component is a composite component, let resourceName be the resourceName of the `Resource` for this composite component, replacing the file extension with ".properties". Let libraryName be the libraryName of the the `Resource` for this composite component. Call `ResourceHandler.createResource(java.lang.String,java.lang.String)`, passing the derived resourceName and libraryName. Note that this will automatically allow for the localization of the `ResourceBundle` due to the localization facility implemented in `createResource`, which is specified in section JSF.2.6.1.3 of the spec prose document. If the resultant `Resource` exists and can be found, the `InputStream` for the resource is used to create a `ResourceBundle`. If either of the two previous steps for obtaining the `ResourceBundle` for this component is successful, the `ResourceBundle` is wrapped in a `Map<String,String>` and returned. Otherwise `Collections.EMPTY_MAP` is returned.

      Since:
        2.0

    - #### getChildren

          public abstract List<UIComponent> getChildren()

      Return a mutable `List` representing the child `UIComponent`s 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`.

      - After the child component has been added to the view, `Application.publishEvent(javax.faces.context.FacesContext, java.lang.Class<? extends javax.faces.event.SystemEvent>, java.lang.Object)` must be called, passing `PostAddToViewEvent``.class` as the first argument and the newly added component as the second argument if any the following cases are true.

        - `FacesContext.getCurrentPhaseId()` returns `PhaseId.RESTORE_VIEW` and partial state saving is enabled.

        - `FacesContext.isPostback()` returns `false` and `FacesContext.getCurrentPhaseId()` returns something other than `PhaseId.RESTORE_VIEW`

    - #### getChildCount

          public abstract int getChildCount()

      Return the number of child `UIComponent`s 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.

    - #### findComponent

          public abstract UIComponent findComponent(String expr)

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

      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 `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. `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.
      Parameters:
        `expr` - Search expression identifying the `UIComponent` to be returned
      Returns:
        the found `UIComponent`, or `null` if the component was not found.
      Throws:
        `IllegalArgumentException` - if an intermediate identifier in a search expression identifies a `UIComponent` that is not a `NamingContainer`
        `NullPointerException` - if `expr` is `null`

    - #### invokeOnComponent

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

      Starting at this component in the View hierarchy, search for a component with a `clientId` equal to the argument `clientId` and, if found, call the `ContextCallback.invokeContextCallback(javax.faces.context.FacesContext, javax.faces.component.UIComponent)` method on the argument `callback`, passing the current `FacesContext` and the found component as arguments. This method is similar to `findComponent(java.lang.String)` but it does not support the leading `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 `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 `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 `getFacetsAndChildren()`, call `invokeOnComponent()` passing the arguments to this method, in order. The first time `invokeOnComponent()` returns true, abort traversing the rest of the `Iterator` and return `true`.

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

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

      Simple usage example to find a component by `clientId`.

          private UIComponent found = null;

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

      Parameters:
        `context` - the `FacesContext` for the current request
        `clientId` - the client identifier of the component to be passed to the argument callback.
        `callback` - an implementation of the Callback interface.
      Returns:
        `true` if the a component with the given `clientId` is found, the callback method was successfully invoked passing that component as an argument, and no Exception was thrown. Returns `false` if no component with the given `clientId` is found.
      Throws:
        `NullPointerException` - if any of the arguments are null
        `FacesException` - if the argument Callback throws an Exception, it is wrapped in a `FacesException` and re-thrown.
      Since:
        1.2

    - #### getFacets

          public abstract Map<String,UIComponent> getFacets()

      Return a mutable `Map` representing the facet `UIComponent`s 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`.

    - #### getFacetCount

          public int getFacetCount()

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

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

      Since:
        1.2

    - #### getFacet

          public abstract UIComponent getFacet(String name)

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

      Parameters:
        `name` - Name of the desired facet

    - #### getFacetsAndChildren

          public abstract Iterator<UIComponent> getFacetsAndChildren()

      Return an `Iterator` over the facet followed by child `UIComponent`s 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.

    - #### broadcast

          public abstract void broadcast(FacesEvent event)
                                  throws AbortProcessingException

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

      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.

      Parameters:
        `event` - The `FacesEvent` to be broadcast
      Throws:
        `AbortProcessingException` - Signal the JavaServer Faces implementation that no further processing on the current event should be performed
        `IllegalArgumentException` - if the implementation class of this `FacesEvent` is not supported by this component
        `NullPointerException` - if `event` is `null`

    - #### decode

          public abstract void decode(FacesContext context)

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

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

      Parameters:
        `context` - `FacesContext` for the request we are processing
      Throws:
        `NullPointerException` - if `context` is `null`

    - #### visitTree

          public boolean visitTree(VisitContext context,
                          VisitCallback callback)

      Perform a tree visit starting at this node in the tree.

      UIComponent.visitTree() implementations do not invoke the `VisitCallback` directly, but instead call `VisitContext.invokeVisitCallback(javax.faces.component.UIComponent, javax.faces.component.visit.VisitCallback)` to invoke the callback. This allows `VisitContext` implementations to provide optimized tree traversals, for example by only calling the `VisitCallback` for a subset of components.

      UIComponent.visitTree() implementations must call UIComponent.pushComponentToEL() before performing the visit and UIComponent.popComponentFromEL() after the visit.

      Parameters:
        `context` - the `VisitContext` for this visit
        `callback` - the `VisitCallback` instance whose `visit` method will be called for each node visited.
      Returns:
        component implementations may return `true` to indicate that the tree visit is complete (eg. all components that need to be visited have been visited). This results in the tree visit being short-circuited such that no more components are visited.
      Since:
        2.0
      See Also:
        `VisitContext.invokeVisitCallback()`

    - #### isVisitable

          protected boolean isVisitable(VisitContext context)

      Return `true` if this component should be visited, `false` otherwise. Called by `UIComponent.visitTree()` to determine whether this component satisfies the hints returned by `VisitContext.getHints()`.

      If this method returns false, the tree visited is short-circuited such that neither the component nor any of its descendents will be visited>

      Custom `visitTree()` implementations may call this method to determine whether the component is visitable before performing any visit-related processing.

      Since:
        2.0

    - #### encodeBegin

          public abstract void encodeBegin(FacesContext context)
                                    throws IOException

      If our `rendered` property is `true`, render the beginning of the current state of this `UIComponent` to the response contained in the specified `FacesContext`. Call `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 `pushComponentToEL(javax.faces.context.FacesContext,javax.faces.component.UIComponent)` and return immediately.

Parameters:
  `context` - `FacesContext` for the response we are creating
Throws:
  `IOException` - if an input/output error occurs while rendering
  `NullPointerException` - if `context` is `null`

- #### encodeChildren

      public abstract void encodeChildren(FacesContext context)
                                   throws IOException

  If our `rendered` property is `true`, render the child `UIComponent`s 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)`. If no `Renderer` is associated with this `UIComponent`, iterate over each of the children of this component and call `encodeAll(javax.faces.context.FacesContext)`.

  Parameters:
    `context` - `FacesContext` for the response we are creating
  Throws:
    `IOException` - if an input/output error occurs while rendering
    `NullPointerException` - if `context` is `null`

- #### encodeEnd

      public abstract void encodeEnd(FacesContext context)
                              throws IOException

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

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

  Call `popComponentFromEL(javax.faces.context.FacesContext)`. before returning regardless of the value of the `rendered` property.

  Parameters:
    `context` - `FacesContext` for the response we are creating
  Throws:
    `IOException` - if an input/output error occurs while rendering
    `NullPointerException` - if `context` is `null`

- #### encodeAll

      public void encodeAll(FacesContext context)
                     throws IOException

  If this component returns `true` from `isRendered()`, take the following action.

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

Throws:
  `IOException` - if an input/output error occurs while rendering
  `NullPointerException` - if `context` is `null`
Since:
  1.2

- #### pushComponentToEL

      public final void pushComponentToEL(FacesContext context,
                           UIComponent component)

  Push the current `UIComponent` `this` to the `FacesContext` attribute map using the key `CURRENT_COMPONENT` saving the previous `UIComponent` associated with `CURRENT_COMPONENT` for a subsequent call to `popComponentFromEL(javax.faces.context.FacesContext)`.

  This method and `popComponentFromEL()` form the basis for the contract that enables the EL Expression "`#{component}`" to resolve to the "current" component that is being processed in the lifecycle. The requirements for when `pushComponentToEL()` and `popComponentFromEL()` must be called are specified as needed in the javadoc for this class.

  After `pushComponentToEL()` returns, a call to `getCurrentComponent(javax.faces.context.FacesContext)` must return `this` `UIComponent` instance until `popComponentFromEL()` is called, after which point the previous `UIComponent` instance will be returned from `getCurrentComponent()`

  Parameters:
    `context` - the `FacesContext` for the current request
    `component` - the `component` to push to the EL. If `component` is `null` the `UIComponent` instance that this call was invoked upon will be pushed to the EL.
  Throws:
    `NullPointerException` - if `context` is `null`
  Since:
    2.0
  See Also:
    `FacesContext.getAttributes()`

- #### popComponentFromEL

      public final void popComponentFromEL(FacesContext context)

  Pop the current `UIComponent` from the `FacesContext` attributes map so that the previous `UIComponent`, if any, becomes the current component.

  Parameters:
    `context` - the `FacesContext` for the current request
  Throws:
    `NullPointerException` - if `context` is `null`
  Since:
    2.0
  See Also:
    `FacesContext.getAttributes()`

- #### isCompositeComponent

      public static boolean isCompositeComponent(UIComponent component)

  Return `true` if `component` is a composite component, otherwise `false`.

  Parameters:
    `component` - the `UIComponent` to test
  Throws:
    `NullPointerException` - if `component` is `null`
  Since:
    2.0

- #### getCompositeComponentParent

      public static UIComponent getCompositeComponentParent(UIComponent component)

  Finds the nearest composite component parent of the specified component.

  Parameters:
    `component` - the component from which to start the search from
  Returns:
    if `component` is `null`, return `null`, otherwise search the component's parent hierachy for the nearest parent composite component. If no parent composite component is found, return `null`
  Since:
    2.0

- #### getCurrentComponent

      public static UIComponent getCurrentComponent(FacesContext context)

  Return the `UIComponent` instance that is currently processing. This is equivalent to evaluating the EL expression "`#{component}`" and doing a `getValue` operation on the resultant `ValueExpression`.

  This method must return `null` if there is no currently processing `UIComponent`

  Parameters:
    `context` - `FacesContext` for the request we are processing
  Throws:
    `NullPointerException` - if `context` is `null`
  Since:
    2.0

- #### getCurrentCompositeComponent

      public static UIComponent getCurrentCompositeComponent(FacesContext context)

  Return the closest ancestor component, relative to the component returned from `getCurrentComponent(javax.faces.context.FacesContext)`, that is a composite component, or `null` if no such component exists.

  Parameters:
    `context` - `FacesContext` for the request we are processing
  Throws:
    `NullPointerException` - if `context` is `null`
  Since:
    2.0

- #### addFacesListener

      protected abstract void addFacesListener(FacesListener listener)

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

       public class FooEvent extends FacesEvent { ... }

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

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

  Parameters:
    `listener` - The `FacesListener` to be registered
  Throws:
    `NullPointerException` - if `listener` is `null`

- #### getFacesListeners

      protected abstract FacesListener[] getFacesListeners(Class clazz)

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

  Parameters:
    `clazz` - Class that must be implemented by a `FacesListener` for it to be returned
  Throws:
    `IllegalArgumentException` - if `class` is not, and does not implement, `FacesListener`
    `NullPointerException` - if `clazz` is `null`

- #### removeFacesListener

      protected abstract void removeFacesListener(FacesListener listener)

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

  Parameters:
    `listener` - The `FacesListener` to be deregistered
  Throws:
    `NullPointerException` - if `listener` is `null`

- #### queueEvent

      public abstract void queueEvent(FacesEvent event)

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

  Parameters:
    `event` - `FacesEvent` to be queued
  Throws:
    `IllegalStateException` - if this component is not a descendant of a `UIViewRoot`
    `NullPointerException` - if `event` is `null`

- #### subscribeToEvent

      public void subscribeToEvent(Class<? extends SystemEvent> eventClass,
                          ComponentSystemEventListener componentListener)

  This implementation throws `UnsupportedOperationException` and is provided for the sole purpose of not breaking existing applications that extend this class. `UIComponentBase` provides the implementation of this method.

  Since:
    2.1

- #### unsubscribeFromEvent

      public void unsubscribeFromEvent(Class<? extends SystemEvent> eventClass,
                              ComponentSystemEventListener componentListener)

  This implementation throws `UnsupportedOperationException` and is provided for the sole purpose of not breaking existing applications that extend this class. `UIComponentBase` provides the implementation of this method.

  Since:
    2.1

- #### getListenersForEventClass

      public List<SystemEventListener> getListenersForEventClass(Class<? extends SystemEvent> eventClass)

  This implementation throws `UnsupportedOperationException` and is provided for the sole purpose of not breaking existing applications that extend this class. `UIComponentBase` provides the implementation of this method.

  Specified by:
    `getListenersForEventClass` in interface `SystemEventListenerHolder`
  Since:
    2.1

- #### getNamingContainer

      public UIComponent getNamingContainer()

  Starting with "this", return the closest component in the ancestry that is a `NamingContainer` or `null` if none can be found.

  Since:
    2.0

- #### processRestoreState

      public abstract void processRestoreState(FacesContext context,
                             Object state)

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

  - Call the `restoreState()` method of this component.
  - Call `pushComponentToEL(javax.faces.context.FacesContext, javax.faces.component.UIComponent)`.
  - Call the `processRestoreState()` method of all facets and children of this `UIComponent` in the order determined by a call to `getFacetsAndChildren()`. After returning from the `processRestoreState()` method on a child or facet, call `popComponentFromEL(javax.faces.context.FacesContext)`

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

  Parameters:
    `context` - `FacesContext` for the request we are processing
  Throws:
    `NullPointerException` - if `context` is `null`

- #### processDecodes

      public abstract void processDecodes(FacesContext context)

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

  - If the `rendered` property of this `UIComponent` is `false`, skip further processing.
  - Call `pushComponentToEL(javax.faces.context.FacesContext, javax.faces.component.UIComponent)`.
  - 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.
  - Call `popComponentFromEL(javax.faces.context.FacesContext)` from inside of a `finally block, just before returning.`
  - If a `RuntimeException` is thrown during decode processing, call `FacesContext.renderResponse()` and re-throw the exception.
  Parameters:
    `context` - `FacesContext` for the request we are processing
  Throws:
    `NullPointerException` - if `context` is `null`

- #### processEvent

      public void processEvent(ComponentSystemEvent event)
                        throws AbortProcessingException

  The default implementation performs the following action. If the argument `event` is an instance of `PostRestoreStateEvent`, call `this.``getValueExpression(java.lang.String)` passing the literal string “binding”, without the quotes, as the argument. If the result is non-`null`, set the value of the `ValueExpression` to be `this`.

  Specified by:
    `processEvent` in interface `ComponentSystemEventListener`
  Parameters:
    `event` - the `ComponentSystemEvent` instance that is being processed.
  Throws:
    `AbortProcessingException` - if lifecycle processing should cease for this request.

- #### processValidators

      public abstract void processValidators(FacesContext context)

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

  - If the `rendered` property of this `UIComponent` is `false`, skip further processing.
  - Call `pushComponentToEL(javax.faces.context.FacesContext, javax.faces.component.UIComponent)`.
  - Call the `processValidators()` method of all facets and children of this `UIComponent`, in the order determined by a call to `getFacetsAndChildren()`.
  - After returning from calling `getFacetsAndChildren()` call `popComponentFromEL(javax.faces.context.FacesContext)`.
  Parameters:
    `context` - `FacesContext` for the request we are processing
  Throws:
    `NullPointerException` - if `context` is `null`

- #### processUpdates

      public abstract void processUpdates(FacesContext context)

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

  - If the `rendered` property of this `UIComponent` is `false`, skip further processing.
  - Call `pushComponentToEL(javax.faces.context.FacesContext, javax.faces.component.UIComponent)`.
  - Call the `processUpdates()` method of all facets and children of this `UIComponent`, in the order determined by a call to `getFacetsAndChildren()`. After returning from the `processUpdates()` method on a child or facet, call `popComponentFromEL(javax.faces.context.FacesContext)`
  Parameters:
    `context` - `FacesContext` for the request we are processing
  Throws:
    `NullPointerException` - if `context` is `null`

- #### processSaveState

      public abstract Object processSaveState(FacesContext context)

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

  - consult the `transient` property of this component. If true, just return `null`.
  - Call `pushComponentToEL(javax.faces.context.FacesContext, javax.faces.component.UIComponent)`.
  - 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. Ensure that `popComponentFromEL(javax.faces.context.FacesContext)` is called correctly after each child or facet.
  - Call the `saveState()` method of this component.
  - Encapsulate the child state and your state into a Serializable Object and return it.

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

  Parameters:
    `context` - `FacesContext` for the request we are processing
  Throws:
    `NullPointerException` - if `context` is `null`

- #### getFacesContext

      protected abstract FacesContext getFacesContext()

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

- #### getRenderer

      protected abstract Renderer getRenderer(FacesContext context)

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

  Parameters:
    `context` - `FacesContext` for the current request

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.