public class UILeaf extends UIComponentBase implements UntargetableComponent
ATTRS_WITH_DECLARED_DEFAULT_VALUES, BEANINFO_KEY, bindings, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, CURRENT_COMPONENT, CURRENT_COMPOSITE_COMPONENT, FACETS_KEY, HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME, VIEW_LOCATION_KEY
Constructor and Description |
---|
UILeaf() |
Modifier and Type | Method and Description |
---|---|
protected void |
addFacesListener(FacesListener faces)
Add the specified
FacesListener to the set of listeners registered to receive event
notifications from this UIComponent . |
void |
broadcast(FacesEvent event)
Broadcast the specified
FacesEvent to all registered event listeners who
have expressed an interest in events of this type. |
void |
decode(FacesContext faces)
Decode any new state of this
UIComponent from the request contained in the
specified FacesContext , and store this state as needed. |
void |
encodeAll(FacesContext faces)
If this component returns
true from UIComponent.isRendered() , take the
following action. |
void |
encodeBegin(FacesContext faces)
If our
rendered property is
true , render the beginning of the current state of this
UIComponent to the response contained in the specified
FacesContext . |
void |
encodeChildren(FacesContext faces)
|
void |
encodeEnd(FacesContext faces)
|
UIComponent |
findComponent(String id)
Search for and return the
UIComponent with an id that matches the specified search
expression (if any), according to the algorithm described below. |
int |
getChildCount()
Return the number of child
UIComponent s that are associated with this
UIComponent . |
List<UIComponent> |
getChildren()
|
protected FacesContext |
getFacesContext()
Convenience method to return the
FacesContext instance for the current
request. |
protected FacesListener[] |
getFacesListeners(Class faces)
Return an array of registered
FacesListener s that are instances of the
specified class. |
UIComponent |
getFacet(String name)
Convenience method to return the named facet, if it exists, or
null
otherwise. |
int |
getFacetCount()
Return the number of facet
UIComponent s that are associated with this
UIComponent . |
Map<String,UIComponent> |
getFacets()
Return a mutable
Map representing the facet UIComponent s
associated with this UIComponent , keyed by facet name (which must be a
String). |
Iterator<UIComponent> |
getFacetsAndChildren()
|
String |
getFamily()
Return the identifier of the component family to which this component belongs. |
UIComponent |
getParent()
Return the parent
UIComponent of this UIComponent , if any. |
protected Renderer |
getRenderer(FacesContext faces)
Convenience method to return the
Renderer instance associated with this
component, if any; otherwise, return null . |
String |
getRendererType()
Return the
Renderer type for this UIComponent (if any). |
boolean |
getRendersChildren()
Return a flag indicating whether this component is responsible for rendering its
child components.
|
ValueBinding |
getValueBinding(String binding)
Call through to
UIComponent.getValueExpression(java.lang.String) and examine the result. |
javax.el.ValueExpression |
getValueExpression(String name)
Return the
ValueExpression used to calculate the value for the specified
attribute or property name, if any. |
boolean |
isTransient()
If true, the Object implementing this interface must not
participate in state saving or restoring.
|
void |
processDecodes(FacesContext faces)
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 |
processUpdates(FacesContext faces)
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.
|
void |
processValidators(FacesContext faces)
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 |
queueEvent(FacesEvent event)
Queue an event for broadcast at the end of the current request processing lifecycle
phase.
|
protected void |
removeFacesListener(FacesListener faces)
Remove the specified
FacesListener from the set of listeners registered to receive
event notifications from this UIComponent . |
void |
setParent(UIComponent parent)
Set the parent
|
void |
setRendererType(String rendererType)
|
void |
setTransient(boolean tranzient)
Denotes
whether or not the Object implementing this interface must or
must not participate in state saving or restoring.
|
void |
setValueBinding(String name,
ValueBinding binding)
Wrap the argument
binding in an implementation of
ValueExpression and call through to UIComponent.setValueExpression(java.lang.String, javax.el.ValueExpression) . |
void |
setValueExpression(String name,
javax.el.ValueExpression arg1)
Set the
ValueExpression used to calculate the value for the specified
attribute or property name, if any. |
addClientBehavior, clearInitialState, getAttributes, getClientBehaviors, getClientId, getDefaultEventName, getEventNames, getId, getListenersForEventClass, getPassThroughAttributes, invokeOnComponent, isRendered, markInitialState, processRestoreState, processSaveState, restoreAttachedState, restoreState, saveAttachedState, saveState, setId, setRendered, subscribeToEvent, unsubscribeFromEvent
getClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getNamingContainer, getPassThroughAttributes, getResourceBundleMap, getStateHelper, getStateHelper, getTransientStateHelper, getTransientStateHelper, initialStateMarked, isCompositeComponent, isInView, isVisitable, popComponentFromEL, processEvent, pushComponentToEL, restoreTransientState, saveTransientState, setInView, visitTree
public ValueBinding getValueBinding(String binding)
UIComponentBase
Call through to UIComponent.getValueExpression(java.lang.String)
and examine the result. If the result
is an instance of the wrapper class mandated in UIComponent.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.
getValueBinding
in class UIComponentBase
binding
- Name of the attribute or property for which to retrieve a
ValueBinding
public void setValueBinding(String name, ValueBinding binding)
UIComponentBase
Wrap the argument binding
in an implementation of
ValueExpression
and call through to UIComponent.setValueExpression(java.lang.String, javax.el.ValueExpression)
.
setValueBinding
in class UIComponentBase
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
public javax.el.ValueExpression getValueExpression(String name)
UIComponent
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.
getValueExpression
in class UIComponent
name
- Name of the attribute or property for which to retrieve a
ValueExpression
null
.public void setValueExpression(String name, javax.el.ValueExpression arg1)
UIComponent
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 UIComponent.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.
setValueExpression
in class UIComponent
name
- Name of the attribute or property for which to set a
ValueExpression
arg1
- The ValueExpression
to set, or null
to remove any
currently set ValueExpression
public String getFamily()
UIComponent
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
getFamily
in class UIComponent
public UIComponent getParent()
UIComponent
Return the parent UIComponent
of this UIComponent
, if any. A
component must allow child components to be added to and removed from the list of
children of this component, even though the child component returns null from
getParent( )
.
getParent
in class UIComponentBase
public void setParent(UIComponent parent)
UIComponent
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
.
setParent
in class UIComponentBase
parent
- The new parent, or null
for the root node of a component
treepublic String getRendererType()
UIComponent
Return the Renderer
type for this UIComponent
(if any).
getRendererType
in class UIComponentBase
public void setRendererType(String rendererType)
UIComponent
Set the Renderer
type for this UIComponent
, or null
for components that render themselves.
setRendererType
in class UIComponentBase
rendererType
- Logical identifier of the type of Renderer
to use, or
null
for components that render themselvespublic boolean getRendersChildren()
UIComponent
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)
.
getRendersChildren
in class UIComponentBase
true
if the component renders its children, false
otherwise.public List<UIComponent> getChildren()
UIComponent
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
getChildren
in class UIComponentBase
public int getChildCount()
UIComponent
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.
getChildCount
in class UIComponentBase
public UIComponent findComponent(String id)
UIComponent
Search for and return the
UIComponent
with an id
that matches the specified search
expression (if any), according to the algorithm described below.
WARNING: The found UIComponent
instance, if any, is returned
without regard for its tree traversal context. Retrieving an
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 UIComponent.invokeOnComponent(javax.faces.context.FacesContext, java.lang.String, javax.faces.component.ContextCallback)
for a method that
does correctly account for the tree traversal context when
operating on the found UIComponent
instance.
UIComponent.invokeOnComponent(javax.faces.context.FacesContext, java.lang.String, javax.faces.component.ContextCallback)
is also useful to find components given a simple
clientId
.
Component identifiers are required to be unique within the scope of the closest
ancestor NamingContainer
that encloses this component (which might be this
component itself). If there are no NamingContainer
components in the
ancestry of this component, the root component in the tree is treated as if it were
a NamingContainer
, whether or not its class actually implements the
NamingContainer
interface.
A search expression consists of either an identifier (which is matched
exactly against the id
property of a UIComponent
, or a series
of such identifiers linked by the UINamingContainer.getSeparatorChar(javax.faces.context.FacesContext)
character value. The search algorithm should operates as follows, though alternate
alogrithms may be used as long as the end result is the same:
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.findComponent
in class UIComponentBase
id
- Search expression identifying the UIComponent
to be returnedUIComponent
, or null
if the component was
not found.public Map<String,UIComponent> getFacets()
UIComponent
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
.getFacets
in class UIComponentBase
public int getFacetCount()
UIComponent
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 UIComponent.getFacets()
and then
calls the size()
method on the returned Map
. A more
optimized version of this method is provided in
UIComponentBase.getFacetCount()
.
getFacetCount
in class UIComponentBase
public UIComponent getFacet(String name)
UIComponent
Convenience method to return the named facet, if it exists, or null
otherwise. If the requested facet does not exist, the facets Map must not be
created.
getFacet
in class UIComponentBase
name
- Name of the desired facetnull
.public Iterator<UIComponent> getFacetsAndChildren()
UIComponent
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.
getFacetsAndChildren
in class UIComponentBase
public void broadcast(FacesEvent event) throws AbortProcessingException
UIComponent
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.
broadcast
in class UIComponentBase
event
- The FacesEvent
to be broadcastAbortProcessingException
- Signal the Jakarta Server Faces implementation that no further processing
on the current event should be performedpublic void decode(FacesContext faces)
UIComponent
Decode any new state of this UIComponent
from the request contained in the
specified FacesContext
, and store this state as needed.
During decoding, events may be enqueued for later processing (by event listeners
who have registered an interest), by calling queueEvent()
.
decode
in class UIComponentBase
faces
- FacesContext
for the request we are processingpublic void encodeBegin(FacesContext faces) throws IOException
UIComponent
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
UIComponent.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
UIComponent.pushComponentToEL(javax.faces.context.FacesContext,javax.faces.component.UIComponent)
and return immediately.
encodeBegin
in class UIComponentBase
faces
- FacesContext
for the response we are creatingIOException
- if an input/output error occurs while renderingpublic void encodeChildren(FacesContext faces) throws IOException
UIComponent
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
UIComponent.encodeAll(javax.faces.context.FacesContext)
.
encodeChildren
in class UIComponentBase
faces
- FacesContext
for the response we are creatingIOException
- if an input/output error occurs while renderingpublic void encodeEnd(FacesContext faces) throws IOException
UIComponent
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 UIComponent.popComponentFromEL(javax.faces.context.FacesContext)
. before returning regardless of the
value of the rendered
property.
encodeEnd
in class UIComponentBase
faces
- FacesContext
for the response we are creatingIOException
- if an input/output error occurs while renderingpublic void encodeAll(FacesContext faces) throws IOException
UIComponent
If this component returns true
from UIComponent.isRendered()
, take the
following action.
Render this component and all its children that return true
from
isRendered()
, regardless of the value of the
UIComponent.getRendersChildren()
flag.
encodeAll
in class UIComponent
faces
- the Faces context.IOException
- if an input/output error occurs while renderingprotected void addFacesListener(FacesListener faces)
UIComponentBase
Add the specified FacesListener
to the set of listeners registered to receive event
notifications from this UIComponent
. It is expected that UIComponent
classes
acting as event sources will have corresponding typesafe APIs for registering listeners of
the required type, and the implementation of those registration methods will delegate to this
method. For example:
public class FooEvent extends FacesEvent { ... protected boolean isAppropriateListener(FacesListener listener) { return (listener instanceof FooListener); } protected void processListener(FacesListener listener) { ((FooListener) listener).processFoo(this); } ... } public interface FooListener extends FacesListener { public void processFoo(FooEvent event); } public class FooComponent extends UIComponentBase { ... public void addFooListener(FooListener listener) { addFacesListener(listener); } public void removeFooListener(FooListener listener) { removeFacesListener(listener); } ... }
addFacesListener
in class UIComponentBase
faces
- The FacesListener
to be registeredprotected FacesListener[] getFacesListeners(Class faces)
UIComponent
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
.
getFacesListeners
in class UIComponentBase
faces
- Class that must be implemented by a FacesListener
for it to be
returnedprotected void removeFacesListener(FacesListener faces)
UIComponentBase
Remove the specified FacesListener
from the set of listeners registered to receive
event notifications from this UIComponent
.
removeFacesListener
in class UIComponentBase
faces
- The FacesListener
to be deregisteredpublic void queueEvent(FacesEvent event)
UIComponent
Queue an event for broadcast at the end of the current request processing lifecycle
phase. The default implementation in UIComponentBase
must delegate this
call to the queueEvent()
method of the parent UIComponent
.
queueEvent
in class UIComponentBase
event
- FacesEvent
to be queuedpublic void processDecodes(FacesContext faces)
UIComponent
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.UIComponent.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.UIComponent.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.processDecodes
in class UIComponentBase
faces
- FacesContext
for the request we are processingpublic void processValidators(FacesContext faces)
UIComponent
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.UIComponent.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
UIComponent.popComponentFromEL(javax.faces.context.FacesContext)
.processValidators
in class UIComponentBase
faces
- FacesContext
for the request we are processingPreValidateEvent
,
PostValidateEvent
public void processUpdates(FacesContext faces)
UIComponent
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.UIComponent.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
UIComponent.popComponentFromEL(javax.faces.context.FacesContext)
processUpdates
in class UIComponentBase
faces
- FacesContext
for the request we are processingprotected FacesContext getFacesContext()
UIComponent
Convenience method to return the FacesContext
instance for the current
request.
getFacesContext
in class UIComponentBase
protected Renderer getRenderer(FacesContext faces)
UIComponent
Convenience method to return the Renderer
instance associated with this
component, if any; otherwise, return null
.
getRenderer
in class UIComponentBase
faces
- FacesContext
for the current requestnull
.public boolean isTransient()
StateHolder
If true, the Object implementing this interface must not participate in state saving or restoring.
isTransient
in interface StateHolder
isTransient
in class UIComponentBase
true
if transient, false
otherwise.public void setTransient(boolean tranzient)
StateHolder
Denotes whether or not the Object implementing this interface must or must not participate in state saving or restoring.
setTransient
in interface StateHolder
setTransient
in class UIComponentBase
tranzient
- boolean pass true
if this
Object will not
participate in state saving or restoring, otherwise pass
false
.Comments to: faces-dev@eclipse.org.
Copyright © 2019 Eclipse Foundation. All rights reserved.
Use is subject to license terms.