Using the Standard Converters

Converting a Component's Value

UsingDateTimeConverter

UsingNumberConverter

Using the Standard Converters

The JavaServer Faces implementation provides a set ofConverter implementations that you can useto convert component data. For more information on the conceptual details of theconversion model, seeConversion Model.

The standardConverter implementations, located in thejavax.faces.convert package, are as follows:

• BigDecimalConverter

• BigIntegerConverter

• BooleanConverter

• ByteConverter

• CharacterConverter

• DateTimeConverter

• DoubleConverter

• FloatConverter

• IntegerConverter

• LongConverter

• NumberConverter

• ShortConverter

Each of these converters has a standard error message associated with them. Ifyou have registered one of these converters onto a component on your page,and the converter is not able to convert the component’s value, the converter’serror message will display on the page. For example, the error message thatdisplays ifBigIntegerConverter fails to convert a value is:

{0} must be a number consisting of one or more digits

In this case the{0} substitution parameter will be replaced with the nameof the input component on which the converter is registered. See section 2.4.5of the JavaServer Faces specification, version 1.2, for a complete list of errormessages.

Two of the standard converters (DateTimeConverter andNumberConverter) have their own tags,which allow you to configure the format of the component data using thetag attributes.UsingDateTimeConverter discusses usingDateTimeConverter.UsingNumberConverter discusses usingNumberConverter. The following sectionexplains how to convert a component’s value including how to register the otherstandard converters with a component.

Converting a Component’s Value

To use a particular converter to convert a component’s value, you need toregister the converter onto the component. You can register any of the standardconverters on a component in one of four ways:

• Nest one of the standard converter tags inside the component’s tag. These tags areconvertDateTime andconvertNumber and are described inUsingDateTimeConverter andUsingNumberConverter, respectively.

• Bind the value of the component to a backing bean property of the same type as the converter.

• Refer to the converter from the component tag’sconverter attribute.

• Nest aconverter tag inside of the component tag and use either theconverter tag’sconverterId attribute or itsbinding attribute to refer to the converter.

As an example of the second approach, if you want a component’s datato be converted to anInteger, you can simply bind the component’s valueto a property similar to this:

Integer age = 0;public Integer getAge(){ return age;}public void setAge(Integer age) {this.age = age;}

If the component is not bound to a bean property, you canemploy the third technique by using theconverter attribute on the component tag:

<h:inputText    converter="javax.faces.convert.IntegerConverter" />

This example shows theconverter attribute referring to the fully-qualified class name ofthe converter. Theconverter attribute can also take the ID of thecomponent. If the converter is a custom converter, the ID is defined inthe application configuration resource file (seeApplication Configuration Resource File).

The data corresponding to this exampleinputText tag will be converted to ajava.lang.Integer.Notice that theInteger type is already a supported type of theNumberConverter. If you don’t need to specify any formatting instructions using theconvertNumbertag attributes, and if one of the other converters will suffice, you cansimply reference that converter using the component tag’sconverter attribute.

Finally, you can nest aconverter tag within the component tag and useeither the converter tag’sconverterId attribute or itsbinding attribute to reference theconverter.

TheconverterId attribute must reference the converter’s ID. Again, if the converter isa custom converter, the value ofconverterID must match the ID in the applicationconfiguration resource file; otherwise it must match the ID as defined in theconverter class. Here is an example:

<h:inputText value="#{LoginBean.Age}" />    <f:converter converterId="Integer" /></h:inputText>

Instead of using theconverterId attribute, theconverter tag can use thebinding attribute. Thebinding attribute must resolve to a bean property that accepts andreturns an appropriateConverter instance. SeeBinding Converters, Listeners, and Validators to Backing Bean Properties for more information.

UsingDateTimeConverter

You can convert a component’s data to ajava.util.Date by nesting theconvertDateTime taginside the component tag. TheconvertDateTime tag has several attributes that allow you tospecify the format and type of the data.Table 11-5 lists the attributes.

Here is a simple example of aconvertDateTime tag from thebookreceipt.jsp page:

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

When binding theDateTime converter to a component, ensure that the backing beanproperty to which the component is bound is of typejava.util.Date. In thecase of the preceding example,cashier.shipDate must be of typejava.util.Date.

Here is an example of a date and time that the precedingtag can display:

Saturday, Feb 22, 2003

You can also display the same date and time using this tag:

<h:outputText value="#{cashier.shipDate}">    <f:convertDateTime         pattern="EEEEEEEE, MMM dd, yyyy" /></h:outputText>

If you want to display the example date in Spanish, you canuse thelocale attribute:

<h:inputText value="#{cashier.shipDate}">    <f:convertDateTime dateStyle="full"         locale="Locale.SPAIN"        timeStyle="long" type="both" /></h:inputText>

This tag would display

sabado 23 de septiembre de 2006

Please refer to theCustomizing Formats lesson of the Java Tutorial athttp://download.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html formore information on how to format the output using thepattern attribute oftheconvertDateTime tag.

Table 11-5convertDateTime Tag Attributes

UsingNumberConverter

You can convert a component’s data to ajava.lang.Number by nesting theconvertNumbertag inside the component tag. TheconvertNumber tag has several attributes that allowyou to specify the format and type of the data.Table 11-6 lists theattributes.

Thebookcashier.jsp page of Duke’s Bookstore uses aconvertNumber tag to display thetotal prices of the books in the shopping cart:

<h:outputText value="#{cart.total}" >    <f:convertNumber type="currency"/></h:outputText>

When binding theNumber converter to a component, ensure that the backing beanproperty to which the component is bound is of primitive type or hasa type ofjava.lang.Number. In the case of the preceding example,cart.total isof typejava.lang.Number.

Here is an example of a number this tag can display

$934

This number can also be displayed using this tag:

<h:outputText     value="#{cart.Total}" >    <f:convertNumber pattern="$####" /></h:outputText>

Please refer to theCustomizing Formats lesson of the Java Tutorial athttp://download.oracle.com/javase/tutorial/i18n/format/decimalFormat.html formore information on how to format the output using the pattern attribute oftheconvertNumber tag.

Table 11-6convertNumber Attributes

Copyright © 2010, Oracle and/or its affiliates. All rights reserved.Legal Notices