Search for and return the UIComponent
with an id
that matches the specified search expression (if any), according to the
algorithm described below.
For a method to find a component given a simple
clientId
, see UIComponent.invokeOnComponent(javax.faces.context.FacesContext, java.lang.String, javax.faces.component.ContextCallback)
.
Component identifiers are required to be unique within the scope of
the closest ancestor NamingContainer
that encloses this
component (which might be this component itself). If there are no
NamingContainer
components in the ancestry of this component,
the root component in the tree is treated as if it were a
NamingContainer
, whether or not its class actually implements
the NamingContainer
interface.
A search expression consists of either an identifier
(which is matched exactly against the id
property of
a UIComponent
, or a series of such identifiers linked by
the 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.
- Overrides:
findComponent
in class UIComponentBase
- Parameters:
expr
- Search expression identifying the UIComponent
to be returned
- Returns:
- the found
UIComponent
, or null
if the component was not found.