public class WebDataBinder extends DataBinder
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.
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
Modifier and Type | Field and Description |
---|---|
static String |
DEFAULT_FIELD_DEFAULT_PREFIX
Default prefix that field default parameters start with, followed by the field
name: e.g.
|
static String |
DEFAULT_FIELD_MARKER_PREFIX
Default prefix that field marker parameters start with, followed by the field
name: e.g.
|
DEFAULT_AUTO_GROW_COLLECTION_LIMIT, DEFAULT_OBJECT_NAME, logger
Constructor and Description |
---|
WebDataBinder(Object target)
Create a new WebDataBinder instance, with default object name.
|
WebDataBinder(Object target,
String objectName)
Create a new WebDataBinder instance.
|
Modifier and Type | Method and Description |
---|---|
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).
|
protected void |
bindMultipartFiles(Map<String,MultipartFile> multipartFiles,
MutablePropertyValues mpvs)
Deprecated.
as of Spring 3.0, in favor of
bindMultipart(java.util.Map<java.lang.String, java.util.List<org.springframework.web.multipart.MultipartFile>>, org.springframework.beans.MutablePropertyValues) which binds
all multipart files, even if more than one sent for the same name |
protected void |
checkFieldDefaults(MutablePropertyValues mpvs)
Check the given property values for field defaults,
i.e.
|
protected void |
checkFieldMarkers(MutablePropertyValues mpvs)
Check the given property values for field markers,
i.e.
|
protected void |
doBind(MutablePropertyValues mpvs)
This implementation performs a field default and 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 |
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.
|
applyPropertyValues, bind, checkAllowedFields, checkRequiredFields, close, convertIfNecessary, convertIfNecessary, convertIfNecessary, findCustomEditor, getAllowedFields, getAutoGrowCollectionLimit, getBindingErrorProcessor, getBindingResult, getConversionService, getDisallowedFields, getErrors, getInternalBindingResult, getObjectName, getPropertyAccessor, getPropertyEditorRegistry, getRequiredFields, getSimpleTypeConverter, getTarget, getTypeConverter, getValidator, initBeanPropertyAccess, initDirectFieldAccess, isAllowed, isAutoGrowNestedPaths, isIgnoreInvalidFields, isIgnoreUnknownFields, registerCustomEditor, registerCustomEditor, setAllowedFields, setAutoGrowCollectionLimit, setAutoGrowNestedPaths, setBindingErrorProcessor, setConversionService, setDisallowedFields, setExtractOldValueForEditor, setIgnoreInvalidFields, setIgnoreUnknownFields, setMessageCodesResolver, setRequiredFields, setValidator, validate, validate
public static final String DEFAULT_FIELD_MARKER_PREFIX
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 static final String DEFAULT_FIELD_DEFAULT_PREFIX
Default parameters differ from field markers in that they provide a default value instead of an empty value.
public WebDataBinder(Object target)
target
- the target object to bind onto (or null
if the binder is just used to convert a plain parameter value)DataBinder.DEFAULT_OBJECT_NAME
public void setFieldMarkerPrefix(String fieldMarkerPrefix)
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.
public String getFieldMarkerPrefix()
public void setFieldDefaultPrefix(String fieldDefaultPrefix)
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 String getFieldDefaultPrefix()
public void setBindEmptyMultipartFiles(boolean bindEmptyMultipartFiles)
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.
MultipartFile
public boolean isBindEmptyMultipartFiles()
protected void doBind(MutablePropertyValues mpvs)
doBind
in class DataBinder
mpvs
- the property values to bind,
as MutablePropertyValues instancecheckFieldDefaults(org.springframework.beans.MutablePropertyValues)
,
checkFieldMarkers(org.springframework.beans.MutablePropertyValues)
protected void checkFieldDefaults(MutablePropertyValues mpvs)
The existence of a field defaults indicates that the specified value should be used if the field is otherwise not present.
mpvs
- the property values to be bound (can be modified)getFieldDefaultPrefix()
protected void checkFieldMarkers(MutablePropertyValues mpvs)
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.
mpvs
- the property values to be bound (can be modified)getFieldMarkerPrefix()
,
getEmptyValue(String, Class)
protected Object getEmptyValue(String field, Class fieldType)
Default implementation returns Boolean.FALSE
for boolean fields and an empty array of array types.
Else, null
is used as default.
field
- the name of the fieldfieldType
- the type of the field@Deprecated protected void bindMultipartFiles(Map<String,MultipartFile> multipartFiles, MutablePropertyValues mpvs)
bindMultipart(java.util.Map<java.lang.String, java.util.List<org.springframework.web.multipart.MultipartFile>>, org.springframework.beans.MutablePropertyValues)
which binds
all multipart files, even if more than one sent for the same nameMultipart 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.
multipartFiles
- Map of field name String to MultipartFile objectmpvs
- the property values to be bound (can be modified)MultipartFile
,
setBindEmptyMultipartFiles(boolean)
protected void bindMultipart(Map<String,List<MultipartFile>> multipartFiles, MutablePropertyValues mpvs)
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.
multipartFiles
- Map of field name String to MultipartFile objectmpvs
- the property values to be bound (can be modified)MultipartFile
,
setBindEmptyMultipartFiles(boolean)