StandardUserInterfaceComponents.adoc

Standard User Interface Components

In addition to the abstract base class UIComponent and the abstract base class UIComponentBase, described in the previous chapter, Jakarta Faces provides a number of concrete user interface component implementation classes that cover the most common requirements. In addition, component writers will typically create new components by subclassing one of the standard component classes (or the UIComponentBase class). It is anticipated that the number of standard component classes will grow in future versions of the Jakarta Faces specification.

Each of these classes defines the render-independent characteristics of the corresponding component as JavaBeans component properties. Some of these properties may be value expressions that indirectly point to values related to the current request, or to the properties of model data objects that are accessible through request-scope, session-scope, or application-scope attributes. In addition, the rendererType property of each concrete implementation class is set to a defined value, indicating that decoding and encoding for this component will (by default) be delegated to the corresponding Renderer.

Standard User Interface Components

This section documents the features and functionality of the standard UIComponent classes and implementations that are included in Jakarta Faces.

The implementation for each standard UIComponent class must specify two public static final String constant values:

• COMPONENT_TYPE —The standard component type identifier under which the corresponding component class is registered with the Application object for this application. This value may be used as a parameter to the createComponent() method.

• COMPONENT_FAMILY —The standard component family identifier used to select an appropriate Renderer for this component.

For all render-independent properties in the following sections (except for id, scope, and var) the value may either be a literal, or it may come from a value expression. Please see Value Expressions for more information.

The following UML class diagram shows the classes and interfaces in the package jakarta.faces.component.

The jakarta.faces.component package

UIColumn

UIColumn (extends UIComponentBase) is a component that represents a single column of data with a parent UIData component. The child components of a UIColumn will be processed once for each row in the data managed by the parent UIData.

Component Type

The standard component type for UIColumn components is “jakarta.faces.Column”.

Properties

UIColumn adds the following render-independent properties:

Name	Access	Type	Description
footer	RW	UIComponent	Convenience methods to get and set the “footer” facet for this component.
header	RW	UIComponent	Convenience methods to get and set the “header” facet for this component.

UIColumn specializes the behavior of render-independent properties inherited from the parent class as follows:

• The default value of the family property must be set to “jakarta.faces.Column”.

• The default value of the rendererType property must be set to null.

Methods

UIColumn adds no new processing methods.

Events

UIColumn adds no new event handling methods.

UICommand

UICommand (extends UIComponentBase; implements ActionSource) is a control which, when activated by the user, triggers an application-specific “command” or “action.” Such a component is typically rendered as a push button, a menu item, or a hyperlink.

Component Type

The standard component type for UICommand components is “jakarta.faces.Command”.

Properties

UICommand adds the following render-independent properties.

Name	Access	Type	Description
value	RW	Object	The value of this component, normally used as a label.

See ActionSource for information about properties introduced by the implemented classes.

UICommand components specialize the behavior of render-independent properties inherited from the parent class as follows:

• The default value of the family property must be set to “jakarta.faces.Command”.

• The default value of the rendererType property must be set to “jakarta.faces.Button”.

Methods

UICommand adds no new processing methods. See ActionSource for information about methods introduced by the implemented classes.

Events

UICommand adds no new event processing methods. See ActionSource for information about event handling introduced by the implemented classes.

UIData

UIData (extends UIComponentBase; implements NamingContainer) is a component that represents a data binding to a collection of data objects represented by a DataModel instance (see DataModel). Only children of type UIColumn should be processed by renderers associated with this component.

Component Type

The standard component type for UIData components is “jakarta.faces.Data”

Properties

UIData adds the following render-independent properties.

