Writing Properties Bound to Component Values (The Java EE 6 Tutorial)

The Java EE 6 Tutorial

Writing Properties Bound to Component Values

To write a backing bean property that is bound to a component’s value, you must match the property type to the component’s value.

Table 9–1 lists the javax.faces.component classes and the acceptable types of their values.

Table 9–1 Acceptable Types of Component Values


Component Class	Acceptable Types of Component Values
`UIInput`, `UIOutput`, `UISelectItem`, `UISelectOne`	Any of the basic primitive and numeric types or any Java programming language object type for which an appropriate `Converter` implementation is available
`UIData`	`array` of beans, `List` of beans, single bean, `java.sql.ResultSet`, `javax.servlet.jsp.jstl.sql.Result`, `javax.sql.RowSet`
`UISelectBoolean`	`boolean` or `Boolean`
`UISelectItems`	`java.lang.String`, `Collection`, `Array`, `Map`
`UISelectMany`	`array` or `List`, though elements of the `array` or `List` can be any of the standard types

When they bind components to properties by using the value attributes of the component tags, page authors need to ensure that the corresponding properties match the types of the components’ values.

`UIInput` and `UIOutput` Properties

In the following example, an h:inputText tag binds the name component to the name property of a backing bean called CashierBean.

<h:inputText id="name" size="50"
    value="#{cashier.name}">
</h:inputText>

The following code snippet from the backing bean CashierBean shows the bean property type bound by the preceding component tag:

protected String name = null;

public void setName(String name) {
    this.name = name;
}
public String getName() {
    return this.name;
}

As described in Using the Standard Converters, to convert the value of an input or output component, you can either apply a converter or create the bean property bound to the component with the matching type. Here is the example tag, from Using DateTimeConverter, that displays the date when items will be shipped.

<h:outputText value="#{cashier.shipDate}">
    <f:convertDateTime dateStyle="full" />
</h:outputText>

The bean property represented by this tag must have a type of java.util.Date. The following code snippet shows the shipDate property, from the backing bean CashierBean, that is bound by the tag’s value in the preceding example:

protected Date shipDate;

public Date getShipDate() {
    return this.shipDate;
}
public void setShipDate(Date shipDate) {
    this.shipDate = shipDate;
}

`UIData` Properties

Data components must be bound to one of the backing bean property types listed in Table 9–1. Data components are discussed in Using Data-Bound Table Components. Here is part of the start tag of dataTable from that section:

<h:dataTable id="items"
    ...
    value="#{cart.items}"
    var="item" >

The value expression points to the items property of a shopping cart bean named cart. The cart bean maintains a map of ShoppingCartItem beans.

The getItems method from the cart bean populates a List with ShoppingCartItem instances that are saved in the items map when the customer adds items to the cart, as shown in the following code segment:

public synchronized List getItems() {
    List results = new ArrayList();
    results.addAll(this.items.values());
    return results;
}

All the components contained in the data component are bound to the properties of the cart bean that is bound to the entire data component. For example, here is the h:outputText tag that displays the item name in the table:

<h:commandLink action="#{showcart.details}">
    <h:outputText value="#{item.item.name}"/>
</h:commandLink>

`UISelectBoolean` Properties

Backing bean properties that hold a UISelectBoolean component’s data must be of boolean or Boolean type. The example selectBooleanCheckbox tag from the section Displaying Components for Selecting One Value binds a component to a property. The following example shows a tag that binds a component value to a boolean property:

<h:selectBooleanCheckbox title="#{bundle.receiveEmails}"
     value="#{custFormBean.receiveEmails}" >
</h:selectBooleanCheckbox>
<h:outputText value="#{bundle.receiveEmails}">

Here is an example property that can be bound to the component represented by the example tag:

protected boolean receiveEmails = false;
        ...
    public void setReceiveEmails(boolean receiveEmails) {
        this.receiveEmails = receiveEmails;
    }
    public boolean getReceiveEmails() {
        return receiveEmails;
    }

`UISelectMany` Properties

Because a UISelectMany component allows a user to select one or more items from a list of items, this component must map to a bean property of type List or array. This bean property represents the set of currently selected items from the list of available items.

