org.springframework.validation

Class DataBinder

java.lang.Object

org.springframework.validation.DataBinder

All Implemented Interfaces:

org.springframework.beans.PropertyEditorRegistry, org.springframework.beans.TypeConverter

public class DataBinder
extends Object
implements org.springframework.beans.PropertyEditorRegistry, org.springframework.beans.TypeConverter

Binder that allows for setting property values onto a target object, including support for validation and binding result analysis. The binding process can be customized through specifying allowed fields, required fields, custom editors, etc.

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 BindingResult interface, extending the Errors interface: see the getBindingResult() method. Missing fields and property access exceptions will be converted to FieldErrors, collected in the Errors instance, using the following error codes:

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

By default, binding errors get resolved through the BindingErrorProcessor strategy, processing for missing fields and property access exceptions: see the setBindingErrorProcessor(org.springframework.validation.BindingErrorProcessor) method. You can override the default strategy if needed, for example to generate different error codes.

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, which is able to resolve an ObjectError/FieldError through its MessageSource.getMessage(org.springframework.context.MessageSourceResolvable, java.util.Locale) method. The list of message codes can be customized through the MessageCodesResolver strategy: see the setMessageCodesResolver(org.springframework.validation.MessageCodesResolver) method. DefaultMessageCodesResolver's javadoc states details on the default resolution rules.

This generic data binder can be used in any kind of environment. It is typically used by Spring web MVC controllers, via the web-specific subclasses org.springframework.web.bind.ServletRequestDataBinder and org.springframework.web.portlet.bind.PortletRequestDataBinder.

Author:

Rod Johnson, Juergen Hoeller, Rob Harrop

See Also:

setAllowedFields(java.lang.String...), setRequiredFields(java.lang.String...), registerCustomEditor(java.lang.Class<?>, java.beans.PropertyEditor), setMessageCodesResolver(org.springframework.validation.MessageCodesResolver), setBindingErrorProcessor(org.springframework.validation.BindingErrorProcessor), bind(org.springframework.beans.PropertyValues), getBindingResult(), DefaultMessageCodesResolver, DefaultBindingErrorProcessor, MessageSource, org.springframework.web.bind.ServletRequestDataBinder

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_AUTO_GROW_COLLECTION_LIMIT Default limit for array and collection growing: 256
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

Constructors

Constructor and Description
DataBinder(Object target) Create a new DataBinder instance, with default object name.
DataBinder(Object target, String objectName) Create a new DataBinder instance.

Method Summary

Methods

