javax.faces.component
Class UIComponentBase

java.lang.Object
  extended by javax.faces.component.UIComponent
      extended by javax.faces.component.UIComponentBase
All Implemented Interfaces:
StateHolder
Direct Known Subclasses:
UIColumn, UICommand, UIData, UIForm, UIGraphic, UIMessage, UIMessages, UINamingContainer, UIOutput, UIPanel, UIParameter, UISelectItem, UISelectItems, UIViewRoot

public abstract class UIComponentBase
extends UIComponent

Standard implementation of the UIComponent base class; all standard JSF components extend this class.

Disclaimer: The official definition for the behaviour of this class is the JSF 1.1 specification but for legal reasons the specification cannot be replicated here. Any javadoc here therefore describes the current implementation rather than the spec, though this class has been verified as correctly implementing the spec.

See Javadoc of JSF Specification for more.

Version:
$Revision: 949070 $ $Date: 2010-05-27 21:22:03 -0500 (Thu, 27 May 2010) $
Author:
Manfred Geiler (latest modification by $Author: lu4242 $)

Constructor Summary
UIComponentBase()
           
 
Method Summary
protected  void addFacesListener(FacesListener listener)
           
 void broadcast(FacesEvent event)
          Invoke any listeners attached to this object which are listening for an event whose type matches the specified event's runtime type.
 void decode(FacesContext context)
          Check the submitted form parameters for data associated with this component.
 void encodeBegin(FacesContext context)
           
 void encodeChildren(FacesContext context)
           
 void encodeEnd(FacesContext context)
           
 UIComponent findComponent(String expr)
          Standard method for finding other components by id, inherited by most UIComponent objects.
 Map getAttributes()
          Get a map through which all the UIComponent's properties, value-bindings and non-property attributes can be read and written.
 int getChildCount()
          Return the number of direct child components this component has.
 List getChildren()
          Return a list of the UIComponent objects which are direct children of this component.
 String getClientId(FacesContext context)
          Get a string which can be output to the response which uniquely identifies this UIComponent within the current view.
protected  FacesContext getFacesContext()
           
protected  FacesListener[] getFacesListeners(Class clazz)
           
 UIComponent getFacet(String name)
           
 Map getFacets()
           
 Iterator getFacetsAndChildren()
           
 String getId()
          An identifier for this particular component instance within a component view.
 UIComponent getParent()
           
protected  Renderer getRenderer(FacesContext context)
           
 String getRendererType()
           
 boolean getRendersChildren()
          Indicates whether this component or its renderer manages the invocation of the rendering methods of its child components.
 ValueBinding getValueBinding(String name)
          Get the named value-binding associated with this component.
 boolean isRendered()
          A boolean value that indicates whether this component should be rendered.
 boolean isTransient()
           
 void processDecodes(FacesContext context)
           
 void processRestoreState(FacesContext context, Object state)
           
 Object processSaveState(FacesContext context)
           
 void processUpdates(FacesContext context)
          This isn't an input component, so just pass on the processUpdates call to child components and facets that might be input components.
 void processValidators(FacesContext context)
           
 void queueEvent(FacesEvent event)
           
protected  void removeFacesListener(FacesListener listener)
           
static Object restoreAttachedState(FacesContext context, Object stateObj)
           
 void restoreState(FacesContext context, Object state)
          Invoked in the "restore view" phase, this initialises this object's members from the values saved previously into the provided state object.
static Object saveAttachedState(FacesContext context, Object attachedObject)
          Serializes objects which are "attached" to this component but which are not UIComponent children of it.
 Object saveState(FacesContext context)
          Invoked after the render phase has completed, this method returns an object which can be passed to the restoreState of some other instance of UIComponentBase to reset that object's state to the same values as this object currently has.
 void setId(String id)
          Set an identifier for this component which is unique within the scope of the nearest ancestor NamingContainer component.
 void setParent(UIComponent parent)
          For JSF-framework internal use only.
 void setRendered(boolean rendered)
           
 void setRendererType(String rendererType)
           
 void setTransient(boolean transientFlag)
           
 void setValueBinding(String name, ValueBinding binding)
          Put the provided value-binding into a map of value-bindings associated with this component.
 
Methods inherited from class javax.faces.component.UIComponent
getFamily
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

UIComponentBase

public UIComponentBase()
Method Detail

getAttributes

public Map getAttributes()
Get a map through which all the UIComponent's properties, value-bindings and non-property attributes can be read and written.

When writing to the returned map:

Note that value-bindings are not written by put calls to this map. Writing to the attributes map using a key for which a value-binding exists will just store the value in the attributes map rather than evaluating the binding, effectively "hiding" the value-binding from later attributes.get calls. Setter methods on components commonly do not evaluate a binding of the same name; they just store the provided value directly on the component.

