The Java EE 6 Tutorial, Volume I

Writing Bean Properties

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

These properties follow the conventions of JavaBeans components (also called beans). For more information on JavaBeans components, see JavaBeans Tutorial.

The component’s tag binds the component’s value to a backing bean property using its value attribute and binds the component’s instance to a backing bean property using its binding attribute.

Likewise, all the converter, listener, and validator tags use their binding attributes to bind their associated implementations to backing bean properties. Binding is an advanced topic covered in Java EE 6 Tutorial, Volume II: Advanced Topics.

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 SelectBoolean component’s value, the property should accept and return a boolean value or a Boolean wrapper Object instance.

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

Similarly, to bind a converter, listener, or validator implementation to a backing bean 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 Components to a Page Using HTML Tags, and to converter, listener, and validator implementations.

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 component classes described in Adding Components to a Page Using HTML Tags and the acceptable types of their values.

Table 9–1 Acceptable Types of Component Values


Acceptable Types of Component Values 

Input, Output, SelectItem, SelectOne

Any of the basic primitive and numeric types or any Java programming language object type for which an appropriate Converter implementation is available


array of beans, List of beans, single bean, java.sql.ResultSet, javax.servlet.jsp.jstl.sql.Result, javax.sql.RowSet


boolean or Boolean


java.lang.String, Collection, Array, Map


array or List though elements of the array or List can be any of the standard types

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.

Input and Output Properties

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

<h:inputText id="name" size="50"

The following code segment 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) { = name;
public String getName() {

As described in Using the Standard Converters, to convert the value of a 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 that books will be shipped.

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

The bean property represented by this tag must be of a type of java.util.Date. The following code segment 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;

Data Properties

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

<h:dataTable  id="items"
    var="item" >

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

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

public synchronized List getItems() {
    List results = new ArrayList();
    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 book title in the table:

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

SelectBoolean Properties

Backing bean properties that hold the SelectBoolean 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: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;

SelectMany Properties

Because a SelectMany 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 selectManyCheckbox tag comes fromRendering Components for Selecting Multiple Values:

    <f:selectItems value="#{newsletters}"/>

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 SelectItem and SelectItems components are used to represent all the values in a SelectMany component. See SelectItem Properties and SelectItems Properties for information on writing the bean properties for the SelectItem and SelectItems components.

SelectOne Properties

SelectOne properties accept the same types as Input and Output properties, because a SelectOne 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"

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

The SelectItem and SelectItems components are used to represent all the values in a SelectOne 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 SelectItem and SelectItems components, see SelectItem Properties and SelectItems Properties .

SelectItem Properties

A SelectItem component represents a single value in a set of values in a SelectMany or SelectOne component. A SelectItem component can be bound to a backing bean property 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 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;

SelectItems Properties

The SelectItems components are children of SelectMany and SelectOne components. Each SelectItems component is composed of a set of either SelectItem instances or anycollection of objects such as an array, or a list or even POJOs..

The following section describes how to write the properties for selectItems tags containing SelectItem instances.

Properties for SelectItems Composed of SelectItem Instances

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

  1. In your backing bean, create a list that is bound to the SelectItem component.

  2. Then define a set of SelectItem objects, set their values, and populate the list with the SelectItem objects.

Here is an example code snippet from a backing bean 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
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.

Writing Properties Bound to Component Instances

A property bound to a component instance returns and accepts a component instance rather than a component value. The following components bind a component instance to a backing bean property:

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

The selectBooleanCheckbox tag renders a check box and binds the fanClub SelectBoolean component to the specialOffer property of CashierBean. The outputLabel tag binds the fanClubLabel component (which represents the check box’s label) to the specialOfferText property of CashierBean. If the user orders more than $100 worth of books and clicks the Submit button, the submit method of CashierBean sets both components’ rendered properties to true, causing the check box and label to display when the page is re-rendered.

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 Output type, and the specialOffer property must be of SelectBoolean 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;

For more general information on component binding, see Backing Beans.

For information on how to reference a backing bean method that performs navigation when a button is clicked, see Referencing a Method That Performs Navigation.

For more information on writing backing bean methods that handle navigation, see Writing a Method to 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 binding converter, listener, or validator implementations to backing bean properties.

The following example 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}" />

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