Class Hierarchy All Classes All Fields and Methods

 

Class javax.faces.component.UIComponent

java.lang.Object
        javax.faces.component.UIComponent

public abstract class UIComponent
implements StateHolder
extends Object

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.

Constructor Index

Constructor	Description
UIComponent()

Method Index

Method	Description
void addFacesListener(FacesListener)	Add the specified FacesListener to the set of listeners registered to receive event notifications from this UIComponent.
void broadcast(FacesEvent)	Broadcast the specified FacesEvent to all registered event listeners who have expressed an interest in events of this type.
void decode(FacesContext)	Decode any new state of this UIComponent from the request contained in the specified FacesContext, and store this state as needed.
void encodeBegin(FacesContext)	If our rendered property is true, render the beginning of the current state of this UIComponent to the response contained in the specified FacesContext.
void encodeChildren(FacesContext)	If our rendered property is true, render the child UIComponents of this UIComponent.
void encodeEnd(FacesContext)	If our rendered property is true, render the ending of the current state of this UIComponent.
UIComponent findComponent(String)	Search for and return the UIComponent with an id that matches the specified search expression (if any), according to the algorithm described below.
Map getAttributes()	Return a mutable Map representing the attributes (and properties, see below) associated wth this UIComponent, keyed by attribute name (which must be a String).
int getChildCount()	Return the number of child UIComponents that are associated with this UIComponent.
List getChildren()	Return a mutable List representing the child UIComponents associated with this component.
String getClientId(FacesContext)	Return a client-side identifier for this component, generating one if necessary.
FacesContext getFacesContext()	Convenience method to return the FacesContext instance for the current request.
FacesListener[] getFacesListeners(Class)	Return an array of registered FacesListeners that are instances of the specified class.
UIComponent getFacet(String)	Convenience method to return the named facet, if it exists, or null otherwise.
Map getFacets()	Return a mutable Map representing the facet UIComponents associated with this UIComponent, keyed by facet name (which must be a String).
Iterator getFacetsAndChildren()	Return an Iterator over the facet followed by child UIComponents of this UIComponent.
String getFamily()	Return the identifier of the component family to which this component belongs.
String getId()	Return the component identifier of this UIComponent.
UIComponent getParent()	Return the parent UIComponent of this UIComponent, if any.
Renderer getRenderer(FacesContext)	Convenience method to return the Renderer instance associated with this component, if any; otherwise, return null.
String getRendererType()	Return the Renderer type for this UIComponent (if any).
boolean getRendersChildren()	Return a flag indicating whether this component is responsible for rendering its child components.
ValueBinding getValueBinding(String)	Return the ValueBinding used to calculate the value for the specified attribute or property name, if any.
boolean isRendered()	Return true if this component (and its children) should be rendered during the Render Response phase of the request processing lifecycle.
void processDecodes(FacesContext)	Perform the component tree processing required by the Apply Request Values phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
void processRestoreState(FacesContext, Object)	Perform the component tree processing required by the Restore View phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
Object processSaveState(FacesContext)	Perform the component tree processing required by the state saving portion of the Render Response phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
void processUpdates(FacesContext)	Perform the component tree processing required by the Update Model Values phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
void processValidators(FacesContext)	Perform the component tree processing required by the Process Validations phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
void queueEvent(FacesEvent)	Queue an event for broadcast at the end of the current request processing lifecycle phase.
void removeFacesListener(FacesListener)	Remove the specified FacesListener from the set of listeners registered to receive event notifications from this UIComponent.
void setId(String)	Set the component identifier of this UIComponent (if any).
void setParent(UIComponent)	Set the parent UIComponent of this UIComponent.
void setRendered(boolean)	Set the rendered property of this UIComponent.
void setRendererType(String)	Set the Renderer type for this UIComponent, or null for components that render themselves.
void setValueBinding(String, ValueBinding)	Set the ValueBinding used to calculate the value for the specified attribute or property name, if any.

 

Constructors

 

UIComponent

public UIComponent() 

 

Methods

 

addFacesListener

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);
   }
   ...
 }
 

• Parameters

  • listener - The FacesListener to be registered

• Throws

  • NullPointerException if listener is null

 

broadcast

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.

• Parameters

  • event - The FacesEvent to be broadcast

• Throws

  • AbortProcessingException Signal the JavaServer Faces implementation that no further processing on the current event should be performed

• Throws

  • IllegalArgumentException if the implementation class of this FacesEvent is not supported by this component

• Throws

  • NullPointerException if event is null

 