Name	Access	Type	Description
dataModel	protected RW	DataModel	The internal value representation of the UIData instance. Subclasses might write to this property if they want to restore the internal model during the Restore View Phase or if they want to explicitly refresh the model for the Render Response phase.
first	RW	int	Zero-relative row number of the first row in the underlying data model to be displayed, or zero to start at the beginning of the data model.
footer	RW	UIComponent	Convenience methods to get and set the “footer” facet for this component.
header	RW	UIComponent	Convenience methods to get and set the “header” facet for this component.
rowCount	RO	int	The number of rows in the underlying DataModel, which can be -1 if the number of rows is unknown.
rowAvailable	RO	boolean	Return true if there is row data available for the currently specified rowIndex ; else return false.
rowData	RO	Object	The data object representing the data for the currently selected rowIndex value.
rowIndex	RW	int	Zero-relative index of the row currently being accessed in the underlying DataModel, or -1 for no current row. See below for further information.
rows	RW	int	The number of rows (starting with the one identified by the first property) to be displayed, or zero to display the entire set of available rows.
value	RW	Object	The DataModel instance representing the data to which this component is bound, or a collection of data for which a DataModel instance is synthesized. See below for more information.
var	RW	String	The request-scope attribute (if any) under which the data object for the current row will be exposed when iterating.

See NamingContainer for information about properties introduced by the implemented classes.

UIData specializes the behavior of render-independent properties inherited from the parent component as follows:

• The default value of the family property must be set to “jakarta.faces.Data”.

• The default value of the rendererType property must be set to “jakarta.faces.Table”.

The current value identified by the value property is normally of type DataModel. However, a DataModel wrapper instance must automatically be provided by the Jakarta Faces implementation if the current value is of one of the following types:

• java.util.List

• Array of java.util.Object

• java.sql.ResultSet (which therefore also supports javax.sql.RowSet)

