org.springframework.web.bind
Class WebDataBinder

java.lang.Object
  extended by org.springframework.validation.DataBinder
      extended by org.springframework.web.bind.WebDataBinder
All Implemented Interfaces:
PropertyEditorRegistry
Direct Known Subclasses:
ServletRequestDataBinder

public class WebDataBinder
extends DataBinder

Special DataBinder to perform data binding from web request parameters to JavaBeans. Designed for web environments, but not dependent on the Servlet API; serves as base class for more specific DataBinder variants, such as ServletRequestDataBinder.

Includes support for field markers which address a common problem with HTML checkboxes and select options: detecting that a field was part of the form, but did not generate a request parameter because it was empty. A field marker allows to detect that state and reset the corresponding bean property accordingly.

Since:
1.2
Author:
Juergen Hoeller
See Also:
DataBinder.registerCustomEditor(java.lang.Class, java.beans.PropertyEditor), DataBinder.setAllowedFields(java.lang.String[]), DataBinder.setRequiredFields(java.lang.String[]), setFieldMarkerPrefix(java.lang.String), ServletRequestDataBinder

Field Summary
static String DEFAULT_FIELD_MARKER_PREFIX
          Default prefix that field marker parameters start with, followed by the field name: e.g.
 
Fields inherited from class org.springframework.validation.DataBinder
DEFAULT_OBJECT_NAME, logger
 
Constructor Summary
WebDataBinder(Object target)
          Create a new WebDataBinder instance, with default object name.
WebDataBinder(Object target, String objectName)
          Create a new WebDataBinder instance.
 
Method Summary
protected  void checkFieldMarkers(MutablePropertyValues mpvs)
          Check the given property values for field markers, i.e. for fields that start with the field marker prefix.
protected  void doBind(MutablePropertyValues mpvs)
          This implementation performs a field marker check before delegating to the superclass binding process.
protected  Object getEmptyValue(String field, Class fieldType)
          Determine an empty value for the specified field.
 String getFieldMarkerPrefix()
          Return the prefix for parameters that mark potentially empty fields.
 void setFieldMarkerPrefix(String fieldMarkerPrefix)
          Specify a prefix that can be used for parameters that mark potentially empty fields, having "prefix + field" as name.
 
Methods inherited from class org.springframework.validation.DataBinder
applyPropertyValues, bind, checkAllowedFields, checkRequiredFields, close, createErrors, findCustomEditor, getAllowedFields, getBeanWrapper, getBindingErrorProcessor, getErrors, getObjectName, getRequiredFields, getTarget, isAllowed, isIgnoreUnknownFields, registerCustomEditor, registerCustomEditor, setAllowedFields, setBindingErrorProcessor, setExtractOldValueForEditor, setIgnoreUnknownFields, setMessageCodesResolver, setRequiredFields
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_FIELD_MARKER_PREFIX

public static final String DEFAULT_FIELD_MARKER_PREFIX
Default prefix that field marker parameters start with, followed by the field name: e.g. "_subscribeToNewsletter" for a field "subscribeToNewsletter".

Such a marker parameter indicates that the field was visible respectively existed in the form that caused the submission. If no corresponding field value parameter was found, the field will be reset. This is particularly useful for HTML checkboxes and select options.

See Also:
setFieldMarkerPrefix(java.lang.String), Constant Field Values
Constructor Detail

WebDataBinder

public WebDataBinder(Object target)
Create a new WebDataBinder instance, with default object name.

Parameters:
target - target object to bind onto
See Also:
DataBinder.DEFAULT_OBJECT_NAME

WebDataBinder

public WebDataBinder(Object target,
                     String objectName)
Create a new WebDataBinder instance.

Parameters:
target - target object to bind onto
objectName - objectName of the target object
Method Detail

setFieldMarkerPrefix

public void setFieldMarkerPrefix(String fieldMarkerPrefix)
Specify a prefix that can be used for parameters that mark potentially empty fields, having "prefix + field" as name. Such a marker parameter is checked by existence: You can send any value for it, for example "visible". This is particularly useful for HTML checkboxes and select options.

Default is "_", for "_FIELD" parameters (e.g. "_subscribeToNewsletter"). Set this to null if you want to turn off the empty field check completely.

HTML checkboxes only send a value when they're checked, so it is not possible to detect that a formerly checked box has just been unchecked, at least not with standard HTML means.

One way to address this is to look for a checkbox parameter value if you know that the checkbox has been visible in the form, resetting the checkbox if no value found. In Spring web MVC, this typically happens in a custom onBind implementation.

This auto-reset mechanism addresses this deficiency, provided that a marker parameter is sent for each checkbox field, like "_subscribeToNewsletter" for a "subscribeToNewsletter" field. As the marker parameter is sent in any case, the data binder can detect an empty field and automatically reset its value.

See Also:
DEFAULT_FIELD_MARKER_PREFIX, BaseCommandController.onBind(javax.servlet.http.HttpServletRequest, java.lang.Object, org.springframework.validation.BindException)

getFieldMarkerPrefix

public String getFieldMarkerPrefix()
Return the prefix for parameters that mark potentially empty fields.


doBind

protected void doBind(MutablePropertyValues mpvs)
This implementation performs a field marker check before delegating to the superclass binding process.

Overrides:
doBind in class DataBinder
Parameters:
mpvs - the property values to bind, as MutablePropertyValues instance
See Also:
checkFieldMarkers(org.springframework.beans.MutablePropertyValues)

checkFieldMarkers

protected void checkFieldMarkers(MutablePropertyValues mpvs)
Check the given property values for field markers, i.e. for fields that start with the field marker prefix.

The existence of a field marker indicates that the specified field existed in the form. If the property values do not contain a corresponding field value, the field will be considered as empty and will be reset appropriately.

Parameters:
mpvs - the property values to be bound (can be modified)
See Also:
getFieldMarkerPrefix(), getEmptyValue(String, Class)

getEmptyValue

protected Object getEmptyValue(String field,
                               Class fieldType)
Determine an empty value for the specified field.

Default implementation returns Boolean.FALSE for boolean fields and an empty array of array types. Else, null is used as default.

Parameters:
field - the name of the field
fieldType - the type of the field
Returns:
the empty value (for most fields: null)


Copyright (c) 2002-2006 The Spring Framework Project.