Home | Download | PDF | API | FAQ | Search | Feedback | History

> ## 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 289).

> 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 discusses using `DateTimeConverter`. Using NumberConverter 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 and Using NumberConverter, 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 450).

> 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 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. Table 10-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 10-5 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.

> ### 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 10-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 10-6 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.