Download FAQ History

API Search Feedback

Writing a Model Object Class

A model object is a JavaBeans component that encapsulates the data on a set of UI components. It might also perform the application-specific functionality associated with the component data. For example, a model object might perform a currency conversion using a value that the user enters into a UIInput component and then output the conversion to a UIOutput component. The model object follows JavaBeans component conventions in that it must contain an empty constructor and a set of properties for setting and getting the data:

...
String myBeanProperty = null;
...
public MyBean() {}
String getMyBeanProperty{
  return myBeanProperty;
}
void setMyBeanProperty(String beanProperty){
  myBeanProperty = beanProperty;
} 

You can bind most of the component classes to model object properties, but you are not required to do so.

In order to bind a component to a model object property, the type of the property must match the type of the component object to which it is bound. In other words, if a model object property is bound to a UISelectBoolean component, the property should accept and return a boolean value. The rest of this section explains how to write properties that can be bound to the component classes described in Using the HTML Tags.

Writing Model Object Properties

Table 21-14 lists all the component classes described in Using the HTML Tags and the acceptable types of their values.

Table 21-14 Acceptable Component Types 

Component	Renderer	Types
UIInput/ UIOutput	Date	java.util.Date
	DateTime	java.util.Date
	Number	java.lang.Number
	Time	java.util.Date
	Text	java.lang.String With a standard converter: Date and Number
UIInput	Hidden	java.lang.String With a standard converter: Date and Number
	Secret	java.lang.String With a standard converter: Date and Number
UIOutput	Message	java.lang.String
UIPanel	Data	array,java.util.Collection, java.util.Iterator, java.util.Map
UISelectBoolean	Checkbox	boolean
UISelectItem		java.lang.String
UISelectItems		java.lang.String, Collection, Array, Map
UISelectMany	CheckboxList, Listbox, Menu	Collection, Array
UISelectOne	Listbox, Menu, Radio	java.lang.String,int, double, long

Make sure to use the valueRef attribute in the tags of the components that are mapped to model object properties. Also, be sure to use the proper names of the properties. For example, if a valueRef tag has a value of CurrentOptionServer.currentOption, the corresponding String property should be:

String currentOption = null;
String getCurrentOption(){...}
void setCurrentOption(String option){...} 

For more information on JavaBeans conventions, see JavaBeans Components.

UIInput and UIOutput Properties

Properties for UIInput and UIOutput objects accept the same types and are the most flexible in terms of the number of types they accept, as shown in Table 21-14.

Most of the UIInput and UIOutput properties in the cardemo application are of type String. The zip UIInput component is mapped to an int property in CustomerBean.java because the zip component is rendered with the Number renderer:

<h:input_number id="zip"  formatPattern="#####"
  valueRef="CustomerBean.zip" size="5">
  ...
</h:input_number> 

Here is the property mapped to the zip component tag:

int zip = 0;
...
public void setZip(int zipCode) {
  zip = zipCode;
}
public int getZip() {
  return zip;
} 

The components represented by the input_text, output_text, input_hidden, and input_secret tags can also be bound to the Date, Number and custom types in addition to java.lang.String when a Converter is applied to the component. See Performing Data Conversions for more information.

UIPanel Properties

Only UIPanel components rendered with a Data renderer can be mapped to a model object. These UIPanel components must be mapped to a JavaBeans component of type array, java.util.Collection, java.util.Iterator, or java.util.Map. Here is a bean that maps to the panel_data component from the section Using the panel_list Tag:

public class CustomerListBean extends java.util.ArrayList{
  public ListBean() {
    add(new CustomerBean("123456", "Sun Microsystems, Inc.",
      "SUNW", 2345.60));
    add(new CustomerBean("789101", "ABC Company, Inc.", 
      "ABC", 458.21));
  }
} 

UISelectBoolean Properties

Properties that hold this component's data must be of boolean type. Here is the property for the sunRoof UISelectBoolean component:

  protected boolean sunRoof = false;
    ...
  public void setSunRoof(boolean roof) {
    sunRoof = roof;
  }
  public boolean getSunRoof() {
    return sunRoof;
  } 

UISelectMany Properties

Since a UISelectMany component allows a user to select one or more items from a list of items, this component must map to a model object property of type java.util.Collection or array. This model object property represents the set of currently selected items from the list of available items.

Here is the model object property that maps to the valueRef of the selectmany_checkboxlist example from the section Using the selectmany_checkboxlist Tag:

protected ArrayList currentOptions = null; 
public Object[] getCurrentOptions() {
  return currentOptions.toArray();
}
public void setCurrentOptions(Object []newCurrentOptions) {
  int len = 0;
  if (null == newCurrentOptions ||
    (len = newCurrentOptions.length) == 0) {
      return;
  }
  currentOptions.clear();
  currentOptions = new ArrayList(len);
  for (int i = 0; i < len; i++) {
    currentOptions.add(newCurrentOptions[i]);
  }
} 

Note that the setCurrentOptions(Object) method must clear the Collection and rebuild it with the new set of values that the user selected.

As explained in the section The UISelectMany Component, 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 model object properties for the UISelectItem and UISelectItems components.

UISelectOne Properties

The 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 could be a String, int, long, or double. Here is the property corresponding to the engineOption UISelectOne component from more.jsp:

protected Object currentEngineOption = engines[0];
...
public void setCurrentEngineOption(Object eng) {
  currentEngineOption = eng;
}

public Object getCurrentEngineOption() {
  return currentEngineOption;
} 

Note that currentEngineOption is one of the objects in an array of objects, representing the list of items in the UISelectOne component.

As explained in the section The UISelectOne Component, 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 model object 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. A UISelectItem property must be mapped to a property of type SelectItem. A SelectItem object is composed of: an Object representing the value, and two Strings representing the label and description of the SelectItem.

Here is an example model object property for a SelectItem component:

SelectItem itemOne = null;

SelectItem getItemOne(){
  return SelectItem(String value, String label, String
    description);
}

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

UISelectItems Properties

The UISelectItems properties are the most difficult to write and require the most code. The UISelectItems components are used as children of UISelectMany and UISelectOne components. Each UISelectItems component is composed of a set of SelectItem instances. In your model object, you must define a set of SelectItem objects, set their values, and populate the UISelectItems object with the SelectItem objects. The following code snippet from CurrentOptionServer shows how to create the engineOption UISelectItems property.

import javax.faces.component.SelectItem;
...
protected ArrayList engineOption;
...
public CurrentOptionServer() {
  protected String engines[] = {
    "V4", "V6", "V8"
  };
  engineOption = new ArrayList(engines.length);
  ...
  for (i = 0; i < engines.length; i++) {
    engineOption.add(new SelectItem(engines[i],
            engines[i], engines[i]));
  } 
}
...
public void setEngineOption(Collection eng) {
  engineOption = new ArrayList(eng);
}
public Collection getEngineOption() {
  return engineOption;
} 

The code first initializes engineOption as an ArrayList. The for loop creates a set of SelectItem objects with values, labels and descriptions for each of the engine types. Finally, the code includes the obligatory setEngineOption and getEngineOption accessor methods.

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.