When reading from the returned map:

Note that components commonly define getter methods such that they evaluate a value-binding of the same name if there isn't yet a local property.

Assigning values to the map which are not explicit properties on the underlying component can be used to "tunnel" attributes from the JSP tag (or view-specific equivalent) to the associated renderer without modifying the component itself.

Any value-bindings and non-property attributes stored in this map are automatically serialized along with the component when the view is serialized.

Specified by:
getAttributes in class UIComponent

getValueBinding

public ValueBinding getValueBinding(String name)
Get the named value-binding associated with this component.

Value-bindings are stored in a map associated with the component, though there is commonly a property (setter/getter methods) of the same name defined on the component itself which evaluates the value-binding when called.

Specified by:
getValueBinding in class UIComponent

setValueBinding

public void setValueBinding(String name,
                            ValueBinding binding)
Put the provided value-binding into a map of value-bindings associated with this component.

Specified by:
setValueBinding in class UIComponent

getClientId

public String getClientId(FacesContext context)
Get a string which can be output to the response which uniquely identifies this UIComponent within the current view.

The component should have an id attribute already assigned to it; however if the id property is currently null then a unique id is generated and set for this component. This only happens when components are programmatically created without ids, as components created by a ViewHandler should be assigned ids when they are created.

If this component is a descendant of a NamingContainer then the client id is of form "{namingContainerId}:{componentId}". Note that the naming container's id may itself be of compound form if it has an ancestor naming container. Note also that this only applies to naming containers; other UIComponent types in the component's ancestry do not affect the clientId.

Finally the renderer associated with this component is asked to convert the id into a suitable form. This allows escaping of any characters in the clientId which are significant for the markup language generated by that renderer.

Specified by:
getClientId in class UIComponent

getId

public String getId()
An identifier for this particular component instance within a component view.

The id must be unique within the scope of the tag's enclosing NamingContainer (eg h:form or f:subview). The id is not necessarily unique across all components in the current view

This value must be a static value, ie not change over the lifetime of a component. It cannot be defined via an EL expression; only a string is permitted.

Specified by:
getId in class UIComponent

setId

public void setId(String id)
Set an identifier for this component which is unique within the scope of the nearest ancestor NamingContainer component. The id is not necessarily unique across all components in the current view.

The id must start with an underscore if it is generated by the JSF framework, and must not start with an underscore if it has been specified by the user (eg in a JSP tag).

The first character of the id must be an underscore or letter. Following characters may be letters, digits, underscores or dashes.

Null is allowed as a parameter, and will reset the id to null.

The clientId of this component is reset by this method; see getClientId for more info.

Specified by:
setId in class UIComponent
Throws:
IllegalArgumentException - if the id is not valid.

getParent

public UIComponent getParent()
Specified by:
getParent in class UIComponent

setParent

public void setParent(UIComponent parent)
Description copied from class: UIComponent
For JSF-framework internal use only. Don't call this method to add components to the component tree. Use parent.getChildren().add(child) instead.

Specified by:
setParent in class UIComponent

getRendersChildren

public boolean getRendersChildren()
Indicates whether this component or its renderer manages the invocation of the rendering methods of its child components. When this is true:

Specified by:
getRendersChildren in class UIComponent

getChildren

public List getChildren()
Return a list of the UIComponent objects which are direct children of this component.

The list object returned has some non-standard behaviour:

Specified by:
getChildren in class UIComponent

getChildCount

public int getChildCount()
Return the number of direct child components this component has.

Identical to getChildren().size() except that when this component has no children this method will not force an empty list to be created.

Specified by:
getChildCount in class UIComponent

findComponent

public UIComponent findComponent(String expr)
Standard method for finding other components by id, inherited by most UIComponent objects.

The lookup is performed in a manner similar to finding a file in a filesystem; there is a "base" at which to start, and the id can be for something in the "local directory", or can include a relative path. Here, NamingContainer components fill the role of directories, and ":" is the "path separator". Note, however, that although components have a strict parent/child hierarchy, component ids are only prefixed ("namespaced") with the id of their parent when the parent is a NamingContainer.

The base node at which the search starts is determined as follows:

Specified by:
findComponent in class UIComponent
Parameters:
expr - is of form "id1:id2:id3".
Returns:
UIComponent or null if no component with the specified id is found.

getFacets

public Map getFacets()
Specified by:
getFacets in class UIComponent

getFacet

public UIComponent getFacet(String name)
Specified by:
getFacet in class UIComponent

getFacetsAndChildren

public Iterator getFacetsAndChildren()
Specified by:
getFacetsAndChildren in class UIComponent

broadcast

public void broadcast(FacesEvent event)
               throws AbortProcessingException
Invoke any listeners attached to this object which are listening for an event whose type matches the specified event's runtime type.

