public class

WebDataBinder

extends DataBinder

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

Known Direct Subclasses

PortletRequestDataBinder, ServletRequestDataBinder, WebRequestDataBinder

Class Overview

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

Summary

Constants
String	DEFAULT_FIELD_DEFAULT_PREFIX	Default prefix that field default parameters start with, followed by the field name: e.g.
String	DEFAULT_FIELD_MARKER_PREFIX	Default prefix that field marker parameters start with, followed by the field name: e.g.

[Expand]

Inherited Constants

From class org.springframework.validation.DataBinder

[Expand]

Inherited Fields

From class org.springframework.validation.DataBinder

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

Public Methods
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.
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.

Protected Methods
void	bindMultipart(Map<String, List<MultipartFile>> multipartFiles, MutablePropertyValues mpvs) Bind all multipart files contained in the given request, if any (in case of a multipart request).
void	bindMultipartFiles(Map<String, MultipartFile> multipartFiles, MutablePropertyValues mpvs) This method is deprecated. as of Spring 3.0, in favor of `bindMultipart(Map>, MutablePropertyValues)` which binds all multipart files, even if more than one sent for the same name
void	checkFieldDefaults(MutablePropertyValues mpvs) Check the given property values for field defaults, i.e.
void	checkFieldMarkers(MutablePropertyValues mpvs) Check the given property values for field markers, i.e.
void	doBind(MutablePropertyValues mpvs) This implementation performs a field default and marker check before delegating to the superclass binding process.
Object	getEmptyValue(String field, Class fieldType) Determine an empty value for the specified field.

[Expand]

Inherited Methods

From class org.springframework.validation.DataBinder

void	applyPropertyValues(MutablePropertyValues mpvs) Apply given property values to the target object.
void	bind(PropertyValues pvs) Bind the given property values to this binder's target.
void	checkAllowedFields(MutablePropertyValues mpvs) Check the given property values against the allowed fields, removing values for fields that are not allowed.
void	checkRequiredFields(MutablePropertyValues mpvs) Check the given property values against the required fields, generating missing field errors where appropriate.
Map	close() Close this DataBinder, which may result in throwing a BindException if it encountered any errors.
<T> T	convertIfNecessary(Object value, Class<T> requiredType) Convert the value to the required type (if necessary from a String).
<T> T	convertIfNecessary(Object value, Class<T> requiredType, MethodParameter methodParam) Convert the value to the required type (if necessary from a String).
void	doBind(MutablePropertyValues mpvs) Actual implementation of the binding process, working with the passed-in MutablePropertyValues instance.
PropertyEditor	findCustomEditor(Class requiredType, String propertyPath) Find a custom property editor for the given type and property.
String[]	getAllowedFields() Return the fields that should be allowed for binding.
BindingErrorProcessor	getBindingErrorProcessor() Return the strategy for processing binding errors.
BindingResult	getBindingResult() Return the BindingResult instance created by this DataBinder.
ConversionService	getConversionService() Return the associated ConversionService, if any.
String[]	getDisallowedFields() Return the fields that should not be allowed for binding.
BindException	getErrors() This method is deprecated. in favor of `getBindingResult()`. Use the `BindException(BindingResult)` constructor to create a BindException instance if still needed.
AbstractPropertyBindingResult	getInternalBindingResult() Return the internal BindingResult held by this DataBinder, as AbstractPropertyBindingResult.
String	getObjectName() Return the name of the bound object.
ConfigurablePropertyAccessor	getPropertyAccessor() Return the underlying PropertyAccessor of this binder's BindingResult.
PropertyEditorRegistry	getPropertyEditorRegistry() Return the underlying TypeConverter of this binder's BindingResult.
String[]	getRequiredFields() Return the fields that are required for each binding process.
SimpleTypeConverter	getSimpleTypeConverter() Return this binder's underlying SimpleTypeConverter.
Object	getTarget() Return the wrapped target object.
TypeConverter	getTypeConverter() Return the underlying TypeConverter of this binder's BindingResult.
Validator	getValidator() Return the Validator to apply after each binding step, if any.
void	initBeanPropertyAccess() Initialize standard JavaBean property access for this DataBinder.
void	initDirectFieldAccess() Initialize direct field access for this DataBinder, as alternative to the default bean property access.
boolean	isAllowed(String field) Return if the given field is allowed for binding.
boolean	isAutoGrowNestedPaths() Return whether "auto-growing" of nested paths has been activated.
boolean	isIgnoreInvalidFields() Return whether to ignore invalid fields when binding.
boolean	isIgnoreUnknownFields() Return whether to ignore unknown fields when binding.
void	registerCustomEditor(Class requiredType, String field, PropertyEditor propertyEditor) Register the given custom property editor for the given type and property, or for all properties of the given type.
void	registerCustomEditor(Class requiredType, PropertyEditor propertyEditor) Register the given custom property editor for all properties of the given type.
void	setAllowedFields(String... allowedFields) Register fields that should be allowed for binding.
void	setAutoGrowNestedPaths(boolean autoGrowNestedPaths) Set whether this binder should attempt to "auto-grow" a nested path that contains a null value.
void	setBindingErrorProcessor(BindingErrorProcessor bindingErrorProcessor) Set the strategy to use for processing binding errors, that is, required field errors and `PropertyAccessException`s.
void	setConversionService(ConversionService conversionService) Specify a Spring 3.0 ConversionService to use for converting property values, as an alternative to JavaBeans PropertyEditors.
void	setDisallowedFields(String... disallowedFields) Register fields that should not be allowed for binding.
void	setExtractOldValueForEditor(boolean extractOldValueForEditor) Set whether to extract the old field value when applying a property editor to a new value for a field.
void	setIgnoreInvalidFields(boolean ignoreInvalidFields) Set whether to ignore invalid fields, that is, whether to ignore bind parameters that have corresponding fields in the target object which are not accessible (for example because of null values in the nested path).
void	setIgnoreUnknownFields(boolean ignoreUnknownFields) Set whether to ignore unknown fields, that is, whether to ignore bind parameters that do not have corresponding fields in the target object.
void	setMessageCodesResolver(MessageCodesResolver messageCodesResolver) Set the strategy to use for resolving errors into message codes.
void	setRequiredFields(String... requiredFields) Register fields that are required for each binding process.
void	setValidator(Validator validator) Set the Validator to apply after each binding step.
void	validate() Invoke the specified Validator, if any.

