Skip Headers

Oracle® Application Development Framework Developer's Guide 10g Release 3 (10.1.3) B25386-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 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:

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

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

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

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

1. Write a JavaScript version of the converter, passing relevant information to a constructor.

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

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