decode

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().

• Parameters

  • context - FacesContext for the request we are processing

• Throws

  • NullPointerException if context is null

 

encodeBegin

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.

If a Renderer is associated with this UIComponent, the actual encoding will be delegated to encodeBegin.

• Parameters

  • context - FacesContext for the response we are creating

• Throws

  • IOException if an input/output error occurs while rendering

• Throws

  • NullPointerException if context is null

 

encodeChildren

public abstract void encodeChildren(FacesContext context) throws 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 encodeBegin.

• Parameters

  • context - FacesContext for the response we are creating

• Throws

  • IOException if an input/output error occurs while rendering

• Throws

  • NullPointerException if context is null

 

encodeEnd

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 encodeBegin.

• Parameters

  • context - FacesContext for the response we are creating

• Throws

  • IOException if an input/output error occurs while rendering

• Throws

  • NullPointerException if context is null

 

findComponent

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.

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 SEPARATOR_CHAR character value. The search algorithm operates as follows:

• Identify the UIComponent that will be the base for searching, by stopping as soon as one of the following conditions is met:
  • If the search expression begins with the the separator character (called an "absolute" search expression), the base will be the root 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.
  • Otherwise, if this UIComponent is a NamingContainer it will serve as the basis.
  • Otherwise, search up the parents of this component. If a NamingContainer is encountered, it will be the base.
  • Otherwise (if no NamingContainer is encountered) the root UIComponent will be the base.

• The search expression (possibly modified in the previous step) is now a "relative" search expression that will be used to locate the component (if any) that has an id that matches, within the scope of the base component. The match is performed as follows:
  • If the search expression is a simple identifier, this value is compared to the 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).
  • If the search expression includes more than one identifier separated by the separator character, the first identifier is used to locate a 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.

• Parameters

  • expr - Search expression identifying the UIComponent to be returned

• Returns

  • the found UIComponent, or null if the component was not found.

• Throws

  • IllegalArgumentException if an intermediate identifier in a search expression identifies a UIComponent that is not a NamingContainer

• Throws

  • NullPointerException if expr is null

 

getAttributes

public abstract Map 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:

• The Map implementation must implement the java.io.Serializable interface.
• 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 a ClassCastException.
• If the attribute name specified as a key matches a property of this 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.

 

getChildCount

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.

 

getChildren

public abstract List 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:

• The List implementation must implement the java.io.Serializable interface.
• Any attempt to add a null must throw a NullPointerException
• Any attempt to add an object that does not implement UIComponent must throw a ClassCastException.
• Whenever a new child component is added, the 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).
• Whenever an existing child component is removed, the parent property of the child must be set to null.

 

getClientId

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.

• Parameters

  • context - The FacesContext for the current request

• Throws

  • NullPointerException if context is null

 

getFacesContext

protected abstract FacesContext getFacesContext() 

Convenience method to return the FacesContext instance for the current request.

 

getFacesListeners

protected abstract FacesListener[] getFacesListeners(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.

• Parameters

  • clazz - Class that must be implemented by a FacesListener for it to be returned

• Throws

  • IllegalArgumentException if class is not, and does not implement, FacesListener

• Throws

  • NullPointerException if clazz is null

 

getFacet

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.

• Parameters

  • name - Name of the desired facet

 

getFacets

public abstract Map 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:

• The Map implementation must implement the java.io.Serializable interface.
• 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 a ClassCastException.
• Any attempt to add a value that is not a UIComponent must throw a ClassCastException.
• Whenever a new facet UIComponent is added:
  • The parent property of the component must be set to this component instance.
  • If the 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).

• Whenever an existing facet UIComponent is removed:
  • The parent property of the facet must be set to null.

 

getFacetsAndChildren

public abstract Iterator 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.

 

getFamily

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.

 

getId

public abstract String getId() 

Return the component identifier of this UIComponent.

 

getParent

public abstract UIComponent getParent() 

Return the parent UIComponent of this UIComponent, if any.

 

getRenderer

protected abstract Renderer getRenderer(FacesContext context) 

Convenience method to return the Renderer instance associated with this component, if any; otherwise, return null.

• Parameters

  • context - FacesContext for the current request

 

getRendererType

public abstract String getRendererType() 

Return the Renderer type for this UIComponent (if any).

 

getRendersChildren

public abstract boolean getRendersChildren() 

Return a flag indicating whether this component is responsible for rendering its child components. The default implementation in getRendersChildren tries to find the renderer for this component. If it does, it calls getRendersChildren and returns the result. If it doesn't, it returns false.

 

