Using the Standard Converters






Using the Standard Converters

The JavaServer Faces implementation provides a set of Converter implementations that you can use to convert component data. For more information on the conceptual details of the conversion model, see Conversion Model (page 298).

The standard Converter implementations, located in the javax.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. If you 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's error message will display on the page. For example, the error message that displays if BigIntegerConverter 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 name of the input component on which the converter is registered. See section 2.4.5 of the JavaServer Faces specification, version 1.2, for a complete list of error messages.

Two of the standard converters (DateTimeConverter and NumberConverter) have their own tags, which allow you to configure the format of the component data using the tag attributes. Using DateTimeConverter (page 362) discusses using DateTimeConverter. Using NumberConverter (page 364) discusses using NumberConverter. The following section explains how to convert a component's value including how to register the other standard converters with a component.

Converting a Component's Value

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

  • Nest one of the standard converter tags inside the component's tag. These tags are convertDateTime and convertNumber and are described in Using DateTimeConverter (page 362) and Using NumberConverter (page 364), 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's converter attribute.

  • Nest a converter tag inside of the component tag and use either the converter tag's converterId attribute or its binding attribute to refer to the converter.

As an example of the second approach, if you want a component's data to be converted to an Integer, you can simply bind the component's value to 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 can employ the third technique by using the converter attribute on the component tag:

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

This example shows the converter attribute referring to the fully-qualified class name of the converter. The converter attribute can also take the ID of the component. If the converter is a custom converter, the ID is defined in the application configuration resource file (see Application Configuration Resource File, page 458).

The data corresponding to this example inputText tag will be converted to a java.lang.Integer. Notice that the Integer type is already a supported type of the NumberConverter. If you don't need to specify any formatting instructions using the convertNumber tag attributes, and if one of the other converters will suffice, you can simply reference that converter using the component tag's converter attribute.

Finally, you can nest a converter tag within the component tag and use either the converter tag's converterId attribute or its binding attribute to reference the converter.

The converterId attribute must reference the converter's ID. Again, if the converter is a custom converter, the value of converterID must match the ID in the application configuration resource file; otherwise it must match the ID as defined in the converter class. Here is an example:

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

Instead of using the converterId attribute, the converter tag can use the binding attribute. The binding attribute must resolve to a bean property that accepts and returns an appropriate Converter instance. See Binding Converters, Listeners, and Validators to Backing Bean Properties (page 378) for more information.

Using DateTimeConverter

You can convert a component's data to a java.util.Date by nesting the convertDateTime tag inside the component tag. The convertDateTime tag has several attributes that allow you to specify the format and type of the data. Figure lists the attributes.

Figure convertDateTime Tag Attributes

Attribute

Type

Description

binding

DateTimeConverter

Used to bind a converter to a backing bean property

dateStyle

String

Defines the format, as specified by java.text.DateFormat, of a date or the date part of a date string. Applied only if type is date (or both) and pattern is not defined. Valid values: default, short, medium, long, and full. If no value is specified, default is used.

locale

String or Locale

Locale whose predefined styles for dates and times are used during formatting or parsing. If not specified, the Locale returned by FacesContext.getLocale will be used.

pattern

String

Custom formatting pattern that determines how the date/time string should be formatted and parsed. If this attribute is specified, dateStyle, timeStyle, and type attributes are ignored.

timeStyle

String

Defines the format, as specified by java.text.DateFormat, of a time or the time part of a date string. Applied only if type is time and pattern is not defined. Valid values: default, short, medium, long, and full. If no value is specified, default is used.

timeZone

String or TimeZone

Time zone in which to interpret any time information in the date string.

type

String

Specifies whether the string value will contain a date, a time, or both. Valid values are date, time, or both. If no value is specified, date is used.


Here is a simple example of a convertDateTime tag from the bookreceipt.jsp page:

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

When binding the DateTime converter to a component, ensure that the backing bean property to which the component is bound is of type java.util.Date. In the case of the preceding example, cashier.shipDate must be of type java.util.Date.

Here is an example of a date and time that the preceding tag 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 can use the locale 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 the Customizing Formats lesson of the Java Tutorial at http://java.sun.com/docs/books/tutorial/i18n/format/simpleDateFormat.html for more information on how to format the output using the pattern attribute of the convertDateTime tag..

Using NumberConverter

You can convert a component's data to a java.lang.Number by nesting the convertNumber tag inside the component tag. The convertNumber tag has several attributes that allow you to specify the format and type of the data. Figure lists the attributes.

Figure convertNumber Attributes

Attribute

Type

Description

binding

NumberConverter

Used to bind a converter to a backing bean property

currencyCode

String

ISO4217 currency code, used only when formatting currencies.

currencySymbol

String

Currency symbol, applied only when formatting currencies.

groupingUsed

boolean

Specifies whether formatted output contains grouping separators.

integerOnly

boolean

Specifies whether only the integer part of the value will be parsed.

locale

String or Locale

Locale whose number styles are used to format or parse data.

maxFractionDigits

int

Maximum number of digits formatted in the fractional part of the output.

maxIntegerDigits

int

Maximum number of digits formatted in the integer part of the output.

minFractionDigits

int

Minimum number of digits formatted in the fractional part of the output.

minIntegerDigits

int

Minimum number of digits formatted in the integer part of the output.

pattern

String

Custom formatting pattern that determines how the number string is formatted and parsed.

type

String

Specifies whether the string value is parsed and formatted as a number, currency, or percentage. If not specified, number is used.


The bookcashier.jsp page of Duke's Bookstore uses a convertNumber tag to display the total prices of the books in the shopping cart:

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

When binding the Number converter to a component, ensure that the backing bean property to which the component is bound is of primitive type or has a type of java.lang.Number. In the case of the preceding example, cart.total is of type java.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 id="cartTotal"
     value="#{cart.Total}" >
     <f:convertNumber pattern="$####" />
   </h:outputText>

Please refer to the Customizing Formats lesson of the Java Tutorial at http://java.sun.com/docs/books/tutorial/i18n/format/decimalFormat.html for more information on how to format the output using the pattern attribute of the convertNumber tag.



 Python   SQL   Java   php   Perl 
 game development   web development   internet   *nix   graphics   hardware 
 telecommunications   C++ 
 Flash   Active Directory   Windows