Package org.springframework.web.bind

# Class WebDataBinder

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

All Implemented Interfaces:
  `org.springframework.beans.PropertyEditorRegistry`, `org.springframework.beans.TypeConverter`

Direct Known Subclasses:
  `ServletRequestDataBinder`, `WebExchangeDataBinder`, `WebRequestDataBinder`

public class WebDataBinder extends org.springframework.validation.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`.

WARNING: Data binding can lead to security issues by exposing parts of the object graph that are not meant to be accessed or modified by external clients. Therefore, the design and use of data binding should be considered carefully with regard to security. For more details, please refer to the dedicated sections on data binding for Spring Web MVC and Spring WebFlux in the reference manual.

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. Default values, for parameters that are otherwise not present, can specify a value for the field other than empty.

Since:
  1.2
Author:
  Juergen Hoeller, Scott Andrews, Brian Clozel
See Also:
  - `DataBinder.registerCustomEditor(java.lang.Class<?>, java.beans.PropertyEditor)`
  - `DataBinder.setAllowedFields(java.lang.String...)`
  - `DataBinder.setRequiredFields(java.lang.String...)`
  - `setFieldMarkerPrefix(java.lang.String)`
  - `setFieldDefaultPrefix(java.lang.String)`
  - `ServletRequestDataBinder`

## Nested Class Summary

## Nested classes/interfaces inherited from class org.springframework.validation.DataBinder

`org.springframework.validation.DataBinder.NameResolver, org.springframework.validation.DataBinder.ValueResolver`

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`DEFAULT_FIELD_DEFAULT_PREFIX`
Default prefix that field default parameters start with, followed by the field name: for example, "!subscribeToNewsletter" for a field "subscribeToNewsletter".
`static final String`
`DEFAULT_FIELD_MARKER_PREFIX`
Default prefix that field marker parameters start with, followed by the field name: for example, "_subscribeToNewsletter" for a field "subscribeToNewsletter".

### Fields inherited from class org.springframework.validation.DataBinder

`DEFAULT_AUTO_GROW_COLLECTION_LIMIT, DEFAULT_OBJECT_NAME, logger`

## Constructor Summary

Constructors
Constructor
Description
`WebDataBinder(Object target)`
Create a new WebDataBinder instance, with default object name.
`WebDataBinder(Object target, String objectName)`
Create a new WebDataBinder instance.

## Method Summary

Modifier and Type
Method
Description
`protected void`
`adaptEmptyArrayIndices(org.springframework.beans.MutablePropertyValues mpvs)`
Check for property values with names that end on `"[]"`.
`protected void`
`bindMultipart(Map<String,List<MultipartFile>> multipartFiles, org.springframework.beans.MutablePropertyValues mpvs)`
Bind all multipart files contained in the given request, if any (in case of a multipart request).
`protected void`
`checkFieldDefaults(org.springframework.beans.MutablePropertyValues mpvs)`
Check the given property values for field defaults, i.e.
`protected void`
`checkFieldMarkers(org.springframework.beans.MutablePropertyValues mpvs)`
Check the given property values for field markers, i.e.
`protected void`
`doBind(org.springframework.beans.MutablePropertyValues mpvs)`
This implementation performs a field default and marker check before delegating to the superclass binding process.
`Object`
`getEmptyValue(Class<?> fieldType)`
Determine an empty value for the specified field.
`protected Object`
`getEmptyValue(String field, Class<?> fieldType)`
Determine an empty value for the specified field.
`String`
`getFieldDefaultPrefix()`
Return the prefix for parameters that mark default fields.
`String`
`getFieldMarkerPrefix()`
Return the prefix for parameters that mark potentially empty fields.
`boolean`
`isBindEmptyMultipartFiles()`
Return whether to bind empty MultipartFile parameters.
`protected Object`
`resolvePrefixValue(String name, Class<?> type, BiFunction<String,Class<?>,Object> resolver)`
Check if a value can be resolved if `getFieldDefaultPrefix()` or `getFieldMarkerPrefix()` is prepended.
`void`
`setBindEmptyMultipartFiles(boolean bindEmptyMultipartFiles)`
Set whether to bind empty MultipartFile parameters.
`void`
`setFieldDefaultPrefix(String fieldDefaultPrefix)`
Specify a prefix that can be used for parameters that indicate default value fields, having "prefix + field" as name.
`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

