12.6 Creating Custom Converters

You can create your own converters to meet your specific business needs. As with creating custom validators, you can create custom 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 Converter

Creating a custom converter requires writing the business logic for the conversion by overriding the getAsObject and getAsString methods in an implementation of the Converter interface, and then registering the 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 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 converter:

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

The getAsObject method takes the FacesContext instance, the component, and the String to be converted to a specified object. For example:
```
public void getAsObject(FacesContext context, 
                        UIComponent component, 
                        java.lang.String value){
..
}
```
The getAsString method takes the FacesContext instance, the component, and the object to be converted to a String. For example:
```
public void 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/.
Make your custom converter implementation serializable or implement StateHolder, and the saveState(FacesContext) and restoreState(FacesContext, Object) methods of StateHolder if your application saves state on the client. For more information, see the Javadoc for the StateHolder interface of javax.faces.component.
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 the custom converters on a JSF page:

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

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 accesses the data from the component in the current FacesContext and execute the conversion logic.