public abstract class UIComponent extends Object implements PartialStateHolder, TransientStateHolder, SystemEventListenerHolder, ComponentSystemEventListener
UIComponent is
the base class for all user interface components in JavaServer Faces.
The set of UIComponent
instances associated with a particular request
and response are organized into a component tree under a UIViewRoot
that represents the entire content of the request or
response.
For the convenience of component developers,
UIComponentBase
provides the default
behavior that is specified for a UIComponent
, and is the base class
for all of the concrete UIComponent
"base" implementations.
Component writers are encouraged to subclass
UIComponentBase
, instead of directly
implementing this abstract class, to reduce the impact of any future changes
to the method signatures.
If the ListenerFor
annotation is attached to the class
definition of a Component
, that class must also
implement ComponentSystemEventListener
.
Modifier and Type | Field and Description |
---|---|
static String |
ATTRS_WITH_DECLARED_DEFAULT_VALUES
This constant enables one to quickly discover the names of the declared composite component attributes that have been given default values by the composite component author. |
static String |
BEANINFO_KEY
The value of this constant is used as the key in the
component attribute map, the value for which is a
|
protected Map<String,ValueExpression> |
bindings
Deprecated.
|
static String |
COMPOSITE_COMPONENT_TYPE_KEY
The value of this constant is used as the key
in the composite component BeanDescriptor for a
|
static String |
COMPOSITE_FACET_NAME
The value of this constant is used as the key
in the |
static String |
CURRENT_COMPONENT
Deprecated.
|
static String |
CURRENT_COMPOSITE_COMPONENT
Deprecated.
|
static String |
FACETS_KEY
The value of this constant is used as the key
in the composite component BeanDescriptor for the
|
static String |
HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME
The |
static String |
VIEW_LOCATION_KEY
The value of this constant is used as the key
in the component attributes |
Constructor and Description |
---|
UIComponent() |
Modifier and Type | Method and Description |
---|---|
protected abstract void |
addFacesListener(FacesListener listener)
Add the specified
FacesListener to the set of listeners
registered to receive event notifications from this UIComponent . |
abstract void |
broadcast(FacesEvent event)
Broadcast the specified
FacesEvent to all registered
event listeners who have expressed an interest in events of this
type. |
void |
clearInitialState()
An implementation of |
abstract void |
decode(FacesContext context)
Decode any new state of this
UIComponent from the
request contained in the specified FacesContext , and store
this state as needed. |
void |
encodeAll(FacesContext context)
If this component
returns
true from isRendered() , take the
following action. |
abstract void |
encodeBegin(FacesContext context)
If our
rendered property is true , render the
beginning of the current state of this UIComponent to the
response contained in the specified FacesContext . |
abstract void |
encodeChildren(FacesContext context)
|
abstract void |
encodeEnd(FacesContext context)
|
abstract UIComponent |
findComponent(String expr)
Search for and
return the
UIComponent with an id that
matches the specified search expression (if any), according to
the algorithm described below. |
abstract 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). |
abstract int |
getChildCount()
Return the number of child
UIComponent s that are
associated with this UIComponent . |
abstract List<UIComponent> |
getChildren()
|
String |
getClientId()
Enable EL to access the |
abstract String |
getClientId(FacesContext context)
Return a client-side identifier for this component, generating
one if necessary.
|
static UIComponent |
getCompositeComponentParent(UIComponent component)
Finds the nearest composite component parent of the specified component.
|
String |
getContainerClientId(FacesContext context)
Allow components that implement
NamingContainer to
selectively disable prepending their clientId to their
descendent's clientIds by breaking the prepending logic into a
seperately callable method. |
static UIComponent |
getCurrentComponent(FacesContext context)
Return the |
static UIComponent |
getCurrentCompositeComponent(FacesContext context)
Return the closest ancestor
component, relative to the component returned from |
protected abstract FacesContext |
getFacesContext()
Convenience method to return the
FacesContext instance
for the current request. |
protected abstract FacesListener[] |
getFacesListeners(Class clazz)
Return an array of registered
FacesListener s that are
instances of the specified class. |
abstract 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 . |
abstract 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). |
abstract Iterator<UIComponent> |
getFacetsAndChildren()
|
abstract String |
getFamily()
Return the identifier of the component family to which this
component belongs.
|
abstract String |
getId()
Return the component identifier of this
UIComponent . |
List<SystemEventListener> |
getListenersForEventClass(Class<? extends SystemEvent> eventClass)
This implementation throws
|
UIComponent |
getNamingContainer()
Starting with "this", return the closest
component in the ancestry that is a |
abstract UIComponent |
getParent()
Return the parent
UIComponent of this
UIComponent , if any. |
Map<String,Object> |
getPassThroughAttributes()
This is a convenience method that
simply calls |
Map<String,Object> |
getPassThroughAttributes(boolean create)
This method has the same specification as
|
protected abstract Renderer |
getRenderer(FacesContext context)
Convenience method to return the
Renderer instance
associated with this component, if any; otherwise, return
null . |
abstract String |
getRendererType()
Return the
Renderer type for this UIComponent
(if any). |
abstract boolean |
getRendersChildren()
Return a flag indicating whether this component is responsible
for rendering its child components.
|
Map<String,String> |
getResourceBundleMap()
Return a
|
protected StateHelper |
getStateHelper()
Return the |
protected StateHelper |
getStateHelper(boolean create)
Like |
TransientStateHelper |
getTransientStateHelper()
Return the |
TransientStateHelper |
getTransientStateHelper(boolean create)
Return the |
abstract ValueBinding |
getValueBinding(String name)
Deprecated.
This has been replaced by
getValueExpression(java.lang.String) . |
ValueExpression |
getValueExpression(String name)
Return the
ValueExpression used to calculate the value for the
specified attribute or property name, if any. |
boolean |
initialStateMarked()
An implementation of |
boolean |
invokeOnComponent(FacesContext context,
String clientId,
ContextCallback callback)
Starting at this
component in the View hierarchy, search for a component with a
clientId equal to the argument clientId
and, if found, call the ContextCallback.invokeContextCallback(javax.faces.context.FacesContext, javax.faces.component.UIComponent) method on the argument
callback , passing the current FacesContext
and the found component as arguments. |
static boolean |
isCompositeComponent(UIComponent component)
Return |
boolean |
isInView()
Return |
abstract boolean |
isRendered()
Return
true if this component (and its children)
should be rendered during the Render Response phase
of the request processing lifecycle. |
protected boolean |
isVisitable(VisitContext context)
Return |
void |
markInitialState()
An implementation of |
void |
popComponentFromEL(FacesContext context)
Pop the current
|
abstract void |
processDecodes(FacesContext context)
Perform the
component tree processing required by the Apply Request
Values phase of the request processing lifecycle for all
facets of this component, all children of this component, and
this component itself, as follows.
|
void |
processEvent(ComponentSystemEvent event)
The default implementation performs the following action. |
abstract void |
processRestoreState(FacesContext context,
Object state)
Perform the
component tree processing required by the Restore View
phase of the request processing lifecycle for all facets of this
component, all children of this component, and this component
itself, as follows.
|
abstract Object |
processSaveState(FacesContext context)
Perform the
component tree processing required by the state saving portion of
the Render Response phase of the request processing
lifecycle for all facets of this component, all children of this
component, and this component itself, as follows.
|
abstract void |
processUpdates(FacesContext context)
Perform the
component tree processing required by the Update Model
Values phase of the request processing lifecycle for all
facets of this component, all children of this component, and
this component itself, as follows.
|
abstract void |
processValidators(FacesContext context)
Perform the component
tree processing required by the Process Validations
phase of the request processing lifecycle for all facets of this
component, all children of this component, and this component
itself, as follows.
|
void |
pushComponentToEL(FacesContext context,
UIComponent component)
Push the current
|
abstract void |
queueEvent(FacesEvent event)
Queue an event for broadcast at the end of the current request
processing lifecycle phase.
|
protected abstract void |
removeFacesListener(FacesListener listener)
Remove the specified
FacesListener from the set of listeners
registered to receive event notifications from this UIComponent . |
void |
restoreTransientState(FacesContext context,
Object state)
For components that need to support
the concept of transient state, this method will restore any
state saved on a prior call to |
Object |
saveTransientState(FacesContext context)
For components that need to support the concept of transient state, this method will save any state that is known to be transient in nature. |
abstract void |
setId(String id)
Set the component identifier of this
UIComponent (if any). |
void |
setInView(boolean isInView)
Updates the status as to whether or not this component is currently within the view hierarchy. |
abstract void |
setParent(UIComponent parent)
Set the parent
|
abstract void |
setRendered(boolean rendered)
Set the
rendered property of this
UIComponent . |
abstract void |
setRendererType(String rendererType)
|
abstract void |
setValueBinding(String name,
ValueBinding binding)
Deprecated.
This has been replaced by
setValueExpression(java.lang.String, javax.el.ValueExpression) . |
void |
setValueExpression(String name,
ValueExpression binding)
Set the
ValueExpression used to calculate the value
for the specified attribute or property name, if any. |
void |
subscribeToEvent(Class<? extends SystemEvent> eventClass,
ComponentSystemEventListener componentListener)
This implementation throws
|
void |
unsubscribeFromEvent(Class<? extends SystemEvent> eventClass,
ComponentSystemEventListener componentListener)
This implementation throws
|
boolean |
visitTree(VisitContext context,
VisitCallback callback)
Perform a tree visit starting at this node in the tree. |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
isTransient, restoreState, saveState, setTransient
public static final String HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME
The ServletContext
init
parameter consulted by
the UIComponent
to tell whether or not the
CURRENT_COMPONENT
and CURRENT_COMPOSITE_COMPONENT
attribute keys should be honored as specified.
If this parameter is not specified, or is set to false, the contract
specified by the CURRENT_COMPONENT
and
CURRENT_COMPOSITE_COMPONENT
method is not honored. If this
parameter is set to true, the contract is honored.
public static final String CURRENT_COMPONENT
The key to which the
UIComponent
currently being processed will be
associated with within the FacesContext
attributes
map. The use of this constant is
deprecated. Please see HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME
to enable its
use.
FacesContext.getAttributes()
,
Constant Field Valuespublic static final String CURRENT_COMPOSITE_COMPONENT
The key to which the
composite UIComponent
currently being
processed will be associated with within the FacesContext
attributes map. The use of this
constant is deprecated. Please see HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME
to enable its
use.
FacesContext.getAttributes()
,
Constant Field Valuespublic static final String BEANINFO_KEY
The value of this constant is used as the key in the
component attribute map, the value for which is a
java.beans.BeanInfo
implementation describing the composite
component. This BeanInfo
is known as the
composite component BeanInfo.
public static final String FACETS_KEY
The value of this constant is used as the key
in the composite component BeanDescriptor for the
Map<PropertyDescriptor>
that contains meta-information
for the declared facets for this composite component.
This map must contain an entry under the key COMPOSITE_FACET_NAME
, even
if no facets were explicitly declared. See COMPOSITE_FACET_NAME
.
public static final String VIEW_LOCATION_KEY
The value of this constant is used as the key
in the component attributes Map
for the
Location
in the view at which this component
instance resides.
public static final String COMPOSITE_COMPONENT_TYPE_KEY
The value of this constant is used as the key
in the composite component BeanDescriptor for a
ValueExpression
that evaluates to the
component-type
of the composite component root
UIComponent
for this composite component, if
one was declared by the composite component author.
public static final String COMPOSITE_FACET_NAME
The value of this constant is used as the key
in the Map
returned as described in FACETS_KEY
for the
PropertyDescriptor
describing the composite component facet.
The value of this constant is also used as the key in the Map
returned from getFacets()
. In this case, it refers to the actual
facet that is the UIPanel
that is the parent of the all
of the components in the <composite:implementation>
section of the composite component VDL file.
public static final String ATTRS_WITH_DECLARED_DEFAULT_VALUES
This constant enables one to quickly discover
the names of the declared composite component attributes that have been
given default values by the composite component author. The information
is exposed as a Collection<String>
returned from the
getValue()
method on the composite component
BeanDescriptor, when this constant is passed as the argument.
@Deprecated protected Map<String,ValueExpression> bindings
public abstract 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). The returned
implementation must support all of the standard and optional
Map
methods, plus support the following additional
requirements:
Map
implementation must implement
the java.io.Serializable
interface.null
key or value must
throw a NullPointerException
.ClassCastException
.UIComponent
's implementation class, the following
methods will have special behavior:
containsKey
- Return false
.get()
- If the property is readable, call
the getter method and return the returned value (wrapping
primitive values in their corresponding wrapper classes);
otherwise throw IllegalArgumentException
.put()
- If the property is writeable, call
the setter method to set the corresponding value (unwrapping
primitive values in their corresponding wrapper classes).
If the property is not writeable, or an attempt is made to
set a property of primitive type to null
,
throw IllegalArgumentException
.remove
- Throw
IllegalArgumentException
.public final Map<String,Object> getPassThroughAttributes()
This is a convenience method that
simply calls getPassThroughAttributes(boolean)
, passing true
as the argument. This method must never return null
.
public Map<String,Object> getPassThroughAttributes(boolean create)
This method has the same specification as
getPassThroughAttributes()
except that it is allowed to return
null
if and only if the argument create
is false
and no pass through attribute data structure exists for this instance.
The returned Map
implementation must support all of the standard and optional
Map
methods, plus support the following additional requirements.
The map must be stored in using getStateHelper()
.
The Map
implementation must implement java.io.Serializable
.
Any attempt to add a null
key or value must throw a NullPointerException
.
Any attempt to add a key that is not a String
must
throw an IllegalArgumentException
.
For backward compatibility with components that extend directly from this class, a default implementation is provided that returns the empty map.
create
- if true
, a new Map
instance will be created if it does not exist already. If
false
, and there is no existing
Map
instance, one will not be created and
null
will be returned.Map
instance, or null
.public abstract ValueBinding getValueBinding(String name)
getValueExpression(java.lang.String)
.Call through to getValueExpression(java.lang.String)
and examine the
result. If the result is an instance of the wrapper class
mandated in setValueBinding(java.lang.String, javax.faces.el.ValueBinding)
, extract the
ValueBinding
instance and return it. Otherwise,
wrap the result in an implementation of
ValueBinding
, and return it.
name
- Name of the attribute or property for which to retrieve a
ValueBinding
NullPointerException
- if name
is null
public abstract void setValueBinding(String name, ValueBinding binding)
setValueExpression(java.lang.String, javax.el.ValueExpression)
.Wrap the argument binding
in an implementation of
ValueExpression
and call through to setValueExpression(java.lang.String, javax.el.ValueExpression)
.
name
- Name of the attribute or property for which to set a
ValueBinding
binding
- The ValueBinding
to set, or null
to remove any currently set ValueBinding
IllegalArgumentException
- if name
is one of
id
or parent
NullPointerException
- if name
is null
public ValueExpression getValueExpression(String name)
Return the ValueExpression
used to calculate the value for the
specified attribute or property name, if any.
This method must be overridden and implemented for components that comply with JSF 1.2 and later.
name
- Name of the attribute or property for which to retrieve a
ValueExpression
NullPointerException
- if name
is null
public void setValueExpression(String name, ValueExpression binding)
Set the ValueExpression
used to calculate the value
for the specified attribute or property name, if any.
The implementation must call Expression.isLiteralText()
on the argument
expression
. If isLiteralText()
returns
true
, invoke ValueExpression.getValue(javax.el.ELContext)
on the
argument expression and pass the result as the value
parameter in a call to this.
where getAttributes()
.put(name, value)name
is the argument name
. If an exception is thrown as
a result of calling ValueExpression.getValue(javax.el.ELContext)
, wrap it in
a FacesException
and re-throw it. If
isLiteralText()
returns false
, simply
store the un-evaluated expression
argument in the
collection of ValueExpression
s under the key given
by the argument name
.
This method must be overridden and implemented for components that comply with JSF 1.2 and later.
name
- Name of the attribute or property for which to set a
ValueExpression
binding
- The ValueExpression
to set, or null
to remove any currently set ValueExpression
IllegalArgumentException
- if name
is one of
id
or parent
NullPointerException
- if name
is null
public void markInitialState()
An implementation of PartialStateHolder.markInitialState()
, this method is called by
the runtime to indicate that the instance should start tracking
changes to its state.
markInitialState
in interface PartialStateHolder
public boolean initialStateMarked()
An implementation of PartialStateHolder.initialStateMarked()
, this method is called by
the runtime to test if the PartialStateHolder.markInitialState()
method was called.
initialStateMarked
in interface PartialStateHolder
public void clearInitialState()
An implementation of PartialStateHolder.clearInitialState()
, this method is called by
the runtime to tell the instance to stop tracking state
changes.
clearInitialState
in interface PartialStateHolder
protected StateHelper getStateHelper()
Return the StateHelper
instance used to help this component implement PartialStateHolder
.
protected StateHelper getStateHelper(boolean create)
Like getStateHelper()
, but
only create a state helper instance if the argument
creat
is true
.
create
- if true
, a new StateHelper
instance will be created if it does not exist already. If
false
, and there is no existing
StateHelper
instance, one will not be created and
null
will be returned.public final TransientStateHelper getTransientStateHelper()
Return the TransientStateHelper
instance for this UIComponent
instance. The default implementation simply calls through to
getTransientStateHelper(boolean)
passing true
as the argument.
public TransientStateHelper getTransientStateHelper(boolean create)
Return the TransientStateHelper
instance for this UIComponent
instance.
create
- if true
create, if necessary, any
internal data structures. If false
, do not create
any instances. In this case, it is possible for this method to
return null
.public void restoreTransientState(FacesContext context, Object state)
For components that need to support
the concept of transient state, this method will restore any
state saved on a prior call to saveTransientState(javax.faces.context.FacesContext)
.
restoreTransientState
in interface TransientStateHolder
state
- the object containing transient valuespublic Object saveTransientState(FacesContext context)
For components that need to support the concept of transient state, this method will save any state that is known to be transient in nature.
saveTransientState
in interface TransientStateHolder
public boolean isInView()
Return true
if this
component is within the view hierarchy otherwise
false
public void setInView(boolean isInView)
Updates the status as to whether or
not this component is currently within the view hierarchy.
This method must never be called by developers; a UIComponent
's internal implementation will call it as components
are added to or removed from a parent's child List
or facet Map
.
isInView
- flag indicating whether or not this component is within
the view hierachypublic String getClientId()
Enable EL to access the clientId
of a component. This is particularly useful in combination with the
component
and cc
implicit
objects. A default implementation is provided that simply calls
FacesContext.getCurrentInstance()
and then calls through to
getClientId(FacesContext)
.
public abstract String getClientId(FacesContext context)
Return a client-side identifier for this component, generating
one if necessary. The associated Renderer
, if any,
will be asked to convert the clientId to a form suitable for
transmission to the client.
The return from this method must be the same value throughout
the lifetime of the instance, unless the id
property
of the component is changed, or the component is placed in
a NamingContainer
whose client ID changes (for example,
UIData
). However, even in these cases, consecutive
calls to this method must always return the same value. The
implementation must follow these steps in determining the
clientId:
Find the closest ancestor to this component in the view
hierarchy that implements NamingContainer
. Call
getContainerClientId()
on it and save the result as
the parentId
local variable. Call getId()
on
this component and save the result as the
myId
local variable. If myId
is
null
, call
context.getViewRoot().createUniqueId()
and assign
the result to myId. If parentId
is
non-null
, let myId
equal parentId
+
. Call
UINamingContainer.getSeparatorChar(javax.faces.context.FacesContext)
+ myIdRenderer.convertClientId(javax.faces.context.FacesContext, java.lang.String)
, passing myId
, and
return the result.
context
- The FacesContext
for the current requestNullPointerException
- if context
is null
public String getContainerClientId(FacesContext context)
Allow components that implement NamingContainer
to
selectively disable prepending their clientId to their
descendent's clientIds by breaking the prepending logic into a
seperately callable method. See getClientId()
for usage.
By default, this method will call through to getClientId()
and return the result.
NullPointerException
- if context
is
null
public abstract String getFamily()
Return the identifier of the component family to which this
component belongs. This identifier, in conjunction with the value
of the rendererType
property, may be used to select
the appropriate Renderer
for this component instance.
public abstract String getId()
Return the component identifier of this UIComponent
.
public abstract void setId(String id)
Set the component identifier of this UIComponent
(if any).
Component identifiers must obey the following syntax restrictions:
Component identifiers must also obey the following semantic
restrictions (note that this restriction is NOT
enforced by the setId()
implementation):
UIComponent
that is a NamingContainer
, or within
the scope of the entire component tree if there is no such
ancestor that is a NamingContainer
.id
- The new component identifier, or null
to indicate
that this UIComponent
does not have a component identifierIllegalArgumentException
- if id
is not
syntactically validpublic abstract UIComponent getParent()
Return the parent UIComponent
of this
UIComponent
, if any. A component must allow child
components to be added to and removed from the list of children
of this component, even though the child component returns null
from getParent( )
.
public abstract void setParent(UIComponent parent)
Set the parent
UIComponent
of this UIComponent
. If
parent.isInView()
returns true
, calling
this method will first cause a PreRemoveFromViewEvent
to be published, for
this node, and then the children of this node. Then, once the
re-parenting has occurred, a PostAddToViewEvent
will be published as well,
first for this node, and then for the node's children, but only if any of the
following conditions are true.
FacesContext.getCurrentPhaseId()
returns
PhaseId.RESTORE_VIEW
and partial
state saving is enabled.
FacesContext.isPostback()
returns false
and FacesContext.getCurrentPhaseId()
returns
something other than PhaseId.RESTORE_VIEW
This method must never
be called by developers; a UIComponent
's internal
implementation will call it as components are added to or removed
from a parent's child List
or facet
Map
.
parent
- The new parent, or null
for the root node
of a component treepublic abstract boolean isRendered()
Return true
if this component (and its children)
should be rendered during the Render Response phase
of the request processing lifecycle.
public abstract void setRendered(boolean rendered)
Set the rendered
property of this
UIComponent
.
rendered
- If true
render this component;
otherwise, do not render this componentpublic abstract String getRendererType()
Return the Renderer
type for this UIComponent
(if any).
public abstract void setRendererType(String rendererType)
Set the Renderer
type for this UIComponent
,
or null
for components that render themselves.
rendererType
- Logical identifier of the type of
Renderer
to use, or null
for components
that render themselvespublic abstract boolean getRendersChildren()
Return a flag indicating whether this component is responsible
for rendering its child components. The default implementation
in UIComponentBase.getRendersChildren()
tries to find the
renderer for this component. If it does, it calls Renderer.getRendersChildren()
and returns the result. If it
doesn't, it returns false. As of version 1.2 of the JavaServer
Faces Specification, component authors are encouraged to return
true
from this method and rely on UIComponentBase.encodeChildren(javax.faces.context.FacesContext)
.
public Map<String,String> getResourceBundleMap()
Return a
Map<String,String>
of the
ResourceBundle
for this component. A component may
have a ResourceBundle
associated with it. This
bundle may contain localized properties relating to instances of
this component. The default implementation first looks for a
ResourceBundle
with a base name equal to the fully
qualified class name of the current UIComponent this
and Locale
equal to the Locale
of the
current UIViewRoot
. If no such bundle is found, and
the component is a composite component, let resourceName
be the resourceName of the Resource
for this
composite component, replacing the file extension with
".properties". Let libraryName be the
libraryName of the the Resource
for this
composite component. Call ResourceHandler.createResource(java.lang.String,java.lang.String)
,
passing the derived resourceName and
libraryName. Note that this will automatically allow
for the localization of the ResourceBundle
due to
the localization facility implemented in
createResource
, which is specified in section
JSF.2.6.1.3 of the spec prose document. If the resultant Resource
exists and can be found, the InputStream
for the resource is used to create a ResourceBundle
.
If either of the two previous steps for obtaining the
ResourceBundle
for this component is successful, the
ResourceBundle
is wrapped in a
Map<String,String>
and returned. Otherwise
Collections.EMPTY_MAP
is returned.
public abstract List<UIComponent> getChildren()
Return a mutable
List
representing the child UIComponent
s
associated with this component. The returned implementation must
support all of the standard and optional List
methods, plus support the following additional requirements:
List
implementation must implement the
java.io.Serializable
interface.null
must throw a NullPointerExceptionUIComponent
must throw a ClassCastException.parent
property of
the child must be set to this component instance. If the
parent
property of the child was already non-null,
the child must first be removed from its previous parent (where
it may have been either a child or a facet).parent
property of the child must be set to null
.After the child component has
been added to the view, Application.publishEvent(javax.faces.context.FacesContext, java.lang.Class<? extends javax.faces.event.SystemEvent>, java.lang.Object)
must be
called, passing PostAddToViewEvent
.class
as
the first argument and the newly added component as the
second argument if any the following cases are true.
FacesContext.getCurrentPhaseId()
returns
PhaseId.RESTORE_VIEW
and partial
state saving is enabled.
FacesContext.isPostback()
returns false
and FacesContext.getCurrentPhaseId()
returns
something other than PhaseId.RESTORE_VIEW
public abstract int getChildCount()
Return the number of child UIComponent
s that are
associated with this UIComponent
. If there are no
children, this method must return 0. The method must not cause
the creation of a child component list.
public abstract UIComponent findComponent(String expr)
Search for and
return the UIComponent
with an id
that
matches the specified search expression (if any), according to
the algorithm described below.
WARNING: The found
UIComponent
instance, if any, is returned
without regard for its tree traversal context.
Retrieving an EL-bound attribute from the component is not safe.
EL expressions can contain implicit objects, such as
#{component}
, which assume they are being evaluated
within the scope of a tree traversal context. Evaluating
expressions with these kinds of implicit objects outside of a
tree traversal context produces undefined results. See invokeOnComponent(javax.faces.context.FacesContext, java.lang.String, javax.faces.component.ContextCallback)
for a method that does
correctly account for the tree traversal context when operating
on the found UIComponent
instance. invokeOnComponent(javax.faces.context.FacesContext, java.lang.String, javax.faces.component.ContextCallback)
is also useful to find components given a simple clientId
.
Component identifiers are required to be unique within the scope of
the closest ancestor NamingContainer
that encloses this
component (which might be this component itself). If there are no
NamingContainer
components in the ancestry of this component,
the root component in the tree is treated as if it were a
NamingContainer
, whether or not its class actually implements
the NamingContainer
interface.
A search expression consists of either an identifier
(which is matched exactly against the id
property of
a UIComponent
, or a series of such identifiers linked by
the UINamingContainer.getSeparatorChar(javax.faces.context.FacesContext)
character value.
The search algorithm should operates as follows, though alternate
alogrithms may be used as long as the end result is the same:
UIComponent
that will be the base for searching,
by stopping as soon as one of the following conditions is met:
UIComponent
of the component
tree. The leading separator character will be stripped off,
and the remainder of the search expression will be treated as
a "relative" search expression as described below.UIComponent
is a
NamingContainer
it will serve as the basis.NamingContainer
is encountered, it will be the base.
NamingContainer
is encountered)
the root UIComponent
will be the base.id
that matches, within
the scope of the base component. The match is performed as follows:
id
property, and then recursively
through the facets and children of the base UIComponent
(except that if a descendant NamingContainer
is found,
its own facets and children are not searched).NamingContainer
by the rules in the
previous bullet point. Then, the findComponent()
method of this NamingContainer
will be called, passing
the remainder of the search expression.expr
- Search expression identifying the UIComponent
to be returnedUIComponent
, or null
if the component was not found.IllegalArgumentException
- if an intermediate identifier
in a search expression identifies a UIComponent
that is
not a NamingContainer
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(javax.faces.context.FacesContext, javax.faces.component.UIComponent)
method on the argument
callback
, passing the current FacesContext
and the found component as arguments. This method is similar to
findComponent(java.lang.String)
but it does not support the leading UINamingContainer.getSeparatorChar(javax.faces.context.FacesContext)
syntax for searching from the
root of the View.
The default implementation will first check if
this.getClientId()
is equal to the argument
clientId
. If so, first call pushComponentToEL(javax.faces.context.FacesContext, javax.faces.component.UIComponent)
,
then call the ContextCallback.invokeContextCallback(javax.faces.context.FacesContext, javax.faces.component.UIComponent)
method on the argument
callback, passing through the FacesContext
argument
and passing this as the component argument. Then call popComponentFromEL(javax.faces.context.FacesContext)
.
If an Exception
is thrown by the callback, wrap it
in a FacesException
and re-throw it. Otherwise, return
true
.
Otherwise, for each component returned by getFacetsAndChildren()
, call invokeOnComponent()
passing the arguments to this method, in order. The first time
invokeOnComponent()
returns true, abort traversing
the rest of the Iterator
and return
true
.
When calling ContextCallback.invokeContextCallback(javax.faces.context.FacesContext, javax.faces.component.UIComponent)
the implementation of this method must guarantee that the state
of the component passed to the callback correctly reflects the
component's position in the View hierarchy with respect to any
state found in the argument clientId
. For example,
an iterating component such as UIData
will need to set
its row index to correctly reflect the argument
clientId
before finding the appropriate child
component backed by the correct row. When the callback returns,
either normally or by throwing an Exception
the
implementation of this method must restore the state of the view
to the way it was before invoking the callback.
If none of the elements from getFacetsAndChildren()
returned true
from
invokeOnComponent()
, return false
.
Simple usage example to find a component by
clientId
.
private UIComponent found = null;
private void doFind(FacesContext context, String clientId) {
context.getViewRoot().invokeOnComponent(context, clientId,
new ContextCallback() {
public void invokeContextCallback(FacesContext context,
UIComponent component) {
found = component;
}
});
}
context
- the FacesContext
for the current requestclientId
- the client identifier of the component to be passed
to the argument callback.callback
- an implementation of the Callback interface.true
if the a component with the given
clientId
is found, the callback method was
successfully invoked passing that component as an argument, and
no Exception was thrown. Returns false
if no
component with the given clientId
is found.NullPointerException
- if any of the arguments are nullFacesException
- if the argument Callback throws an
Exception, it is wrapped in a FacesException
and re-thrown.public abstract 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). The returned
implementation must support all of the standard and optional
Map
methods, plus support the following additional
requirements:
Map
implementation must implement
the java.io.Serializable
interface.null
key or value must
throw a NullPointerException.UIComponent
must throw a ClassCastException.UIComponent
is added:
parent
property of the component must be set to
this component instance.parent
property of the component was already
non-null, the component must first be removed from its previous
parent (where it may have been either a child or a facet).UIComponent
is removed:
parent
property of the facet must be
set to null
.public int getFacetCount()
Return the number of facet UIComponent
s that are
associated with this UIComponent
. If there are no
facets, this method must return 0. The method must not cause
the creation of a facet component map.
For backwards compatability with classes that extend UIComponent
directly, a default implementation is provided that simply calls
getFacets()
and then calls the size()
method on the
returned Map
. A more optimized version of this method is
provided in UIComponentBase.getFacetCount()
.
public abstract UIComponent getFacet(String name)
Convenience method to return the named facet, if it exists, or
null
otherwise. If the requested facet does not
exist, the facets Map must not be created.
name
- Name of the desired facetpublic abstract Iterator<UIComponent> getFacetsAndChildren()
Return an Iterator
over the facet followed by child
UIComponent
s of this UIComponent
.
Facets are returned in an undefined order, followed by
all the children in the order they are stored in the child list. If this
component has no facets or children, an empty Iterator
is returned.
The returned Iterator
must not support the
remove()
operation.
public abstract void broadcast(FacesEvent event) throws AbortProcessingException
Broadcast the specified FacesEvent
to all registered
event listeners who have expressed an interest in events of this
type. Listeners are called in the order in which they were
added.
If the event
is an instance of
BehaviorEvent
and the current
component
is the source of the event
call BehaviorEvent.getBehavior()
to get the
Behavior
for the event.
Call Behavior.broadcast(javax.faces.event.BehaviorEvent)
on the Behavior
instance.
event
- The FacesEvent
to be broadcastAbortProcessingException
- Signal the JavaServer Faces
implementation that no further processing on the current event
should be performedIllegalArgumentException
- if the implementation class
of this FacesEvent
is not supported by this componentNullPointerException
- if event
is
null
public abstract void decode(FacesContext context)
Decode any new state of this UIComponent
from the
request contained in the specified FacesContext
, and store
this state as needed.
During decoding, events may be enqueued for later processing
(by event listeners who have registered an interest), by calling
queueEvent()
.
context
- FacesContext
for the request we are processingNullPointerException
- if context
is null
public boolean visitTree(VisitContext context, VisitCallback callback)
Perform a tree visit starting at this node in the tree.
UIComponent.visitTree() implementations do not invoke the
VisitCallback
directly, but instead call VisitContext.invokeVisitCallback(javax.faces.component.UIComponent, javax.faces.component.visit.VisitCallback)
to invoke the callback. This
allows VisitContext
implementations to provide optimized
tree traversals, for example by only calling the VisitCallback
for a subset of components.
UIComponent.visitTree() implementations must call UIComponent.pushComponentToEL() before performing the visit and UIComponent.popComponentFromEL() after the visit.
context
- the VisitContext
for this visitcallback
- the VisitCallback
instance
whose visit
method will be called
for each node visited.true
to indicate that the tree visit is complete (eg. all components
that need to be visited have been visited). This results in
the tree visit being short-circuited such that no more components
are visited.
VisitContext.invokeVisitCallback()
protected boolean isVisitable(VisitContext context)
Return true
if this
component should be visited, false
otherwise.
Called by UIComponent.visitTree()
to determine whether this component satisfies the hints returned
by VisitContext.getHints()
.
If this method returns false, the tree visited is short-circuited such that neither the component nor any of its descendents will be visited>
Custom visitTree()
implementations may call this
method to determine whether the component is visitable before
performing any visit-related processing.
public abstract void encodeBegin(FacesContext context) throws IOException
If our
rendered
property is true
, render the
beginning of the current state of this UIComponent
to the
response contained in the specified FacesContext
.
Call pushComponentToEL(javax.faces.context.FacesContext,javax.faces.component.UIComponent)
.
Call Application.publishEvent(javax.faces.context.FacesContext, java.lang.Class<? extends javax.faces.event.SystemEvent>, java.lang.Object)
, passing
PreRenderComponentEvent
.class
as the
first argument and the component instance to be rendered as the
second argument.
If a Renderer
is associated with this UIComponent
, the actual encoding will be delegated to
Renderer.encodeBegin(FacesContext, UIComponent)
.
If our rendered
property is
false
, call pushComponentToEL(javax.faces.context.FacesContext,javax.faces.component.UIComponent)
and return immediately.
context
- FacesContext
for the response we are creatingIOException
- if an input/output error occurs while renderingNullPointerException
- if context
is null
public abstract void encodeChildren(FacesContext context) throws IOException
If our rendered
property is true
,
render the child UIComponent
s of this UIComponent
.
This method will only be called
if the rendersChildren
property is true
.
If a Renderer
is associated with this UIComponent
,
the actual encoding will be delegated to
Renderer.encodeChildren(FacesContext, UIComponent)
.
If no Renderer
is associated
with this UIComponent
, iterate over each of the children of this
component and call
encodeAll(javax.faces.context.FacesContext)
.
context
- FacesContext
for the response we are creatingIOException
- if an input/output error occurs while renderingNullPointerException
- if context
is null
public abstract void encodeEnd(FacesContext context) throws IOException
If our
rendered
property is true
, render the
ending of the current state of this UIComponent
.
If a Renderer
is associated with this UIComponent
,
the actual encoding will be delegated to
Renderer.encodeEnd(FacesContext, UIComponent)
.
Call popComponentFromEL(javax.faces.context.FacesContext)
. before returning regardless of the value
of the rendered
property.
context
- FacesContext
for the response we are creatingIOException
- if an input/output error occurs while renderingNullPointerException
- if context
is null
public void encodeAll(FacesContext context) throws IOException
If this component
returns true
from isRendered()
, take the
following action.
Render this component and all its children that return
true
from isRendered()
, regardless of
the value of the getRendersChildren()
flag.
IOException
- if an input/output error occurs while renderingNullPointerException
- if context
is null
public final void pushComponentToEL(FacesContext context, UIComponent component)
Push the current
UIComponent
this
to the FacesContext
attribute map using the key CURRENT_COMPONENT
saving the previous
UIComponent
associated with CURRENT_COMPONENT
for a
subsequent call to popComponentFromEL(javax.faces.context.FacesContext)
.
popComponentFromEL()
form the basis for
the contract that enables the EL Expression "#{component}
" to
resolve to the "current" component that is being processed in the
lifecycle. The requirements for when pushComponentToEL()
and
popComponentFromEL()
must be called are specified as
needed in the javadoc for this class.
After
pushComponentToEL()
returns, a call to getCurrentComponent(javax.faces.context.FacesContext)
must return this
UIComponent
instance until
popComponentFromEL()
is called, after which point
the previous UIComponent
instance will be returned
from getCurrentComponent()
context
- the FacesContext
for the current requestcomponent
- the component
to push to the EL. If
component
is null
the UIComponent
instance that this call was invoked upon will be pushed to the EL.NullPointerException
- if context
is null
FacesContext.getAttributes()
public final void popComponentFromEL(FacesContext context)
Pop the current
UIComponent
from the FacesContext
attributes map
so that the previous UIComponent
, if any, becomes the current
component.
context
- the FacesContext
for the current requestNullPointerException
- if context
is null
FacesContext.getAttributes()
public static boolean isCompositeComponent(UIComponent component)
Return true
if
component
is a composite component, otherwise
false
.
component
- the UIComponent
to testNullPointerException
- if component
is null
public static UIComponent getCompositeComponentParent(UIComponent component)
Finds the nearest composite component parent of the specified component.
component
- the component from which to start the search fromcomponent
is null
, return
null
, otherwise search the component's parent hierachy
for the nearest parent composite component. If no parent composite
component is found, return null
public static UIComponent getCurrentComponent(FacesContext context)
Return the UIComponent
instance that is currently processing. This is equivalent to
evaluating the EL expression "#{component}
" and
doing a getValue
operation on the resultant
ValueExpression
.
This method must return
null
if there is no currently processing
UIComponent
context
- FacesContext
for the request we are processingNullPointerException
- if context
is null
public static UIComponent getCurrentCompositeComponent(FacesContext context)
Return the closest ancestor
component, relative to the component returned from getCurrentComponent(javax.faces.context.FacesContext)
, that is a composite component, or
null
if no such component exists.
context
- FacesContext
for the request we are processingNullPointerException
- if context
is null
protected abstract void addFacesListener(FacesListener listener)
Add the specified FacesListener
to the set of listeners
registered to receive event notifications from this UIComponent
.
It is expected that UIComponent
classes acting as event sources
will have corresponding typesafe APIs for registering listeners of the
required type, and the implementation of those registration methods
will delegate to this method. For example:
public class FooEvent extends FacesEvent { ... } public interface FooListener extends FacesListener { public void processFoo(FooEvent event); } public class FooComponent extends UIComponentBase { ... public void addFooListener(FooListener listener) { addFacesListener(listener); } public void removeFooListener(FooListener listener) { removeFacesListener(listener); } ... }
listener
- The FacesListener
to be registeredNullPointerException
- if listener
is null
protected abstract FacesListener[] getFacesListeners(Class clazz)
Return an array of registered FacesListener
s that are
instances of the specified class. If there are no such registered
listeners, a zero-length array is returned. The returned
array can be safely be cast to an array strongly typed to
an element type of clazz
.
clazz
- Class that must be implemented by a FacesListener
for it to be returnedIllegalArgumentException
- if class
is not,
and does not implement, FacesListener
NullPointerException
- if clazz
is null
protected abstract void removeFacesListener(FacesListener listener)
Remove the specified FacesListener
from the set of listeners
registered to receive event notifications from this UIComponent
.
listener
- The FacesListener
to be deregisteredNullPointerException
- if listener
is null
public abstract void queueEvent(FacesEvent event)
Queue an event for broadcast at the end of the current request
processing lifecycle phase. The default implementation in
UIComponentBase
must delegate this call to the
queueEvent()
method of the parent UIComponent
.
event
- FacesEvent
to be 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)
This implementation throws
UnsupportedOperationException
and is provided
for the sole purpose of not breaking existing applications that extend
this class. UIComponentBase
provides the implementation of
this method.
public void unsubscribeFromEvent(Class<? extends SystemEvent> eventClass, ComponentSystemEventListener componentListener)
This implementation throws
UnsupportedOperationException
and is provided
for the sole purpose of not breaking existing applications that extend
this class. UIComponentBase
provides the implementation of
this method.
public List<SystemEventListener> getListenersForEventClass(Class<? extends SystemEvent> eventClass)
This implementation throws
UnsupportedOperationException
and is provided
for the sole purpose of not breaking existing applications that extend
this class. UIComponentBase
provides the implementation of
this method.
getListenersForEventClass
in interface SystemEventListenerHolder
public UIComponent getNamingContainer()
Starting with "this", return the closest
component in the ancestry that is a NamingContainer
or null
if none can be found.
public abstract 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.
restoreState()
method of this component.pushComponentToEL(javax.faces.context.FacesContext, javax.faces.component.UIComponent)
. processRestoreState()
method of all
facets and children of this UIComponent
in the order
determined by a call to getFacetsAndChildren()
.
After returning from the
processRestoreState()
method on a child or facet,
call popComponentFromEL(javax.faces.context.FacesContext)
This method may not be called if the state saving method is set to server.
context
- FacesContext
for the request we are processingNullPointerException
- if context
is null
public abstract void processDecodes(FacesContext context)
Perform the component tree processing required by the Apply Request Values phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
rendered
property of this UIComponent
is false
, skip further processing.pushComponentToEL(javax.faces.context.FacesContext, javax.faces.component.UIComponent)
.processDecodes()
method of all facets
and children of this UIComponent
, in the order determined
by a call to getFacetsAndChildren()
.decode()
method of this component.popComponentFromEL(javax.faces.context.FacesContext)
from inside of a
finally block, just before returning.
RuntimeException
is thrown during
decode processing, call FacesContext.renderResponse()
and re-throw the exception.context
- FacesContext
for the request we are processingNullPointerException
- if context
is null
public void processEvent(ComponentSystemEvent event) throws AbortProcessingException
The default implementation performs
the following action. If the argument event
is an
instance of PostRestoreStateEvent
, call
this.
getValueExpression(java.lang.String)
passing the literal
string “binding”, without the quotes, as the
argument. If the result is non-null
, set the value
of the ValueExpression
to be this
.
processEvent
in interface ComponentSystemEventListener
event
- the ComponentSystemEvent
instance that
is being processed.AbortProcessingException
- if lifecycle processing should
cease for this request.public abstract void processValidators(FacesContext context)
Perform the component tree processing required by the Process Validations phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
rendered
property of this UIComponent
is false
, skip further processing.pushComponentToEL(javax.faces.context.FacesContext, javax.faces.component.UIComponent)
.processValidators()
method of all facets
and children of this UIComponent
, in the order determined
by a call to getFacetsAndChildren()
.getFacetsAndChildren()
call popComponentFromEL(javax.faces.context.FacesContext)
.context
- FacesContext
for the request we are processingNullPointerException
- if context
is null
public abstract void processUpdates(FacesContext context)
Perform the component tree processing required by the Update Model Values phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
rendered
property of this UIComponent
is false
, skip further processing.pushComponentToEL(javax.faces.context.FacesContext, javax.faces.component.UIComponent)
.processUpdates()
method of all facets
and children of this UIComponent
, in the order determined
by a call to getFacetsAndChildren()
. After returning from the
processUpdates()
method on a child or facet, call
popComponentFromEL(javax.faces.context.FacesContext)
context
- FacesContext
for the request we are processingNullPointerException
- if context
is null
public abstract Object processSaveState(FacesContext context)
Perform the component tree processing required by the state saving portion of the Render Response phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
transient
property of this
component. If true, just return null
.pushComponentToEL(javax.faces.context.FacesContext, javax.faces.component.UIComponent)
.processSaveState()
method of all facets
and children of this UIComponent
in the order determined
by a call to getFacetsAndChildren()
, skipping
children and facets that are transient. Ensure that popComponentFromEL(javax.faces.context.FacesContext)
is called correctly after each child or
facet.saveState()
method of this component.This method may not be called if the state saving method is set to server.
context
- FacesContext
for the request we are processingNullPointerException
- if context
is null
protected abstract FacesContext getFacesContext()
Convenience method to return the FacesContext
instance
for the current request.
protected abstract Renderer getRenderer(FacesContext context)
Convenience method to return the Renderer
instance
associated with this component, if any; otherwise, return
null
.
context
- FacesContext
for the current requestCopyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.