• java.util.Map (uses the wrapper for java.lang.Iterable by providing access to java.util.Map#entrySet())

• Any other Java object is wrapped by a DataModel instance with a single row.

Convenience implementations of DataModel are provided in the jakarta.faces.model package for each of the above (see Concrete Implementations), and must be used by the UIData component to create the required DataModel wrapper.

Methods

UIData adds no new processing methods. However, the getDataModel() method is now protected, so implementations have access to the underlying data model. See NamingContainer for information about methods introduced by the implemented classes.

UIData specializes the behavior of the getClientId() method inherited from its parent, in order to create a client identifier that includes the current rowIndex value (if it is not -1). Because UIData is a NamingContainer, this makes it possible for rendered client identifiers of child components to be row-specific.

UIData specializes the behavior of the queueEvent() method inherited from its parent, to wrap the specified event (bubbled up from a child component) in a private wrapper containing the current rowIndex value, so that this rowIndex can be reset when the event is later broadcast.

UIData specializes the behavior of the broadcast() method to unwrap the private wrapper (if this event was wrapped), and call setRowIndex() to re-establish the context in which the event was queued, followed by delivery of the event.

UIData specializes the behavior of the processDecodes(), processValidators(), and processUpdates() methods inherited from its parent as follows:

• For each of these methods, the UIData implementation must iterate over each row in the underlying data model, starting with the row identified by the first property, for the number of rows indicated by the rows property, by calling the setRowIndex() method.

• When iteration is complete, set the rowIndex property of this component, and of the underlying DataModel, to zero, and remove any request attribute exposed via the var property.

UIData specializes the behavior of invokeOnComponent() inherited from UIComponentBase to examine the argument clientId and extract the rowIndex, if any, and position the data properly before proceeding to locate the component and invoke the callback. Upon normal or exception return from the callback the data must be repositioned to match how it was before invoking the callback. Please see the javadocs for UIData.invokeOnComponent() for more details.

Events

UIData adds no new event handling methods. See NamingContainer for information about event handling introduced by the implemented classes.

UIForm

UIForm (extends UIComponentBase; implements NamingContainer) is a component that represents an input form to be presented to the user, and whose child components (among other things) represent the input fields to be included when the form is submitted.

The encodeEnd() method of the renderer for UIForm must call ViewHandler.writeState() before writing out the markup for the closing tag of the form.This allows the state for multiple forms to be saved.

Component Type

The standard component type for UIForm components is “jakarta.faces.Form”.

Properties

UIForm adds the following render-independent properties.

Name	Access	Type	Description
prependId	RW	boolean	If true, this UIForm instance does allow its id to be pre-pendend to its descendent’s id during the generation of clientIds for the descendents. The default value of this property is true.

UIForm specializes the behavior of render-independent properties inherited from the parent component as follows:

• The default value of the family property must be set to “jakarta.faces.Form”.

• The default value of the rendererType property must be set to “jakarta.faces.Form”.

Methods.

public boolean isSubmitted();
public void setSubmitted(boolean submitted)

The setSubmitted() method of each UIForm instance in the view must be called during the Apply Request Values phase of the request processing lifecycle, during the processing performed by the UIComponent.decode() method. If this UIForm instance represents the form actually being submitted on this request, the parameter must be set to true; otherwise, it must be set to false. The standard implementation of UIForm delegates the responsibility for calling this method to the Renderer associated with this instance..

The value of a UIForm's submitted property must not be saved as part of its state.

public void processDecodes(FacesContext context);

Override UIComponent.processDecodes() to ensure that the submitted property is set for this component. If the submitted property decodes to false, do not process the children and return immediately.

public void processValidators(FacesContext context);
public void processUpdates(FacesContext context);

Override processValidators() and processUpdates() to ensure that the children of this UIForm instance are only processed if isSubmitted() returns true.

public void saveState(FacesContext context);

The saveState() method of UIForm must call setSubmitted(false) before calling super.saveState() as an extra precaution to ensure the submitted state is not persisted across requests..

protected String getContainerClientId(FacesContext context);

Override the parent method to ensure that children of this UIForm instance in the view have the form’s clientId prepended to their clientIds if and only if the form’s prependId property is true.

Events

UIForm adds no new event handling methods.

UIGraphic

UIGraphic (extends UIComponentBase) is a component that displays a graphical image to the user. The user cannot manipulate this component; it is for display purposes only.

Component Type

The standard component type for UIGraphic components is “jakarta.faces.Graphic”.

Properties

The following render-independent properties are added by the UIGraphic component:

Name	Access	Type	Description
url	RW	String	The URL of the image to be displayed. If this URL begins with a / character, it is assumed to be relative to the context path of the current web application. This property is a typesafe alias for the value property, so that the actual URL to be used can be acquired via a value expression.
value	RW	Object	The value of this component, normally used as a URL.

UIGraphic specializes the behavior of render-independent properties inherited from the parent component as follows:

• The default value of the family property must be set to “jakarta.faces.Graphic”.

• The default value of the rendererType property must be set to “jakarta.faces.Image”.

Methods

UIGraphic adds no new processing methods.

Events

UIGraphic does not originate any standard events.

UIInput

UIInput (extends UIOutput, implements EditableValueHolder) is a component that both displays the current value of the component to the user (as UIOutput components do), and processes request parameters on the subsequent request that need to be decoded.

Component Type

The standard component type for UIInput components is “jakarta.faces.Input”.

Properties

UIInput adds the following renderer independent properties.:

Name	Access	Type	Description
requiredMessage	RW	String	ValueExpression enabled property. If non-null, this property is used as the summary and detail strings of the FacesMessage that is queued on the FacesContext instead of the default message for the required validaiton failure. Note that the message is fully internationalizable via either the f:loadBundle tag or via ResourceBundle access from the EL.
converterMessage	RW	String	ValueExpression enabled property. If non-null, this property is used as the summary and detail strings of the FacesMessage that is queued on the FacesContext instead of the default message for conversion failure. Note that the message is fully internationalizable via either the f:loadBundle tag or via ResourceBundle access from the EL.
validatorMessage	RW	String	ValueExpression enabled property. If non-null, this property is used as the summary and detail strings of the FacesMessage that is queued on the FacesContext instead of the default message for validation failure. Note that the message is fully internationalizable via either the f:loadBundle tag or via ResourceBundle access from the EL.

See EditableValueHolder for information about properties introduced by the implemented interfaces.

UIInput specializes the behavior of render-independent properties inherited from the parent component as follows:

• The default value of the family property must be set to “jakarta.faces.Input”.

• The default value of the rendererType property must be set to “jakarta.faces.Text”.

• The Converter specified by the converter property (if any) must also be used to perform String→Object conversions during decoding.

• If the value property has an associated ValueExpression, the setValue() method of that ValueExpression will be called during the Update Model Values phase of the request processing lifecycle to push the local value of the component back to the corresponding model bean property.

Methods

The following method is used during the Update Model Values phase of the request processing lifecycle, to push the converted (if necessary) and validated (if necessary) local value of this component back to the corresponding model bean property.

public void updateModel(FacesContext context);

The following method is over-ridden from UIComponent:

public void broadcast(FacesEvent event);

In addition to the default UIComponent.broadcast(jakarta.faces.event.FacesEvent) processing, pass the ValueChangeEvent being broadcast to the method referenced by the valueChangeListener property (if any).

public void validate(FacesContext context);

Perform the algorithm described in the javadoc to validate the local value of this UIInput.

public void resetValue();

Perform the algorithm described in the javadoc to reset this UIInput to the state where it has no local value. This method does not touch the value expresson associated with the “value” property.

Events

All events are described in EditableValueHolder.

UIMessage

UIMessage (extends UIComponentBase) encapsulates the rendering of error message(s) related to a specified input component.

Component Type

The standard component type for UIMessage components is “jakarta.faces.Message”.

Properties

The following render-independent properties are added by the UIMessage component:

Name	Access	Type	Description
for	RW	String	Identifier of the component for which to render error messages. If this component is within the same NamingContainer as the target component, this must be the component identifier. Otherwise, it must be an absolute component identifier (starting with “:”). See the UIComponent.findComponent() Javadocs for more information.
showDetail	RW	boolean	Flag indicating whether the “detail” property of messages for the specified component should be rendered. Default value is “true”.
showSummary	RW	boolean	Flag indicating whether the “summary” property of messages for the specified component should be rendered. Default value is “false”.

UIMessage specializes the behavior of render-independent properties inherited from the parent component as follows:

• The default value of the family property must be set to “jakarta.faces.Message”.

• The default value of the rendererType property must be set to “jakarta.faces.Message”.

Methods.

UIMessage adds no new processing methods.

Events

UIMessage adds no new event handling methods.

UIMessages

UIMessage (extends UIComponentBase) encapsulates the rendering of error message(s) not related to a specified input component, or all enqueued messages.

Component Type

The standard component type for UIMessages components is “jakarta.faces.Messages”.

Properties

The following render-independent properties are added by the UIMessages component:

Name	Access	Type	Description
globalOnly	RW	boolean	Flag indicating whether only messages not associated with any specific component should be rendered. If not set, all messages will be rendered. Default value is “false”.
showDetail	RW	boolean	Flag indicating whether the “detail” property of messages for the specified component should be rendered. Default value is “false”.
showSummary	RW	boolean	Flag indicating whether the “summary” property of messages for the specified component should be rendered. Default value is “true”.

UIMessages specializes the behavior of render-independent properties inherited from the parent component as follows:

• The default value of the family property must be set to “jakarta.faces.Messages”.

• The default value of the rendererType property must be set to “jakarta.faces.Messages”.

Methods.

UIMessages adds no new processing methods.

Events

UIMessages adds no new event handling methods.

UIOutcomeTarget

UIOutcomeTarget (UIOutput) is a component that has a value and an outcome, either which may optionally be retrieved from a model tier bean via a value expression (see Value Expressions), and is displayed to the user as a hyperlink, appearing in the form of a link or a button. The user cannot modify the value of the hyperlink, as it’s for display purposes only. The target URL of the hyperlink is derived by passing the outcome to the ConfigurationNavigationHandler to retrieve the matching NavigationCase and then using the ViewHandler to translate the NavigationCase into an action URL. When the client activates the hyperlink, typically by clicking it, the target URL is retrieved using a non-faces request and the response is rendered.

This component introduces a scenario known as "preemptive navigation". The navigation case is resolved during the Render Response phase, before the client activates the link (and may never activate the link). The predetermined navigation is pursued after the client activates the link. In contrast, the UICommand components resolve and execute the navigation at once, after the Invoke Application phase.

The UIOutcomeTarget component allows the developer to leverage the navigation model while at the same time being able to generate bookmarkable, non-faces requests to be included in the response.

Component Type

The standard component type for UIOutcomeTarget is "jakarta.faces.OutcomeTarget".

Properties

The following render-independent properties are added by thec component:

Name	Access	Type	Description
Outcome	RW	String	The logical outcome that is used to resolve a NavigationCase which in turn is used to build the target URL of this component. Default value is the current view ID.
includePageParams	RW	boolean	Flag indicating whether the page parameters should be appended to the query string of the target URL. Default value is "false".

UIOutcomeTarget specializes the behavior of render-independent properties inherited from the parent component as follows:

• The default value of the family property must be set to "jakarta.faces.UIOutcomeTarget"

• The default value of the rendererType property must be set to "jakarta.faces.Link"

Methods

The UIOutcomeTarget adds no event handling methods.

Events

The UIOutcomeTarget adds no event handling methods.

UIOutput

UIOutput (extends UIComponentBase; implements ValueHolder) is a component that has a value, optionally retrieved from a model tier bean via a value expression (see Value Expressions), that is displayed to the user. The user cannot directly modify the rendered value; it is for display purposes only:

Component Type

The standard component type for UIOutput components is “jakarta.faces.Output”.

Properties

UIOutput adds no new render-independent properties. See ValueHolder for information about properties introduced by the implemented classes.

UIOutput specializes the behavior of render-independent properties inherited from the parent component as follows:

• The default value of the family property must be set to “jakarta.faces.Output”.

• The default value of the rendererType property must be set to “jakarta.faces.Text”.

Methods

UIOutput adds no new processing methods. See ValueHolder for information about methods introduced by the implemented interfaces.

Events

UIOutput does not originate any standard events. See ValueHolder for information about events introduced by the implemented interfaces.

UIPanel

UIPanel (extends UIComponentBase) is a component that manages the layout of its child components.

Component Type

The standard component type for UIPanel components is “jakarta.faces.Panel”.

Properties

UIPanel adds no new render-independent properties.

UIPanel specializes the behavior of render-independent properties inherited from the parent component as follows:

• The default value of the family property must be set to “jakarta.faces.Panel”.

• The default value of the rendererType property must be set to null.

Methods

UIPanel adds no new processing methods.

Events

UIPanel does not originate any standard events

UIParameter

UIParameter (extends UIComponentBase) is a component that represents an optionally named configuration parameter that affects the rendering of its parent component. UIParameter components do not generally have rendering behavior of their own.

Component Type

The standard component type for UIParameter components is “jakarta.faces.Parameter”.

Properties

The following render-independent properties are added by the UIParameter component:

Name	Access	Type	Description
name	RW	String	The optional name for this parameter.
value	RW	Object	The value for this parameter.

UIParameter specializes the behavior of render-independent properties inherited from the parent component as follows:

• The default value of the family property must be set to “jakarta.faces.Parameter”.

• The default value of the rendererType property must be set to null.

Methods

UIParameter adds no new processing methods.

Events

UIParameter does not originate any standard events

UISelectBoolean

UISelectBoolean (extends UIInput) is a component that represents a single boolean (true or false) value. It is most commonly rendered as a checkbox.

Component Type

The standard component type for UISelectBoolean components is “jakarta.faces.SelectBoolean”.

Properties

The following render-independent properties are added by the UISelectBoolean component:

Name	Access	Type	Description
selected	RW	boolean	The selected state of this component. This property is a typesafe alias for the value property, so that the actual state to be used can be acquired via a value expression.

UISelectBoolean specializes the behavior of render-independent properties inherited from the parent component as follows:

• The default value of the family property must be set to “jakarta.faces.SelectBoolean”.

• The default value of the rendererType property must be set to “jakarta.faces.Checkbox”.

Methods

UISelectBoolean adds no new processing methods.

Events

UISelectBoolean inherits the ability to send ValueChangeEvent events from its parent UIInput component.

UISelectItem

UISelectItem (extends UIComponentBase) is a component that may be nested inside a UISelectMany or UISelectOne component, and represents exactly one SelectItem instance in the list of available options for that parent component.

Component Type

The standard component type for UISelectItem components is “jakarta.faces.SelectItem”.

Properties

The following render-independent properties are added by the UISelectItem component:

Name	Access	Type	Description
itemDescription	RW	String	The optional description of this available selection item. This may be useful for tools.
itemDisabled	RW	boolean	Flag indicating that any synthesized SelectItem object should have its disabled property set to true.
itemLabel	RW	String	The localized label that will be presented to the user for this selection item.
itemValue	RW	Object	The server-side value of this item, of the same basic data type as the parent component’s value. If the parent component type’s value is a value expression that points at a primitive, this value must be of the corresponding wrapper type.
value	RW	jakarta.faces.model.SelectItem	The SelectItem instance associated with this component.

UISelectItem specializes the behavior of render-independent properties inherited

• The default value of the family property must be set to “jakarta.faces.SelectItem”.

• The default value of the rendererType property must be set to null.

• If the value property is non-null, it must contain a SelectItem instance used to configure the selection item specified by this component.

• If the value property is a value expression, it must point at a SelectItem instance used to configure the selection item specified by this component.

• If the value property is null, and there is no corresponding value expression, the itemDescription, itemDisabled, itemLabel and itemValue properties must be used to construct a new SelectItem representing the selection item specified by this component.

Methods

UISelectItem adds no new processing methods.

Events

UISelectItem does not originate any standard events.

UISelectItems

UISelectItems (extends UIComponentBase) is a component that may be nested inside a UISelectMany or UISelectOne component, and represents zero or more SelectItem instances for adding selection items to the list of available options for that parent component.

Component Type

The standard component type for UISelectItems components is “jakarta.faces.SelectItems”.

Properties

The following render-independent properties are added by the UISelectItems component:

Name	Access	Type	Description
value	RW	See below	The SelectItem instances associated with this component.

UISelectItems specializes the behavior of render-independent properties inherited

• The default value of the family property must be set to “jakarta.faces.SelectItems”.

• The default value of the rendererType property must be set to null.

• If the value property (or the value returned by a value expression associated with the value property) is non-null, it must contain a SelectItem bean, an array of SelectItem beans, a Collection of SelectItem beans, or a Map, where each map entry is used to construct a SelectItem bean with the key as the label property of the bean, and the value as the value property of the bean (which must be of the same basic type as the value of the parent component’s value).

Methods

UISelectItems adds no new processing methods.

Events

UISelectItems does not originate any standard events.

UISelectMany

UISelectMany (extends UIInput) is a component that represents one or more selections from a list of available options. It is most commonly rendered as a combobox or a series of checkboxes.

Component Type

The standard component type for UISelectMany components is “jakarta.faces.SelectMany”.

Properties

The following render-independent properties are added by the UISelectMany component:

Name	Access	Type	Description
selectedValues	RW	Object[] or array of primitives	The selected item values of this component. This property is a typesafe alias for the value property, so that the actual state to be used can be acquired via a value expression.

UISelectMany specializes the behavior of render-independent properties inherited from the parent component as follows:

• The default value of the family property must be set to “jakarta.faces.SelectMany”.

• The default value of the rendererType property must be set to “jakarta.faces.Listbox”.

• See the class Javadocs for UISelectMany for additional requirements related to implicit conversions for the value property.

Methods

UISelectMany must provide a specialized validate() method which ensures that any decoded values are valid options (from the nested UISelectItem and UISelectItems children).

Events

UISelectMany inherits the ability to send ValueChangeEvent events from its parent UIInput component.

UISelectOne

UISelectOne (extends UIInput) is a component that represents zero or one selection from a list of available options. It is most commonly rendered as a combobox or a series of radio buttons.

Component Type

The standard component type for UISelectOne components is “jakarta.faces.SelectOne”.

Properties

UISelectOne adds no new render-independent properties.

UISelectOne specializes the behavior of render-independent properties inherited from the parent component as follows:

• The default value of the family property must be set to “jakarta.faces.SelectOne”.

• The default value of the rendererType property must be set to “jakarta.faces.Menu”.

Methods

UISelectOne must provide a specialized validate() method which ensures that any decoded value is a valid option (from the nested UISelectItem and UISelectItems children).

Events

UISelectOne inherits the ability to send ValueChangeEvent events from its parent UIInput component.

UIViewParameter

UIViewParameter (extends UIInput) is a component that allows the query parameters included in the request by UIOutcomTarget renderers to participate in the lifecycle. Please see the javadocs for the normative speficication of this component.Events.

UIViewRoot

UIViewRoot (extends UIComponentBase;) represents the root of the component tree.

Component Type

The standard component type for UIViewRoot components is “jakarta.faces.ViewRoot”

Properties

The following render-independent properties are added by the UIViewRoot component:

Name	Access	Type	Description
locale	RW	java.util.Locale	The Locale to be used in localizing the response for this view.
renderKitId	RW	String	The id of the RenderKit used to render this page.
viewId	RW	String	The view identifier for this view.
beforePhaseListener	RW	MethodExpression	MethodExpression that will be invoked before all lifecycle phases except for Restore View.
afterPhaseListener	RW	MethodExpression	MethodExpression that will be invoked after all lifecycle phases except for Restore View.
viewMap	RW	java.util.Map	The Map that acts as the interface to the data store that is the "view scope".

For an existing view, the locale property may be modified only from the event handling portion of Process Validations phase through Invoke Application phase, unless it is modified by an Apply Request Values event handler for an ActionSource or EditableValueHolder component that has its immediate property set to true (which therefore causes Process Validations, Update Model Values, and Invoke Application phases to be skipped).

The viewMap property is lazily created the first time it is accessed, and it is destroyed when a different UIViewRoot instance is installed from a call to FacesContext.setViewRoot(). After the Map is created a PostConstructViewMapEvent must be published using UIViewRoot as the event source. Immediately before the Map is destroyed, a PreDestroyViewMapEvent must be published using UIViewRoot as the event source.

UIViewRoot specializes the behavior of render-independent properties inherited from the parent component as follows:

• The default value of the family property must be set to “jakarta.faces.ViewRoot”.

• The default value of the rendererType property must be set to null.

Methods

The following methods are used for adding UIComponent resources to a target area in the view, and they are also used for retrieving UIComponent resources from a target area in the view.

public void addComponentResource(FacesContext context,
    UIComponent componentResource);

Add componentResource, that is assumed to represent a resource instance, to the current view. A resource instance is rendered by a resource Renderer (such as ScriptRenderer, StylesheetRenderer) as described in the Standard HTML RenderKit. This method will cause the resource to be rendered in the “head” element of the view.

public void addComponentResource(FacesContext context,
    UIComponent componentResource, String target);

Add componentResource, that is assumed to represent a resource instance, to the current view at the specified target location. The resource must be added using the algorithm outlined in this method’s Javadocs.

public List<UIComponent> getComponentResources(String target);

Return a List of UIComponent instances residing under the facet identified by target. Each UIComponent instance in the List represents a resource. The List must be formulated in accordance with this method’s Javadocs.

UIViewRoot specializes the behavior of the UIComponent.queueEvent() method to maintain a list of queued events that can be transmitted later. It also specializes the behavior of the processDecodes(), processValidators(), processUpdates(), and processApplication() methods to broadcast queued events to registered listeners. UIViewRoot clears any remaining events from the event queue in these methods if responseComplete() or renderResponse() has been set on the FacesContext. Please see Apply Request Values, Process Validations], Update Model Values and Invoke Application for more details.

