public abstract class UIComponent extends java.lang.Object implements PartialStateHolder, TransientStateHolder, SystemEventListenerHolder, ComponentSystemEventListener
UIComponent is the base class for all user interface components in Jakarta Server
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
.
Dynamically modifying the component tree can happen at any time, during and after restoring the view, but not during state saving and needs to function properly with respect to rendering and state saving
Modifier and Type | Field and Description |
---|---|
static java.lang.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 java.lang.String |
BEANINFO_KEY
The value of this constant is used as the key in the component attribute map, the value for which is a
|
protected java.util.Map<java.lang.String,ValueExpression> |
bindings
Deprecated.
|
static java.lang.String |
COMPOSITE_COMPONENT_TYPE_KEY
The value of this constant is used as the key in the composite component BeanDescriptor for a
|
static java.lang.String |
COMPOSITE_FACET_NAME
The value of this constant is used as the key in the |
static java.lang.String |
FACETS_KEY
The value of this constant is used as the key in the composite component BeanDescriptor for the
|
static java.lang.String |
VIEW_LOCATION_KEY
The value of this constant is used as the key in the component attributes |
Constructor and Description |
---|
UIComponent() |
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 |
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)
|
abstract void |
encodeEnd(FacesContext context)
|
abstract UIComponent |
findComponent(java.lang.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 java.util.Map<java.lang.String,java.lang.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 java.util.List<UIComponent> |
getChildren()
|
java.lang.String |
getClientId()
Enable Jakarta Expression Language to access the |
abstract java.lang.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.
|
java.lang.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 separately callable method. |
static UIComponent |
getCurrentComponent(FacesContext context)
Return the |
static UIComponent |
getCurrentCompositeComponent(FacesContext context)
Return the closest ancestor component, relative to the component returned from |
protected abstract FacesContext |
getFacesContext()
Convenience method to return the
FacesContext instance for the current request. |
protected abstract FacesListener[] |
getFacesListeners(java.lang.Class clazz)
Return an array of registered
FacesListener s that are instances of the specified class. |
abstract UIComponent |
getFacet(java.lang.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 java.util.Map<java.lang.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 java.util.Iterator<UIComponent> |
getFacetsAndChildren()
|
abstract java.lang.String |
getFamily()
Return the identifier of the component family to which this component belongs. |
abstract java.lang.String |
getId()
Return the component identifier of this
UIComponent . |
java.util.List<SystemEventListener> |
getListenersForEventClass(java.lang.Class<? extends SystemEvent> eventClass)
This implementation throws |
UIComponent |
getNamingContainer()
Starting with "this", return the closest component in the ancestry that is a |
abstract UIComponent |
getParent()
Return the parent
UIComponent of this UIComponent , if any. |
java.util.Map<java.lang.String,java.lang.Object> |
getPassThroughAttributes()
This is a convenience method that simply calls |
java.util.Map<java.lang.String,java.lang.Object> |
getPassThroughAttributes(boolean create)
This method has the same specification as |
protected abstract Renderer |
getRenderer(FacesContext context)
Convenience method to return the
Renderer instance associated with this component, if any; otherwise, return
null . |
abstract java.lang.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.
|
java.util.Map<java.lang.String,java.lang.String> |
getResourceBundleMap()
Return a |
protected StateHelper |
getStateHelper()
Return the |
protected StateHelper |
getStateHelper(boolean create)
Like |
TransientStateHelper |
getTransientStateHelper()
Return the |
TransientStateHelper |
getTransientStateHelper(boolean create)
Return the |
ValueExpression |
getValueExpression(java.lang.String name)
Return the
ValueExpression used to calculate the value for the specified attribute or property name, if any. |
boolean |
initialStateMarked()
An implementation of |
boolean |
invokeOnComponent(FacesContext context,
java.lang.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(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent) method on the argument callback , passing the current
FacesContext and the found component as arguments. |
static boolean |
isCompositeComponent(UIComponent component)
Return |
boolean |
isInView()
Return |
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 |
void |
markInitialState()
An implementation of |
void |
popComponentFromEL(FacesContext context)
Pop the current |
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,
java.lang.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 java.lang.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 |
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,
java.lang.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 |
java.lang.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(java.lang.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 |
abstract void |
setRendered(boolean rendered)
Set the
rendered property of this UIComponent . |
abstract void |
setRendererType(java.lang.String rendererType)
|
void |
setValueExpression(java.lang.String name,
ValueExpression binding)
Set the
ValueExpression used to calculate the value for the specified attribute or property name, if any. |
void |
subscribeToEvent(java.lang.Class<? extends SystemEvent> eventClass,
ComponentSystemEventListener componentListener)
This implementation throws |
void |
unsubscribeFromEvent(java.lang.Class<? extends SystemEvent> eventClass,
ComponentSystemEventListener componentListener)
This implementation throws |
boolean |
visitTree(VisitContext visitContext,
VisitCallback callback)
Perform a tree visit starting at this node in the tree. |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
isTransient, restoreState, saveState, setTransient
public static final java.lang.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.
public static final java.lang.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
.
public static final java.lang.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.
public static final java.lang.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.
public static final java.lang.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.
public static final java.lang.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.
@Deprecated protected java.util.Map<java.lang.String,ValueExpression> bindings
public abstract java.util.Map<java.lang.String,java.lang.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:
Map
implementation must implement the java.io.Serializable
interface.null
key or value must throw a NullPointerException
.ClassCastException
.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
.public java.util.Map<java.lang.String,java.lang.Object> getPassThroughAttributes()
This is a convenience method that simply calls getPassThroughAttributes(boolean)
, passing true
as
the argument. This method must never return null
.
public java.util.Map<java.lang.String,java.lang.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.
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.Map
instance, or null
.public ValueExpression getValueExpression(java.lang.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 Jakarta Faces 1.2 and later.
name
- Name of the attribute or property for which to retrieve a ValueExpression
null
.java.lang.NullPointerException
- if name
is null
public void setValueExpression(java.lang.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(jakarta.el.ELContext)
on the argument
expression and pass the result as the value
parameter in a call to this.
where getAttributes()
.put(name, value)name
is the argument name
. If an exception
is thrown as a result of calling ValueExpression.getValue(jakarta.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 Jakarta Faces 1.2 and later.
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
java.lang.IllegalArgumentException
- if name
is one of id
or parent
java.lang.NullPointerException
- if name
is null
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.
markInitialState
in interface PartialStateHolder
public boolean initialStateMarked()
An implementation of PartialStateHolder.initialStateMarked()
, this method is called by the runtime to test if
the PartialStateHolder.markInitialState()
method was called.
initialStateMarked
in interface PartialStateHolder
true
if the initial state is marked, false
otherwise.public void clearInitialState()
An implementation of PartialStateHolder.clearInitialState()
, this method is called by the runtime to tell the
instance to stop tracking state changes.
clearInitialState
in interface PartialStateHolder
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
.
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.public TransientStateHelper getTransientStateHelper()
Return the TransientStateHelper
instance for this UIComponent
instance. The default
implementation simply calls through to getTransientStateHelper(boolean)
passing true
as the
argument.
public TransientStateHelper getTransientStateHelper(boolean create)
Return the TransientStateHelper
instance for this UIComponent
instance.
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
.public void restoreTransientState(FacesContext context, java.lang.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(jakarta.faces.context.FacesContext)
.
restoreTransientState
in interface TransientStateHolder
context
- the Faces contextstate
- the object containing transient valuespublic java.lang.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.
saveTransientState
in interface TransientStateHolder
context
- the Faces context.public boolean isInView()
Return true
if this component is within the view hierarchy otherwise false
true
if within a view hierarchy, false
otherwise.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
.
isInView
- flag indicating whether or not this component is within the view hierachypublic java.lang.String getClientId()
Enable Jakarta Expression Language 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)
.
public abstract java.lang.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
+
. Call UINamingContainer.getSeparatorChar(jakarta.faces.context.FacesContext)
+ myIdRenderer.convertClientId(jakarta.faces.context.FacesContext, java.lang.String)
, passing
myId
, and return the result.
context
- The FacesContext
for the current requestjava.lang.NullPointerException
- if context
is null
public java.lang.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 separately callable method. See getClientId()
for usage.
By default, this method will call through to getClientId()
and return the result.
context
- the Faces context.java.lang.NullPointerException
- if context
is null
public abstract java.lang.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. Note this method should NOT return null
public abstract java.lang.String getId()
Return the component identifier of this UIComponent
.
public abstract void setId(java.lang.String id)
Set the component identifier of this UIComponent
(if any). Component identifiers must obey the following
syntax restrictions:
Component identifiers must also obey the following semantic restrictions (note that this restriction is
NOT enforced by the setId()
implementation):
UIComponent
that is a NamingContainer
, or within the scope of the entire component
tree if there is no such ancestor that is a NamingContainer
.id
- The new component identifier, or null
to indicate that this UIComponent
does not have
a component identifierjava.lang.IllegalArgumentException
- if id
is not syntactically validpublic 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( )
.
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
.
parent
- The new parent, or null
for the root node of a component treepublic abstract boolean isRendered()
Return true
if this component (and its children) should be rendered during the Render Response
phase of the request processing lifecycle.
true
if the component should be rendered, false
otherwise.public abstract void setRendered(boolean rendered)
Set the rendered
property of this UIComponent
.
rendered
- If true
render this component; otherwise, do not render this componentpublic abstract java.lang.String getRendererType()
Return the Renderer
type for this UIComponent
(if any).
public abstract void setRendererType(java.lang.String rendererType)
Set the Renderer
type for this UIComponent
, or null
for components that render
themselves.
rendererType
- Logical identifier of the type of Renderer
to use, or null
for components
that render themselvespublic 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 Jakarta Faces Specification, component authors are encouraged to return true
from this method and rely on UIComponentBase.encodeChildren(jakarta.faces.context.FacesContext)
.
true
if the component renders its children, false
otherwise.public java.util.Map<java.lang.String,java.lang.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 2.6.1.3 "Resource Identifiers" of the Jakarta Faces Specification 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.
public abstract java.util.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:
List
implementation must implement the java.io.Serializable
interface.null
must throw a NullPointerExceptionUIComponent
must throw a ClassCastException.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).parent
property of the child must be set to
null
.
After the child component has been added to the view, Application.publishEvent(jakarta.faces.context.FacesContext, java.lang.Class<? extends jakarta.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
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.
public abstract UIComponent findComponent(java.lang.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 Jakarta Expression Language-bound attribute from the component is not safe.
Jakarta Expression Language 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(jakarta.faces.context.FacesContext, java.lang.String, jakarta.faces.component.ContextCallback)
for a
method that does correctly account for the tree traversal context when operating on the found
UIComponent
instance. invokeOnComponent(jakarta.faces.context.FacesContext, java.lang.String, jakarta.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(jakarta.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:
UIComponent
that will be the base for searching, by stopping as soon as one of the following
conditions is met:
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.UIComponent
is a NamingContainer
it will serve as the basis.NamingContainer
is encountered, it will be the
base.NamingContainer
is encountered) the root UIComponent
will be the base.id
that matches, within the scope of the base
component. The match is performed as follows:
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).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.expr
- Search expression identifying the UIComponent
to be returnedUIComponent
, or null
if the component was not found.java.lang.IllegalArgumentException
- if an intermediate identifier in a search expression identifies a
UIComponent
that is not a NamingContainer
java.lang.NullPointerException
- if expr
is null
public boolean invokeOnComponent(FacesContext context, java.lang.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(jakarta.faces.context.FacesContext, jakarta.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(jakarta.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(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent)
, then call
the ContextCallback.invokeContextCallback(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent)
method on the argument callback, passing through the
FacesContext
argument and passing this as the component argument. Then
call popComponentFromEL(jakarta.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(jakarta.faces.context.FacesContext, jakarta.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;
}
});
}
context
- the FacesContext
for the current requestclientId
- the client identifier of the component to be passed to the argument callback.callback
- an implementation of the Callback interface.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.java.lang.NullPointerException
- if any of the arguments are nullFacesException
- if the argument Callback throws an Exception, it is wrapped in a FacesException
and re-thrown.public abstract java.util.Map<java.lang.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:
Map
implementation must implement the java.io.Serializable
interface.null
key or value must throw a NullPointerException.UIComponent
must throw a ClassCastException.UIComponent
is added:
parent
property of the component must be set to this component instance.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).UIComponent
is removed:
parent
property of the facet must be set to null
.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()
.
public abstract UIComponent getFacet(java.lang.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.
name
- Name of the desired facetnull
.public abstract java.util.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.
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(jakarta.faces.event.BehaviorEvent)
on the
Behavior
instance.
event
- The FacesEvent
to be broadcastAbortProcessingException
- Signal the Jakarta Faces implementation that no further processing on the
current event should be performedjava.lang.IllegalArgumentException
- if the implementation class of this FacesEvent
is not supported by this
componentjava.lang.NullPointerException
- if event
is null
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()
.
context
- FacesContext
for the request we are processingjava.lang.NullPointerException
- if context
is null
public boolean visitTree(VisitContext visitContext, 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(jakarta.faces.component.UIComponent, jakarta.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.
visitContext
- the VisitContext
for this visitcallback
- the VisitCallback
instance whose visit
method will be called for each node
visited.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.VisitContext.invokeVisitCallback()
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.
context
- the Visit context.true
if visitable, false
otherwise.public abstract void encodeBegin(FacesContext context) throws java.io.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(jakarta.faces.context.FacesContext,jakarta.faces.component.UIComponent)
. Call
Application.publishEvent(jakarta.faces.context.FacesContext, java.lang.Class<? extends jakarta.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(jakarta.faces.context.FacesContext,jakarta.faces.component.UIComponent)
and return
immediately.
context
- FacesContext
for the response we are creatingjava.io.IOException
- if an input/output error occurs while renderingjava.lang.NullPointerException
- if context
is null
public abstract void encodeChildren(FacesContext context) throws java.io.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(jakarta.faces.context.FacesContext)
.
context
- FacesContext
for the response we are creatingjava.io.IOException
- if an input/output error occurs while renderingjava.lang.NullPointerException
- if context
is null
public abstract void encodeEnd(FacesContext context) throws java.io.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(jakarta.faces.context.FacesContext)
. before returning regardless of the value of the rendered
property.
context
- FacesContext
for the response we are creatingjava.io.IOException
- if an input/output error occurs while renderingjava.lang.NullPointerException
- if context
is null
public void encodeAll(FacesContext context) throws java.io.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.
context
- the Faces context.java.io.IOException
- if an input/output error occurs while renderingjava.lang.NullPointerException
- if context
is null
public void pushComponentToEL(FacesContext context, UIComponent component)
Push the current UIComponent
this
to the FacesContext
attribute map
saving the previous UIComponent
for a subsequent call to popComponentFromEL(jakarta.faces.context.FacesContext)
.
This method and popComponentFromEL()
form the basis for the contract that enables the Jakarta Expression
Language 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(jakarta.faces.context.FacesContext)
must return this
UIComponent
instance until popComponentFromEL()
is called, after which point the previous
UIComponent
instance will be returned from getCurrentComponent()
context
- the FacesContext
for the current requestcomponent
- 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.java.lang.NullPointerException
- if context
is null
FacesContext.getAttributes()
public void popComponentFromEL(FacesContext context)
Pop the current UIComponent
from the FacesContext
attributes map so that the previous
UIComponent
, if any, becomes the current component.
context
- the FacesContext
for the current requestjava.lang.NullPointerException
- if context
is null
FacesContext.getAttributes()
public static boolean isCompositeComponent(UIComponent component)
Return true
if component
is a composite component, otherwise false
.
component
- the UIComponent
to testtrue
if this is a composite component, false
otherwise.java.lang.NullPointerException
- if component
is null
public static UIComponent getCompositeComponentParent(UIComponent component)
Finds the nearest composite component parent of the specified component.
component
- the component from which to start the search fromcomponent
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
public static UIComponent getCurrentComponent(FacesContext context)
Return the UIComponent
instance that is currently processing. This is equivalent to evaluating the
Jakarta Expression Language expression "#{component}
" and doing a getValue
operation on the
resultant ValueExpression
.
This method must return null
if there is no currently processing UIComponent
context
- FacesContext
for the request we are processingnull
.java.lang.NullPointerException
- if context
is null
public static UIComponent getCurrentCompositeComponent(FacesContext context)
Return the closest ancestor component, relative to the component returned from getCurrentComponent(jakarta.faces.context.FacesContext)
, that is
a composite component, or null
if no such component exists.
context
- FacesContext
for the request we are processingnull
.java.lang.NullPointerException
- if context
is null
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); } ... }
listener
- The FacesListener
to be registeredjava.lang.NullPointerException
- if listener
is null
protected abstract FacesListener[] getFacesListeners(java.lang.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
.
clazz
- Class that must be implemented by a FacesListener
for it to be returnedjava.lang.IllegalArgumentException
- if class
is not, and does not implement, FacesListener
java.lang.NullPointerException
- if clazz
is null
protected abstract void removeFacesListener(FacesListener listener)
Remove the specified FacesListener
from the set of listeners registered to receive event notifications from
this UIComponent
.
listener
- The FacesListener
to be deregisteredjava.lang.NullPointerException
- if listener
is null
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
.
event
- FacesEvent
to be queuedjava.lang.IllegalStateException
- if this component is not a descendant of a UIViewRoot
java.lang.NullPointerException
- if event
is null
public void subscribeToEvent(java.lang.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.
eventClass
- the event class.componentListener
- the listener.public void unsubscribeFromEvent(java.lang.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.
eventClass
- the event class.componentListener
- the component listener.public java.util.List<SystemEventListener> getListenersForEventClass(java.lang.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.
getListenersForEventClass
in interface SystemEventListenerHolder
eventClass
- the event class.null
.public UIComponent getNamingContainer()
Starting with "this", return the closest component in the ancestry that is a NamingContainer
or
null
if none can be found.
null
.public abstract void processRestoreState(FacesContext context, java.lang.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.
restoreState()
method of this component.pushComponentToEL(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent)
.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(jakarta.faces.context.FacesContext)
This method may not be called if the state saving method is set to server.
context
- FacesContext
for the request we are processingstate
- the state.java.lang.NullPointerException
- if context
is null
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.
rendered
property of this UIComponent
is false
, skip further
processing.pushComponentToEL(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent)
.processDecodes()
method of all facets and children of this UIComponent
, in the
order determined by a call to getFacetsAndChildren()
.decode()
method of this component.popComponentFromEL(jakarta.faces.context.FacesContext)
from inside of a finally block, just before returning.
RuntimeException
is thrown during decode processing, call FacesContext.renderResponse()
and re-throw the exception.context
- FacesContext
for the request we are processingjava.lang.NullPointerException
- if context
is null
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
.
processEvent
in interface ComponentSystemEventListener
event
- the ComponentSystemEvent
instance that is being processed.AbortProcessingException
- if lifecycle processing should cease for this request.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.
rendered
property of this UIComponent
is false
, skip further
processing.pushComponentToEL(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent)
.processValidators()
method of all facets and children of this UIComponent
, in the
order determined by a call to getFacetsAndChildren()
.getFacetsAndChildren()
call
popComponentFromEL(jakarta.faces.context.FacesContext)
.context
- FacesContext
for the request we are processingjava.lang.NullPointerException
- if context
is null
PreValidateEvent
,
PostValidateEvent
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.
rendered
property of this UIComponent
is false
, skip further
processing.pushComponentToEL(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent)
.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(jakarta.faces.context.FacesContext)
context
- FacesContext
for the request we are processingjava.lang.NullPointerException
- if context
is null
public abstract java.lang.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.
transient
property of this component. If true, just return null
.pushComponentToEL(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent)
.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(jakarta.faces.context.FacesContext)
is called correctly after each child or facet.saveState()
method of this component.This method may not be called if the state saving method is set to server.
context
- FacesContext
for the request we are processingjava.lang.NullPointerException
- if context
is null
protected abstract FacesContext getFacesContext()
Convenience method to return the FacesContext
instance for the current request.
protected abstract Renderer getRenderer(FacesContext context)
Convenience method to return the Renderer
instance associated with this component, if any; otherwise, return
null
.
context
- FacesContext
for the current requestnull
.