getValueBinding

public abstract ValueBinding getValueBinding(String name) 

Return the ValueBinding used to calculate the value for the specified attribute or property name, if any.

• Parameters

  • name - Name of the attribute or property for which to retrieve a ValueBinding

• Throws

  • NullPointerException if name is null

 

isRendered

public abstract boolean isRendered() 

Return true if this component (and its children) should be rendered during the Render Response phase of the request processing lifecycle.

 

processDecodes

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.

• If the rendered property of this UIComponent is false, skip further processing.
• Call the processDecodes() method of all facets and children of this UIComponent, in the order determined by a call to getFacetsAndChildren().
• Call the decode() method of this component.
• If a RuntimeException is thrown during decode processing, call renderResponse and re-throw the exception.

• Parameters

  • context - FacesContext for the request we are processing

• Throws

  • NullPointerException if context is null

 

processRestoreState

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.

• Call the processRestoreState() method of all facets and children of this UIComponent in the order determined by a call to getFacetsAndChildren().
• Call the restoreState() method of this component.

This method may not be called if the state saving method is set to server.

• Parameters

  • context - FacesContext for the request we are processing

• Throws

  • NullPointerException if context is null

 

processSaveState

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.

• consult the transient property of this component. If true, just return null.
• Call the processSaveState() method of all facets and children of this UIComponent in the order determined by a call to getFacetsAndChildren().
• Call the saveState() method of this component.
• Encapsulate the child state and your state into a Serializable Object and return it.

This method may not be called if the state saving method is set to server.

• Parameters

  • context - FacesContext for the request we are processing

• Throws

  • NullPointerException if context is null

 

processUpdates

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.

• If the rendered property of this UIComponent is false, skip further processing.
• Call the processUpdates() method of all facets and children of this UIComponent, in the order determined by a call to getFacetsAndChildren().

• Parameters

  • context - FacesContext for the request we are processing

• Throws

  • NullPointerException if context is null

 

processValidators

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.

• If the rendered property of this UIComponent is false, skip further processing.
• Call the processValidators() method of all facets and children of this UIComponent, in the order determined by a call to getFacetsAndChildren().

• Parameters

  • context - FacesContext for the request we are processing

• Throws

  • NullPointerException if context is null

 

queueEvent

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.

• Parameters

  • event - FacesEvent to be queued

• Throws

  • IllegalStateException if this component is not a descendant of a UIViewRoot

• Throws

  • NullPointerException if event is null

 

removeFacesListener

protected abstract void removeFacesListener(FacesListener listener) 

Remove the specified FacesListener from the set of listeners registered to receive event notifications from this UIComponent.

• Parameters

  • listener - The FacesListener to be deregistered

• Throws

  • NullPointerException if listener is null

 

setId

public abstract void setId(String id) 

Set the component identifier of this UIComponent (if any). Component identifiers must obey the following syntax restrictions:

• Must not be a zero-length String.
• First character must be a letter or an underscore ('_').
• Subsequent characters must be a letter, a digit, an underscore ('_'), or a dash ('-').

Component identifiers must also obey the following semantic restrictions (note that this restriction is NOT enforced by the setId() implementation):

• The specified identifier must be unique among all the components (including facets) that are descendents of the nearest ancestor UIComponent that is a NamingContainer, or within the scope of the entire component tree if there is no such ancestor that is a NamingContainer.

• Parameters

  • id - The new component identifier, or null to indicate that this UIComponent does not have a component identifier

• Throws

  • IllegalArgumentException if id is not syntactically valid

 

setParent

public abstract void setParent(UIComponent parent) 

Set the parent UIComponent of this UIComponent. 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.

• Parameters

  • parent - The new parent, or null for the root node of a component tree

 

setRendered

public abstract void setRendered(boolean rendered) 

Set the rendered property of this UIComponent.

• Parameters

  • rendered - If true render this component; otherwise, do not render this component

 

setRendererType

public abstract void setRendererType(String rendererType) 

Set the Renderer type for this UIComponent, or null for components that render themselves.

• Parameters

  • rendererType - Logical identifier of the type of Renderer to use, or null for components that render themselves

 

setValueBinding

public abstract void setValueBinding(String name,
                                     ValueBinding binding) 

Set the ValueBinding used to calculate the value for the specified attribute or property name, if any.

• Parameters

  • 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

• Throws

  • IllegalArgumentException if name is one of id or parent

• Throws

  • NullPointerException if name is null

Class Hierarchy All Classes All Fields and Methods