|
DRAFT | ||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Objectjavax.faces.component.UIComponent
public abstract class UIComponent
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.
| Field Summary | |
|---|---|
static java.lang.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 java.util.Map<java.lang.String,ValueExpression> |
bindings
Deprecated. |
static java.lang.String |
COMPOSITE_COMPONENT_TYPE_KEY
The value of this constant is used as the key
in the composite component BeanDescriptor for a
|
static java.lang.String |
COMPOSITE_FACET_NAME
The value of this constant is used as the key
in the |
static java.lang.String |
CURRENT_COMPONENT
The key to which the
|
static java.lang.String |
CURRENT_COMPOSITE_COMPONENT
The key to which the
composite |
static java.lang.String |
FACETS_KEY
The value of this constant is used as the key
in the composite component BeanDescriptor for the
|
static java.lang.String |
VIEW_LOCATION_KEY
The value of this constant is used as the key
in the component attributes |
| Constructor Summary | |
|---|---|
UIComponent()
|
|
| Method Summary | |
|---|---|
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)
If our rendered property is true,
render the child UIComponents of this UIComponent. |
abstract void |
encodeEnd(FacesContext context)
If our rendered property is true, render the
ending of the current state of this UIComponent. |
abstract UIComponent |
findComponent(java.lang.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 java.util.Map<java.lang.String,java.lang.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 UIComponents that are
associated with this UIComponent. |
abstract java.util.List<UIComponent> |
getChildren()
Return a mutable List representing the child UIComponents
associated with this component. |
java.lang.String |
getClientId()
Enable EL to access the |
abstract java.lang.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. |
java.lang.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(java.lang.Class clazz)
Return an array of registered FacesListeners that are
instances of the specified class. |
abstract UIComponent |
getFacet(java.lang.String name)
Convenience method to return the named facet, if it exists, or null otherwise. |
int |
getFacetCount()
Return the number of facet UIComponents that are
associated with this UIComponent. |
abstract java.util.Map<java.lang.String,UIComponent> |
getFacets()
Return a mutable Map representing the facet
UIComponents associated with this UIComponent,
keyed by facet name (which must be a String). |
abstract java.util.Iterator<UIComponent> |
getFacetsAndChildren()
Return an Iterator over the facet followed by child
UIComponents of this UIComponent. |
abstract java.lang.String |
getFamily()
Return the identifier of the component family to which this component belongs. |
abstract java.lang.String |
getId()
Return the component identifier of this UIComponent. |
java.util.List<SystemEventListener> |
getListenersForEventClass(java.lang.Class<? extends SystemEvent> eventClass)
Return the
|
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. |
protected abstract Renderer |
getRenderer(FacesContext context)
Convenience method to return the Renderer instance
associated with this component, if any; otherwise, return
null. |
abstract java.lang.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. |
java.util.Map<java.lang.String,java.lang.String> |
getResourceBundleMap()
Return a
|
protected StateHelper |
getStateHelper()
Return the |
protected StateHelper |
getStateHelper(boolean create)
Like |
abstract ValueBinding |
getValueBinding(java.lang.String name)
Deprecated. This has been replaced by getValueExpression(java.lang.String). |
ValueExpression |
getValueExpression(java.lang.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,
java.lang.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 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,
java.lang.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 java.lang.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. |
abstract void |
setId(java.lang.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(java.lang.String rendererType)
Set the Renderer type for this UIComponent,
or null for components that render themselves. |
abstract void |
setValueBinding(java.lang.String name,
ValueBinding binding)
Deprecated. This has been replaced by setValueExpression(java.lang.String, javax.el.ValueExpression). |
void |
setValueExpression(java.lang.String name,
ValueExpression binding)
Set the ValueExpression used to calculate the value
for the specified attribute or property name, if any. |
void |
subscribeToEvent(java.lang.Class<? extends SystemEvent> eventClass,
ComponentSystemEventListener componentListener)
Install the listener instance
referenced by argument |
void |
unsubscribeFromEvent(java.lang.Class<? extends SystemEvent> eventClass,
ComponentSystemEventListener componentListener)
Remove the listener instance
referenced by argument |
boolean |
visitTree(VisitContext context,
VisitCallback callback)
Perform a tree visit starting at this node in the tree. |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Methods inherited from interface javax.faces.component.StateHolder |
|---|
isTransient, restoreState, saveState, setTransient |
| Field Detail |
|---|
public static final java.lang.String CURRENT_COMPONENT
The key to which the
UIComponent currently being processed will be
associated with within the FacesContext attributes map.
FacesContext.getAttributes(),
Constant Field Valuespublic static final java.lang.String CURRENT_COMPOSITE_COMPONENT
The key to which the
composite UIComponent currently being
processed will be associated with within the FacesContext
attributes map.
FacesContext.getAttributes(),
Constant Field Valuespublic static final java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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.
@Deprecated protected java.util.Map<java.lang.String,ValueExpression> bindings
| Constructor Detail |
|---|
public UIComponent()
| Method Detail |
|---|
public abstract java.util.Map<java.lang.String,java.lang.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 abstract ValueBinding getValueBinding(java.lang.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
java.lang.NullPointerException - if name
is null
public abstract void setValueBinding(java.lang.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
ValueBindingbinding - The ValueBinding to set, or null
to remove any currently set ValueBinding
java.lang.IllegalArgumentException - if name is one of
id or parent
java.lang.NullPointerException - if name
is nullpublic ValueExpression getValueExpression(java.lang.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
java.lang.NullPointerException - if name
is null
public void setValueExpression(java.lang.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 ValueExpression#isLiteralText on the argument
expression. If isLiteralText() returns
true, invoke ValueExpression#getValue 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, wrap it in
a FacesException and re-throw it. If
isLiteralText() returns false, simply
store the un-evaluated expression argument in the
collection of ValueExpressions 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
ValueExpressionbinding - The ValueExpression to set, or null
to remove any currently set ValueExpression
java.lang.IllegalArgumentException - if name is one of
id or parent
java.lang.NullPointerException - if name
is nullpublic 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 PartialStateHolderpublic 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 PartialStateHolderpublic 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 PartialStateHolderprotected 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 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 java.lang.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 java.lang.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 + myIdRenderer#convertClientId, passing myId, and
return the result.
context - The FacesContext for the current request
java.lang.NullPointerException - if context
is nullpublic java.lang.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.
java.lang.NullPointerException - if context is
nullpublic abstract java.lang.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 java.lang.String getId()
Return the component identifier of this UIComponent.
public abstract void setId(java.lang.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 identifier
java.lang.IllegalArgumentException - 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.
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 java.lang.String getRendererType()
Return the Renderer type for this UIComponent
(if any).
public abstract void setRendererType(java.lang.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.
public java.util.Map<java.lang.String,java.lang.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 java.util.List<UIComponent> getChildren()
Return a mutable
List representing the child UIComponents
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, if the following condition is not met:
FacesContext.isPostback()
returns true and FacesContext.getCurrentPhaseId() returns PhaseId.RESTORE_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.
public abstract int getChildCount()
Return the number of child UIComponents 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(java.lang.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.
For a method to find a component given a simple
clientId, see invokeOnComponent(javax.faces.context.FacesContext, java.lang.String, javax.faces.component.ContextCallback).
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 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 returned
UIComponent, or null
if the component was not found.
java.lang.IllegalArgumentException - if an intermediate identifier
in a search expression identifies a UIComponent that is
not a NamingContainer
java.lang.NullPointerException - if expr
is null
public boolean invokeOnComponent(FacesContext context,
java.lang.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 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 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, call the ContextCallback#invokeContextCallback method on the argument callback,
passing through the FacesContext argument and
passing this as the component argument. 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
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.
java.lang.NullPointerException - if any of the arguments are null
FacesException - if the argument Callback throws an
Exception, it is wrapped in a FacesException and re-thrown.public abstract java.util.Map<java.lang.String,UIComponent> getFacets()
Return a mutable Map representing the facet
UIComponents 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 UIComponents 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(java.lang.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 java.util.Iterator<UIComponent> getFacetsAndChildren()
Return an Iterator over the facet followed by child
UIComponents 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. If the
behavior implements ClientBehavior,
call Behavior.broadcast(javax.faces.event.BehaviorEvent)}.
event - The FacesEvent to be broadcast
AbortProcessingException - Signal the JavaServer Faces
implementation that no further processing on the current event
should be performed
java.lang.IllegalArgumentException - if the implementation class
of this FacesEvent is not supported by this component
java.lang.NullPointerException - if event is
nullpublic 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 processing
java.lang.NullPointerException - 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 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 java.io.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 creating
java.io.IOException - if an input/output error occurs while rendering
java.lang.NullPointerException - if context
is null
public abstract void encodeChildren(FacesContext context)
throws java.io.IOException
If our rendered property is true,
render the child UIComponents 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 creating
java.io.IOException - if an input/output error occurs while rendering
java.lang.NullPointerException - if context
is null
public abstract void encodeEnd(FacesContext context)
throws java.io.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 UIComponent#popComponentFromEL. before returning regardless of the value
of the rendered property.
context - FacesContext for the response we are creating
java.io.IOException - if an input/output error occurs while rendering
java.lang.NullPointerException - if context
is null
public void encodeAll(FacesContext context)
throws java.io.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.
java.io.IOException - if an input/output error occurs while rendering
java.lang.NullPointerException - 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.
java.lang.NullPointerException - if context is nullFacesContext.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 request
java.lang.NullPointerException - if context is nullFacesContext.getAttributes()public static boolean isCompositeComponent(UIComponent component)
Return true if
component is a composite component, otherwise
false.
component - the UIComponent to test
java.lang.NullPointerException - if component is nullpublic static UIComponent getCompositeComponentParent(UIComponent component)
Finds the nearest composite component parent of the specified component.
component - the component from which to start the search from
component 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 nullpublic 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 processing
java.lang.NullPointerException - if context
is nullpublic 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 processing
java.lang.NullPointerException - if context
is nullprotected 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 registered
java.lang.NullPointerException - if listener
is nullprotected abstract FacesListener[] getFacesListeners(java.lang.Class clazz)
Return an array of registered FacesListeners that are
instances of the specified class. If there are no such registered
listeners, a zero-length array is returned. The returned
array can be safely be cast to an array strongly typed to
an element type of clazz.
clazz - Class that must be implemented by a FacesListener
for it to be returned
java.lang.IllegalArgumentException - if class is not,
and does not implement, FacesListener
java.lang.NullPointerException - if clazz
is nullprotected 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 deregistered
java.lang.NullPointerException - if listener
is nullpublic 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 queued
IllegalStateException - if this component is not a
descendant of a UIViewRoot
java.lang.NullPointerException - if event
is null
public void subscribeToEvent(java.lang.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 and its implementation of
SystemEventListener#isListenerForSource must return
true if the instance class of this UIComponent is
assignable from the argument to
isListenerForSource.
eventClass - the Class of event for which
listener must be fired.componentListener - the implementation of ComponentSystemEventListener whose ComponentSystemEventListener#processEvent method must be called
when events of type facesEventClass are fired.
NullPointerException - if any of the
arguments are null.
public void unsubscribeFromEvent(java.lang.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.
eventClass - the Class of event for which
listener must be removed.componentListener - the implementation of ComponentSystemEventListener whose ComponentSystemEventListener#processEvent method must no longer be called
when events of type eventClass are fired.
NullPointerException - if any of the
arguments are null.public java.util.List<SystemEventListener> getListenersForEventClass(java.lang.Class<? extends SystemEvent> eventClass)
Return the
SystemEventListener instances registered on this
UIComponent instance that are interested in events
of type eventClass.
getListenersForEventClass in interface SystemEventListenerHoldereventClass - the Class of event for which the
listeners must be returned.
java.lang.NullPointerException - if argument eventClass is null.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,
java.lang.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.UIComponent#pushComponentToEL. 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#popComponentFromELThis method may not be called if the state saving method is set to server.
context - FacesContext for the request we are processing
java.lang.NullPointerException - if context
is nullpublic 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 processing
java.lang.NullPointerException - 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 ComponentSystemEventListenerevent - 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().
context - FacesContext for the request we are processing
java.lang.NullPointerException - if context
is nullpublic 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
UIComponent#popComponentFromEL
context - FacesContext for the request we are processing
java.lang.NullPointerException - if context
is nullpublic abstract java.lang.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 processing
java.lang.NullPointerException - if context
is nullprotected 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 request
|
DRAFT | ||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright © 2009 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.
Generated on 24-November-2009 03:24