Events

UIViewRoot is a source of PhaseEvent events, which are emitted when the instance moves through all phases of the request processing lifecycle except Restore View. This phase cannot emit events from UIViewRoot because the UIViewRoot instance isn’t created when this phase starts. See PhaseEvent and PhaseListener for more details on the event and listener class.

public void addPhaseListener(PhaseListener listener);
public void removePhaseListener(VPhaseListener listener);
public List<PhaseListener> getPhaseListeners();

UIViewRoot must listen for the top level PostAddToViewEvent event sent by the Restore View phase. Refer to Restore View for more details about the publishing of this event. Upon receiving this event, UIViewRoot must cause any “after” Restore View phase listeners to be called.

UIViewRoot is also the source for several kinds of system events. The system must publish a PostAddToViewEvent, with the UIViewRoot as the source, during the Restore View phase, immediately after the new UIViewRoot is set into the FacesContext for the request. The system must publish a PreRenderView event, with UIViewRoot as the source, during the Render Response phase, immediately before ViewHandler.renderView() is called.

Partial Processing

UIViewRoot adds special behavior to processDecodes, processValidators, processUpdates, getRendersChildren and encodeChildren to facilitate partial processing - namely the ability to have one or more components processed through the execute and/or render phases of the request processing lifecycle. Refer to Partial View Traversal, Partial View Processing, Partial View Rendering for an overview of partial processing. UIViewRoot must perform partial processing as outlined in the Javadocs for the “processXXX” and “encodeXXX” methods if the current request is a partial request.