The following example of the selectManyCheckbox tag comes fromDisplaying Components for Selecting Multiple Values:

<h:selectManyCheckbox
    id="newsletters"
    layout="pageDirection"
    value="#{cashier.newsletters}">
    <f:selectItems value="#{newsletters}"/>
</h:selectManyCheckbox>

Here is the bean property that maps to the value of the selectManyCheckbox tag from the preceding example:

protected String newsletters[] = new String[0];

public void setNewsletters(String newsletters[]) {
    this.newsletters = newsletters;
}
public String[] getNewsletters() {
    return this.newsletters;
}

The UISelectItem and UISelectItems components are used to represent all the values in a UISelectMany component. See UISelectItem Properties and UISelectItems Properties for information on writing the bean properties for the UISelectItem and UISelectItems components.

`UISelectOne` Properties

UISelectOne properties accept the same types as UIInput and UIOutput properties, because a UISelectOne component represents the single selected item from a set of items. This item can be any of the primitive types and anything else for which you can apply a converter.

Here is an example of the selectOneMenu tag from Displaying a Menu Using the h:selectOneMenu Tag:

<h:selectOneMenu   id="shippingOption"
    required="true"
    value="#{cashier.shippingOption}">
    <f:selectItem
        itemValue="2"
        itemLabel="#{bundle.QuickShip}"/>
    <f:selectItem
        itemValue="5"
        itemLabel="#{bundle.NormalShip}"/>
    <f:selectItem
        itemValue="7"
        itemLabel="#{bundle.SaverShip}"/>
 </h:selectOneMenu>

Here is the bean property corresponding to this tag:

protected String shippingOption = "2";

public void setShippingOption(String shippingOption) {
    this.shippingOption = shippingOption;
}
public String getShippingOption() {
    return this.shippingOption;
}

Note that shippingOption represents the currently selected item from the list of items in the UISelectOne component.

The UISelectItem and UISelectItems components are used to represent all the values in a UISelectOne component. This is explained in the section Displaying a Menu Using the h:selectOneMenu Tag.

For information on how to write the backing bean properties for the UISelectItem and UISelectItems components, see UISelectItem Properties and UISelectItems Properties.

`UISelectItem` Properties

A UISelectItem component represents a single value in a set of values in a UISelectMany or a UISelectOne component. A UISelectItem component must be bound to a backing bean property of type javax.faces.model.SelectItem. A SelectItem object is composed of an Object representing the value, along with two Strings representing the label and description of the UISelectItem object.

The example selectOneMenu tag from Displaying a Menu Using the h:selectOneMenu Tag contains selectItem tags that set the values of the list of items in the page. Here is an example of a bean property that can set the values for this list in the bean:

SelectItem itemOne = null;

SelectItem getItemOne(){
    return itemOne;
}
void setItemOne(SelectItem item) {
    itemOne = item;
}

`UISelectItems` Properties

UISelectItems components are children of UISelectMany and UISelectOne components. Each UISelectItems component is composed of a set of either javax.faces.model.SelectItem instances or any collection of objects, such as an array, a list, or even POJOs.

This section explains how to write the properties for selectItems tags containing SelectItem instances.

You can populate the UISelectItems with SelectItem instances programmatically in the backing bean.

In your backing bean, create a list that is bound to the SelectItem component.
Define a set of SelectItem objects, set their values, and populate the list with the SelectItem objects.

The following example code snippet from a backing bean shows how to create a SelectItems property:

import javax.faces.model.SelectItem;
...
protected ArrayList options = null;
protected SelectItem newsletter0 =
     new SelectItem("200", "Duke's Quarterly", "");
...
//in constructor, populate the list
    options.add(newsletter0);
    options.add(newsletter1);
    options.add(newsletter2);
...
public SelectItem getNewsletter0(){
    return newsletter0;
}

void setNewsletter0(SelectItem firstNL) {
    newsletter0 = firstNL;
}
// Other SelectItem properties

public Collection[] getOptions(){
    return options;
}
public void setOptions(Collection[] options){
    this.options = new ArrayList(options);
}

The code first initializes options as a list. Each newsletter property is defined with values. Then each newsletter SelectItem is added to the list. Finally, the code includes the obligatory setOptions and getOptions accessor methods.