java.lang.Object | |
↳ | org.springframework.validation.DataBinder |
Known Direct Subclasses |
Known Indirect Subclasses |
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:
By default, binding errors get resolved through the BindingErrorProcessor
strategy, processing for missing fields and property access exceptions: see the
setBindingErrorProcessor(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
getMessage(org.springframework.context.MessageSourceResolvable, java.util.Locale)
method. The list of message codes can be customized through the MessageCodesResolver
strategy: see the setMessageCodesResolver(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 ServletRequestDataBinder
and PortletRequestDataBinder
.
setAllowedFields(String...)
setRequiredFields(String...)
registerCustomEditor(Class, PropertyEditor)
setMessageCodesResolver(MessageCodesResolver)
setBindingErrorProcessor(BindingErrorProcessor)
bind(PropertyValues)
getBindingResult()
DefaultMessageCodesResolver
DefaultBindingErrorProcessor
MessageSource
ServletRequestDataBinder
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
String | DEFAULT_OBJECT_NAME | Default object name used for binding: "target" |
Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
logger | We'll create a lot of DataBinder instances: Let's use a static logger. |
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Create a new DataBinder instance, with default object name.
| |||||||||||
Create a new DataBinder instance.
|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Bind the given property values to this binder's target.
| |||||||||||
Close this DataBinder, which may result in throwing
a BindException if it encountered any errors.
| |||||||||||
Convert the value to the required type (if necessary from a String).
| |||||||||||
Convert the value to the required type (if necessary from a String).
| |||||||||||
Find a custom property editor for the given type and property.
| |||||||||||
Return the fields that should be allowed for binding.
| |||||||||||
Return the strategy for processing binding errors.
| |||||||||||
Return the BindingResult instance created by this DataBinder.
| |||||||||||
Return the associated ConversionService, if any.
| |||||||||||
Return the fields that should not be allowed for binding.
| |||||||||||
This method is deprecated.
in favor of
getBindingResult() .
Use the BindException(BindingResult) constructor
to create a BindException instance if still needed. | |||||||||||
Return the name of the bound object.
| |||||||||||
Return the fields that are required for each binding process.
| |||||||||||
Return the wrapped target object.
| |||||||||||
Return the Validator to apply after each binding step, if any.
| |||||||||||
Initialize standard JavaBean property access for this DataBinder.
| |||||||||||
Initialize direct field access for this DataBinder,
as alternative to the default bean property access.
| |||||||||||
Return whether "auto-growing" of nested paths has been activated.
| |||||||||||
Return whether to ignore invalid fields when binding.
| |||||||||||
Return whether to ignore unknown fields when binding.
| |||||||||||
Register the given custom property editor for the given type and
property, or for all properties of the given type.
| |||||||||||
Register the given custom property editor for all properties of the given type.
| |||||||||||
Register fields that should be allowed for binding.
| |||||||||||
Set whether this binder should attempt to "auto-grow" a nested path that contains a null value.
| |||||||||||
Set the strategy to use for processing binding errors, that is,
required field errors and
PropertyAccessException s. | |||||||||||
Specify a Spring 3.0 ConversionService to use for converting
property values, as an alternative to JavaBeans PropertyEditors.
| |||||||||||
Register fields that should not be allowed for binding.
| |||||||||||
Set whether to extract the old field value when applying a
property editor to a new value for a field.
| |||||||||||
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).
| |||||||||||
Set whether to ignore unknown fields, that is, whether to ignore bind
parameters that do not have corresponding fields in the target object.
| |||||||||||
Set the strategy to use for resolving errors into message codes.
| |||||||||||
Register fields that are required for each binding process.
| |||||||||||
Set the Validator to apply after each binding step.
| |||||||||||
Invoke the specified Validator, if any.
|
Protected Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Apply given property values to the target object.
| |||||||||||
Check the given property values against the allowed fields,
removing values for fields that are not allowed.
| |||||||||||
Check the given property values against the required fields,
generating missing field errors where appropriate.
| |||||||||||
Actual implementation of the binding process, working with the
passed-in MutablePropertyValues instance.
| |||||||||||
Return the internal BindingResult held by this DataBinder,
as AbstractPropertyBindingResult.
| |||||||||||
Return the underlying PropertyAccessor of this binder's BindingResult.
| |||||||||||
Return the underlying TypeConverter of this binder's BindingResult.
| |||||||||||
Return this binder's underlying SimpleTypeConverter.
| |||||||||||
Return the underlying TypeConverter of this binder's BindingResult.
| |||||||||||
Return if the given field is allowed for binding.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
| |||||||||||
From interface
org.springframework.beans.PropertyEditorRegistry
| |||||||||||
From interface
org.springframework.beans.TypeConverter
|
Default object name used for binding: "target"
We'll create a lot of DataBinder instances: Let's use a static logger.
Create a new DataBinder instance, with default object name.
target | the target object to bind onto (or null
if the binder is just used to convert a plain parameter value) |
---|
Create a new DataBinder instance.
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 |
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.
pvs | property values to bind |
---|
Close this DataBinder, which may result in throwing a BindException if it encountered any errors.
BindException | if there were any errors in the bind operation |
---|
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. Note that a PropertyEditor must be registered
for the given class for this to work; this is a standard JavaBeans API.
A number of PropertyEditors are automatically registered.
value | the value to convert |
---|---|
requiredType | the type we must convert to
(or null if not known, for example in case of a collection element) |
TypeMismatchException |
---|
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. Note that a PropertyEditor must be registered
for the given class for this to work; this is a standard JavaBeans API.
A number of PropertyEditors are automatically registered.
value | the value to convert |
---|---|
requiredType | the type we must convert to
(or null 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 be null ) |
TypeMismatchException |
---|
Find a custom property editor for the given type and property.
requiredType | the type of the property (can be null 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), or
null if looking for an editor for all properties of the given type |
null
if none
Return the fields that should be allowed for binding.
Return the strategy for processing binding errors.
Return the BindingResult instance created by this DataBinder. This allows for convenient access to the binding results after a bind operation.
Return the fields that should not be allowed for binding.
This method is deprecated.
in favor of getBindingResult()
.
Use the BindException(BindingResult)
constructor
to create a BindException instance if still needed.
Return the Errors instance for this data binder.
Return the fields that are required for each binding process.
Initialize standard JavaBean property access for this DataBinder.
This is the default; an explicit call just leads to eager initialization.
Initialize direct field access for this DataBinder, as alternative to the default bean property access.
Return whether "auto-growing" of nested paths has been activated.
Return whether to ignore invalid fields when binding.
Return whether to ignore unknown fields when binding.
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 (the PropertyEditor
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.
requiredType | the type of the property. This may be null
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 specify null here in case of a Collection/array! |
---|---|
field | the path of the property (name or nested path), or
null if registering an editor for all properties of the given type |
propertyEditor | editor to register |
Register the given custom property editor for all properties of the given type.
requiredType | the type of the property |
---|---|
propertyEditor | the editor to register |
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.
allowedFields | array of field names |
---|
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.
Set the strategy to use for processing binding errors, that is,
required field errors and PropertyAccessException
s.
Default is a DefaultBindingErrorProcessor.
Specify a Spring 3.0 ConversionService to use for converting property values, as an alternative to JavaBeans PropertyEditors.
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.
disallowedFields | array of field names |
---|
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.
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
.
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
.
Set the strategy to use for resolving errors into message codes. Applies the given strategy to the underlying errors holder.
Default is a DefaultMessageCodesResolver.
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).
requiredFields | array of field names |
---|
Invoke the specified Validator, if any.
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.
mpvs | the property values to be bound (can be modified) |
---|
Check the given property values against the allowed fields, removing values for fields that are not allowed.
mpvs | the property values to be bound (can be modified) |
---|
Check the given property values against the required fields, generating missing field errors where appropriate.
mpvs | the property values to be bound (can be modified) |
---|
Actual implementation of the binding process, working with the passed-in MutablePropertyValues instance.
mpvs | the property values to bind, as MutablePropertyValues instance |
---|
Return the internal BindingResult held by this DataBinder, as AbstractPropertyBindingResult.
Return the underlying PropertyAccessor of this binder's BindingResult.
Return the underlying TypeConverter of this binder's BindingResult.
Return this binder's underlying SimpleTypeConverter.
Return the underlying TypeConverter of this binder's BindingResult.
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.
field | the field to check |
---|