Class DataBinder
- All Implemented Interfaces:
PropertyEditorRegistry
,TypeConverter
- Direct Known Subclasses:
WebDataBinder
The binding process can be customized by specifying allowed field patterns, required fields, custom editors, etc.
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.
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.
- Author:
- Rod Johnson, Juergen Hoeller, Rob Harrop, Stephane Nicoll, Kazuki Shimizu, Sam Brannen
- 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
-
Field Summary
-
Constructor Summary
ConstructorDescriptionDataBinder
(Object target) Create a new DataBinder instance, with default object name.DataBinder
(Object target, String objectName) Create a new DataBinder instance. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addCustomFormatter
(Formatter<?> formatter) Add a custom formatter, applying it to all fields matching theFormatter
-declared type.void
addCustomFormatter
(Formatter<?> formatter, Class<?>... fieldTypes) Add a custom formatter, applying it to the specified field types only, if any, or otherwise to all fields matching theFormatter
-declared type.void
addCustomFormatter
(Formatter<?> formatter, String... fields) Add a custom formatter for the field type specified inFormatter
class, applying it to the specified fields only, if any, or otherwise to all fields.void
addValidators
(Validator... validators) Add Validators to apply after each binding step.protected void
Apply given property values to the target object.void
bind
(PropertyValues pvs) Bind the given property values to this binder's target.protected void
Check the given property values against the allowed fields, removing values for fields that are not allowed.protected void
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, Field field) Convert the value to the required type (if necessary from a String).<T> T
convertIfNecessary
(Object value, Class<T> requiredType, TypeDescriptor typeDescriptor) 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).protected AbstractPropertyBindingResult
Create theAbstractPropertyBindingResult
instance using standard JavaBean property access.protected AbstractPropertyBindingResult
Create theAbstractPropertyBindingResult
instance using direct field access.protected void
doBind
(MutablePropertyValues mpvs) Actual implementation of the binding process, working with the passed-in MutablePropertyValues instance.findCustomEditor
(Class<?> requiredType, String propertyPath) Find a custom property editor for the given type and property.String[]
Return the field patterns that should be allowed for binding.int
Return the current limit for array and collection auto-growing.Return the strategy for processing binding errors.Return the BindingResult instance created by this DataBinder.Return the associated ConversionService, if any.String[]
Return the field patterns that should not be allowed for binding.protected AbstractPropertyBindingResult
Return the internal BindingResult held by this DataBinder, as an AbstractPropertyBindingResult.Return the name of the bound object.protected ConfigurablePropertyAccessor
Return the underlying PropertyAccessor of this binder's BindingResult.protected PropertyEditorRegistry
Return the underlying TypeConverter of this binder's BindingResult.String[]
Return the fields that are required for each binding process.protected SimpleTypeConverter
Return this binder's underlying SimpleTypeConverter.Return the wrapped target object.protected TypeConverter
Return the underlying TypeConverter of this binder's BindingResult.Return the primary Validator to apply after each binding step, if any.Return the Validators to apply after data binding.void
Initialize standard JavaBean property access for this DataBinder.void
Initialize direct field access for this DataBinder, as alternative to the default bean property access.protected boolean
Determine if the given field is allowed for binding.boolean
Return whether "auto-growing" of nested paths has been activated.boolean
Return whether to ignore invalid fields when binding.boolean
Return whether to ignore unknown fields when binding.void
registerCustomEditor
(Class<?> requiredType, PropertyEditor propertyEditor) Register the given custom property editor for all properties of the given type.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
replaceValidators
(Validator... validators) Replace the Validators to apply after each binding step.void
setAllowedFields
(String... allowedFields) Register field patterns 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 andPropertyAccessException
s.void
setConversionService
(ConversionService conversionService) Specify aConversionService
to use for converting property values, as an alternative to JavaBeans PropertyEditors.void
setDisallowedFields
(String... disallowedFields) Register field patterns that should not be allowed for binding.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
Invoke the specified Validators, if any, with the given validation hints.
-
Field Details
-
DEFAULT_OBJECT_NAME
Default object name used for binding: "target".- See Also:
-
DEFAULT_AUTO_GROW_COLLECTION_LIMIT
public static final int DEFAULT_AUTO_GROW_COLLECTION_LIMITDefault limit for array and collection growing: 256.- See Also:
-
logger
We'll create a lot of DataBinder instances: Let's use a static logger.
-
-
Constructor Details
-
DataBinder
Create a new DataBinder instance, with default object name.- Parameters:
target
- the target object to bind onto (ornull
if the binder is just used to convert a plain parameter value)- See Also:
-
DataBinder
Create a new DataBinder instance.- Parameters:
target
- the target object to bind onto (ornull
if the binder is just used to convert a plain parameter value)objectName
- the name of the target object
-
-
Method Details
-
getTarget
Return the wrapped target object. -
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 since Spring 4.1 this feature is supported for bean property access (DataBinder's default mode) and field access.
-
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.
-
createBeanPropertyBindingResult
Create theAbstractPropertyBindingResult
instance using standard JavaBean property access.- Since:
- 4.2.1
-
initDirectFieldAccess
public void initDirectFieldAccess()Initialize direct field access for this DataBinder, as alternative to the default bean property access. -
createDirectFieldBindingResult
Create theAbstractPropertyBindingResult
instance using direct field access.- Since:
- 4.2.1
-
getInternalBindingResult
Return the internal BindingResult held by this DataBinder, as an AbstractPropertyBindingResult. -
getPropertyAccessor
Return the underlying PropertyAccessor of this binder's BindingResult. -
getSimpleTypeConverter
Return this binder's underlying SimpleTypeConverter. -
getPropertyEditorRegistry
Return the underlying TypeConverter of this binder's BindingResult. -
getTypeConverter
Return the underlying TypeConverter of this binder's 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:
-
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
. -
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
. -
isIgnoreInvalidFields
public boolean isIgnoreInvalidFields()Return whether to ignore invalid fields when binding. -
setAllowedFields
Register field patterns 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"
,"*xxx*"
, and"xxx*yyy"
matches (with an arbitrary number of pattern parts), as well as direct equality.The default implementation of this method stores allowed field patterns in canonical form. Subclasses which override this method must therefore take this into account.
More sophisticated matching can be implemented by overriding the
isAllowed(java.lang.String)
method.Alternatively, specify a list of disallowed field patterns.
- Parameters:
allowedFields
- array of allowed field patterns- See Also:
-
getAllowedFields
Return the field patterns that should be allowed for binding.- Returns:
- array of allowed field patterns
- See Also:
-
setDisallowedFields
Register field patterns 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"
,"*xxx*"
, and"xxx*yyy"
matches (with an arbitrary number of pattern parts), as well as direct equality.The default implementation of this method stores disallowed field patterns in canonical form. As of Spring Framework 5.2.21, the default implementation also transforms disallowed field patterns to lowercase to support case-insensitive pattern matching in
isAllowed(java.lang.String)
. Subclasses which override this method must therefore take both of these transformations into account.More sophisticated matching can be implemented by overriding the
isAllowed(java.lang.String)
method.Alternatively, specify a list of allowed field patterns.
- Parameters:
disallowedFields
- array of disallowed field patterns- See Also:
-
getDisallowedFields
Return the field patterns that should not be allowed for binding.- Returns:
- array of disallowed field patterns
- See Also:
-
setRequiredFields
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:
-
getRequiredFields
Return the fields that are required for each binding process.- Returns:
- array of field names
-
setMessageCodesResolver
Set the strategy to use for resolving errors into message codes. Applies the given strategy to the underlying errors holder.Default is a DefaultMessageCodesResolver.
-
setBindingErrorProcessor
Set the strategy to use for processing binding errors, that is, required field errors andPropertyAccessException
s.Default is a DefaultBindingErrorProcessor.
- See Also:
-
getBindingErrorProcessor
Return the strategy for processing binding errors. -
setValidator
Set the Validator to apply after each binding step. -
addValidators
Add Validators to apply after each binding step. -
replaceValidators
Replace the Validators to apply after each binding step. -
getValidator
Return the primary Validator to apply after each binding step, if any. -
getValidators
Return the Validators to apply after data binding. -
setConversionService
Specify aConversionService
to use for converting property values, as an alternative to JavaBeans PropertyEditors. -
getConversionService
Return the associated ConversionService, if any. -
addCustomFormatter
Add a custom formatter, applying it to all fields matching theFormatter
-declared type.Registers a corresponding
PropertyEditor
adapter underneath the covers.- Parameters:
formatter
- the formatter to add, generically declared for a specific type- Since:
- 4.2
- See Also:
-
addCustomFormatter
Add a custom formatter for the field type specified inFormatter
class, applying it to the specified fields only, if any, or otherwise to all fields.Registers a corresponding
PropertyEditor
adapter underneath the covers.- Parameters:
formatter
- the formatter to add, generically declared for a specific typefields
- the fields to apply the formatter to, or none if to be applied to all- Since:
- 4.2
- See Also:
-
addCustomFormatter
Add a custom formatter, applying it to the specified field types only, if any, or otherwise to all fields matching theFormatter
-declared type.Registers a corresponding
PropertyEditor
adapter underneath the covers.- Parameters:
formatter
- the formatter to add (does not need to generically declare a field type if field types are explicitly specified as parameters)fieldTypes
- the field types to apply the formatter to, or none if to be derived from the givenFormatter
implementation class- Since:
- 4.2
- See Also:
-
registerCustomEditor
Description copied from interface:PropertyEditorRegistry
Register the given custom property editor for all properties of the given type.- Specified by:
registerCustomEditor
in interfacePropertyEditorRegistry
- Parameters:
requiredType
- the type of the propertypropertyEditor
- the editor to register
-
registerCustomEditor
public void registerCustomEditor(@Nullable Class<?> requiredType, @Nullable String field, PropertyEditor propertyEditor) Description copied from interface:PropertyEditorRegistry
Register the given custom property editor for the given type and property, or for all properties of the given type.If the property path denotes an array or Collection property, the editor will get applied either to the array/Collection itself (the
PropertyEditor
has to create an array or Collection value) or to each element (thePropertyEditor
has to create the element type), depending on the specified required type.Note: Only one single registered custom editor per property path is supported. In the case of a Collection/array, do not register an editor for both the Collection/array and each element on the same property.
For example, if you wanted to register an editor for "items[n].quantity" (for all values n), you would use "items.quantity" as the value of the 'propertyPath' argument to this method.
- Specified by:
registerCustomEditor
in interfacePropertyEditorRegistry
- Parameters:
requiredType
- the type of the property. This may benull
if a property is given but should be specified in any case, in particular in case of a Collection - making clear whether the editor is supposed to apply to the entire Collection itself or to each of its entries. So as a general rule: Do not specifynull
here in case of a Collection/array!field
- the path of the property (name or nested path), ornull
if registering an editor for all properties of the given typepropertyEditor
- editor to register
-
findCustomEditor
@Nullable public PropertyEditor findCustomEditor(@Nullable Class<?> requiredType, @Nullable String propertyPath) Description copied from interface:PropertyEditorRegistry
Find a custom property editor for the given type and property.- Specified by:
findCustomEditor
in interfacePropertyEditorRegistry
- Parameters:
requiredType
- the type of the property (can benull
if a property is given but should be specified in any case for consistency checking)propertyPath
- the path of the property (name or nested path), ornull
if looking for an editor for all properties of the given type- Returns:
- the registered editor, or
null
if none
-
convertIfNecessary
@Nullable public <T> T convertIfNecessary(@Nullable Object value, @Nullable Class<T> requiredType) throws TypeMismatchException Description copied from interface:TypeConverter
Convert the value to the required type (if necessary from a String).Conversions from String to any type will typically use the
setAsText
method of the PropertyEditor class, or a Spring Converter in a ConversionService.- Specified by:
convertIfNecessary
in interfaceTypeConverter
- Parameters:
value
- the value to convertrequiredType
- the type we must convert to (ornull
if not known, for example in case of a collection element)- Returns:
- the new value, possibly the result of type conversion
- Throws:
TypeMismatchException
- if type conversion failed- See Also:
-
convertIfNecessary
@Nullable public <T> T convertIfNecessary(@Nullable Object value, @Nullable Class<T> requiredType, @Nullable MethodParameter methodParam) throws TypeMismatchException Description copied from interface:TypeConverter
Convert the value to the required type (if necessary from a String).Conversions from String to any type will typically use the
setAsText
method of the PropertyEditor class, or a Spring Converter in a ConversionService.- Specified by:
convertIfNecessary
in interfaceTypeConverter
- Parameters:
value
- the value to convertrequiredType
- the type we must convert to (ornull
if not known, for example in case of a collection element)methodParam
- the method parameter that is the target of the conversion (for analysis of generic types; may benull
)- Returns:
- the new value, possibly the result of type conversion
- Throws:
TypeMismatchException
- if type conversion failed- See Also:
-
convertIfNecessary
@Nullable public <T> T convertIfNecessary(@Nullable Object value, @Nullable Class<T> requiredType, @Nullable Field field) throws TypeMismatchException Description copied from interface:TypeConverter
Convert the value to the required type (if necessary from a String).Conversions from String to any type will typically use the
setAsText
method of the PropertyEditor class, or a Spring Converter in a ConversionService.- Specified by:
convertIfNecessary
in interfaceTypeConverter
- Parameters:
value
- the value to convertrequiredType
- the type we must convert to (ornull
if not known, for example in case of a collection element)field
- the reflective field that is the target of the conversion (for analysis of generic types; may benull
)- Returns:
- the new value, possibly the result of type conversion
- Throws:
TypeMismatchException
- if type conversion failed- See Also:
-
convertIfNecessary
@Nullable public <T> T convertIfNecessary(@Nullable Object value, @Nullable Class<T> requiredType, @Nullable TypeDescriptor typeDescriptor) throws TypeMismatchException Description copied from interface:TypeConverter
Convert the value to the required type (if necessary from a String).Conversions from String to any type will typically use the
setAsText
method of the PropertyEditor class, or a Spring Converter in a ConversionService.- Specified by:
convertIfNecessary
in interfaceTypeConverter
- Parameters:
value
- the value to convertrequiredType
- the type we must convert to (ornull
if not known, for example in case of a collection element)typeDescriptor
- the type descriptor to use (may benull
))- Returns:
- the new value, possibly the result of type conversion
- Throws:
TypeMismatchException
- if type conversion failed- See Also:
-
bind
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
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
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:
-
isAllowed
Determine if the given field is allowed for binding.Invoked for each passed-in property value.
Checks for
"xxx*"
,"*xxx"
,"*xxx*"
, and"xxx*yyy"
matches (with an arbitrary number of pattern parts), as well as direct equality, in the configured lists of allowed field patterns and disallowed field patterns.Matching against allowed field patterns is case-sensitive; whereas, matching against disallowed field patterns is case-insensitive.
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, but care must be taken to honor the aforementioned contract.
- Parameters:
field
- the field to check- Returns:
true
if the field is allowed- See Also:
-
checkRequiredFields
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:
-
applyPropertyValues
Apply given property values to the target object.Default implementation applies all 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:
-
validate
public void validate()Invoke the specified Validators, if any.- See Also:
-
validate
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 aSmartValidator
- Since:
- 3.1
- See Also:
-
close
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:
-