org.springframework.validation
Class DataBinder

public class DataBinder
implements PropertyEditorRegistry
Binder that allows for binding property values to a target object. The binding process can be customized through specifying allowed fields, required fields, and custom editors.

Note that there are potential security implications in failing to set an array of allowed fields. In the case of HTTP form POST data for example, malicious clients can attempt to subvert an application by supplying values for fields or properties that do not exist on the form. In some cases this could lead to illegal data being set on command objects or their nested objects. For this reason, it is highly recommended to specify the allowedFields property on the DataBinder.

The binding results can be examined via the Errors interface, available as BindException instance. Missing field errors and property access exceptions will be converted to FieldErrors, collected in the Errors instance, with the following error codes:

  • Missing field error: "required"
  • Type mismatch error: "typeMismatch"
  • Method invocation error: "methodInvocation"

Custom validation errors can be added afterwards. You will typically want to resolve such error codes into proper user-visible error messages; this can be achieved through resolving each error via a MessageSource. The list of message codes to try can be customized through the MessageCodesResolver strategy. DefaultMessageCodesResolver's javadoc gives details on the default resolution rules.

By default, binding errors are resolved through the binding error processor for required binding errors and property access exceptions. You can override those if needed, for example to generate different error codes.

This generic data binder can be used in any sort of environment. It is heavily used by Spring's web MVC controllers, via the subclass org.springframework.web.bind.ServletRequestDataBinder.

SinceNot specified.
VersionNot specified.
AuthorRod Johnson, Juergen Hoeller
Wiki javadoc Use textile entry format.
Add your comments here.
Field Summary
static String DEFAULT_OBJECT_NAME
Default object name used for binding: "target"
protected static Log logger
We'll create a lot of DataBinder instances: Let's use a static logger.
Constructor Summary
DataBinder( Object target )
Create a new DataBinder instance, with default object name.
DataBinder( Object target, String objectName )
Create a new DataBinder instance.
Method Summary
protected 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.
protected void checkAllowedFields( MutablePropertyValues mpvs )
Check the given property values against the allowed fields, removing values for fields that are not allowed.
protected 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
protected BindException createErrors( Object target, String objectName )
Create a new Errors instance for this data binder.
protected void doBind( MutablePropertyValues mpvs )
Actual implementation of the binding process, working with the passed-in MutablePropertyValues instance.
PropertyEditor findCustomEditor( Class requiredType, String propertyPath )
No description provided.
String[] getAllowedFields()
Return the fields that should be allowed for binding.
protected BeanWrapper getBeanWrapper()
Return the underlying BeanWrapper of the Errors object.
BindingErrorProcessor getBindingErrorProcessor()
Return the strategy for processing binding errors.
BindException getErrors()
Return the Errors instance for this data binder.
String getObjectName()
Return the name of the bound object.
String[] getRequiredFields()
Return the fields that are required for each binding process.
Object getTarget()
Return the wrapped target object.
protected boolean isAllowed( String field )
Return if the given field is allowed for binding.
boolean isIgnoreUnknownFields()
Return whether to ignore unknown fields, i.e.
void registerCustomEditor( Class requiredType, PropertyEditor propertyEditor )
No description provided.
void registerCustomEditor( Class requiredType, String field, PropertyEditor propertyEditor )
No description provided.
void setAllowedFields( String [] allowedFields )
Register fields that should be allowed for binding.
void setBindingErrorProcessor( BindingErrorProcessor bindingErrorProcessor )
Set the strategy to use for processing binding errors, that is, required field errors and PropertyAccessExceptions.
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 setIgnoreUnknownFields( boolean ignoreUnknownFields )
Set whether to ignore unknown fields, i.e.
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.
DEFAULT_OBJECT_NAME
public static String DEFAULT_OBJECT_NAME
Default object name used for binding: "target"
Wiki javadoc Use textile entry format.
Add your comments here.
logger
protected static Log logger
We'll create a lot of DataBinder instances: Let's use a static logger.
Wiki javadoc Use textile entry format.
Add your comments here.
DataBinder
public DataBinder ( Object target )
Create a new DataBinder instance, with default object name.
Parameters
TypeNameDescription
Object target target object to bind onto
Wiki javadoc Use textile entry format.
Add your comments here.
DataBinder
public DataBinder ( Object target, String objectName )
Create a new DataBinder instance.
Parameters
TypeNameDescription
Object target target object to bind onto
String objectName name of the target object
Wiki javadoc Use textile entry format.
Add your comments here.
applyPropertyValues
protected void applyPropertyValues ( MutablePropertyValues mpvs )
Apply given property values to the target object.

Default implementation applies them all of them as bean property values via the corresponding BeanWrapper. Unknown fields will by default be ignored.

Parameters
TypeNameDescription
MutablePropertyValues mpvs the property values to be bound (can be modified)
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
bind
public void bind ( PropertyValues pvs )
Bind the given property values to this binder's target.

This call can create field errors, representing basic binding errors like a required field (code "required"), or type mismatch between value and bean property (code "typeMismatch").

Note that the given PropertyValues should be a throwaway instance: For efficiency, it will be modified to just contain allowed fields if it implements the MutablePropertyValues interface; else, an internal mutable copy will be created for this purpose. Pass in a copy of the PropertyValues if you want your original instance to stay unmodified in any case.

