Class UILeaf
- All Implemented Interfaces:
PartialStateHolder,UntargetableComponent,StateHolder,TransientStateHolder,ComponentSystemEventListener,FacesListener,SystemEventListenerHolder,EventListener
- Direct Known Subclasses:
UIInstructions,UILiteralText,UIText
-
Field Summary
Fields inherited from class jakarta.faces.component.UIComponent
ATTRS_WITH_DECLARED_DEFAULT_VALUES, BEANINFO_KEY, bindings, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, FACETS_KEY, VIEW_LOCATION_KEY -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprotected voidaddFacesListener(FacesListener faces) Add the specifiedFacesListenerto the set of listeners registered to receive event notifications from thisUIComponent.voidbroadcast(FacesEvent event) Broadcast the specifiedFacesEventto all registered event listeners who have expressed an interest in events of this type.voiddecode(FacesContext faces) Decode any new state of thisUIComponentfrom the request contained in the specifiedFacesContext, and store this state as needed.voidencodeAll(FacesContext faces) If this component returnstruefromUIComponent.isRendered(), take the following action.voidencodeBegin(FacesContext faces) If ourrenderedproperty istrue, render the beginning of the current state of thisUIComponentto the response contained in the specifiedFacesContext.voidencodeChildren(FacesContext faces) voidencodeEnd(FacesContext faces) findComponent(String id) Search for and return theUIComponentwith anidthat matches the specified search expression (if any), according to the algorithm described below.intReturn the number of childUIComponents that are associated with thisUIComponent.protected FacesContextConvenience method to return theFacesContextinstance for the current request.protected FacesListener[]getFacesListeners(Class faces) Return an array of registeredFacesListeners that are instances of the specified class.Convenience method to return the named facet, if it exists, ornullotherwise.intReturn the number of facetUIComponents that are associated with thisUIComponent.Return a mutableMaprepresenting the facetUIComponents associated with thisUIComponent, keyed by facet name (which must be a String).Return the identifier of the component family to which this component belongs.Return the parentUIComponentof thisUIComponent, if any.protected RenderergetRenderer(FacesContext faces) Convenience method to return theRendererinstance associated with this component, if any; otherwise, returnnull.Return theRenderertype for thisUIComponent(if any).booleanReturn a flag indicating whether this component is responsible for rendering its child components.jakarta.el.ValueExpressiongetValueExpression(String name) Return theValueExpressionused to calculate the value for the specified attribute or property name, if any.booleanIf true, the Object implementing this interface must not participate in state saving or restoring.voidprocessDecodes(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.voidprocessUpdates(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.voidprocessValidators(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.voidqueueEvent(FacesEvent event) Queue an event for broadcast at the end of the current request processing lifecycle phase.protected voidremoveFacesListener(FacesListener faces) Remove the specifiedFacesListenerfrom the set of listeners registered to receive event notifications from thisUIComponent.voidsetParent(UIComponent parent) Set the parentUIComponentof thisUIComponent.voidsetRendererType(String rendererType) voidsetTransient(boolean tranzient) Denotes whether or not the Object implementing this interface must or must not participate in state saving or restoring.voidsetValueExpression(String name, jakarta.el.ValueExpression arg1) Set theValueExpressionused to calculate the value for the specified attribute or property name, if any.Methods inherited from class jakarta.faces.component.UIComponentBase
addClientBehavior, clearInitialState, getAttributes, getClientBehaviors, getClientId, getDefaultEventName, getEventNames, getId, getListenersForEventClass, getPassThroughAttributes, invokeOnComponent, isRendered, markInitialState, processRestoreState, processSaveState, restoreAttachedState, restoreState, saveAttachedState, saveState, setId, setRendered, subscribeToEvent, unsubscribeFromEventMethods inherited from class jakarta.faces.component.UIComponent
getClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getNamingContainer, getPassThroughAttributes, getResourceBundleMap, getStateHelper, getStateHelper, getTransientStateHelper, getTransientStateHelper, initialStateMarked, isCompositeComponent, isInView, isVisitable, popComponentFromEL, processEvent, pushComponentToEL, restoreTransientState, saveTransientState, setInView, visitTree
-
Constructor Details
-
UILeaf
public UILeaf()
-
-
Method Details
-
getValueExpression
Description copied from class:UIComponentReturn the
ValueExpressionused 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.
- Overrides:
getValueExpressionin classUIComponent- Parameters:
name- Name of the attribute or property for which to retrieve aValueExpression- Returns:
- the value expression, or
null.
-
setValueExpression
Description copied from class:UIComponentSet the
ValueExpressionused to calculate the value for the specified attribute or property name, if any.The implementation must call
Expression.isLiteralText()on the argumentexpression. IfisLiteralText()returnstrue, invokeValueExpression.getValue(jakarta.el.ELContext)on the argument expression and pass the result as thevalueparameter in a call tothis.whereUIComponent.getAttributes().put(name, value)nameis the argumentname. If an exception is thrown as a result of callingValueExpression.getValue(jakarta.el.ELContext), wrap it in aFacesExceptionand re-throw it. IfisLiteralText()returnsfalse, simply store the un-evaluatedexpressionargument in the collection ofValueExpressions under the key given by the argumentname.This method must be overridden and implemented for components that comply with Jakarta Faces 1.2 and later.
- Overrides:
setValueExpressionin classUIComponent- Parameters:
name- Name of the attribute or property for which to set aValueExpressionarg1- TheValueExpressionto set, ornullto remove any currently setValueExpression
-
getFamily
Description copied from class:UIComponentReturn the identifier of the component family to which this component belongs. This identifier, in conjunction with the value of the
rendererTypeproperty, may be used to select the appropriateRendererfor this component instance. Note this method should NOT returnnull- Specified by:
getFamilyin classUIComponent- Returns:
- the component family (not null).
-
getParent
Description copied from class:UIComponentReturn the parent
UIComponentof thisUIComponent, 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 fromgetParent( ).- Overrides:
getParentin classUIComponentBase- Returns:
- the parent component.
-
setParent
Description copied from class:UIComponentSet the parent
UIComponentof thisUIComponent. Ifparent.isInView()returnstrue, calling this method will first cause aPreRemoveFromViewEventto be published, for this node, and then the children of this node. Then, once the re-parenting has occurred, aPostAddToViewEventwill 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()returnsPhaseId.RESTORE_VIEWand partial state saving is enabled. -
FacesContext.isPostback()returnsfalseandFacesContext.getCurrentPhaseId()returns something other thanPhaseId.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 childListor facetMap.- Overrides:
setParentin classUIComponentBase- Parameters:
parent- The new parent, ornullfor the root node of a component tree
-
-
getRendererType
Description copied from class:UIComponentReturn the
Renderertype for thisUIComponent(if any).- Overrides:
getRendererTypein classUIComponentBase- Returns:
- the renderer type.
-
setRendererType
Description copied from class:UIComponentSet the
Renderertype for thisUIComponent, ornullfor components that render themselves.- Overrides:
setRendererTypein classUIComponentBase- Parameters:
rendererType- Logical identifier of the type ofRendererto use, ornullfor components that render themselves
-
getRendersChildren
public boolean getRendersChildren()Description copied from class:UIComponentReturn 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 callsRenderer.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 returntruefrom this method and rely onUIComponentBase.encodeChildren(jakarta.faces.context.FacesContext).- Overrides:
getRendersChildrenin classUIComponentBase- Returns:
trueif the component renders its children,falseotherwise.
-
getChildren
Description copied from class:UIComponentReturn a mutable
Listrepresenting the childUIComponents associated with this component. The returned implementation must support all of the standard and optionalListmethods, plus support the following additional requirements:- The
Listimplementation must implement thejava.io.Serializableinterface. - Any attempt to add a
nullmust throw a NullPointerException - Any attempt to add an object that does not implement
UIComponentmust throw a ClassCastException. - Whenever a new child component is added, the
parentproperty of the child must be set to this component instance. If theparentproperty of the child was already non-null, the child must first be removed from its previous parent (where it may have been either a child or a facet). - Whenever an existing child component is removed, the
parentproperty of the child must be set tonull. -
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, passingPostAddToViewEvent.classas the first argument and the newly added component as the second argument if any the following cases are true.-
FacesContext.getCurrentPhaseId()returnsPhaseId.RESTORE_VIEWand partial state saving is enabled. -
FacesContext.isPostback()returnsfalseandFacesContext.getCurrentPhaseId()returns something other thanPhaseId.RESTORE_VIEW
-
- Overrides:
getChildrenin classUIComponentBase- Returns:
- the list of children.
- The
-
getChildCount
public int getChildCount()Description copied from class:UIComponentReturn the number of child
UIComponents that are associated with thisUIComponent. If there are no children, this method must return 0. The method must not cause the creation of a child component list.- Overrides:
getChildCountin classUIComponentBase- Returns:
- the number of child components.
-
findComponent
Description copied from class:UIComponentSearch for and return the
UIComponentwith anidthat matches the specified search expression (if any), according to the algorithm described below.WARNING: The found
UIComponentinstance, 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. SeeUIComponent.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 foundUIComponentinstance.UIComponent.invokeOnComponent(jakarta.faces.context.FacesContext, java.lang.String, jakarta.faces.component.ContextCallback)is also useful to find components given a simpleclientId.Component identifiers are required to be unique within the scope of the closest ancestor
NamingContainerthat encloses this component (which might be this component itself). If there are noNamingContainercomponents in the ancestry of this component, the root component in the tree is treated as if it were aNamingContainer, whether or not its class actually implements theNamingContainerinterface.A search expression consists of either an identifier (which is matched exactly against the
idproperty of aUIComponent, or a series of such identifiers linked by theUINamingContainer.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:- Identify the
UIComponentthat will be the base for searching, by stopping as soon as one of the following conditions is met:- If the search expression begins with the the separator character (called an "absolute" search expression), the
base will be the root
UIComponentof the component tree. The leading separator character will be stripped off, and the remainder of the search expression will be treated as a "relative" search expression as described below. - Otherwise, if this
UIComponentis aNamingContainerit will serve as the basis. - Otherwise, search up the parents of this component. If a
NamingContaineris encountered, it will be the base. - Otherwise (if no
NamingContaineris encountered) the rootUIComponentwill be the base.
- If the search expression begins with the the separator character (called an "absolute" search expression), the
base will be the root
- The search expression (possibly modified in the previous step) is now a "relative" search expression that will be
used to locate the component (if any) that has an
idthat matches, within the scope of the base component. The match is performed as follows:- If the search expression is a simple identifier, this value is compared to the
idproperty, and then recursively through the facets and children of the baseUIComponent(except that if a descendantNamingContaineris found, its own facets and children are not searched). - If the search expression includes more than one identifier separated by the separator character, the first
identifier is used to locate a
NamingContainerby the rules in the previous bullet point. Then, thefindComponent()method of thisNamingContainerwill be called, passing the remainder of the search expression.
- If the search expression is a simple identifier, this value is compared to the
- Overrides:
findComponentin classUIComponentBase- Parameters:
id- Search expression identifying theUIComponentto be returned- Returns:
- the found
UIComponent, ornullif the component was not found.
- Identify the
-
getFacets
Description copied from class:UIComponentReturn a mutable
Maprepresenting the facetUIComponents associated with thisUIComponent, keyed by facet name (which must be a String). The returned implementation must support all of the standard and optionalMapmethods, plus support the following additional requirements:- The
Mapimplementation must implement thejava.io.Serializableinterface. - Any attempt to add a
nullkey or value must throw a NullPointerException. - Any attempt to add a key that is not a String must throw a ClassCastException.
- Any attempt to add a value that is not a
UIComponentmust throw a ClassCastException. - Whenever a new facet
UIComponentis added:- The
parentproperty of the component must be set to this component instance. - If the
parentproperty 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).
- The
- Whenever an existing facet
UIComponentis removed:- The
parentproperty of the facet must be set tonull.
- The
- Overrides:
getFacetsin classUIComponentBase- Returns:
- the map of facets.
- The
-
getFacetCount
public int getFacetCount()Description copied from class:UIComponentReturn the number of facet
UIComponents that are associated with thisUIComponent. 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 thesize()method on the returnedMap. A more optimized version of this method is provided inUIComponentBase.getFacetCount().- Overrides:
getFacetCountin classUIComponentBase- Returns:
- the number of facets.
-
getFacet
Description copied from class:UIComponentConvenience method to return the named facet, if it exists, or
nullotherwise. If the requested facet does not exist, the facets Map must not be created.- Overrides:
getFacetin classUIComponentBase- Parameters:
name- Name of the desired facet- Returns:
- the component, or
null.
-
getFacetsAndChildren
Description copied from class:UIComponentReturn an
Iteratorover the facet followed by childUIComponents of thisUIComponent. 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 emptyIteratoris returned.The returned
Iteratormust not support theremove()operation.- Overrides:
getFacetsAndChildrenin classUIComponentBase- Returns:
- the facets and children iterator.
-
broadcast
Description copied from class:UIComponentBroadcast the specified
FacesEventto 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
eventis an instance ofBehaviorEventand the currentcomponentis the source of theeventcallBehaviorEvent.getBehavior()to get theBehaviorfor the event. CallBehavior.broadcast(jakarta.faces.event.BehaviorEvent)on theBehaviorinstance.- Overrides:
broadcastin classUIComponentBase- Parameters:
event- TheFacesEventto be broadcast- Throws:
AbortProcessingException- Signal the Jakarta Faces implementation that no further processing on the current event should be performed
-
decode
Description copied from class:UIComponentDecode any new state of this
UIComponentfrom the request contained in the specifiedFacesContext, 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().- Overrides:
decodein classUIComponentBase- Parameters:
faces-FacesContextfor the request we are processing
-
encodeBegin
Description copied from class:UIComponentIf our
renderedproperty istrue, render the beginning of the current state of thisUIComponentto the response contained in the specifiedFacesContext. CallUIComponent.pushComponentToEL(jakarta.faces.context.FacesContext,jakarta.faces.component.UIComponent). CallApplication.publishEvent(jakarta.faces.context.FacesContext, java.lang.Class<? extends jakarta.faces.event.SystemEvent>, java.lang.Object), passingPreRenderComponentEvent.classas the first argument and the component instance to be rendered as the second argument.If a
Rendereris associated with thisUIComponent, the actual encoding will be delegated toRenderer.encodeBegin(FacesContext, UIComponent).If our
renderedproperty isfalse, callUIComponent.pushComponentToEL(jakarta.faces.context.FacesContext,jakarta.faces.component.UIComponent)and return immediately.- Overrides:
encodeBeginin classUIComponentBase- Parameters:
faces-FacesContextfor the response we are creating- Throws:
IOException- if an input/output error occurs while rendering
-
encodeChildren
Description copied from class:UIComponentIf our
renderedproperty istrue, render the childUIComponents of thisUIComponent. This method will only be called if therendersChildrenproperty istrue.If a
Rendereris associated with thisUIComponent, the actual encoding will be delegated toRenderer.encodeChildren(FacesContext, UIComponent). If noRendereris associated with thisUIComponent, iterate over each of the children of this component and callUIComponent.encodeAll(jakarta.faces.context.FacesContext).- Overrides:
encodeChildrenin classUIComponentBase- Parameters:
faces-FacesContextfor the response we are creating- Throws:
IOException- if an input/output error occurs while rendering
-
encodeEnd
Description copied from class:UIComponentIf our
renderedproperty istrue, render the ending of the current state of thisUIComponent.If a
Rendereris associated with thisUIComponent, the actual encoding will be delegated toRenderer.encodeEnd(FacesContext, UIComponent).Call
UIComponent.popComponentFromEL(jakarta.faces.context.FacesContext). before returning regardless of the value of therenderedproperty.- Overrides:
encodeEndin classUIComponentBase- Parameters:
faces-FacesContextfor the response we are creating- Throws:
IOException- if an input/output error occurs while rendering
-
encodeAll
Description copied from class:UIComponentIf this component returns
truefromUIComponent.isRendered(), take the following action.Render this component and all its children that return
truefromisRendered(), regardless of the value of theUIComponent.getRendersChildren()flag.- Overrides:
encodeAllin classUIComponent- Parameters:
faces- the Faces context.- Throws:
IOException- if an input/output error occurs while rendering
-
addFacesListener
Description copied from class:UIComponentBaseAdd the specified
FacesListenerto the set of listeners registered to receive event notifications from thisUIComponent. It is expected thatUIComponentclasses 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); } ... }- Overrides:
addFacesListenerin classUIComponentBase- Parameters:
faces- TheFacesListenerto be registered
-
getFacesListeners
Description copied from class:UIComponentReturn an array of registered
FacesListeners 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 ofclazz.- Overrides:
getFacesListenersin classUIComponentBase- Parameters:
faces- Class that must be implemented by aFacesListenerfor it to be returned- Returns:
- the Faces listeners, or a zero-length array.
-
removeFacesListener
Description copied from class:UIComponentBaseRemove the specified
FacesListenerfrom the set of listeners registered to receive event notifications from thisUIComponent.- Overrides:
removeFacesListenerin classUIComponentBase- Parameters:
faces- TheFacesListenerto be deregistered
-
queueEvent
Description copied from class:UIComponentQueue an event for broadcast at the end of the current request processing lifecycle phase. The default implementation in
UIComponentBasemust delegate this call to thequeueEvent()method of the parentUIComponent.- Overrides:
queueEventin classUIComponentBase- Parameters:
event-FacesEventto be queued
-
processDecodes
Description copied from class:UIComponentPerform the component tree processing required by the Apply Request Values phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
- If the
renderedproperty of thisUIComponentisfalse, skip further processing. - Call
UIComponent.pushComponentToEL(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent). - Call the
processDecodes()method of all facets and children of thisUIComponent, in the order determined by a call togetFacetsAndChildren(). - Call the
decode()method of this component. - Call
UIComponent.popComponentFromEL(jakarta.faces.context.FacesContext)from inside of afinally block, just before returning. - If a
RuntimeExceptionis thrown during decode processing, callFacesContext.renderResponse()and re-throw the exception.
- Overrides:
processDecodesin classUIComponentBase- Parameters:
faces-FacesContextfor the request we are processing
- If the
-
processValidators
Description copied from class:UIComponentPerform the component tree processing required by the Process Validations phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
- If the
renderedproperty of thisUIComponentisfalse, skip further processing. - Call
UIComponent.pushComponentToEL(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent). - Call the
processValidators()method of all facets and children of thisUIComponent, in the order determined by a call togetFacetsAndChildren(). - After returning from calling
getFacetsAndChildren()callUIComponent.popComponentFromEL(jakarta.faces.context.FacesContext).
- Overrides:
processValidatorsin classUIComponentBase- Parameters:
faces-FacesContextfor the request we are processing- See Also:
- If the
-
processUpdates
Description copied from class:UIComponentPerform the component tree processing required by the Update Model Values phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
- If the
renderedproperty of thisUIComponentisfalse, skip further processing. - Call
UIComponent.pushComponentToEL(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent). - Call the
processUpdates()method of all facets and children of thisUIComponent, in the order determined by a call togetFacetsAndChildren(). After returning from theprocessUpdates()method on a child or facet, callUIComponent.popComponentFromEL(jakarta.faces.context.FacesContext)
- Overrides:
processUpdatesin classUIComponentBase- Parameters:
faces-FacesContextfor the request we are processing
- If the
-
getFacesContext
Description copied from class:UIComponentConvenience method to return the
FacesContextinstance for the current request.- Overrides:
getFacesContextin classUIComponentBase- Returns:
- the Faces context.
-
getRenderer
Description copied from class:UIComponentConvenience method to return the
Rendererinstance associated with this component, if any; otherwise, returnnull.- Overrides:
getRendererin classUIComponentBase- Parameters:
faces-FacesContextfor the current request- Returns:
- the renderer, or
null.
-
isTransient
public boolean isTransient()Description copied from interface:StateHolderIf true, the Object implementing this interface must not participate in state saving or restoring.
- Specified by:
isTransientin interfaceStateHolder- Overrides:
isTransientin classUIComponentBase- Returns:
trueif transient,falseotherwise.
-
setTransient
public void setTransient(boolean tranzient) Description copied from interface:StateHolderDenotes whether or not the Object implementing this interface must or must not participate in state saving or restoring.
- Specified by:
setTransientin interfaceStateHolder- Overrides:
setTransientin classUIComponentBase- Parameters:
tranzient- boolean passtrueif this Object will not participate in state saving or restoring, otherwise passfalse.
-