Binding

Default Ognl-base binding

By default all binding of fields to Controllers is handled by Ognl. Waffle's OgnlControllerDataBinder allows for the injection of a ValueConverterFinder, which by default is only configured to use OgnlValueConverter, but can be customized to use any number of Waffle ValueConverters. The OgnlValueConverter allows fields of standard types (e.g. String, Number, primitives) to be bound to your controllers automatically.

A common binding problem that many web application need to deal with is how to bind a String value to a Date object. Of course each application and locale has it's own unique format. As an example we will build a class that supports binding to a Date. From this example you'll gain an understanding of how to bind to any Class type.

Suppose we have the following Controller class ControllerWithDateField which has one field startDate which is of course a java.util.Date:

You could imagine that the request to set this date field would be something similar to startDate=04-07-2006. So inorder to bind this to the underlying Controller we will need to create a custom class that will handle conversion for a specific type(s).

Custom binding using ValueConverters

Implementation of the ValueConverter interface is needed to handle these custom value conversions. This interface defines two methods:

Method Description
boolean accept(Class type) determine whether this implementation can handle conversions for the class type passed.
Object convertValue(String propertyName, String value, Class type) responsible for handling the conversion (only called if implementation returned true from the accept() method.

Nothing clarifies a description better than an example so lets look at the implementation Waffle provides for handling Date types:

Now all that is left is to register this converter within the web.xml

Waffle Custom ValueConverters

Waffle provides for the users' convenience custom ValueConverter for common types, such as Date or List. These need to be registered in the web.xml and of course can be replaced with other custom implementations.

ValueConverter Description
org.codehaus.waffle.bind.converters.DateValueConverter Converts date values with configurable date format and error messages.
org.codehaus.waffle.bind.converters.EnumValueConverter Converts enum values. Included by default in org.codehaus.waffle.bind.ognl.OgnlValueConverterFinder
org.codehaus.waffle.bind.converters.NumberValueConverter Converts number values with configurable number format.
org.codehaus.waffle.bind.converters.NumberListValueConverter Converts CSV Number values to Lists with configurable error message using the injectable NumberFormat instance, which defaults to NumberFormat.getInstance().
org.codehaus.waffle.bind.converters.StringListValueConverter Converts CSV String values to Lists with configurable error messages.
org.codehaus.waffle.bind.converters.StringListMapValueConverter Converts Properties-like String=CSV-String values to Maps with configurable error messages.
org.codehaus.waffle.bind.converters.StringNumberListMapValueConverter Converts Properties-like String=CSV-Number values to Maps with configurable error messages.

Note that by default these converters handle missing values (ie null or empty) by return a null converted value, The behaviour can be nonetheless overridden by extending the converters to throw a new BindException in the convertMissingValue method: