Binding a Component to a Data Source

The UIInput and UIOutput components (and all components that extend these components) support storing a local value and referring to a value in another location with the optional valueRef attribute, which has replaced the modelReference attribute of previous releases. Like the modelReference attribute, the valueRef attribute is used to bind a component's data to data stored in another location.

Also like the modelReference attribute, the valueRef attribute can be used to bind a component's data to a JavaBeans component or one of its properties. What's different about the valueRef attribute is that it also allows you to map the component's data to any primitive (such as int), structure (such as an array), or collection (such as a list), independent of a JavaBeans component.

In addition to the valueRef attribute, this release also introduces the actionRef attribute, which binds an Action to a component. As explained in section Navigating Between Pages, an Action performs some logic and returns an outcome, which tells the navigation model what page to access next.

This section explains how the binding of a component to data works, and how to use valueRef to bind a component to a bean property and primitive, and how to combine the component data with an Action.

How Binding a Component to Data Works

Many of the standard components support storing local data, which is represented by the component's value property. They also support referencing data stored elsewhere, represented by the component's valueRef property.

Here is an example of using a valueRef property to refer to the bean property that stores the same integer:

During the Apply Request Values phase of the standard request processing lifecycle, the component's local data is updated with the values from the current request. During this phase and the Process Validations phase, local values from the current request are checked against the converters and validators registered on the components

During the Update Model Values phase, the JavaServer Faces implementation copies the component's local data to the model data if the component has a valueRef property that points to a model object property.

During the Render Response phase, model data referred to by the component's valueRef property is accessed and rendered to the page.

The valueRef property uses an expression language syntax to reference the data bound to a component. Table 21-6 shows a few examples of valid valueRef expressions.

Table 21-6 Example valueRef Expressions
Value	valueRef Expression
A property initialized from a context init parameter	`initParam.quantity`
A bean property	`CarBean.engineOption`
Value in an array	`engines[3]`
Value in a collection	`CarPriceMap["jalopy"]`
Property of an object in an array of objects	`cars[3].carPrice`

The new ValueBinding API evaluates the valueRef expression that refers to a model object, a model object property, or other primitive or data structure.

A ValueBinding uses a VariableResolver to retrieve a value. The VariableResolver searches the scopes and implicit objects to retrieve the value. Implicit objects map parameters to values. For example, the integer literal, quantity, from Table 21-6 is initialized as a property that is initialized from a context init parameter. The implicit objects that a VariableResolver searches are listed in Table 21-7

Table 21-7 Implicit Objects
Implicit object	What it is
applicationScope	A `Map` of the application scope attribute values, keyed by attribute name.
cookie	A `Map` of the cookie values for the current request, keyed by cookie name.
facesContext	The `FacesContext` instance for the current request.
header	A `Map` of HTTP header values for the current request, keyed by header name.
headerValues	A `Map` of `String` arrays containing all of the header values for HTTP headers in the current request, keyed by header name.
initParam	A `Map` of the context initialization parameters for this web application.
param	A `Map` of the request parameters for this request, keyed by parameter name.
paramValues	A `Map` of `String` arrays containing all of the parameter values for request parameters in the current request, keyed by parameter name.
requestScope	A `Map` of the request attributes for this request, keyed by attribute name.
sessionScope	A `Map` of the session attributes for this request, keyed by attribute name.
tree	The root `UIComponent` in the current component tree stored in the `FacesRequest` for this request.

A VariableResolver also creates and stores objects in scope. The default VariableResolver resolves standard implicit variables and is the Managed Bean Facility, discussed in section Creating Model Objects. The Managed Bean Facility is configured with the application configuration resource file.

It's also possible to create a custom VariableResolver. There are many situations in which you would want to create a VariableResolver. One situation is if you don't want the web application to search a particular scope, or you want it to search only some of the scopes for performance purposes.

Binding a Component to a Bean Property

To bind a component to a bean or its property, you must first specify the name of the bean or property as the value of the valueRef attribute. You configured this bean in the application configuration file, as explained in section Creating Model Objects. If you are binding the component to a bean or its property, the component tag's valueRef expression must match the corresponding message-bean-name element up to the first "." in the expression. Likewise, the part of the valueRef expression after the "." must match the name specified in the corresponding property-name element in the application configuration file. For example, consider this bean configuration:

This example configures a bean called CarBean, which has a property called carName of type String. If there is already a matching instance of this bean in the specified scope, the JavaServer Faces implementation does not create it.

To bind a component to this bean property, you refer to the property using a reference expression from the valueRef attribute of the component's tag:

See section Creating Model Objects for information on how to configure beans in the application configuration file.

Writing Model Object Properties explains in more detail how to write the model object properties for each of the component types.

Binding a Component to an Initial Default

Suppose that you have a set of pages that all display a version number in a UIOutput component. You can save this number in an implicit object. This way, all of the pages can reference it, rather than each page including it. To save versionNo as an initial default value in the context initParam implicit object set the context-param element in your web.xml file:

To access the version number at the time the page is rendered, refer to the parameter from the version component tag's valueRef attribute:

Storing values to and retrieving values from other implicit objects are done in a similar way.

Combining Component Data and Action Objects

An Action is an object that performs application-specific processing when an ActionEvent occurs as a result of clicking a button or a hyperlink. The JavaServer Faces implementation automatically registers a default ActionListener to handle the Action Event.

The processing an Action object performs occurs in its invoke method, which returns a logical outcome as a result of the processing. For example, the invoke method can return "failure" after checking if a password a user enters does not match the password on file.

This outcome is returned to the default NavigationHandler by way of the default ActionListener implementation. The NavigationHandler selects the page to be accessed next by matching the outcome against those defined in a set of navigation rules specified in the application configuration file.

As the section Using an Action Object With a Navigation Rule explains, the component that generated the ActionEvent maps to the Action object with its actionRef property. This property references a bean property that returns the Action object.

It is common practice to include the bean property and the Action implementation to which it refers within the same bean class. Additionally, this bean class should represent the model data for the entire form from which the ActionEvent originated. This is so that the Action object's invoke method has access to the form data and the bean's methods.

To illustrate how convenient it is to combine the form data and the Action object, consider the situation in which a user uses a form to log in to a Web site. This form's data is represented by a bean called LogonForm, which is configured in the application configuration file:

This declaration creates the LogonForm bean in request scope for each individual request if the bean is not already in request scope. For more information on creating beans, see Creating Model Objects.

To logon, the user enters her username and password in the form. The following tags from the login.jsp page accept the username and password input:

The valueRef properties of these UIInput components refer to the LogonForm bean properties. The data for these properties are updated when the user enters the username and password and submits the form by clicking the SUBMIT button. The button is rendered with this command_button tag:

The actionRef property refers to the getLogon method of the LoginForm bean:

This method returns an Action (implemented here as an anonymous inner class), whose invoke method returns an outcome. This outcome is determined by the processing performed in the bean's logon method:

The logon method must access the username and password that is stored in the username and password bean properties so that it can check them against the username and password stored in the database.