Writing Bean Properties

As explained in Backing Beans (page 295), a backing bean property can be bound to one of the following items:

These properties follow JavaBeans component conventions (see JavaBeans Components, page 131).

The UI component's tag binds the component's value to a property using its value attribute and binds the component's instance to a property using its binding attribute, as explained in Binding Component Values and Instances to External Data Sources (page 361). Likewise, all the converter, listener, and validator tags use their binding attributes to bind their associated implementations to backing bean properties, as explained in Binding Converters, Listeners, and Validators to Backing Bean Properties (page 367).

To bind a component's value to a backing bean property, the type of the property must match the type of the component's value to which it is bound. For example, if a backing bean property is bound to a UISelectBoolean component's value, the property should accept and return a boolean value or a Boolean wrapper Object instance.

To bind a component instance, the property must match the component type. For example, if a backing bean property is bound to a UISelectBoolean instance, the property should accept and return UISelectBoolean.

Similarly, in order to bind a converter, listener, or validator implementation to a property, the property must accept and return the same type of converter, listener, or validator object. For example, if you are using the convertDateTime tag to bind a DateTime converter to a property, that property must accept and return a DateTime instance.

The rest of this section explains how to write properties that can be bound to component values, to component instances for the component objects described in Adding UI Components to a Page Using the HTML Component Tags (page 316), and to converter, listener, and validator implementations.

Writing Properties Bound to Component Values

To write a backing bean property bound to a component's value, you must know the types that the component's value can be so that you can make the property match the type of the component's value.

Table 11-1 lists all the component classes described in Adding UI Components to a Page Using the HTML Component Tags (page 316) and the acceptable types of their values.

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

Table 11-1 Acceptable Types of Component Values 
Component
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. Elements of the array or List can be any of the standard types.

UIInput and UIOutput Properties

The following tag binds the name component to the name property of CashierBean. 

<h:inputText id="name" size="50"
  value="#{cashier.name}"
  required="true"> 
  <f:valueChangeListener 
    type="com.sun.bookstore6.listeners.NameChanged" /> 
</h:inputText>

Here is the bean property bound to the name component: 

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

As Using the Standard Converters (page 349) describes, to convert the value of a UIInput or UIOutput component, you can either apply a converter or create the bean property bound to the component with the desired type. Here is the example tag explained in Using DateTimeConverter (page 352) that displays the date books will be shipped: 

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

The application developer must ensure that the property bound to the component represented by this tag has a type of java.util.Date. Here is the shipDate property in CashierBean: 

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

See Binding Component Values and Instances to External Data Sources (page 361) for more information on applying a Converter implementation.

UIData Properties

UIData components must be bound to one of the types listed in Table 11-1. The UIData component from the bookshowcart.jsp page of the Duke's Bookstore example is discussed in the section Using Data-Bound Table Components (page 329). 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 the ShoppingCart bean. The ShoppingCart bean maintains a map of ShoppingCartItem beans.

The getItems method from ShoppingCart populates a List with ShoppingCartItem instances that are saved in the items map from when the customer adds books to the cart: 

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

All the components contained in the UIData component are bound to the properties of the ShoppingCart bean that is bound to the entire UIData component. For example, here is the outputText tag that displays the book title in the table: 

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

The book title is actually a hyperlink to the bookdetails.jsp page. The outputText tag uses the value expression #{item.item.title} to bind its UIOutput component to the title property of the Book bean. The first item in the expression is the ShoppingCartItem instance that the dataTable tag is referencing while rendering the current row. The second item in the expression refers to the item property of ShoppingCartItem, which returns a Book bean. The title part of the expression refers to the title property of Book. The value of the UIOutput component corresponding to this tag is bound to the title property of the Book bean: 

private String title = null; 
public String getTitle() {
  return this.title;
}
public void setTitle(String title) {
  this.title=title;
}

UISelectBoolean Properties

Properties that hold the UISelectBoolean component's data must be of boolean or Boolean type. The example selectBooleanCheckbox tag from the section Rendering Components for Selecting One Value (page 337) binds a component to a property. Here is an example that binds a component value to a 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.

Here is the example selectManyCheckbox tag from Rendering Components for Selecting Multiple Values (page 339): 

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

Here is a bean property that maps to the value of this selectManyCheckbox example: 

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

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

As explained in the section Rendering Components for Selecting Multiple Values (page 339), 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 how to write the bean properties for the UISelectItem and UISelectItems components.

UISelectOne Properties

UISelectOne properties accept the same types as UIInput and UIOutput properties. This is 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 the example selectOneMenu tag from Displaying a Menu Using the selectOneMenu Tag (page 338): 

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

As explained in the section Displaying a Menu Using the selectOneMenu Tag (page 338), the UISelectItem and UISelectItems components are used to represent all the values in a UISelectOne component. See UISelectItem Properties and UISelectItems Properties for information on how to write the backing bean properties for the UISelectItem and UISelectItems components.

UISelectItem Properties

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

The Duke's Bookstore application does not use any UISelectItem components whose values are bound to backing beans. The example selectOneMenu tag from Displaying a Menu Using the selectOneMenu Tag (page 338) contains selectItem tags that set the values of the list of items in the page. Here is an example 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 either a set of SelectItem instances or a set of SelectItemGroup instances. As described in Using the selectItems Tag (page 342), a SelectItemGroup is composed of a set of SelectItem instances. This section describes how to write the properties for selectItems tags containing SelectItem instances and for selectItems tags containing SelectItemGroup instances.

Properties for SelectItems Composed of SelectItem Instances