Standard UIComponent Model Beans

Several of the standard UIComponent subclasses described in the previous section reference JavaBean components to represent the underlying model data that is rendered by those components. The following subsections define the standard UIComponent model bean classes.

DataModel

DataModel is an abstract base class for creating wrappers around arbitrary data binding technologies. It can be used to adapt a wide variety of data sources for use by Jakarta Faces components that want to support access to an underlying data set that can be modelled as multiple rows. The data underlying a DataModel instance is modelled as a collection of row objects that can be accessed randomly via a zero-relative index

Properties

An instance of DataModel supports the following properties:

Name	Access	Type	Description
rowAvailable	RO	boolean	Flag indicating whether the current rowIndex value points at an actual row in the underlying data.
rowCount	RO	int	The number of rows of data objects represented by this DataModel instance, or -1 if the number of rows is unknown.
rowData	RO	Object	An object representing the data for the currently selected row. DataModel implementations must return an object that be successfully processed as the “base” parameter for the ELResolver in use by this application. If the current rowIndex value is -1, null is returned.
rowIndex	RW	int	Zero-relative index of the currently selected row, or -1 if no row is currently selected. When first created, a DataModel instance must return -1 for this property.
wrappedData	RW	Object	Opaque property representing the data object wrapped by this DataModel. Each individual implementation will restrict the types of Object(s) that it supports.