`addCustomFormatter, addCustomFormatter, addCustomFormatter, addValidators, applyPropertyValues, bind, checkAllowedFields, checkRequiredFields, close, construct, convertIfNecessary, convertIfNecessary, convertIfNecessary, convertIfNecessary, createBeanPropertyBindingResult, createDirectFieldBindingResult, findCustomEditor, getAllowedFields, getAutoGrowCollectionLimit, getBindingErrorProcessor, getBindingResult, getConversionService, getDisallowedFields, getInternalBindingResult, getNameResolver, getObjectName, getPropertyAccessor, getPropertyEditorRegistry, getRequiredFields, getSimpleTypeConverter, getTarget, getTargetType, getTypeConverter, getValidator, getValidators, getValidatorsToApply, initBeanPropertyAccess, initDirectFieldAccess, isAllowed, isAutoGrowNestedPaths, isDeclarativeBinding, isIgnoreInvalidFields, isIgnoreUnknownFields, registerCustomEditor, registerCustomEditor, replaceValidators, setAllowedFields, setAutoGrowCollectionLimit, setAutoGrowNestedPaths, setBindingErrorProcessor, setConversionService, setDeclarativeBinding, setDisallowedFields, setExcludedValidators, setIgnoreInvalidFields, setIgnoreUnknownFields, setMessageCodesResolver, setNameResolver, setRequiredFields, setTargetType, setValidator, shouldConstructArgument, shouldNotBindPropertyValues, validate, validate`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### 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: for example, "_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

### DEFAULT_FIELD_DEFAULT_PREFIX

public static final String DEFAULT_FIELD_DEFAULT_PREFIX
Default prefix that field default parameters start with, followed by the field name: for example, "!subscribeToNewsletter" for a field "subscribeToNewsletter".

Default parameters differ from field markers in that they provide a default value instead of an empty value.

See Also:
  - `setFieldDefaultPrefix(java.lang.String)`
  - Constant Field Values

## Constructor Details

### WebDataBinder

public WebDataBinder(@Nullable 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(@Nullable 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 Details

### setFieldMarkerPrefix

public void setFieldMarkerPrefix(@Nullable 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 (for example, "_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`

### getFieldMarkerPrefix

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

### setFieldDefaultPrefix

public void setFieldDefaultPrefix(@Nullable String fieldDefaultPrefix)
Specify a prefix that can be used for parameters that indicate default value fields, having "prefix + field" as name. The value of the default field is used when the field is not provided.

Default is "!", for "!FIELD" parameters (for example, "!subscribeToNewsletter"). Set this to null if you want to turn off the field defaults 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. A default field is especially useful when a checkbox represents a non-boolean value.

The presence of a default parameter preempts the behavior of a field marker for the given field.

See Also:
  - `DEFAULT_FIELD_DEFAULT_PREFIX`

### getFieldDefaultPrefix

@Nullable public String getFieldDefaultPrefix()
Return the prefix for parameters that mark default 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.

### resolvePrefixValue

@Nullable protected Object resolvePrefixValue(String name, Class<?> type, BiFunction<String,Class<?>,Object> resolver)
Check if a value can be resolved if `getFieldDefaultPrefix()` or `getFieldMarkerPrefix()` is prepended.

Parameters:
  `name` - the name of the value to resolve
  `type` - the type of value expected
  `resolver` - delegate resolver to use for the checks
Returns:
  the resolved value, or `null`
Since:
  6.1

### doBind

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

Overrides:
  `doBind` in class `org.springframework.validation.DataBinder`
See Also:
  - `checkFieldDefaults(org.springframework.beans.MutablePropertyValues)`
  - `checkFieldMarkers(org.springframework.beans.MutablePropertyValues)`

### checkFieldDefaults

protected void checkFieldDefaults(org.springframework.beans.MutablePropertyValues mpvs)
Check the given property values for field defaults, i.e. for fields that start with the field default prefix.

The existence of a field defaults indicates that the specified value should be used if the field is otherwise not present.

Parameters:
  `mpvs` - the property values to be bound (can be modified)
See Also:
  - `getFieldDefaultPrefix()`

### checkFieldMarkers

protected void checkFieldMarkers(org.springframework.beans.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)`

### adaptEmptyArrayIndices

protected void adaptEmptyArrayIndices(org.springframework.beans.MutablePropertyValues mpvs)
Check for property values with names that end on `"[]"`. This is used by some clients for array syntax without an explicit index value. If such values are found, drop the brackets to adapt to the expected way of expressing the same for data binding purposes.

Parameters:
  `mpvs` - the property values to be bound (can be modified)
Since:
  5.3

### getEmptyValue

@Nullable protected Object getEmptyValue(String field, @Nullable Class<?> fieldType)
Determine an empty value for the specified field.

The default implementation delegates to `getEmptyValue(Class)` if the field type is known, otherwise falls back to `null`.

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

### getEmptyValue

@Nullable public Object getEmptyValue(Class<?> fieldType)
Determine an empty value for the specified field.

The default implementation returns:

- `Boolean.FALSE` for boolean fields
- an empty array for array types
- Collection implementations for Collection types
- Map implementations for Map types
- else, `null` is used as default

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

### bindMultipart

protected void bindMultipart(Map<String,List<MultipartFile>> multipartFiles, org.springframework.beans.MutablePropertyValues mpvs)
Bind all multipart files contained in the given request, if any (in case of a multipart request). To be called by subclasses.

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` - a Map of field name String to MultipartFile object
  `mpvs` - the property values to be bound (can be modified)
See Also:
  - `MultipartFile`
  - `setBindEmptyMultipartFiles(boolean)`