From class java.lang.Object

From interface org.springframework.beans.PropertyEditorRegistry

From interface org.springframework.beans.TypeConverter

Constants

public static final String DEFAULT_FIELD_DEFAULT_PREFIX

Default prefix that field default parameters start with, followed by the field name: e.g. "!subscribeToNewsletter" for a field "subscribeToNewsletter".

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

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.

Public Constructors

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)

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

Public Methods

public String getFieldDefaultPrefix ()

Return the prefix for parameters that mark default fields.

public String getFieldMarkerPrefix ()

Return the prefix for parameters that mark potentially empty fields.

public boolean isBindEmptyMultipartFiles ()

Return whether to bind empty MultipartFile parameters.

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.

public void setFieldDefaultPrefix (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 (e.g. "!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.

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.

Protected Methods

protected void bindMultipart (Map<String, List<MultipartFile>> multipartFiles, MutablePropertyValues mpvs)

Bind all 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)

protected void bindMultipartFiles (Map<String, MultipartFile> multipartFiles, MutablePropertyValues mpvs)

This method is deprecated.
as of Spring 3.0, in favor of bindMultipart(Map>, MutablePropertyValues) which binds all multipart files, even if more than one sent for the same name

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)

protected void checkFieldDefaults (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)

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)

protected void doBind (MutablePropertyValues mpvs)

This implementation performs a field default and marker check before delegating to the superclass binding process.

Parameters

mpvs	the property values to bind, as MutablePropertyValues instance

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)

Classes

Exceptions

WebDataBinder

Class Overview

See Also

Summary

Constants

public static final String DEFAULT_FIELD_DEFAULT_PREFIX

See Also

public static final String DEFAULT_FIELD_MARKER_PREFIX

See Also

Public Constructors

public WebDataBinder (Object target)

Parameters

See Also

public WebDataBinder (Object target, String objectName)

Parameters

Public Methods

public String getFieldDefaultPrefix ()

public String getFieldMarkerPrefix ()

public boolean isBindEmptyMultipartFiles ()

public void setBindEmptyMultipartFiles (boolean bindEmptyMultipartFiles)

See Also

public void setFieldDefaultPrefix (String fieldDefaultPrefix)

See Also

public void setFieldMarkerPrefix (String fieldMarkerPrefix)

See Also

Protected Methods

protected void bindMultipart (Map<String, List<MultipartFile>> multipartFiles, MutablePropertyValues mpvs)

Parameters

See Also

protected void bindMultipartFiles (Map<String, MultipartFile> multipartFiles, MutablePropertyValues mpvs)

Parameters

See Also

protected void checkFieldDefaults (MutablePropertyValues mpvs)

Parameters

See Also

protected void checkFieldMarkers (MutablePropertyValues mpvs)

Parameters

See Also

protected void doBind (MutablePropertyValues mpvs)

Parameters

See Also

protected Object getEmptyValue (String field, Class fieldType)

Parameters

Returns