Download FAQ History |  | API Search Feedback

> ## 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 `value` property to set an integer value:

>     value="9"

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

>     valueRef="order.quantity"

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

>     <managed-bean>
>       <managed-bean-name>CarBean</managed-bean-name>
>       <managed-property>
>         <property-name>carName</property-name>
>         <value>Jalopy</value>
>       </managed-property>
>       ...
>     </managed-bean>

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

>     <h:output_text valueRef="CarBean.carName" />

> 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

> As explained in How Binding a Component to Data Works, the `valueRef` property can refer to a value mapped in an implicit object.

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

>     <context-param>
>       <param-name>versionNo</param-name>
>       <param-value>1.05</param-name>
>     </context-param>

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

>     <h:output_text id=version valueRef="initParam.versionNo"

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

>     <managed-bean>
>       <managed-bean-name>logonForm</managed-bean-name>
>       <managed-bean-class>foo.LogonForm</managed-bean-class>
>       <managed-bean-scope>request</managed-bean-scope>
>     </managed-bean>

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

>     <h:input_text id="username" size="16"
>       valueRef="logonForm.username" />
>     <h:input_secret id="password" size="16"
>       valueRef="logonForm.password"/>

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

>     <h:command_button id="submit" type="SUBMIT"
>       label="Log On" actionRef="logonForm.logon" />

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

>     public Action getLogon() {
>       return new Action() {
>         public String invoke() {
>           return (logon());
>         }
>       };
>     }

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

>     protected String logon() {
>       // If the username is not found in the database, or the
>         password does not match that stored for the username:
>           -Add an error message to the FacesContext
>           -Return null to reload the current page.
>       // else if the username and password are correct:
>         -Save the username in the current session
>         -Return the outcome, "success"
>     }

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

Download FAQ History |  | API Search Feedback

All of the material in The Java(TM) Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.