20.5 Adding Conversion

A web application can store data of many types (such as int, long, date) in the model layer. When viewed in a client browser, however, the user interface has to present the data in a manner that can be read or modified by the user. For example, a date field in a form might represent a java.util.Date object as a text string in the format pattern mm/dd/yyyy. When a user edits a date field and submits the form, the string must be converted back to the type that is required by the application. Then the data is validated against any rules and conditions.

When you create an inputText component by dropping an attribute that is of a type for which there is a converter, JDeveloper automatically adds that converter's tag as a child of the input component. This tag invokes the converter, which will convert the String entered by the user back into the type expected by the object.

The JSF standard converters, which handle conversion between Strings and simple data types, implement the javax.faces.convert.Converter interface. The supplied JSF standard converter classes are:

BigDecimalConverter
BigIntegerConverter
BooleanConverter
ByteConverter
CharacterConverter
DateTimeConverter
DoubleConverter
FloatConverter
IntegerConverter
LongConverter
NumberConverter
ShortConverter

Table 20-5 shows the converters provided by ADF Faces.

Table 20-5 ADF Faces Converters

Converter	Tag Name	Description
`ColorConverter`	`af:convertColor`	Converts `java.lang.String` objects to `java.awt.Color` objects. You specify a set of color patterns as an attribute of the converter.
`DateTimeConverter`	`af:convertDateTime`	Converts `java.lang.String` objects to `java.util.Date` objects. You specify the pattern and style of the date as attributes of the converter.
`NumberConverter`	`af:convertNumber`	Converts `java.lang.String` objects to `java.lang.Number` objects. You specify the pattern and type of the number as attributes of the converter.

As with validators, the ADF Faces converters are also run on the client side unless client-side validation is explicitly disabled in the adf-faces-config.xml file.

Note:

JSF reference implementation converters are not run on the client-side

In addition to JavaScript-enabled converters for color, date, and number, ADF Faces also provides JavaScript-enabled converters for input text fields that are bound to any of these Java types:

java.lang.Integer
java.lang.Long
java.lang.Short
java.lang.Byte
java.lang.Float
java.lang.Double

Unlike the converters listed in Table 20-5, the JavaScript-enabled converters are automatically used whenever needed. They do not have associated tags that can be nested in the component.

20.5.1 How to Use Converters

Whenever you drop an attribute from the Data Control Palette for which there is an ADF Faces converter, JDeveloper automatically adds the converter to the input component. You can also manually insert a converter.

To add ADF Faces converters that have a tag:

In the Structure window, right-click the component for which you'd like to add a converter.
In the context menu, choose Insert inside <UI component> > ADF Faces Core to insert an ADF Faces converter or JSF Core to insert a JSF converter.
Choose a converter tag (for example, ConvertDateTime).
In the Property Inspector, set values for the attributes, including any messages for conversion errors. For additional help, right-click any of the attributes and choose Help.

ADF Faces lets you customize the detail portion of a conversion error message. By setting a value for an XxxMessageDetail attribute, where Xxx is the conversion error type (for example, convertDateMessageDetail), ADF Faces displays the custom message instead of a default message, if conversion fails.

20.5.2 What Happens When You Create Input Fields Using the Data Control Palette

When you use the Data Control Palette to create input fields that are of a type supported by a converter, JDeveloper automatically provides ADF Faces conversion code on the JSF page by:

Adding an af:messages tag as a child of the body tag. By default the globalOnly attribute is set to false, and the message and text attributes are not set. For more information, see Section 20.7, "Displaying Error Messages".
Adding a converter tag as a child of the input component.

By default, the pattern attribute is bound to the format property of the associated binding. The format property determines how the String is formatted according to the format masks defined in the business layer objects, using an EL expression such as #{bindings.someObject.format}. For example, with the convertNumber converter, it might determine whether decimals are used.

For example, if you drop the ProdId attribute from the ProductList collection as an inputText component, JDeveloper automatically adds the convertNumber converter as a child of the input component, as shown in Example 20-7.

Example 20-7 Converter Tag in a JSF Page

<af:inputText value="#{bindings.ProductListProdId.inputValue}"
              required="#{bindings.ProductListProdId.mandatory}"
              columns="#{bindings.ProductListProdId.displayWidth}">
  ...
  <f:convertNumber groupingUsed="false"
                   pattern="#{bindings.ProductListProdId.format}"/>
</af:inputText>

The binding evaluates to the format property as it is set on the data control itself.

Tip:

If you drop a primary key attribute that is of type DBSequence from the Data Control Palette, JDeveloper does not add the f:convertNumber tag to the input component. If you create an edit form that uses a primary key of type Number, and later changed the type to DBSequence, you must either remove the f:convertNumber tag from the input component that was created earlier, or recreate the form. For information about DBSequence, see Section 6.6.3.8, "Trigger-Assigned Primary Key Values from a Database Sequence".

20.5.3 What Happens at Runtime

When the user submits the page containing converters, the ADF Faces validate() method calls the converter's getAsObject() method to convert the string value to the required object type. When there isn't an attached converter and if the component is bound to a bean property in the model, then JSF automatically uses the converter that has the same data type as the bean property. If conversion fails, the submitted value is marked as invalid and JSF adds an error message to a queue that is maintained by FacesContext. If conversion is successful and there are no validators attached to the component, the converted value is stored as a local value that is later used to update the model.