Modifier and Type	Method and Description
void	addValidators(Validator... validators) Add Validators to apply after each binding step.
protected void	applyPropertyValues(org.springframework.beans.MutablePropertyValues mpvs) Apply given property values to the target object.
void	bind(org.springframework.beans.PropertyValues pvs) Bind the given property values to this binder's target.
protected void	checkAllowedFields(org.springframework.beans.MutablePropertyValues mpvs) Check the given property values against the allowed fields, removing values for fields that are not allowed.
protected void	checkRequiredFields(org.springframework.beans.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)
<T> T	convertIfNecessary(Object value, Class<T> requiredType, Field field)
<T> T	convertIfNecessary(Object value, Class<T> requiredType, org.springframework.core.MethodParameter methodParam)
protected void	doBind(org.springframework.beans.MutablePropertyValues mpvs) Actual implementation of the binding process, working with the passed-in MutablePropertyValues instance.
PropertyEditor	findCustomEditor(Class<?> requiredType, String propertyPath)
String[]	getAllowedFields() Return the fields that should be allowed for binding.
int	getAutoGrowCollectionLimit() Return the current limit for array and collection auto-growing.
BindingErrorProcessor	getBindingErrorProcessor() Return the strategy for processing binding errors.
BindingResult	getBindingResult() Return the BindingResult instance created by this DataBinder.
org.springframework.core.convert.ConversionService	getConversionService() Return the associated ConversionService, if any.
String[]	getDisallowedFields() Return the fields that should not be allowed for binding.
BindException	getErrors() Deprecated. in favor of getBindingResult(). Use the BindException.BindException(BindingResult) constructor to create a BindException instance if still needed.
protected AbstractPropertyBindingResult	getInternalBindingResult() Return the internal BindingResult held by this DataBinder, as AbstractPropertyBindingResult.
String	getObjectName() Return the name of the bound object.
protected org.springframework.beans.ConfigurablePropertyAccessor	getPropertyAccessor() Return the underlying PropertyAccessor of this binder's BindingResult.
protected org.springframework.beans.PropertyEditorRegistry	getPropertyEditorRegistry() Return the underlying TypeConverter of this binder's BindingResult.
String[]	getRequiredFields() Return the fields that are required for each binding process.
protected org.springframework.beans.SimpleTypeConverter	getSimpleTypeConverter() Return this binder's underlying SimpleTypeConverter.
Object	getTarget() Return the wrapped target object.
protected org.springframework.beans.TypeConverter	getTypeConverter() Return the underlying TypeConverter of this binder's BindingResult.
Validator	getValidator() Return the primary Validator to apply after each binding step, if any.
List<Validator>	getValidators() Return the Validators to apply after data binding.
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.
protected 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, PropertyEditor propertyEditor)
void	registerCustomEditor(Class<?> requiredType, String field, PropertyEditor propertyEditor)
void	replaceValidators(Validator... validators) Replace the Validators to apply after each binding step.
void	setAllowedFields(String... allowedFields) Register fields that should be allowed for binding.
void	setAutoGrowCollectionLimit(int autoGrowCollectionLimit) Specify the limit for array and collection auto-growing.
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 PropertyAccessExceptions.
void	setConversionService(org.springframework.core.convert.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 Validators, if any.
void	validate(Object... validationHints) Invoke the specified Validators, if any, with the given validation hints.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_OBJECT_NAME

public static final String DEFAULT_OBJECT_NAME

Default object name used for binding: "target"

See Also:

Constant Field Values

DEFAULT_AUTO_GROW_COLLECTION_LIMIT

public static final int DEFAULT_AUTO_GROW_COLLECTION_LIMIT

Default limit for array and collection growing: 256

See Also:

Constant Field Values

logger

protected static final Log logger

We'll create a lot of DataBinder instances: Let's use a static logger.

Constructor Detail

DataBinder

public DataBinder(Object target)

Create a new DataBinder 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:

DEFAULT_OBJECT_NAME

DataBinder

public DataBinder(Object target,
          String objectName)

Create a new DataBinder 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

getTarget

public Object getTarget()

Return the wrapped target object.

getObjectName

public String getObjectName()

Return the name of the bound object.

setAutoGrowNestedPaths

public void setAutoGrowNestedPaths(boolean autoGrowNestedPaths)

Set whether this binder should attempt to "auto-grow" a nested path that contains a null value.

If "true", a null path location will be populated with a default object value and traversed instead of resulting in an exception. This flag also enables auto-growth of collection elements when accessing an out-of-bounds index.

Default is "true" on a standard DataBinder. Note that this feature is only supported for bean property access (DataBinder's default mode), not for field access.

See Also:

initBeanPropertyAccess(), BeanWrapper.setAutoGrowNestedPaths(boolean)

isAutoGrowNestedPaths

public boolean isAutoGrowNestedPaths()

Return whether "auto-growing" of nested paths has been activated.

setAutoGrowCollectionLimit

public void setAutoGrowCollectionLimit(int autoGrowCollectionLimit)

Specify the limit for array and collection auto-growing.

Default is 256, preventing OutOfMemoryErrors in case of large indexes. Raise this limit if your auto-growing needs are unusually high.

getAutoGrowCollectionLimit

public int getAutoGrowCollectionLimit()

Return the current limit for array and collection auto-growing.

initBeanPropertyAccess

public void initBeanPropertyAccess()

Initialize standard JavaBean property access for this DataBinder.

This is the default; an explicit call just leads to eager initialization.

See Also:

initDirectFieldAccess()

initDirectFieldAccess

public void initDirectFieldAccess()

Initialize direct field access for this DataBinder, as alternative to the default bean property access.

See Also:

initBeanPropertyAccess()

getInternalBindingResult

protected AbstractPropertyBindingResult getInternalBindingResult()

Return the internal BindingResult held by this DataBinder, as AbstractPropertyBindingResult.

getPropertyAccessor

protected org.springframework.beans.ConfigurablePropertyAccessor getPropertyAccessor()

Return the underlying PropertyAccessor of this binder's BindingResult.

getSimpleTypeConverter

protected org.springframework.beans.SimpleTypeConverter getSimpleTypeConverter()

Return this binder's underlying SimpleTypeConverter.

getPropertyEditorRegistry

protected org.springframework.beans.PropertyEditorRegistry getPropertyEditorRegistry()

Return the underlying TypeConverter of this binder's BindingResult.

getTypeConverter

protected org.springframework.beans.TypeConverter getTypeConverter()

Return the underlying TypeConverter of this binder's BindingResult.

getBindingResult

public BindingResult getBindingResult()

Return the BindingResult instance created by this DataBinder. This allows for convenient access to the binding results after a bind operation.

Returns:

the BindingResult instance, to be treated as BindingResult or as Errors instance (Errors is a super-interface of BindingResult)

See Also:

Errors, bind(org.springframework.beans.PropertyValues)

getErrors

@Deprecated
public BindException getErrors()

Deprecated. in favor of getBindingResult(). Use the BindException.BindException(BindingResult) constructor to create a BindException instance if still needed.

Return the Errors instance for this data binder.

Returns:

the Errors instance, to be treated as Errors or as BindException

See Also:

getBindingResult()

setIgnoreUnknownFields

public 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.

Default is "true". Turn this off to enforce that all bind parameters must have a matching field in the target object.

Note that this setting only applies to binding operations on this DataBinder, not to retrieving values via its BindingResult.

See Also:

bind(org.springframework.beans.PropertyValues)

isIgnoreUnknownFields

public boolean isIgnoreUnknownFields()

Return whether to ignore unknown fields when binding.

setIgnoreInvalidFields

public 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).

Default is "false". Turn this on to ignore bind parameters for nested objects in non-existing parts of the target object graph.

Note that this setting only applies to binding operations on this DataBinder, not to retrieving values via its BindingResult.

See Also:

bind(org.springframework.beans.PropertyValues)

isIgnoreInvalidFields

public boolean isIgnoreInvalidFields()

Return whether to ignore invalid fields when binding.

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*", "*xxx" and "*xxx*" patterns. More sophisticated matching can be implemented by overriding the isAllowed method.

Alternatively, specify a list of disallowed fields.

Parameters:

allowedFields - array of field names

See Also:

setDisallowedFields(java.lang.String...), isAllowed(String), org.springframework.web.bind.ServletRequestDataBinder

getAllowedFields

public String[] getAllowedFields()

Return the fields that should be allowed for binding.

Returns:

array of field names

setDisallowedFields

public void setDisallowedFields(String... disallowedFields)

Register fields that should not be allowed for binding. Default is none. Mark fields as disallowed for example to avoid unwanted modifications by malicious users when binding HTTP request parameters.

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

Alternatively, specify a list of allowed fields.

Parameters:

disallowedFields - array of field names

See Also:

setAllowedFields(java.lang.String...), isAllowed(String), org.springframework.web.bind.ServletRequestDataBinder

getDisallowedFields

public String[] getDisallowedFields()

Return the fields that should not be allowed for binding.

Returns:

array of field names

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:

requiredFields - array of field names

See Also:

setBindingErrorProcessor(org.springframework.validation.BindingErrorProcessor), DefaultBindingErrorProcessor.MISSING_FIELD_ERROR_CODE

getRequiredFields

public String[] getRequiredFields()

Return the fields that are required for each binding process.

Returns:

array of field names

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.

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.

See Also:

AbstractBindingResult.setMessageCodesResolver(org.springframework.validation.MessageCodesResolver), DefaultMessageCodesResolver

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.

See Also:

DefaultBindingErrorProcessor

getBindingErrorProcessor

public BindingErrorProcessor getBindingErrorProcessor()

Return the strategy for processing binding errors.

setValidator

public void setValidator(Validator validator)

Set the Validator to apply after each binding step.

See Also:

addValidators(Validator...), replaceValidators(Validator...)

addValidators

public void addValidators(Validator... validators)

Add Validators to apply after each binding step.

See Also:

setValidator(Validator), replaceValidators(Validator...)

replaceValidators

public void replaceValidators(Validator... validators)

Replace the Validators to apply after each binding step.

See Also:

setValidator(Validator), addValidators(Validator...)

getValidator

public Validator getValidator()

Return the primary Validator to apply after each binding step, if any.

getValidators

public List<Validator> getValidators()

Return the Validators to apply after data binding.

setConversionService

public void setConversionService(org.springframework.core.convert.ConversionService conversionService)

Specify a Spring 3.0 ConversionService to use for converting property values, as an alternative to JavaBeans PropertyEditors.

getConversionService

public org.springframework.core.convert.ConversionService getConversionService()

Return the associated ConversionService, if any.

registerCustomEditor

public void registerCustomEditor(Class<?> requiredType,
                        PropertyEditor propertyEditor)

Specified by:

registerCustomEditor in interface org.springframework.beans.PropertyEditorRegistry

registerCustomEditor

public void registerCustomEditor(Class<?> requiredType,
                        String field,
                        PropertyEditor propertyEditor)

Specified by:

registerCustomEditor in interface org.springframework.beans.PropertyEditorRegistry

findCustomEditor

public PropertyEditor findCustomEditor(Class<?> requiredType,
                              String propertyPath)

Specified by:

findCustomEditor in interface org.springframework.beans.PropertyEditorRegistry

convertIfNecessary

public <T> T convertIfNecessary(Object value,
                       Class<T> requiredType)
                     throws org.springframework.beans.TypeMismatchException

Specified by:

convertIfNecessary in interface org.springframework.beans.TypeConverter

Throws:

org.springframework.beans.TypeMismatchException

convertIfNecessary

public <T> T convertIfNecessary(Object value,
                       Class<T> requiredType,
                       org.springframework.core.MethodParameter methodParam)
                     throws org.springframework.beans.TypeMismatchException

Specified by:

convertIfNecessary in interface org.springframework.beans.TypeConverter

Throws:

org.springframework.beans.TypeMismatchException

convertIfNecessary

public <T> T convertIfNecessary(Object value,
                       Class<T> requiredType,
                       Field field)
                     throws org.springframework.beans.TypeMismatchException

Specified by:

convertIfNecessary in interface org.springframework.beans.TypeConverter

Throws:

org.springframework.beans.TypeMismatchException

bind

public void bind(org.springframework.beans.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:

pvs - property values to bind

See Also:

doBind(org.springframework.beans.MutablePropertyValues)

doBind

protected void doBind(org.springframework.beans.MutablePropertyValues mpvs)

Actual implementation of the binding process, working with the passed-in MutablePropertyValues instance.

Parameters:

mpvs - the property values to bind, as MutablePropertyValues instance

See Also:

checkAllowedFields(org.springframework.beans.MutablePropertyValues), checkRequiredFields(org.springframework.beans.MutablePropertyValues), applyPropertyValues(org.springframework.beans.MutablePropertyValues)

checkAllowedFields

protected void checkAllowedFields(org.springframework.beans.MutablePropertyValues mpvs)

Check the given property values against the allowed fields, removing values for fields that are not allowed.

Parameters:

mpvs - the property values to be bound (can be modified)

See Also:

getAllowedFields(), isAllowed(String)

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*", "*xxx" and "*xxx*" matches, as well as direct equality, in the specified lists of allowed fields and disallowed fields. A field matching a disallowed pattern will not be accepted even if it also happens to match a pattern in the allowed list.

Can be overridden in subclasses.

Parameters:

field - the field to check

Returns:

if the field is allowed

See Also:

setAllowedFields(java.lang.String...), setDisallowedFields(java.lang.String...), PatternMatchUtils.simpleMatch(String, String)

checkRequiredFields

protected void checkRequiredFields(org.springframework.beans.MutablePropertyValues mpvs)

Check the given property values against the required fields, generating missing field errors where appropriate.

Parameters:

mpvs - the property values to be bound (can be modified)

See Also:

getRequiredFields(), getBindingErrorProcessor(), BindingErrorProcessor.processMissingFieldError(java.lang.String, org.springframework.validation.BindingResult)

applyPropertyValues

protected void applyPropertyValues(org.springframework.beans.MutablePropertyValues mpvs)

Apply given property values to the target object.

Default implementation applies all of the supplied property values as bean property values. By default, unknown fields will be ignored.

Parameters:

mpvs - the property values to be bound (can be modified)

See Also:

getTarget(), getPropertyAccessor(), isIgnoreUnknownFields(), getBindingErrorProcessor(), BindingErrorProcessor.processPropertyAccessException(org.springframework.beans.PropertyAccessException, org.springframework.validation.BindingResult)

validate

public void validate()

Invoke the specified Validators, if any.

See Also:

setValidator(Validator), getBindingResult()

validate

public void validate(Object... validationHints)

Invoke the specified Validators, if any, with the given validation hints.

Note: Validation hints may get ignored by the actual target Validator.

Parameters:

validationHints - one or more hint objects to be passed to a SmartValidator

See Also:

setValidator(Validator), SmartValidator.validate(Object, Errors, Object...)

close

public Map<?,?> close()
               throws BindException

Close this DataBinder, which may result in throwing a BindException if it encountered any errors.

Returns:

the model Map, containing target object and Errors instance

Throws:

BindException - if there were any errors in the bind operation

See Also:

BindingResult.getModel()