Class UIComponentBase
- java.lang.Object
-
- jakarta.faces.component.UIComponent
-
- jakarta.faces.component.UIComponentBase
-
- All Implemented Interfaces:
PartialStateHolder
,StateHolder
,TransientStateHolder
,ComponentSystemEventListener
,FacesListener
,SystemEventListenerHolder
,EventListener
- Direct Known Subclasses:
UIColumn
,UICommand
,UIData
,UIForm
,UIGraphic
,UIImportConstants
,UIMessage
,UIMessages
,UINamingContainer
,UIOutput
,UIPanel
,UIParameter
,UISelectItem
,UISelectItems
,UIViewAction
,UIViewRoot
,UIWebsocket
@JSFComponent(type="jakarta.faces.ComponentBase", family="jakarta.faces.ComponentBase", desc="base component when all components must inherit", tagClass="jakarta.faces.webapp.UIComponentELTag", configExcluded=true) @JSFJspProperty(name="binding", returnType="jakarta.faces.component.UIComponent", longDesc="Identifies a backing bean property (of type UIComponent or appropriate subclass) to bind to this component instance. This value must be an EL expression.", desc="backing bean property to bind to this component instance") public abstract class UIComponentBase extends UIComponent
Standard implementation of the UIComponent base class; all standard Faces components extend this class.Disclaimer: The official definition for the behaviour of this class is the Faces 1.1 specification but for legal reasons the specification cannot be replicated here. Any javadoc here therefore describes the current implementation rather than the spec, though this class has been verified as correctly implementing the spec. see Javadoc of Faces Specification for more.
-
-
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 Constructor Description UIComponentBase()
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addClientBehavior(String eventName, ClientBehavior behavior)
protected void
addFacesListener(FacesListener listener)
void
broadcast(FacesEvent event)
Invoke any listeners attached to this object which are listening for an event whose type matches the specified event's runtime type.void
clearInitialState()
void
decode(FacesContext context)
Check the submitted form parameters for data associated with this component.void
encodeAll(FacesContext context)
void
encodeBegin(FacesContext context)
void
encodeChildren(FacesContext context)
void
encodeEnd(FacesContext context)
UIComponent
findComponent(String expr)
Standard method for finding other components by id, inherited by most UIComponent objects.Map<String,Object>
getAttributes()
Get a map through which all the UIComponent's properties, value-bindings and non-property attributes can be read and written.int
getChildCount()
Return the number of direct child components this component has.List<UIComponent>
getChildren()
Return a list of the UIComponent objects which are direct children of this component.Map<String,List<ClientBehavior>>
getClientBehaviors()
String
getClientId(FacesContext context)
Get a string which can be output to the response which uniquely identifies this UIComponent within the current view.String
getDefaultEventName()
Collection<String>
getEventNames()
protected FacesContext
getFacesContext()
protected FacesListener[]
getFacesListeners(Class clazz)
UIComponent
getFacet(String name)
int
getFacetCount()
Map<String,UIComponent>
getFacets()
Iterator<UIComponent>
getFacetsAndChildren()
String
getId()
Get a string which uniquely identifies this UIComponent within the scope of the nearest ancestor NamingContainer component.UIComponent
getParent()
Returns the parent of the component.Map<String,Object>
getPassThroughAttributes(boolean create)
protected Renderer
getRenderer(FacesContext context)
String
getRendererType()
boolean
getRendersChildren()
Indicates whether this component or its renderer manages the invocation of the rendering methods of its child components.boolean
invokeOnComponent(FacesContext context, String clientId, ContextCallback callback)
invokeOnComponent
must be implemented inUIComponentBase
too...boolean
isRendered()
A boolean value that indicates whether this component should be rendered.boolean
isTransient()
void
markInitialState()
void
processDecodes(FacesContext context)
void
processRestoreState(FacesContext context, Object state)
Object
processSaveState(FacesContext context)
void
processUpdates(FacesContext context)
This isn't an input component, so just pass on the processUpdates call to child components and facets that might be input components.void
processValidators(FacesContext context)
void
queueEvent(FacesEvent event)
protected void
removeFacesListener(FacesListener listener)
static Object
restoreAttachedState(FacesContext context, Object stateObj)
void
restoreState(FacesContext context, Object state)
Invoked in the "restore view" phase, this initialises this object's members from the values saved previously into the provided state object.static Object
saveAttachedState(FacesContext context, Object attachedObject)
Serializes objects which are "attached" to this component but which are not UIComponent children of it.Object
saveState(FacesContext context)
Invoked after the render phase has completed, this method returns an object which can be passed to the restoreState of some other instance of UIComponentBase to reset that object's state to the same values as this object currently has.void
setId(String id)
Set an identifier for this component which is unique within the scope of the nearest ancestor NamingContainer component.void
setParent(UIComponent parent)
Set the parentUIComponent
of thisUIComponent
.void
setRendered(boolean rendered)
void
setRendererType(String rendererType)
void
setTransient(boolean transientFlag)
boolean
visitTree(VisitContext context, VisitCallback callback)
The visit tree method, visit tree walks over a subtree and processes the callback object to perform some operation on the subtree-
Methods inherited from class jakarta.faces.component.UIComponent
getClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getFamily, getListenersForEventClass, getNamingContainer, getPassThroughAttributes, getResourceBundleMap, getStateHelper, getStateHelper, getTransientStateHelper, getTransientStateHelper, getValueExpression, initialStateMarked, isCompositeComponent, isInView, isVisitable, popComponentFromEL, processEvent, pushComponentToEL, restoreTransientState, saveTransientState, setInView, setValueExpression, subscribeToEvent, unsubscribeFromEvent
-
-
-
-
Method Detail
-
setId
public void setId(String id)
Set an identifier for this component which is unique within the scope of the nearest ancestor NamingContainer component. The id is not necessarily unique across all components in the current view.The id must start with an underscore if it is generated by the Faces framework, and must not start with an underscore if it has been specified by the user (eg in a JSP tag).
The first character of the id must be an underscore or letter. Following characters may be letters, digits, underscores or dashes.
Null is allowed as a parameter, and will reset the id to null.
The clientId of this component is reset by this method; see getClientId for more info.
- Specified by:
setId
in classUIComponent
- Throws:
IllegalArgumentException
- if the id is not valid.
-
setParent
public void setParent(UIComponent parent)
Set the parent
UIComponent
of thisUIComponent
.- Specified by:
setParent
in classUIComponent
- Parameters:
parent
- The new parent, ornull
for the root node of a component tree
-
addClientBehavior
public void addClientBehavior(String eventName, ClientBehavior behavior)
- Parameters:
eventName
-behavior
-- Since:
- 2.0
-
broadcast
public void broadcast(FacesEvent event) throws AbortProcessingException
Invoke any listeners attached to this object which are listening for an event whose type matches the specified event's runtime type.This method does not propagate the event up to parent components, ie listeners attached to parent components don't automatically get called.
If any of the listeners throws AbortProcessingException then that exception will prevent any further listener callbacks from occurring, and the exception propagates out of this method without alteration.
ActionEvent events are typically queued by the renderer associated with this component in its decode method; ValueChangeEvent events by the component's validate method. In either case the event's source property references a component. At some later time the UIViewRoot component iterates over its queued events and invokes the broadcast method on each event's source object.
- Specified by:
broadcast
in classUIComponent
- Parameters:
event
- must not be null.- Throws:
AbortProcessingException
-
clearInitialState
public void clearInitialState()
Description copied from class:UIComponent
- Specified by:
clearInitialState
in interfacePartialStateHolder
- Overrides:
clearInitialState
in classUIComponent
-
decode
public void decode(FacesContext context)
Check the submitted form parameters for data associated with this component. This default implementation delegates to this component's renderer if there is one, and otherwise ignores the call.- Specified by:
decode
in classUIComponent
-
encodeAll
public void encodeAll(FacesContext context) throws IOException
- Overrides:
encodeAll
in classUIComponent
- Throws:
IOException
-
encodeBegin
public void encodeBegin(FacesContext context) throws IOException
- Specified by:
encodeBegin
in classUIComponent
- Throws:
IOException
-
encodeChildren
public void encodeChildren(FacesContext context) throws IOException
- Specified by:
encodeChildren
in classUIComponent
- Throws:
IOException
-
encodeEnd
public void encodeEnd(FacesContext context) throws IOException
- Specified by:
encodeEnd
in classUIComponent
- Throws:
IOException
-
findComponent
public UIComponent findComponent(String expr)
Standard method for finding other components by id, inherited by most UIComponent objects.The lookup is performed in a manner similar to finding a file in a filesystem; there is a "base" at which to start, and the id can be for something in the "local directory", or can include a relative path. Here, NamingContainer components fill the role of directories, and ":" is the "path separator". Note, however, that although components have a strict parent/child hierarchy, component ids are only prefixed ("namespaced") with the id of their parent when the parent is a NamingContainer.
The base node at which the search starts is determined as follows:
- When expr starts with ':', the search starts with the root component of the tree that this component is in (ie the ancestor whose parent is null).
- Otherwise, if this component is a NamingContainer then the search starts with this component.
- Otherwise, the search starts from the nearest ancestor NamingContainer (or the root component if there is no NamingContainer ancestor).
- Specified by:
findComponent
in classUIComponent
- Parameters:
expr
- is of form "id1:id2:id3".- Returns:
- UIComponent or null if no component with the specified id is found.
-
getAttributes
public Map<String,Object> getAttributes()
Get a map through which all the UIComponent's properties, value-bindings and non-property attributes can be read and written.When writing to the returned map:
- If this component has an explicit property for the specified key then the setter method is called. An IllegalArgumentException is thrown if the property is read-only. If the property is readable then the old value is returned, otherwise null is returned.
- Otherwise the key/value pair is stored in a map associated with the component.
When reading from the returned map:
- If this component has an explicit property for the specified key then the getter method is called. If the property exists, but is read-only (ie only a setter method is defined) then an IllegalArgumentException is thrown.
- If the attribute map associated with the component has an entry with the specified key, then that is returned.
- If this component has a value-binding for the specified key, then the value-binding is evaluated to fetch the value.
- Otherwise, null is returned.
Assigning values to the map which are not explicit properties on the underlying component can be used to "tunnel" attributes from the JSP tag (or view-specific equivalent) to the associated renderer without modifying the component itself.
Any value-bindings and non-property attributes stored in this map are automatically serialized along with the component when the view is serialized.
- Specified by:
getAttributes
in classUIComponent
-
getPassThroughAttributes
public Map<String,Object> getPassThroughAttributes(boolean create)
- Overrides:
getPassThroughAttributes
in classUIComponent
- Returns:
- A
Map
instance, ornull
.
-
getChildCount
public int getChildCount()
Return the number of direct child components this component has.Identical to getChildren().size() except that when this component has no children this method will not force an empty list to be created.
- Specified by:
getChildCount
in classUIComponent
-
getChildren
public List<UIComponent> getChildren()
Return a list of the UIComponent objects which are direct children of this component.The list object returned has some non-standard behaviour:
- The list is type-checked; only UIComponent objects can be added.
- If a component is added to the list with an id which is the same as some other component in the list then an exception is thrown. However multiple components with a null id may be added.
- The component's parent property is set to this component. If the component already had a parent, then the component is first removed from its original parent's child list.
- Specified by:
getChildren
in classUIComponent
-
getClientBehaviors
public Map<String,List<ClientBehavior>> getClientBehaviors()
- Returns:
- Since:
- 2.0
-
getClientId
public String getClientId(FacesContext context)
Get a string which can be output to the response which uniquely identifies this UIComponent within the current view.The component should have an id attribute already assigned to it; however if the id property is currently null then a unique id is generated and set for this component. This only happens when components are programmatically created without ids, as components created by a ViewHandler should be assigned ids when they are created.
If this component is a descendant of a NamingContainer then the client id is of form "{namingContainerId}:{componentId}". Note that the naming container's id may itself be of compound form if it has an ancestor naming container. Note also that this only applies to naming containers; other UIComponent types in the component's ancestry do not affect the clientId.
Finally the renderer associated with this component is asked to convert the id into a suitable form. This allows escaping of any characters in the clientId which are significant for the markup language generated by that renderer.
- Specified by:
getClientId
in classUIComponent
-
getDefaultEventName
public String getDefaultEventName()
- Returns:
- Since:
- 2.0
-
getEventNames
public Collection<String> getEventNames()
- Returns:
- Since:
- 2.0
-
getFacet
public UIComponent getFacet(String name)
- Specified by:
getFacet
in classUIComponent
-
getFacetCount
public int getFacetCount()
- Overrides:
getFacetCount
in classUIComponent
- Since:
- 1.2
-
getFacets
public Map<String,UIComponent> getFacets()
- Specified by:
getFacets
in classUIComponent
-
getFacetsAndChildren
public Iterator<UIComponent> getFacetsAndChildren()
- Specified by:
getFacetsAndChildren
in classUIComponent
-
getId
@JSFProperty(rtexprvalue=true) public String getId()
Get a string which uniquely identifies this UIComponent within the scope of the nearest ancestor NamingContainer component. The id is not necessarily unique across all components in the current view.- Specified by:
getId
in classUIComponent
-
getParent
public UIComponent getParent()
Description copied from class:UIComponent
Returns the parent of the component. Children can be added to or removed from a component even if this method returns null for the child.- Specified by:
getParent
in classUIComponent
-
getRendererType
public String getRendererType()
- Specified by:
getRendererType
in classUIComponent
-
getRendersChildren
public boolean getRendersChildren()
Indicates whether this component or its renderer manages the invocation of the rendering methods of its child components. When this is true:- This component's encodeBegin method will only be called after all the child components have been created and added to this component.
- This component's encodeChildren method will be called after its encodeBegin method. Components for which this method returns false do not get this method invoked at all.
- No rendering methods will be called automatically on child components; this component is required to invoke the encodeBegin/encodeEnd/etc on them itself.
- Specified by:
getRendersChildren
in classUIComponent
-
invokeOnComponent
public boolean invokeOnComponent(FacesContext context, String clientId, ContextCallback callback) throws FacesException
invokeOnComponent
must be implemented inUIComponentBase
too...- Overrides:
invokeOnComponent
in classUIComponent
- Parameters:
context
-FacesContext
for the current requestclientId
- the id of the desiredUIComponent
clazzcallback
- Implementation of theContextCallback
to be called- Returns:
- has component been found ?
- Throws:
FacesException
-
visitTree
public boolean visitTree(VisitContext context, VisitCallback callback)
Description copied from class:UIComponent
The visit tree method, visit tree walks over a subtree and processes the callback object to perform some operation on the subtreethere are some details in the implementation which according to the spec have to be in place: a) before calling the callback and traversing into the subtree pushComponentToEL has to be called b) after the processing popComponentFromEL has to be performed to remove the component from the el
The tree traversal optimizations are located in the visit context and can be replaced via the VisitContextFactory in the faces-config factory section
- Overrides:
visitTree
in classUIComponent
- Parameters:
context
- the visit context which handles the processing detailscallback
- the callback to be performed- Returns:
- false if the processing is not done true if we can shortcut the visiting because we are done with everything
-
isRendered
@JSFProperty public boolean isRendered()
A boolean value that indicates whether this component should be rendered. Default value: true.- Specified by:
isRendered
in classUIComponent
-
isTransient
@JSFProperty(literalOnly=true, istransient=true, tagExcluded=true) public boolean isTransient()
-
markInitialState
public void markInitialState()
- Specified by:
markInitialState
in interfacePartialStateHolder
- Overrides:
markInitialState
in classUIComponent
-
addFacesListener
protected void addFacesListener(FacesListener listener)
- Specified by:
addFacesListener
in classUIComponent
-
getFacesContext
protected FacesContext getFacesContext()
- Specified by:
getFacesContext
in classUIComponent
-
getFacesListeners
protected FacesListener[] getFacesListeners(Class clazz)
- Specified by:
getFacesListeners
in classUIComponent
-
getRenderer
protected Renderer getRenderer(FacesContext context)
- Specified by:
getRenderer
in classUIComponent
-
removeFacesListener
protected void removeFacesListener(FacesListener listener)
- Specified by:
removeFacesListener
in classUIComponent
-
queueEvent
public void queueEvent(FacesEvent event)
- Specified by:
queueEvent
in classUIComponent
-
processDecodes
public void processDecodes(FacesContext context)
- Specified by:
processDecodes
in classUIComponent
-
processValidators
public void processValidators(FacesContext context)
- Specified by:
processValidators
in classUIComponent
-
processUpdates
public void processUpdates(FacesContext context)
This isn't an input component, so just pass on the processUpdates call to child components and facets that might be input components.Components that were never rendered can't possibly be receiving update data (no corresponding fields were ever put into the response) so if this component is not rendered then this method does not invoke processUpdates on its children.
- Specified by:
processUpdates
in classUIComponent
-
processSaveState
public Object processSaveState(FacesContext context)
- Specified by:
processSaveState
in classUIComponent
-
processRestoreState
public void processRestoreState(FacesContext context, Object state)
- Specified by:
processRestoreState
in classUIComponent
-
setTransient
public void setTransient(boolean transientFlag)
-
saveAttachedState
public static Object saveAttachedState(FacesContext context, Object attachedObject)
Serializes objects which are "attached" to this component but which are not UIComponent children of it. Examples are validator and listener objects. To be precise, it returns an object which implements java.io.Serializable, and which when serialized will persist the state of the provided object.If the attachedObject is a List then every object in the list is saved via a call to this method, and the returned wrapper object contains a List object.
If the object implements StateHolder then the object's saveState is called immediately, and a wrapper is returned which contains both this saved state and the original class name. However in the case where the StateHolder.isTransient method returns true, null is returned instead.
If the object implements java.io.Serializable then the object is simply returned immediately; standard java serialization will later be used to store this object.
In all other cases, a wrapper is returned which simply stores the type of the provided object. When deserialized, a default instance of that type will be recreated.
-
restoreAttachedState
public static Object restoreAttachedState(FacesContext context, Object stateObj) throws IllegalStateException
- Throws:
IllegalStateException
-
saveState
public Object saveState(FacesContext context)
Invoked after the render phase has completed, this method returns an object which can be passed to the restoreState of some other instance of UIComponentBase to reset that object's state to the same values as this object currently has.
-
restoreState
public void restoreState(FacesContext context, Object state)
Invoked in the "restore view" phase, this initialises this object's members from the values saved previously into the provided state object.- Parameters:
state
- is an object previously returned by the saveState method of this class.
-
setRendered
public void setRendered(boolean rendered)
- Specified by:
setRendered
in classUIComponent
-
setRendererType
public void setRendererType(String rendererType)
- Specified by:
setRendererType
in classUIComponent
-
-