This method does not propagate the event up to parent components, ie listeners attached to parent components don't automatically get called.

If any of the listeners throws AbortProcessingException then that exception will prevent any further listener callbacks from occurring, and the exception propagates out of this method without alteration.

ActionEvent events are typically queued by the renderer associated with this component in its decode method; ValueChangeEvent events by the component's validate method. In either case the event's source property references a component. At some later time the UIViewRoot component iterates over its queued events and invokes the broadcast method on each event's source object.

Specified by:
broadcast in class UIComponent
Parameters:
event - must not be null.
Throws:
AbortProcessingException

decode

public void decode(FacesContext context)
Check the submitted form parameters for data associated with this component. This default implementation delegates to this component's renderer if there is one, and otherwise ignores the call.

Specified by:
decode in class UIComponent

encodeBegin

public void encodeBegin(FacesContext context)
                 throws IOException
Specified by:
encodeBegin in class UIComponent
Throws:
IOException

encodeChildren

public void encodeChildren(FacesContext context)
                    throws IOException
Specified by:
encodeChildren in class UIComponent
Throws:
IOException

encodeEnd

public void encodeEnd(FacesContext context)
               throws IOException
Specified by:
encodeEnd in class UIComponent
Throws:
IOException

addFacesListener

protected void addFacesListener(FacesListener listener)
Specified by:
addFacesListener in class UIComponent

getFacesListeners

protected FacesListener[] getFacesListeners(Class clazz)
Specified by:
getFacesListeners in class UIComponent

removeFacesListener

protected void removeFacesListener(FacesListener listener)
Specified by:
removeFacesListener in class UIComponent

queueEvent

public void queueEvent(FacesEvent event)
Specified by:
queueEvent in class UIComponent

processDecodes

public void processDecodes(FacesContext context)
Specified by:
processDecodes in class UIComponent

processValidators

public void processValidators(FacesContext context)
Specified by:
processValidators in class UIComponent

processUpdates

public void processUpdates(FacesContext context)
This isn't an input component, so just pass on the processUpdates call to child components and facets that might be input components.

Components that were never rendered can't possibly be receiving update data (no corresponding fields were ever put into the response) so if this component is not rendered then this method does not invoke processUpdates on its children.

Specified by:
processUpdates in class UIComponent

processSaveState

public Object processSaveState(FacesContext context)
Specified by:
processSaveState in class UIComponent

processRestoreState

public void processRestoreState(FacesContext context,
                                Object state)
Specified by:
processRestoreState in class UIComponent

getFacesContext

protected FacesContext getFacesContext()
Specified by:
getFacesContext in class UIComponent

getRenderer

protected Renderer getRenderer(FacesContext context)
Specified by:
getRenderer in class UIComponent

isTransient

public boolean isTransient()

setTransient

public void setTransient(boolean transientFlag)

saveAttachedState

public static Object saveAttachedState(FacesContext context,
                                       Object attachedObject)
Serializes objects which are "attached" to this component but which are not UIComponent children of it. Examples are validator and listener objects. To be precise, it returns an object which implements java.io.Serializable, and which when serialized will persist the state of the provided object.

If the attachedObject is a List then every object in the list is saved via a call to this method, and the returned wrapper object contains a List object.

If the object implements StateHolder then the object's saveState is called immediately, and a wrapper is returned which contains both this saved state and the original class name. However in the case where the StateHolder.isTransient method returns true, null is returned instead.

If the object implements java.io.Serializable then the object is simply returned immediately; standard java serialization will later be used to store this object.

In all other cases, a wrapper is returned which simply stores the type of the provided object. When deserialized, a default instance of that type will be recreated.


restoreAttachedState

public static Object restoreAttachedState(FacesContext context,
                                          Object stateObj)
                                   throws IllegalStateException
Throws:
IllegalStateException

saveState

public Object saveState(FacesContext context)
Invoked after the render phase has completed, this method returns an object which can be passed to the restoreState of some other instance of UIComponentBase to reset that object's state to the same values as this object currently has.


restoreState

public void restoreState(FacesContext context,
                         Object state)
Invoked in the "restore view" phase, this initialises this object's members from the values saved previously into the provided state object.

Parameters:
state - is an object previously returned by the saveState method of this class.

setRendered

public void setRendered(boolean rendered)
Specified by:
setRendered in class UIComponent

isRendered

public boolean isRendered()
A boolean value that indicates whether this component should be rendered. Default value: true.

Specified by:
isRendered in class UIComponent

setRendererType

public void setRendererType(String rendererType)
Specified by:
setRendererType in class UIComponent

getRendererType

public String getRendererType()
Specified by:
getRendererType in class UIComponent


Copyright © 2012 The Apache Software Foundation. All Rights Reserved.