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 |
CURRENT_COMPONENT
Deprecated.
|
static java.lang.String |
CURRENT_COMPOSITE_COMPONENT
Deprecated.
|
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 |
HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME
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 |
abstract ValueBinding |
getValueBinding(java.lang.String name)
Deprecated.
This has been replaced by
getValueExpression(java.lang.String) . |
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(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 |
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)
|
abstract void |
setValueBinding(java.lang.String name,
ValueBinding binding)
Deprecated.
This has been replaced by
setValueExpression(java.lang.String, javax.el.ValueExpression) . |
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 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.
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.
public static final java.lang.String CURRENT_COMPONENT
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.
FacesContext.getAttributes()
,
Constant Field Valuespublic static final java.lang.String CURRENT_COMPOSITE_COMPONENT
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.
FacesContext.getAttributes()
,
Constant Field Values@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 Server 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(javax.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(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 Jakarta Server 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(javax.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(javax.faces.context.FacesContext)
+ myIdRenderer.convertClientId(javax.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 Server Faces
Specification, component authors are encouraged to return true
from
this method and rely on UIComponentBase.encodeChildren(javax.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 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.
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(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
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(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:
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(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;
}
});
}
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(javax.faces.event.BehaviorEvent)
on the Behavior
instance.
event
- The FacesEvent
to be broadcastAbortProcessingException
- Signal the Jakarta Server 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(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.
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(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.
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(javax.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(javax.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 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 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(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()
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(javax.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.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(javax.faces.context.FacesContext, javax.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(javax.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(javax.faces.context.FacesContext, javax.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(javax.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(javax.faces.context.FacesContext, javax.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(javax.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(javax.faces.context.FacesContext, javax.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(javax.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(javax.faces.context.FacesContext, javax.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(javax.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
.public abstract ValueBinding getValueBinding(java.lang.String name)
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.
name
- Name of the attribute or property for which to retrieve a
ValueBinding
java.lang.NullPointerException
- if name
is null
public abstract void setValueBinding(java.lang.String name, ValueBinding binding)
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)
.
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
java.lang.IllegalArgumentException
- if name
is one of id
or parent
java.lang.NullPointerException
- if name
is null