Methods

DataModel must provide an iterator() to iterate over the row data for this model.

Events

No events are generated for this component.

Concrete Implementations

The Jakarta Faces implementation must provide concrete implementations of DataModel (in the jakarta.faces.model package) for the following data wrapping scenarios:

• ArrayDataModel —Wrap an array of Java objects.

• ListDataModel —Wrap a java.util.List of Java objects.

• ResultSetDataModel —Wrap an object of type java.sql.ResultSet (which therefore means that javax.sql.RowSet instances are also supported).

• ScalarDataModel —Wrap a single Java object in what appears to be a one-row data set.

Each concrete DataModel implementation must extend the DataModel abstract base class, and must provide a constructor that accepts a single parameter of the object type being wrapped by that implementation (in addition to a zero-args constructor). See the JavaDocs for specific implementation requirements on DataModel defined methods, for each of the concrete implementation classes.

SelectItem

SelectItem is a utility class representing a single choice, from among those made available to the user, for a UISelectMany or UISelectOne component. It is not itself a UIComponent subclass.

Properties

An instance of SelectItem supports the following properties:

Name	Access	Type	Description
description	RW	String	A description of this selection item, for use in development tools.
disabled	RW	boolean	Flag indicating that this option should be rendered in a fashion that disables selection by the user. Default value is false.
label	RW	String	Label of this selection item that should be rendered to the user.
value	RW	Object	The server-side value of this item, of the same basic data type as the parent component’s value. If the parent component type’s value is a value expression that points at a primitive, this value must be of the corresponding wrapper type.

Methods

An instance of SelectItem supports no additional public processing methods.

Events

An instance of SelectItem supports no events.

SelectItemGroup

SelectItemGroup is a utility class extending SelectItem, that represents a group of subordinate SelectItem instances that can be rendered as a “sub-menu” or “option group”. Renderers will typically ignore the value property of this instance, but will use the label property to render a heading for the sub-menu.

Properties

An instance of SelectItemGroup supports the following additional properties:

Name	Access	Type	Description
selectItems	RW	SelectItem[]	Array of SelectItem instances representing the subordinate selection items that are members of the group represented by this SelectItemGroup instance.

Note that, since SelectItemGroup is a subclass of SelectItem, SelectItemGroup instances can be included in the selectItems property in order to create hierarchies of subordinate menus. However, some rendering environments may limit the depth to which such nesting is supported; for example, HTML Living Standard does not allow an <optgroup> to be nested inside another <optgroup> within a <select> control.

Methods

An instance of SelectItemGroup supports no additional public processing methods.

Events

An instance of SelectItemGroup supports no events.