Using the selectItems Tag (page 342) describes how the newsletters list of the Duke's Bookstore application is populated using the application configuration resource file. You can also populate the SelectItems with SelectItem instances programmatically in the backing bean. This section explains how to do this.

In your backing bean, you create a list that is bound to the SelectItem component. Then you define a set of SelectItem objects, set their values, and populate the list with the SelectItem objects. Here is an example code snippet that shows how to create a SelectItems property: 

import javax.faces.component.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.

Properties for SelectItems Composed of SelectItemGroup Instances

The preceding section explains how to write the bean property for a SelectItems component composed of SelectItem instances. This section explains how to change the example property from the preceding section so that the SelectItems is composed of SelectItemGroup instances.

Let's separate the newsletters into two groups: One group includes Duke's newsletters, and the other group includes the Innovator's Almanac and Random Ramblings newsletters.

In your backing bean, you need a list that contains two SelectItemGroup instances. Each SelectItemGroup instance contains two SelectItem instances, each representing a newsletter: 

import javax.faces.model.SelectItemGroup;
...
private ArrayList optionsGroup = null;

optionsGroup = new ArrayList(2);

private static final SelectItem options1[] = {
  new SelectItem("200", "Duke's Quarterly", "");
  new SelectItem("202", 
    "Duke's Diet and Exercise Journal", "");
};
private static final SelectItem options2[] = {
  new SelectItem("201", "Innovator's Almanac", "");
  new SelectItem("203", "Random Ramblings", "");
};

SelectItemGroup group1 = 
  new SelectItemGroup("Duke's", null, true, options1);
SelectItemGroup group2 =
  new SelectItemGroup("General Interest", null, true, 
    options2);

optionsGroup.add(group1);
optionsGroup.add(group2);
...
public Collection getOptionsGroup() {
  return optionsGroup;
} 
public void setOptionsGroup(Collection newGroupOptions) {
  optionsGroup = new ArrayList(newGroupOptions);
}

The code first initializes optionsGroup as a list. The optionsGroup list contains two SelectItemGroup objects. Each object is initialized with the label of the group appearing in the list or menu; a value; a Boolean indicating whether or not the label is disabled; and an array containing two SelectItem instances. Then each SelectItemGroup is added to the list. Finally, the code includes the setOptionsGroup and getOptionsGroup accessor methods so that the tag can access the values. The selectItems tag references the optionsGroup property to get the SelectItemGroup objects for populating the list or menu on the page.

Writing Properties Bound to Component Instances

A property bound to a component instance returns and accepts a component instance rather than a component value. Here are the tags described in Binding a Component Instance to a Bean Property (page 366) that bind components to backing bean properties: 

<h:selectBooleanCheckbox 
  id="fanClub"
  rendered="false"
  binding="#{cashier.specialOffer}" />
<h:outputLabel for="fanClub"
  rendered="false"
  binding="#{cashier.specialOfferText}"  >
  <h:outputText id="fanClubLabel"
    value="#{bundle.DukeFanClub}" />
</h:outputLabel>

As Binding a Component Instance to a Bean Property (page 366) explains, the selectBooleanCheckbox tag renders a checkbox and binds the fanClub UISelectBoolean component to the specialOffer property of CashierBean. The outputLabel tag binds the fanClubLabel component (which represents the checkbox's label) to the specialOfferText property of CashierBean. If the user orders more than $100 (or 100 euros) worth of books and clicks the Submit button, the submit method of CashierBean sets both components' rendered properties to true, causing the checkbox and label to display when the page is rerendered.

Because the components corresponding to the example tags are bound to the backing bean properties, these properties must match the components' types. This means that the specialOfferText property must be of UIOutput type, and the specialOffer property must be of UISelectBoolean type: 

UIOutput specialOfferText = null;

public UIOutput getSpecialOfferText() {
  return this.specialOfferText;
}
public void setSpecialOfferText(UIOutput specialOfferText) {
  this.specialOfferText = specialOfferText;
}

UISelectBoolean specialOffer = null;

public UISelectBoolean getSpecialOffer() {
  return this.specialOffer;
}
public void setSpecialOffer(UISelectBoolean specialOffer) {
  this.specialOffer = specialOffer;
}

See Backing Beans (page 295) for more general information on component binding.

See Referencing a Method That Performs Navigation (page 370) for information on how to reference a backing bean method that performs navigation when a button is clicked.

See Writing a Method to Handle Navigation for more information on writing backing bean methods that handle navigation.

Writing Properties Bound to Converters, Listeners, or Validators

All of the standard converter, listener, and validator tags that are included with JavaServer Faces technology support binding attributes that allow page authors to bind converter, listener, or validator implementations to backing bean properties.

The following example from Binding Converters, Listeners, and Validators to Backing Bean Properties (page 367) shows a standard convertDateTime tag using a value expression with its binding attribute to bind the DateTimeConverter instance to the convertDate property of LoginBean.: 

<h:inputText value="#{LoginBean.birthDate}">
  <f:convertDateTime binding="#{LoginBean.convertDate}" />
</h:inputText>

The convertDate property must therefore accept and return a DateTimeConverter object, as shown here: 

private DateTimeConverter convertDate; 
public DateTimeConverter getConvertDate() {
  ...
  return convertDate;
{ 
public void setConvertDate(DateTimeConverter convertDate) {
  convertDate.setPattern("EEEEEEEE, MMM dd, yyyy");
  this.convertDate = convertDate;
}

Because the converter is bound to a backing bean property, the backing bean property is able to modify the attributes of the converter or add new functionality to it. In the case of the preceding example, the property sets the date pattern that the converter will use to parse the user's input into a Date object.

The backing bean properties that are bound to validator or listener implementations are written in the same way and have the same general purpose.