Java EE 5 SDK

javax.faces.component
Class UIComponent

java.lang.Object
  extended by javax.faces.component.UIComponent
All Implemented Interfaces:
StateHolder
Direct Known Subclasses:
UIComponentBase

public abstract class UIComponent
extends Object
implements StateHolder

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.


Field Summary
protected  Map<String,ValueExpression> bindings
           
 
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.
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(), render this component and all its children that return true from isRendered(), regardless of the value of the getRendersChildren() flag.
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(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 UIComponents that are associated with this UIComponent.
abstract  List<UIComponent> getChildren()
          Return a mutable List representing the child UIComponents associated with this component.
abstract  String getClientId(FacesContext context)
          Return a client-side identifier for this component, generating one if necessary.
 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.
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 FacesListeners 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 UIComponents that are associated with this UIComponent.
abstract  Map<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  Iterator<UIComponent> getFacetsAndChildren()
          Return an Iterator over the facet followed by child UIComponents of this UIComponent.
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.
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  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.
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 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.
abstract  boolean isRendered()
          Return true if this component (and its children) should be rendered during the Render Response phase of the request processing lifecycle.
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.
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.
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(String id)
          Set the component identifier of this UIComponent (if any).
abstract  void setParent(UIComponent parent)
          Set the parent UIComponent of this UIComponent.
abstract  void setRendered(boolean rendered)
          Set the rendered property of this UIComponent.
abstract  void setRendererType(String rendererType)
          Set the Renderer type for this UIComponent, or null for components that render themselves.
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.
 
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

bindings

protected Map<String,ValueExpression> bindings
Constructor Detail

UIComponent

public UIComponent()
Method Detail

getAttributes

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:


getValueBinding

public abstract ValueBinding getValueBinding(String name)
Deprecated. This has been replaced by 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.

Parameters:
name - Name of the attribute or property for which to retrieve a ValueBinding
Throws:
NullPointerException - if name is null

setValueBinding

public abstract void setValueBinding(String name,
                                     ValueBinding binding)
Deprecated. This has been replaced by 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).

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
NullPointerException - if name is null

getValueExpression

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.

Parameters:
name - Name of the attribute or property for which to retrieve a ValueExpression
Throws:
NullPointerException - if name is null
Since:
1.2

setValueExpression

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.getAttributes().put(name, value) where 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 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.

Parameters:
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
Throws:
IllegalArgumentException - if name is one of id or parent
NullPointerException - if name is null
Since:
1.2

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. 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 + NamingContainer.SEPARATOR_CHAR + myId. Call Renderer.convertClientId(javax.faces.context.FacesContext, java.lang.String), passing myId, and return the result.

Parameters:
context - The FacesContext for the current request
Throws:
NullPointerException - if context is null

getContainerClientId

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(javax.faces.context.FacesContext) for usage.

By default, this method will call through to getClientId(javax.faces.context.FacesContext) and return the result.

Throws:
NullPointerException - if context is null
Since:
1.2

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.


setId

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):

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

getParent

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


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

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.


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

getRendererType

public abstract String getRendererType()

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


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

getRendersChildren

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


getChildren

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


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.


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.

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 NamingContainer.SEPARATOR_CHAR character value. The search algorithm should operates as follows, though alternate alogrithms may be used as long as the end result is the same:

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
NullPointerException - if expr is null

invokeOnComponent

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 NamingContainer.SEPARATOR_CHAR 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(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. 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 invokeOnComponent(FacesContext context,
                                       UIComponent component) {
           found = component;
         }
      });
}
 

Parameters:
context - the FacesContext for the current request
clientId - the client identifier of the component to be passed to the argument callback.
callback - an implementation of the Callback interface.
Returns:
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.
Throws:
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.
Since:
1.2

getFacets

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


getFacetCount

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

Since:
1.2

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

getFacetsAndChildren

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


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
IllegalArgumentException - if the implementation class of this FacesEvent is not supported by this component
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 Renderer.encodeBegin(FacesContext, UIComponent).

Parameters:
context - FacesContext for the response we are creating
Throws:
IOException - if an input/output error occurs while rendering
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 Renderer.encodeBegin(FacesContext, UIComponent).

Parameters:
context - FacesContext for the response we are creating
Throws:
IOException - if an input/output error occurs while rendering
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 Renderer.encodeBegin(FacesContext, UIComponent).

Parameters:
context - FacesContext for the response we are creating
Throws:
IOException - if an input/output error occurs while rendering
NullPointerException - if context is null

encodeAll

public void encodeAll(FacesContext context)
               throws IOException

If this component returns true from isRendered(), render this component and all its children that return true from isRendered(), regardless of the value of the getRendersChildren() flag.

Throws:
IOException - if an input/output error occurs while rendering
NullPointerException - if context is null
Since:
1.2

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

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
NullPointerException - if clazz 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

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
NullPointerException - if event 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.

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

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.

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.

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.

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.

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

getFacesContext

protected abstract FacesContext getFacesContext()

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


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

Java EE 5 SDK

Submit a bug or feature

Copyright 2006 Sun Microsystems, Inc. All rights reserved.