javax.faces.component
Interface UIComponent

All Superinterfaces:

java.io.Serializable

All Known Implementing Classes:

UIComponentBase

public interface UIComponent

extends java.io.Serializable

UIComponent is the base interface for all user interface components in JavaServer Faces. The set of UIComponent instances associated with a particular request and response are organized into a tree under a root UIComponent 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 standard UIComponent implementations. Component writers are encouraged to subclass UIComponentBase, instead of directly implementing this interface, to reduce the impact of any future changes to the method signatures of this interface.

Field Summary

static char

SEPARATOR_CHAR The separator character used in component identifiers to demarcate navigation to a child naming container.

Method Summary

void	addChild(int index, UIComponent component) Insert the specified UIComponent at the specified position in the child list for this component.
void	addChild(UIComponent component) Append the specified UIComponent to the end of the child list for this component.
void	addFacet(java.lang.String facetName, UIComponent facet) Add the specified UIComponent as a facet associated with the name specified by the facetName argument, replacing any previous facet with that name.
void	addValidator(Validator validator) Add a Validator instance to the set associated with this UIComponent.
boolean	broadcast(FacesEvent event, PhaseId phaseId) Broadcast the specified FacesEvent to all registered event listeners who have expressed an interest in events of this type, for the specified PhaseId (or for any phase, if the listener returns PhaseId.ANY_PHASE from its getPhaseId() method.
void	clearChildren() Remove all child UIComponents from the child list.
void	clearFacets() Remove all facet UIComponents from this component.
void	clearValidators() Clear any Validators that have been registered for processing by this component.
boolean	containsChild(UIComponent component) Return true if the specified UIComponent is a direct child of this UIComponent; otherwise, return false.
void	decode(FacesContext context) Decode the current state of this UIComponent from the request contained in the specified FacesContext, and attempt to convert this state information into an object of the required type for this component (optionally using the registered Converter for this component, if there is one.
void	encodeBegin(FacesContext context) Render the beginning of the current state of this UIComponent to the response contained in the specified FacesContext.
void	encodeChildren(FacesContext context) Render the child UIComponents of this UIComponent, following the rules described for encodeBegin() to acquire the appropriate value to be rendered.
void	encodeEnd(FacesContext context) Render the ending of the current state of this UIComponent, following the rules described for encodeBegin() to acquire the appropriate value to be rendered.
UIComponent	findComponent(java.lang.String expr) Find the UIComponent named by the specified expression, if any is found.
java.lang.Object	getAttribute(java.lang.String name) Return the value of the attribute with the specified name (if any); otherwise, return null.
java.util.Iterator	getAttributeNames() Return an Iterator over the names of all currently defined attributes of this UIComponent that have a non-null value.
UIComponent	getChild(int index) Return the UIComponent at the specified position in the child list for this component.
int	getChildCount() Return the number of UIComponents on the child list for this component.
java.util.Iterator	getChildren() Return an Iterator over the child UIComponents of this UIComponent, in the order of their position in the child list.
java.lang.String	getClientId(FacesContext context) Return a client-side identifier for this component, generating one if necessary.
java.lang.String	getComponentId() Return the identifier of this UIComponent.
java.lang.String	getConverter() Return the converter id of the Converter that is registered for this component.
UIComponent	getFacet(java.lang.String name) Return the facet UIComponent associated with the specified name, if any.
java.util.Iterator	getFacetNames() Return an Iterator over the names of the facet UIComponents of this UIComponent.
java.util.Iterator	getFacetsAndChildren() Return an Iterator over the facet followed by child UIComponents of this UIComponent.
UIComponent	getParent() Return the parent UIComponent of this UIComponent, if any.
java.lang.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.
boolean	getRendersSelf() Return a flag indicating whether this component has concrete implementations of the decode() and encodeXxx() methods, and is therefore suitable for use in the direct implementation programming model for rendering.
java.util.Iterator	getValidators() Return an Iterator over the Validators associated with this UIComponent.
boolean	isRendered() Return true if this component (and its children) should be rendered during the Render Response phase of the request processing lifecycle.
boolean	isValid() Return the current validity state of this component.
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	processReconstitutes(FacesContext context) Perform the component tree processing required by the Reconstitute Component Tree 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 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.
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	reconstitute(FacesContext context) Perform any processing required to correct the state of this component as a result of the owning component tree having been reconstructed during Reconstitute Component Tree phase of the request processing lifecycle.
void	removeChild(int index) Remove the child UIComponent at the specified position in the child list for this component.
void	removeChild(UIComponent component) Remove the child UIComponent from the child list for this component.
void	removeFacet(java.lang.String name) Remove the facet UIComponent associated with the specified name, if there is one.
void	removeValidator(Validator validator) Remove a Validator instance from the set associated with this UIComponent, if it was previously associated.
void	setAttribute(java.lang.String name, java.lang.Object value) Set the new value of the attribute with the specified name, replacing any existing value for that name.
void	setComponentId(java.lang.String componentId) Set the identifier of this UIComponent.
void	setConverter(java.lang.String converter) Set the converter id of the Converter that is registered for this component, or null to indicate that there is no registered Converter.
void	setParent(UIComponent parent) Set the parent UIComponent of this UIComponent.
void	setRendered(boolean rendered) Set the rendered property of this UIComponent.
void	setRendererType(java.lang.String rendererType) Set the Renderer type for this UIComponent, or null for components that render themselves.
void	setValid(boolean valid) Set the current validity state of this component.
void	updateModel(FacesContext context) Update the model data associated with this UIComponent, if any.
void	validate(FacesContext context) Perform any correctness checks that this component wishes to perform on itself.

Field Detail

SEPARATOR_CHAR

public static final char SEPARATOR_CHAR

The separator character used in component identifiers to demarcate navigation to a child naming container.

See Also:

Constant Field Values

Method Detail

getAttribute

public java.lang.Object getAttribute(java.lang.String name)

Return the value of the attribute with the specified name (if any); otherwise, return null.

Parameters:

name - Name of the requested attribute

Throws:

java.lang.NullPointerException - if name is null

getAttributeNames

public java.util.Iterator getAttributeNames()

Return an Iterator over the names of all currently defined attributes of this UIComponent that have a non-null value.

setAttribute

public void setAttribute(java.lang.String name,
                         java.lang.Object value)

Set the new value of the attribute with the specified name, replacing any existing value for that name.

Parameters:

name - Name of the requested attribute

value - New value (or null to remove any attribute value for the specified name

Throws:

java.lang.IllegalArgumentException - if name represents a read-only property of this component

java.lang.NullPointerException - if name is null

getClientId

public java.lang.String getClientId(FacesContext context)

Return a client-side identifier for this component, generating one if necessary. Generation will be delegated to the associated Renderer (if there is one).

Parameters:

context - The FacesContext for the current request

Throws:

java.lang.NullPointerException - if context is null

getComponentId

public java.lang.String getComponentId()

Return the identifier of this UIComponent.

setComponentId

public void setComponentId(java.lang.String componentId)

Set the identifier of this UIComponent.

Parameters:

componentId - The new identifier

Throws:

java.lang.IllegalArgumentException - if componentId is zero length or contains invalid characters

java.lang.NullPointerException - if componentId is null

java.lang.IllegalArgumentException - if this UIComponent instance is already in the tree and and is not unique within the namespace of the closest ancestor that is a naming container.

getConverter

public java.lang.String getConverter()

Return the converter id of the Converter that is registered for this component.

setConverter

public void setConverter(java.lang.String converter)

Set the converter id of the Converter that is registered for this component, or null to indicate that there is no registered Converter.

Parameters:

converter - New converter identifier (or null)

getParent

public UIComponent getParent()

Return the parent UIComponent of this UIComponent, if any.

setParent

public void setParent(UIComponent parent)

Set the parent UIComponent of this UIComponent.

Parameters:

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

isRendered

public 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 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 java.lang.String getRendererType()

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

setRendererType

public void setRendererType(java.lang.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 boolean getRendersChildren()

Return a flag indicating whether this component is responsible for rendering its child components.

getRendersSelf

public boolean getRendersSelf()

Return a flag indicating whether this component has concrete implementations of the decode() and encodeXxx() methods, and is therefore suitable for use in the direct implementation programming model for rendering.

isValid

public boolean isValid()

Return the current validity state of this component. The validity state of a component is adjusted at the following points during the request processing lifecycle:

• During the Apply Request Values phase, set to true or false by decode(), based on the success or failure of decoding a new local value for this component.
• During the Process Validations phase, set to false by processValidations() if any call to a validate() method returned false.
• During the Update Model Values phase, set to false by updateModel() if any conversion or update error occurred.

setValid

public void setValid(boolean valid)

Set the current validity state of this component.

Parameters:

valid - The new validity state

addChild

public void addChild(UIComponent component)

Append the specified UIComponent to the end of the child list for this component.

If the child to be added has a non-null and valid component identifier, the identifier is added to the namespace of the closest ancestor that is a naming container.

It is valid for a component to have a null component identifier or a component identifier that is the empty string.

Parameters:

component - UIComponent to be added

Throws:

java.lang.IllegalStateException - if the component identifier of the new component is non-null, and is not unique in the namespace of the closest ancestor that is a naming container.

java.lang.IllegalArgumentException - if the component is null.

java.lang.NullPointerException - if component is null

addChild

public void addChild(int index,
                     UIComponent component)

Insert the specified UIComponent at the specified position in the child list for this component.

If the child to be added has a non-null and valid component identifier, the identifier is added to the namespace of the closest ancestor that is a naming container.

It is valid for a component to have a null component identifier or a component identifier that is the empty string.

Parameters:

index - Zero-relative index at which to add this UIComponent

component - The UIComponent to be added

Throws:

java.lang.IllegalStateException - if the component identifier of the new component is non-null, and is not unique in the namespace of the closest ancestor that is a naming container.

java.lang.IllegalArgumentException - if the component is null.

java.lang.IndexOutOfBoundsException - if the index is out of range ((index < 0) || (index > size()))

java.lang.NullPointerException - if component is null

clearChildren

public void clearChildren()

Remove all child UIComponents from the child list.

containsChild

public boolean containsChild(UIComponent component)

Return true if the specified UIComponent is a direct child of this UIComponent; otherwise, return false.

Parameters:

component - UIComponent to be checked

Throws:

java.lang.NullPointerException - if component is null

findComponent

public UIComponent findComponent(java.lang.String expr)

Find the UIComponent named by the specified expression, if any is found. This is done by locating the closest parent UIComponent that is a NamingContainer, and calling its findComponentInNamespace() method.

The specified expr may contain either a component identifier, or a set of component identifiers separated by SEPARATOR_CHAR characters.

Parameters:

expr - Expression identifying the UIComponent to be returned

Returns:

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

Throws:

java.lang.NullPointerException - if expr is null

getChild

public UIComponent getChild(int index)

Return the UIComponent at the specified position in the child list for this component.

Parameters:

index - Position of the desired component

Throws:

java.lang.IndexOutOfBoundsException - if index is out of range ((index < 0) || (index >= size()))

getChildCount

public int getChildCount()

Return the number of UIComponents on the child list for this component.

getChildren

public java.util.Iterator getChildren()

Return an Iterator over the child UIComponents of this UIComponent, in the order of their position in the child list. If this component has no children, an empty Iterator is returned.

removeChild

public void removeChild(int index)

Remove the child UIComponent at the specified position in the child list for this component.

Parameters:

index - Position of the component to be removed

Throws:

java.lang.IndexOutOfBoundsException - if the index is out of range ((index < 0) || (index >= size()))

removeChild

public void removeChild(UIComponent component)

Remove the child UIComponent from the child list for this component.

Parameters:

component - Child component to be removed

Throws:

java.lang.IllegalArgumentException - if component is not a child of this component

java.lang.NullPointerException - if component is null

addFacet

public void addFacet(java.lang.String facetName,
                     UIComponent facet)

Add the specified UIComponent as a facet associated with the name specified by the facetName argument, replacing any previous facet with that name. The newly added facet will have its parent property set to this component.

Parameters:

facetName - The name of this facet

facet - The new facet UIComponent

Throws:

java.lang.NullPointerException - if the either of the facetName or facet arguments are null.

clearFacets

public void clearFacets()

Remove all facet UIComponents from this component.

getFacet

public UIComponent getFacet(java.lang.String name)

Return the facet UIComponent associated with the specified name, if any. Otherwise, return null.

Parameters:

name - Name of the facet to be retrieved

Throws:

java.lang.NullPointerException - if name is null

getFacetNames

public java.util.Iterator getFacetNames()

Return an Iterator over the names of the facet UIComponents of this UIComponent. If this component has no facets, an empty Iterator is returned.

removeFacet

public void removeFacet(java.lang.String name)

Remove the facet UIComponent associated with the specified name, if there is one. The removed facet will have its parent property cleared.

Parameters:

name - Name of the facet to be removed

Throws:

java.lang.NullPointerException - if name is null

getFacetsAndChildren

public java.util.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.

addValidator

public void addValidator(Validator validator)

Add a Validator instance to the set associated with this UIComponent.

Parameters:

validator - The Validator to add

Throws:

java.lang.NullPointerException - if validator is null

clearValidators

public void clearValidators()

Clear any Validators that have been registered for processing by this component.

getValidators

public java.util.Iterator getValidators()

Return an Iterator over the Validators associated with this UIComponent.

removeValidator

public void removeValidator(Validator validator)

Remove a Validator instance from the set associated with this UIComponent, if it was previously associated. Otherwise, do nothing.

Parameters:

validator - The Validator to remove

broadcast

public boolean broadcast(FacesEvent event,
                         PhaseId phaseId)
                  throws AbortProcessingException

Broadcast the specified FacesEvent to all registered event listeners who have expressed an interest in events of this type, for the specified PhaseId (or for any phase, if the listener returns PhaseId.ANY_PHASE from its getPhaseId() method. The order in which registered listeners are notified is implementation dependent.

After all interested listeners have been notified, return false if this event does not have any listeners interested in this event in future phases of the request processing lifecycle. Otherwise, return true.

Parameters:

event - The FacesEvent to be broadcast

phaseId - The PhaseId of the current phase of the request processing lifecycle

Throws:

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.IllegalStateException - if PhaseId.ANY_PHASE is passed for the phase identifier

java.lang.NullPointerException - if event or phaseId is null

decode

public void decode(FacesContext context)
            throws java.io.IOException

Decode the current state of this UIComponent from the request contained in the specified FacesContext, and attempt to convert this state information into an object of the required type for this component (optionally using the registered Converter for this component, if there is one.

If conversion is successful:

• Save the new local value of this component by calling setValue() and passing the new value.
• Set the valid property of this component to true.

If conversion is not successful:

• Save state information in such a way that encoding can reproduce the previous input (even though it was syntactically or semantically incorrect)
• Add an appropriate conversion failure error message by calling context.addMessage().
• Set the valid property of this comonent to false.

During decoding, events may be enqueued for later processing (by event listeners who have registered an interest), by calling addFacesEvent() on the associated FacesContext.

Parameters:

context - FacesContext for the request we are processing

Throws:

java.io.IOException - if an input/output error occurs during decoding

java.lang.NullPointerException - if context is null

encodeBegin

public void encodeBegin(FacesContext context)
                 throws java.io.IOException

Render the beginning of the current state of this UIComponent to the response contained in the specified FacesContext. If the conversion attempted in a previous call to decode() for this component failed, the state information saved during execution of decode() should be utilized to reproduce the incorrect input. If the conversion was successful, or if there was no previous call to decode(), the value to be displayed should be acquired by calling currentValue(), and rendering the value as appropriate.

Parameters:

context - FacesContext for the response we are creating

Throws:

java.io.IOException - if an input/output error occurs while rendering

java.lang.NullPointerException - if context is null

encodeChildren

public void encodeChildren(FacesContext context)
                    throws java.io.IOException

Render the child UIComponents of this UIComponent, following the rules described for encodeBegin() to acquire the appropriate value to be rendered. This method will only be called if the rendersChildren property is true.

Parameters:

context - FacesContext for the response we are creating

Throws:

java.io.IOException - if an input/output error occurs while rendering

java.lang.NullPointerException - if context is null

encodeEnd

public void encodeEnd(FacesContext context)
               throws java.io.IOException

Render the ending of the current state of this UIComponent, following the rules described for encodeBegin() to acquire the appropriate value to be rendered.

Parameters:

context - FacesContext for the response we are creating

Throws:

java.io.IOException - if an input/output error occurs while rendering

java.lang.NullPointerException - if context is null

reconstitute

public void reconstitute(FacesContext context)
                  throws java.io.IOException

Perform any processing required to correct the state of this component as a result of the owning component tree having been reconstructed during Reconstitute Component Tree phase of the request processing lifecycle. The default implementation of this method does nothing.

Parameters:

context - FacesContext for the request we are processing

Throws:

java.io.IOException - if an input/output error occurs during processing

java.lang.NullPointerException - if context is null

updateModel

public void updateModel(FacesContext context)

Update the model data associated with this UIComponent, if any. The default implementation in UIComponentBase does no processing; concrete implementations of components that represent controls that can be altered by users (such as UIInput must provide an apppropriate implementation of this method.

Parameters:

context - FacesContext for the request we are processing

Throws:

java.lang.NullPointerException - if context is null

validate

public void validate(FacesContext context)

Perform any correctness checks that this component wishes to perform on itself. This method will be called during the Process Validations phase of the request processing lifecycle. If errors are encountered, appropriate Message instances should be added to the FacesContext for the current request, and the valid property of this UIComponent should be set to false.

Parameters:

context - FacesContext for the request we are processing

Throws:

java.lang.NullPointerException - if context is null

processReconstitutes

public void processReconstitutes(FacesContext context)
                          throws java.io.IOException

Perform the component tree processing required by the Reconstitute Component Tree 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 processReconstitutes() method of all facets and children of this UIComponent in the order determined by a call to getFacetsAndChildren().
• Call the reconstitute() method of this component.

Parameters:

context - FacesContext for the request we are processing

Throws:

java.io.IOException - if an input/output error occurs during processing

java.lang.NullPointerException - if context is null

processDecodes

public void processDecodes(FacesContext context)
                    throws java.io.IOException

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.

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

Parameters:

context - FacesContext for the request we are processing

Throws:

java.io.IOException - if an input/output error occurs during decoding

java.lang.NullPointerException - if context is null

processValidators

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

• Call the processValidators() method of all facets and children of this UIComponent, in the order determined by a call to getFacetsAndChildren().
• If the valid property of this component is currently true:
  • Call the validate() method of each Validator registered for this UIComponent.
  • Call the validate() method of this component.
  • Set the valid property of this component to the result returned from the validate() method.
• If the valid property of this UIComponent is now false, call FacesContext.renderResponse() to transfer control at the end of the current phase.

Parameters:

context - FacesContext for the request we are processing

Throws:

java.lang.NullPointerException - if context is null

processUpdates

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

• Call the processUpdates() method of all facets and children of this UIComponent, in the order determined by a call to getFacetsAndChildren().
• Call the updateModel() method of this component.
• If the valid property of this UIComponent is now false, call FacesContext.renderResponse() to transfer control at the end of the current phase.

Parameters:

context - FacesContext for the request we are processing

Throws:

java.lang.NullPointerException - if context is null