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.

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

Two of these standard converters (DateTimeConverter and NumberConverter) have their own tags, which allow you to configure the format of the component data by configuring the tag attributes. Using DateTimeConverter discusses using DateTimeConverter. Using NumberConverter discusses using NumberConverter.

You can use the other standard converters in one of three ways:

You can make sure that the component that uses the converter has its value bound to a backing bean property of the same type as the converter.

You can refer to the converter by class or by its ID using the component tag's converter attribute. The ID is defined in the application configuration resource file (see Application Configuration Resource File).

You can refer to the converter by its ID using the converterId attribute of the converter tag.

The latter two will convert the component's local value. The first method will convert the model value of the component. For example, if you want a component's data to be converted to an Integer, you can bind the component to a property similar to this:
Integer age = 0;
public Integer getAge(){ return age;}
public void setAge(Integer age) {this.age = age;}
Alternatively, if the component is not bound to a bean property, you can use the converter attribute on the component tag:
<h:inputText
 converter="javax.faces.convert.IntegerConverter" />
The data corresponding to this 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 refer to the converter's ID via the converter tag's converterId attribute. If the tag is referring to a custom converter, the value of converterID must match the ID in the application configuration resource file. Here is an example:
<h:inputText value="#{LoginBean.Age}" />
 <f:converter converterId="Integer" />
</h:inputText>
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. Table 18-5 lists the attributes.

Here is a simple example of a convertDateTime tag from the bookreceipt.jsp page:
<h:outputText value="#{cashier.shipDate}">
 <f:convertDateTime dateStyle="full" />
</h:outputText>
Here is an example of a date and time that this 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, Feb 22, 2003
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.

Table 18-5 convertDateTime Tag Attributes

Attribute

Type

Description

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.

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. Table 18-6 lists the attributes.

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

Table 18-6 convertNumber Attributes

Attribute

Type

Description

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.

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.

locale

String or Locale

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

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.

Attribute	Type	Description
`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.

Attribute	Type	Description
`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.
`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.
`locale`	`String` or `Locale`	`Locale` whose number styles are used to format or parse data.
`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.