public abstract class UIComponentBase extends UIComponent
UIComponentBase is a
convenience base class that implements the default concrete behavior of all methods defined by UIComponent
.
By default, this class defines getRendersChildren()
to find the renderer for this component and call its
getRendersChildren()
method. The default implementation on the Renderer
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 the implementation of encodeChildren(jakarta.faces.context.FacesContext)
in this class and
in the Renderer (Renderer.encodeChildren(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent)
). Subclasses that wish to manage the rendering of their children
should override this method to return true
instead.
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 |
---|
UIComponentBase() |
Modifier and Type | Method and Description |
---|---|
void |
addClientBehavior(String eventName,
ClientBehavior behavior)
This is a default implementation of |
protected void |
addFacesListener(FacesListener listener)
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 |
clearInitialState()
For each of the attached objects on this instance that implement |
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 |
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 . |
void |
encodeChildren(FacesContext context)
|
void |
encodeEnd(FacesContext context)
|
UIComponent |
findComponent(String expression)
Search for and return the
UIComponent with an id that
matches the specified search expression (if any), according to the algorithm described below. |
Map<String,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). |
int |
getChildCount()
Return the number of child
UIComponent s that are associated with this UIComponent . |
List<UIComponent> |
getChildren()
|
Map<String,List<ClientBehavior>> |
getClientBehaviors()
This is a default implementation of |
String |
getClientId(FacesContext context)
Return a client-side identifier for this component, generating one if necessary.
|
String |
getDefaultEventName()
This is a default implementation of
|
Collection<String> |
getEventNames()
This is a default implementation of |
protected FacesContext |
getFacesContext()
Convenience method to return the
FacesContext instance for the current request. |
protected FacesListener[] |
getFacesListeners(Class clazz)
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 |
getId()
Return the component identifier of this
UIComponent . |
List<SystemEventListener> |
getListenersForEventClass(Class<? extends SystemEvent> eventClass)
Return the |
UIComponent |
getParent()
Return the parent
UIComponent of this UIComponent , if any. |
Map<String,Object> |
getPassThroughAttributes(boolean create)
This method has the same specification as |
protected Renderer |
getRenderer(FacesContext context)
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 name)
Deprecated.
This has been replaced by
UIComponent.getValueExpression(java.lang.String) . |
boolean |
invokeOnComponent(FacesContext context,
String clientId,
ContextCallback callback)
Starting at this component in the View hierarchy, search for a component
with a
clientId equal to the argument clientId and, if found, call the
ContextCallback.invokeContextCallback(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent) method on the argument callback , passing the current
FacesContext and the found component as arguments. |
boolean |
isRendered()
Return
true if this component (and its children) should be rendered during the Render Response
phase of the request processing lifecycle. |
boolean |
isTransient()
If true, the Object implementing this interface must not participate in state saving or restoring.
|
void |
markInitialState()
For each of the attached objects on this instance that implement |
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 |
processRestoreState(FacesContext context,
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.
|
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.
|
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.
|
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 |
queueEvent(FacesEvent event)
Queue an event for broadcast at the end of the current request processing lifecycle phase.
|
protected void |
removeFacesListener(FacesListener listener)
Remove the specified
FacesListener from the set of listeners registered to receive event notifications from
this UIComponent . |
static Object |
restoreAttachedState(FacesContext context,
Object stateObj)
This method is called by
UIComponent subclasses that need to restore the objects they saved using
saveAttachedState(jakarta.faces.context.FacesContext, java.lang.Object) . |
void |
restoreState(FacesContext context,
Object state)
Perform any processing required to restore the state from the entries
in the state Object.
|
static Object |
saveAttachedState(FacesContext context,
Object attachedObject)
This method is called by |
Object |
saveState(FacesContext context)
Gets the state of the instance as a
Serializable Object. |
void |
setId(String id)
Set the component identifier of this
UIComponent (if any). |
void |
setParent(UIComponent parent)
Set the parent |
void |
setRendered(boolean rendered)
Set the
rendered property of this UIComponent . |
void |
setRendererType(String rendererType)
|
void |
setTransient(boolean transientFlag)
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)
Deprecated.
This has been replaced by
UIComponent.setValueExpression(java.lang.String, jakarta.el.ValueExpression) . |
void |
subscribeToEvent(Class<? extends SystemEvent> eventClass,
ComponentSystemEventListener componentListener)
Install the listener instance referenced by argument |
void |
unsubscribeFromEvent(Class<? extends SystemEvent> eventClass,
ComponentSystemEventListener componentListener)
Remove the listener instance referenced by argument |
encodeAll, getClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getFamily, getNamingContainer, getPassThroughAttributes, getResourceBundleMap, getStateHelper, getStateHelper, getTransientStateHelper, getTransientStateHelper, getValueExpression, initialStateMarked, isCompositeComponent, isInView, isVisitable, popComponentFromEL, processEvent, pushComponentToEL, restoreTransientState, saveTransientState, setInView, setValueExpression, visitTree
public Map<String,Object> getAttributes()
UIComponent
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
.getAttributes
in class UIComponent
public Map<String,Object> getPassThroughAttributes(boolean create)
UIComponent
This method has the same specification as UIComponent.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
UIComponent.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.
getPassThroughAttributes
in class UIComponent
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 String getClientId(FacesContext context)
UIComponent
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 UIComponent.getId()
on this component and save the result as the
myId
local variable. If myId
is null
, call
context.getViewRoot().createUniqueId()
and assign the result to myId. If parentId
is
non-null
, let myId
equal parentId
+
. Call UINamingContainer.getSeparatorChar(jakarta.faces.context.FacesContext)
+ myIdRenderer.convertClientId(jakarta.faces.context.FacesContext, java.lang.String)
, passing
myId
, and return the result.
getClientId
in class UIComponent
context
- The FacesContext
for the current requestNullPointerException
- if context
is null
public String getId()
UIComponent
Return the component identifier of this UIComponent
.
getId
in class UIComponent
public void setId(String id)
UIComponent
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
.setId
in class UIComponent
id
- The new component identifier, or null
to indicate that this UIComponent
does not have
a component identifierIllegalArgumentException
- if id
is not syntactically validIllegalStateException
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 UIComponent
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 UIComponent
parent
- The new parent, or null
for the root node of a component treepublic boolean isRendered()
UIComponent
Return true
if this component (and its children) should be rendered during the Render Response
phase of the request processing lifecycle.
isRendered
in class UIComponent
true
if the component should be rendered, false
otherwise.public void setRendered(boolean rendered)
UIComponent
Set the rendered
property of this UIComponent
.
setRendered
in class UIComponent
rendered
- If true
render this component; otherwise, do not render this componentpublic String getRendererType()
UIComponent
Return the Renderer
type for this UIComponent
(if any).
getRendererType
in class UIComponent
public void setRendererType(String rendererType)
UIComponent
Set the Renderer
type for this UIComponent
, or null
for components that render
themselves.
setRendererType
in class UIComponent
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 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 encodeChildren(jakarta.faces.context.FacesContext)
.
getRendersChildren
in class UIComponent
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(jakarta.faces.context.FacesContext, java.lang.Class<? extends jakarta.faces.event.SystemEvent>, java.lang.Object)
must
be called, passing PostAddToViewEvent
.class
as the first argument and the
newly added component as the second argument if any the following cases are true.
FacesContext.getCurrentPhaseId()
returns PhaseId.RESTORE_VIEW
and partial state saving is enabled.
FacesContext.isPostback()
returns false
and
FacesContext.getCurrentPhaseId()
returns something other than
PhaseId.RESTORE_VIEW
getChildren
in class UIComponent
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 UIComponent
public UIComponent findComponent(String expression)
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(jakarta.faces.context.FacesContext, java.lang.String, jakarta.faces.component.ContextCallback)
for a
method that does correctly account for the tree traversal context when operating on the found
UIComponent
instance. UIComponent.invokeOnComponent(jakarta.faces.context.FacesContext, java.lang.String, jakarta.faces.component.ContextCallback)
is also useful to find components given a simple
clientId
.
Component identifiers are required to be unique within the scope of the closest ancestor NamingContainer
that
encloses this component (which might be this component itself). If there are no NamingContainer
components in
the ancestry of this component, the root component in the tree is treated as if it were a NamingContainer
,
whether or not its class actually implements the NamingContainer
interface.
A search expression consists of either an identifier (which is matched exactly against the id
property of a UIComponent
, or a series of such identifiers linked by the
UINamingContainer.getSeparatorChar(jakarta.faces.context.FacesContext)
character value. The search algorithm should operates as follows, though
alternate alogrithms may be used as long as the end result is the same:
UIComponent
that will be the base for searching, by stopping as soon as one of the following
conditions is met:
UIComponent
of the component tree. The leading separator character will be stripped
off, and the remainder of the search expression will be treated as a "relative" search expression as described
below.UIComponent
is a NamingContainer
it will serve as the basis.NamingContainer
is encountered, it will be the
base.NamingContainer
is encountered) the root UIComponent
will be the base.id
that matches, within the scope of the base
component. The match is performed as follows:
id
property, and then
recursively through the facets and children of the base UIComponent
(except that if a descendant
NamingContainer
is found, its own facets and children are not searched).NamingContainer
by the rules in the previous bullet point. Then, the
findComponent()
method of this NamingContainer
will be called, passing the remainder of the
search expression.findComponent
in class UIComponent
expression
- Search expression identifying the UIComponent
to be returnedUIComponent
, or null
if the component was not found.NullPointerException
- if expr
is null
public boolean invokeOnComponent(FacesContext context, String clientId, ContextCallback callback) throws FacesException
Starting at this component in the View hierarchy, search for a component
with a clientId
equal to the argument clientId
and, if found, call the
ContextCallback.invokeContextCallback(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent)
method on the argument callback
, passing the current
FacesContext
and the found component as arguments. This method is similar to UIComponent.findComponent(java.lang.String)
but it
does not support the leading UINamingContainer.getSeparatorChar(jakarta.faces.context.FacesContext)
syntax for searching from the root of the
View.
The default implementation will first check if this.getClientId()
is equal to the argument
clientId
. If so, first call UIComponent.pushComponentToEL(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent)
, then call
the ContextCallback.invokeContextCallback(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent)
method on the argument callback, passing through the
FacesContext
argument and passing this as the component argument. Then
call UIComponent.popComponentFromEL(jakarta.faces.context.FacesContext)
. If an Exception
is thrown by the callback, wrap it in a
FacesException
and re-throw it. Otherwise, return true
.
Otherwise, for each component returned by UIComponent.getFacetsAndChildren()
, call invokeOnComponent()
passing the arguments to this method, in order. The first time invokeOnComponent()
returns true, abort
traversing the rest of the Iterator
and return true
.
When calling ContextCallback.invokeContextCallback(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent)
the implementation of this method must guarantee that the
state of the component passed to the callback correctly reflects the component's position in the View hierarchy with
respect to any state found in the argument clientId
. For example, an iterating component such as
UIData
will need to set its row index to correctly reflect the argument clientId
before finding
the appropriate child component backed by the correct row. When the callback returns, either normally or by throwing
an Exception
the implementation of this method must restore the state of the view to the way it was
before invoking the callback.
If none of the elements from UIComponent.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;
}
});
}
invokeOnComponent
in class UIComponent
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.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 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 UIComponent
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 getFacetCount()
.
getFacetCount
in class UIComponent
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 UIComponent
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 UIComponent
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(jakarta.faces.event.BehaviorEvent)
on the
Behavior
instance.
broadcast
in class UIComponent
event
- The FacesEvent
to be broadcastAbortProcessingException
- Signal the Jakarta Server Faces implementation that no further processing on the
current event should be performedIllegalStateException
NullPointerException
- if event
is null
public void decode(FacesContext context)
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 UIComponent
context
- FacesContext
for the request we are processingNullPointerException
- if context
is null
public void encodeBegin(FacesContext context) 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(jakarta.faces.context.FacesContext,jakarta.faces.component.UIComponent)
. Call
Application.publishEvent(jakarta.faces.context.FacesContext, java.lang.Class<? extends jakarta.faces.event.SystemEvent>, java.lang.Object)
, passing
PreRenderComponentEvent
.class
as the first argument and the component
instance to be rendered as the second argument.
If a Renderer
is associated with this UIComponent
, the actual encoding will be delegated to
Renderer.encodeBegin(FacesContext, UIComponent)
.
If our rendered
property is false
, call
UIComponent.pushComponentToEL(jakarta.faces.context.FacesContext,jakarta.faces.component.UIComponent)
and return
immediately.
encodeBegin
in class UIComponent
context
- FacesContext
for the response we are creatingNullPointerException
- if context
is null
IOException
- if an input/output error occurs while renderingpublic void encodeChildren(FacesContext context) 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(jakarta.faces.context.FacesContext)
.
encodeChildren
in class UIComponent
context
- FacesContext
for the response we are creatingNullPointerException
- if context
is null
IOException
- if an input/output error occurs while renderingpublic void encodeEnd(FacesContext context) 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(jakarta.faces.context.FacesContext)
. before returning regardless of the value of the rendered
property.
encodeEnd
in class UIComponent
context
- FacesContext
for the response we are creatingIOException
- if an input/output error occurs while renderingNullPointerException
- if context
is null
protected 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 { ... 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 UIComponent
listener
- The FacesListener
to be registeredNullPointerException
- if listener
is null
protected FacesListener[] getFacesListeners(Class clazz)
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 UIComponent
clazz
- Class that must be implemented by a FacesListener
for it to be returnedIllegalArgumentException
- if class
is not, and does not implement, FacesListener
NullPointerException
- if clazz
is null
protected void removeFacesListener(FacesListener listener)
Remove the specified FacesListener
from the set of listeners registered to receive event notifications from
this UIComponent
.
removeFacesListener
in class UIComponent
listener
- The FacesListener
to be deregisteredNullPointerException
- if listener
is null
public 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 UIComponent
event
- FacesEvent
to be queuedIllegalStateException
- if this component is not a descendant of a UIViewRoot
NullPointerException
- if event
is null
public void subscribeToEvent(Class<? extends SystemEvent> eventClass, ComponentSystemEventListener componentListener)
Install the listener instance referenced by argument componentListener
as a listener for events of type
eventClass
originating from this specific instance of UIComponent
. The default
implementation creates an inner SystemEventListener
instance that wraps argument
componentListener
as the listener
argument. This inner class must call through to the
argument componentListener
in its implementation of SystemEventListener.processEvent(jakarta.faces.event.SystemEvent)
and its
implementation of SystemEventListener.isListenerForSource(java.lang.Object)
must return true if the instance class of this
UIComponent
is assignable from the argument to isListenerForSource
.
subscribeToEvent
in class UIComponent
eventClass
- the Class
of event for which listener
must be fired.componentListener
- the implementation of ComponentSystemEventListener
whose
ComponentSystemEventListener.processEvent(jakarta.faces.event.ComponentSystemEvent)
method must be called when events of type
facesEventClass
are fired.NullPointerException
- if any of the arguments are null
.public void unsubscribeFromEvent(Class<? extends SystemEvent> eventClass, ComponentSystemEventListener componentListener)
Remove the listener instance referenced by argument componentListener
as a listener for events of type
eventClass
originating from this specific instance of UIComponent
. When doing the
comparison to determine if an existing listener is equal to the argument componentListener
(and thus
must be removed), the equals()
method on the existing listener must be invoked, passing the
argument componentListener
, rather than the other way around.
unsubscribeFromEvent
in class UIComponent
eventClass
- the Class
of event for which listener
must be removed.componentListener
- the implementation of ComponentSystemEventListener
whose
ComponentSystemEventListener.processEvent(jakarta.faces.event.ComponentSystemEvent)
method must no longer be called when events of type
eventClass
are fired.NullPointerException
- if any of the arguments are null
.public List<SystemEventListener> getListenersForEventClass(Class<? extends SystemEvent> eventClass)
Return the SystemEventListener
instances registered on this UIComponent
instance that are
interested in events of type eventClass
.
getListenersForEventClass
in interface SystemEventListenerHolder
getListenersForEventClass
in class UIComponent
eventClass
- the Class
of event for which the listeners must be returned.NullPointerException
- if argument eventClass
is null
.public void processDecodes(FacesContext context)
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(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent)
.processDecodes()
method of all facets and children of this UIComponent
, in the
order determined by a call to getFacetsAndChildren()
.decode()
method of this component.UIComponent.popComponentFromEL(jakarta.faces.context.FacesContext)
from inside of a finally block, just before returning.
RuntimeException
is thrown during decode processing, call FacesContext.renderResponse()
and re-throw the exception.processDecodes
in class UIComponent
context
- FacesContext
for the request we are processingNullPointerException
- if context
is null
public void processValidators(FacesContext context)
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(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent)
.processValidators()
method of all facets and children of this UIComponent
, in the
order determined by a call to getFacetsAndChildren()
.getFacetsAndChildren()
call
UIComponent.popComponentFromEL(jakarta.faces.context.FacesContext)
.processValidators
in class UIComponent
context
- FacesContext
for the request we are processingNullPointerException
- if context
is null
PreValidateEvent
,
PostValidateEvent
public void processUpdates(FacesContext context)
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(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent)
.processUpdates()
method of all facets and children of this UIComponent
, in the
order determined by a call to getFacetsAndChildren()
. After returning
from the processUpdates()
method on a child or facet, call
UIComponent.popComponentFromEL(jakarta.faces.context.FacesContext)
processUpdates
in class UIComponent
context
- FacesContext
for the request we are processingNullPointerException
- if context
is null
public Object processSaveState(FacesContext context)
UIComponent
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
.UIComponent.pushComponentToEL(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent)
.processSaveState()
method of all facets and children of this UIComponent
in the
order determined by a call to getFacetsAndChildren()
, skipping children and facets that are transient.
Ensure that UIComponent.popComponentFromEL(jakarta.faces.context.FacesContext)
is called correctly after each child or facet.saveState()
method of this component.This method may not be called if the state saving method is set to server.
processSaveState
in class UIComponent
context
- FacesContext
for the request we are processingNullPointerException
- if context
is null
public void processRestoreState(FacesContext context, Object state)
UIComponent
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.UIComponent.pushComponentToEL(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent)
.processRestoreState()
method of all facets and children of this UIComponent
in the
order determined by a call to getFacetsAndChildren()
. After returning
from the processRestoreState()
method on a child or facet, call
UIComponent.popComponentFromEL(jakarta.faces.context.FacesContext)
This method may not be called if the state saving method is set to server.
processRestoreState
in class UIComponent
context
- FacesContext
for the request we are processingstate
- the state.NullPointerException
- if context
is null
protected FacesContext getFacesContext()
UIComponent
Convenience method to return the FacesContext
instance for the current request.
getFacesContext
in class UIComponent
protected Renderer getRenderer(FacesContext context)
UIComponent
Convenience method to return the Renderer
instance associated with this component, if any; otherwise, return
null
.
getRenderer
in class UIComponent
context
- FacesContext
for the current requestnull
.public void markInitialState()
For each of the attached objects on this instance that implement PartialStateHolder
, call
PartialStateHolder.markInitialState()
on the attached object.
markInitialState
in interface PartialStateHolder
markInitialState
in class UIComponent
public void clearInitialState()
For each of the attached objects on this instance that implement PartialStateHolder
, call
PartialStateHolder.clearInitialState()
on the attached object.
clearInitialState
in interface PartialStateHolder
clearInitialState
in class UIComponent
public Object saveState(FacesContext context)
StateHolder
Gets the state of the instance as a Serializable
Object.
If the class that implements this interface has references to instances that implement StateHolder (such as a
UIComponent
with event handlers, validators, etc.) this method must call the StateHolder.saveState(jakarta.faces.context.FacesContext)
method
on all those instances as well. This method must not save the state of children and facets. That is
done via the StateManager
This method must not alter the state of the implementing object. In other words, after executing this code:
Object state = component.saveState(facesContext);
component
should be the same as before executing it.
The return from this method must be Serializable
context
- the Faces context.public void restoreState(FacesContext context, Object state)
StateHolder
Perform any processing required to restore the state from the entries in the state Object.
If the class that implements this interface has references to instances that also implement StateHolder (such as a
UIComponent
with event handlers, validators, etc.) this method must call the StateHolder.restoreState(jakarta.faces.context.FacesContext, java.lang.Object)
method on all those instances as well.
If the state
argument is null
, take no action and return.
context
- the Faces context.state
- the state.public boolean isTransient()
StateHolder
If true, the Object implementing this interface must not participate in state saving or restoring.
true
if transient, false
otherwise.public void setTransient(boolean transientFlag)
StateHolder
Denotes whether or not the Object implementing this interface must or must not participate in state saving or restoring.
transientFlag
- boolean pass true
if this Object will
not participate in state saving or restoring, otherwise pass false
.public static Object saveAttachedState(FacesContext context, Object attachedObject)
This method is called by UIComponent
subclasses that want to save one or more attached objects. It is a
convenience method that does the work of saving attached objects that may or may not implement the
StateHolder
interface. Using this method implies the use of restoreAttachedState(jakarta.faces.context.FacesContext, java.lang.Object)
to restore the
attached objects.
This method supports saving attached objects of the following type: Object
s, null
values,
and Collection
s of these objects. If any contained objects are not Collection
s and do not implement StateHolder
, they must have
zero-argument public constructors. The exact structure of the returned object is undefined and opaque, but will be
serializable.
context
- the FacesContext
for this request.attachedObject
- the object, which may be a List
instance, or an Object. The
attachedObject
(or the elements that comprise attachedObject
may implement
StateHolder
.NullPointerException
- if the context argument is null.public static Object restoreAttachedState(FacesContext context, Object stateObj) throws IllegalStateException
This method is called by UIComponent
subclasses that need to restore the objects they saved using
saveAttachedState(jakarta.faces.context.FacesContext, java.lang.Object)
. This method is tightly coupled with saveAttachedState(jakarta.faces.context.FacesContext, java.lang.Object)
.
This method supports restoring all attached objects types supported by saveAttachedState(jakarta.faces.context.FacesContext, java.lang.Object)
.
context
- the FacesContext
for this requeststateObj
- the opaque object returned from saveAttachedState(jakarta.faces.context.FacesContext, java.lang.Object)
stateObj
.NullPointerException
- if context is null.IllegalStateException
- if the object is not previously returned by saveAttachedState(jakarta.faces.context.FacesContext, java.lang.Object)
.public void addClientBehavior(String eventName, ClientBehavior behavior)
This is a default implementation of ClientBehaviorHolder.addClientBehavior(java.lang.String, jakarta.faces.component.behavior.ClientBehavior)
.
UIComponent
does not implement the ClientBehaviorHolder
interface, but provides default implementations for the methods defined by
ClientBehaviorHolder
to simplify subclass implementations. Subclasses that
wish to support the ClientBehaviorHolder
contract must declare that the
subclass implements ClientBehaviorHolder
, and must provide an implementation
of ClientBehaviorHolder.getEventNames()
.
eventName
- the logical name of the client-side event to attach the behavior to.behavior
- the Behavior
instance to attach for the specified event
name.public Collection<String> getEventNames()
This is a default implementation of ClientBehaviorHolder.getEventNames()
.
UIComponent
does not implement the ClientBehaviorHolder
interface, but provides default implementations for the methods defined by
ClientBehaviorHolder
to simplify subclass implementations. Subclasses that
wish to support the ClientBehaviorHolder
contract must declare that the
subclass implements ClientBehaviorHolder
, and must override this method to
return a non-Empty Collection
of the client event names that the component supports.
public Map<String,List<ClientBehavior>> getClientBehaviors()
This is a default implementation of ClientBehaviorHolder.getClientBehaviors()
.
UIComponent
does not implement the ClientBehaviorHolder
interface, but provides default implementations for the methods defined by
ClientBehaviorHolder
to simplify subclass implementations. Subclasses that
wish to support the ClientBehaviorHolder
contract must declare that the
subclass implements ClientBehaviorHolder
, and must add an implementation of
ClientBehaviorHolder.getEventNames()
.
public String getDefaultEventName()
This is a default implementation of
ClientBehaviorHolder.getDefaultEventName()
. UIComponent
does not
implement the ClientBehaviorHolder
interface, but provides default
implementations for the methods defined by ClientBehaviorHolder
to simplify
subclass implementations. Subclasses that wish to support the
ClientBehaviorHolder
contract must declare that the subclass implements
ClientBehaviorHolder
, and must provide an implementation of
ClientBehaviorHolder.getEventNames()
.
@Deprecated public ValueBinding getValueBinding(String name)
UIComponent.getValueExpression(java.lang.String)
.
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, jakarta.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 UIComponent
name
- Name of the attribute or property for which to retrieve a ValueBinding
NullPointerException
- if name
is null
@Deprecated public void setValueBinding(String name, ValueBinding binding)
UIComponent.setValueExpression(java.lang.String, jakarta.el.ValueExpression)
.
Wrap the argument binding
in an implementation of ValueExpression
and call through to
UIComponent.setValueExpression(java.lang.String, jakarta.el.ValueExpression)
.
setValueBinding
in class UIComponent
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
IllegalArgumentException
- if name
is one of id
or parent
NullPointerException
- if name
is null
Copyright © 2018,2020 Eclipse Foundation.
Use is subject to license terms.