12.6 Creating Custom JSF Converters

You can create your own converters to meet your specific business needs. As with creating custom JSF validators, you can create custom JSF converters that run on the server side, and then also create a JavaScript version that can run on the client side. However, unlike creating custom validators, you can create only converter classes. You cannot add a method to a backing bean to provide conversion.

12.6.1 How to Create a Custom JSF Converter

Creating a custom converter requires writing the business logic for the conversion by creating an implementation of the Converter interface that contains methods overriding the getAsObject and getAsString methods of the Converter interface, and then registering the custom converter with the application. You then use the f:converter tag and nest the custom converter as a property of that tag, or you can use the converter attribute on the input component to bind to that converter.

You can also create a client-side version of the converter. ADF Faces client-side converters work in the same way standard JSF conversion works on the server, except that JavaScript is used on the client: JavaScript converter objects can throw ConverterExceptions, and they support the getAsObject and getAsString methods.

Note:

If the JavaScript form.submit() function is called, the ADF Faces support for client-side conversion is bypassed. ADF Faces provides a submitForm() method that you can use instead, or you can use the autoSubmit attribute on ADF Faces input components.

To create a custom JSF converter:

Create a Java class that implements the javax.faces.converter.Converter interface. The implementation must contain a public no-args constructor, a set of accessor methods for any attributes, and getAsObject and getAsString methods, which override the same methods of the Converter interface.

The getAsObject method takes the FacesContext instance, the UI component, and the String to be converted to a specified object. For example:
```
public Object getAsObject(FacesContext context, 
                        UIComponent component, 
                        java.lang.String value){
..
}
```
The getAsString method takes the FacesContext instance, the UI component, and the object to be converted to a String. For example:
```
public String getAsString(FacesContext context, 
                        UIComponent component, 
                        Object value){
..
}
```
For more information about these classes, refer to the Javadoc or visit http://java.sun.com/.
Add the needed conversion logic. This logic should use javax.faces.converter.ConverterException to throw the appropriate exceptions and javax.faces.application.FacesMessage to generate the corresponding error messages. For more information about the Converter interface and FacesMessage, see the Javadoc for javax.faces.converter.Converter and javax.faces.application.FacesMessage, or visit http://java.sun.com/.
If your application saves state on the client, make your custom converter implementation implement the Serializable interface, or implement the StateHolder interface, and the saveState(FacesContext) and restoreState(FacesContext, Object) methods of StateHolder. For more information, see the Javadoc for the StateHolder interface of javax.faces.component package.
Register the converter in the faces-config.xml file.
- Open the faces-config.xml file and select the Overview tab in the editor window. The faces-config.xml file is located in the <View_Project>/WEB-INF directory.
- In the window, select Converters and click New. Click Help or press F1 for additional help in registering the converter.

To create a client-side version of the converter:

Write a JavaScript version of the converter, passing relevant information to a constructor.
Implement the interface oracle.adf.view.faces.converter.ClientConverter, which has two methods. The first method is getClientScript(), which returns an implementation of the JavaScript Converter object. The second method is getClientConversion(), which returns a JavaScript constructor that is used to instantiate an instance of the converter.

For a complete example of how to add client-side conversion to a converter implementation, see "Client-Side Converters and Validators" in Development Guidelines for Oracle ADF Faces Applications.

To use a custom converter on a JSF page:

Bind your converter class to the converter attribute of the input component.

Example 12-10 shows a custom converter referenced by the converter attribute of an inputText component.

Example 12-10 A Custom Converter on a JSF Page

<af:inputText value="#{bindings.name.inputValue}"
              label="#{bindings.name.label}"
              required="#{bindings.name.mandatory}"
              columns="#{bindings.name.displayWidth}"
              converter="srdemo.MyConverter">
</af:inputText>

Note:

If a custom converter is registered in an application under a class for a specific data type, whenever a component's value references a value binding that has the same type as the custom converter object, JSF will automatically use the converter of that class to convert the data. In that case, you don't need to use the converter attribute to register the custom converter on a component, as shown in the following code snippet:

<h:inputText value="#{myBean.myProperty}"/>

where myProperty has the same type as the custom converter.

12.6.2 What Happens When You Use a Custom Converter

When you use a custom converter, the application accesses the converter class referenced in the converter attribute, and executes the getAsObject or getAsString method as appropriate. These methods access the data from the component in the current FacesContext and execute the conversion logic.