Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| The Spring Framework
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.springframework.web.bind
Class WebDataBinder

    java.lang.Object
      org.springframework.validation.DataBinder
          org.springframework.web.bind.WebDataBinder

All Implemented Interfaces:
  PropertyEditorRegistry, TypeConverter

Direct Known Subclasses:
  PortletRequestDataBinder, ServletRequestDataBinder, WebRequestDataBinder

    public class WebDataBinder

extends DataBinder

Special `DataBinder` for data binding from web request parameters to JavaBean objects. 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` | `bindMultipartFiles(Map multipartFiles, MutablePropertyValues mpvs)` Bind the multipart files contained in the given request, if any (in case of a multipart request).
`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.
`boolean` | `isBindEmptyMultipartFiles()` Return whether to bind empty MultipartFile parameters.
`void` | `setBindEmptyMultipartFiles(boolean bindEmptyMultipartFiles)` Set whether to bind empty MultipartFile parameters.
`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, convertIfNecessary, convertIfNecessary, findCustomEditor, getAllowedFields, getBindingErrorProcessor, getBindingResult, getDisallowedFields, getErrors, getInternalBindingResult, getObjectName, getPropertyAccessor, getPropertyEditorRegistry, getRequiredFields, getSimpleTypeConverter, getTarget, getTypeConverter, initBeanPropertyAccess, initDirectFieldAccess, isAllowed, isIgnoreInvalidFields, isIgnoreUnknownFields, registerCustomEditor, registerCustomEditor, setAllowedFields, setBindingErrorProcessor, setDisallowedFields, setExtractOldValueForEditor, setIgnoreInvalidFields, 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, that is, existed in the form that caused the submission. If no corresponding field value parameter was found, the field will be reset. The value of the field marker parameter does not matter in this case; an arbitrary value can be used. 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` - the target object to bind onto (or `null` if the binder is just used to convert a plain parameter value)
  See Also:
    `DataBinder.DEFAULT_OBJECT_NAME`

### WebDataBinder

    public WebDataBinder(Object target,
                         String objectName)

  Create a new WebDataBinder instance.

  Parameters:
    `target` - the target object to bind onto (or `null` if the binder is just used to convert a plain parameter value)
    `objectName` - the name 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.

### setBindEmptyMultipartFiles

    public void setBindEmptyMultipartFiles(boolean bindEmptyMultipartFiles)

  Set whether to bind empty MultipartFile parameters. Default is "true".

  Turn this off if you want to keep an already bound MultipartFile when the user resubmits the form without choosing a different file. Else, the already bound MultipartFile will be replaced by an empty MultipartFile holder.

  See Also:
    `MultipartFile`

### isBindEmptyMultipartFiles

    public boolean isBindEmptyMultipartFiles()

  Return whether to bind empty MultipartFile parameters.

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

### bindMultipartFiles

    protected void bindMultipartFiles(Map multipartFiles,
                                      MutablePropertyValues mpvs)

  Bind the multipart files contained in the given request, if any (in case of a multipart request).

  Multipart files will only be added to the property values if they are not empty or if we're configured to bind empty multipart files too.

  Parameters:
    `multipartFiles` - Map of field name String to MultipartFile object
    `mpvs` - the property values to be bound (can be modified)
  See Also:
    `MultipartFile`, `setBindEmptyMultipartFiles(boolean)`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| The Spring Framework
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002-2008 The Spring Framework.