Parameters
TypeNameDescription
PropertyValues pvs property values to bind
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
checkAllowedFields
protected void checkAllowedFields ( MutablePropertyValues mpvs )
Check the given property values against the allowed fields, removing values for fields that are not allowed.
Parameters
TypeNameDescription
MutablePropertyValues mpvs the property values to be bound (can be modified)
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
checkRequiredFields
protected void checkRequiredFields ( MutablePropertyValues mpvs )
Check the given property values against the required fields, generating missing field errors where appropriate.
Parameters
TypeNameDescription
MutablePropertyValues mpvs the property values to be bound (can be modified)
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
close
public Map close ( )
throws
Close this DataBinder, which may result in throwing a BindException if it encountered any errors
Exceptions
BindException if there were any errors in the bind operation
See also
Wiki javadoc Use textile entry format.
Add your comments here.
createErrors
protected BindException createErrors ( Object target, String objectName )
Create a new Errors instance for this data binder. Can be overridden in subclasses to. Needs to be a subclass of BindException.
Parameters
TypeNameDescription
Object target target object to bind onto
String objectName name of the target object
See also
Wiki javadoc Use textile entry format.
Add your comments here.
doBind
protected void doBind ( MutablePropertyValues mpvs )
Actual implementation of the binding process, working with the passed-in MutablePropertyValues instance.
Parameters
TypeNameDescription
MutablePropertyValues mpvs the property values to bind, as MutablePropertyValues instance
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
findCustomEditor
public PropertyEditor findCustomEditor ( Class requiredType, String propertyPath )
No description provided.
Implements method in PropertyEditorRegistry
Parameters
TypeNameDescription
Class requiredType No description provided.
String propertyPath No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
getAllowedFields
public String[] getAllowedFields ( )
Return the fields that should be allowed for binding.
Wiki javadoc Use textile entry format.
Add your comments here.
getBeanWrapper
protected BeanWrapper getBeanWrapper ( )
Return the underlying BeanWrapper of the Errors object. To be used by binder subclasses that need bean property checks.
Wiki javadoc Use textile entry format.
Add your comments here.
getBindingErrorProcessor
public BindingErrorProcessor getBindingErrorProcessor ( )
Return the strategy for processing binding errors.
Wiki javadoc Use textile entry format.
Add your comments here.
getErrors
public BindException getErrors ( )
Return the Errors instance for this data binder.
See also
Wiki javadoc Use textile entry format.
Add your comments here.
getObjectName
public String getObjectName ( )
Return the name of the bound object.
Wiki javadoc Use textile entry format.
Add your comments here.
getRequiredFields
public String[] getRequiredFields ( )
Return the fields that are required for each binding process.
Wiki javadoc Use textile entry format.
Add your comments here.
getTarget
public Object getTarget ( )
Return the wrapped target object.
Wiki javadoc Use textile entry format.
Add your comments here.
isAllowed
protected boolean isAllowed ( String field )
Return if the given field is allowed for binding. Invoked for each passed-in property value.

The default implementation checks for "xxx*" and "*xxx" matches. Can be overridden in subclasses.

If the field is found in the allowedFields array as direct match, this method will not be invoked.

Parameters
TypeNameDescription
String field the field to check
Wiki javadoc Use textile entry format.
Add your comments here.
isIgnoreUnknownFields
public boolean isIgnoreUnknownFields ( )
Return whether to ignore unknown fields, i.e. whether to ignore request parameters that don't have corresponding fields in the target object.
Wiki javadoc Use textile entry format.
Add your comments here.
registerCustomEditor
public void registerCustomEditor ( Class requiredType, PropertyEditor propertyEditor )
No description provided.
Implements method in PropertyEditorRegistry
Parameters
TypeNameDescription
Class requiredType No description provided.
PropertyEditor propertyEditor No description provided.
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
registerCustomEditor
public void registerCustomEditor ( Class requiredType, String field, PropertyEditor propertyEditor )
No description provided.
Implements method in PropertyEditorRegistry
Parameters
TypeNameDescription
Class requiredType No description provided.
String field No description provided.
PropertyEditor propertyEditor No description provided.
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
setAllowedFields
public void setAllowedFields ( String [] allowedFields )
Register fields that should be allowed for binding. Default is all fields. Restrict this for example to avoid unwanted modifications by malicious users when binding HTTP request parameters.

Supports "xxx*" and "*xxx" patterns. More sophisticated matching can be implemented by overriding the isAllowed method.

Parameters
TypeNameDescription
String [] allowedFields array of field names
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
setBindingErrorProcessor
public void setBindingErrorProcessor ( BindingErrorProcessor bindingErrorProcessor )
Set the strategy to use for processing binding errors, that is, required field errors and PropertyAccessExceptions.

Default is a DefaultBindingErrorProcessor.

Parameters
TypeNameDescription
BindingErrorProcessor bindingErrorProcessor No description provided.
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
setExtractOldValueForEditor
public void setExtractOldValueForEditor ( boolean extractOldValueForEditor )
Set whether to extract the old field value when applying a property editor to a new value for a field.

Default is "true", exposing previous field values to custom editors. Turn this to "false" to avoid side effects caused by getters.

Parameters
TypeNameDescription
boolean extractOldValueForEditor No description provided.
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
setIgnoreUnknownFields
public void setIgnoreUnknownFields ( boolean ignoreUnknownFields )
Set whether to ignore unknown fields, i.e. whether to ignore request parameters that don't have corresponding fields in the target object.
Parameters
TypeNameDescription
boolean ignoreUnknownFields No description provided.
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
setMessageCodesResolver
public void setMessageCodesResolver ( MessageCodesResolver messageCodesResolver )
Set the strategy to use for resolving errors into message codes. Applies the given strategy to the underlying errors holder.

Default is a DefaultMessageCodesResolver.

Parameters
TypeNameDescription
MessageCodesResolver messageCodesResolver No description provided.
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
setRequiredFields
public void setRequiredFields ( String [] requiredFields )
Register fields that are required for each binding process.

If one of the specified fields is not contained in the list of incoming property values, a corresponding "missing field" error will be created, with error code "required" (by the default binding error processor).

Parameters
TypeNameDescription
String [] requiredFields array of field names
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.