Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| The Spring Framework
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.springframework.validation
Class DataBinder

    java.lang.Object
      org.springframework.validation.DataBinder

All Implemented Interfaces:
  PropertyEditorRegistry, TypeConverter

Direct Known Subclasses:
  WebDataBinder

    public class DataBinder

extends Object
implements PropertyEditorRegistry, 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 `ServletRequestDataBinder` and `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`, `ServletRequestDataBinder`

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.
`Object` | `convertIfNecessary(Object value, Class requiredType)` Convert the value to the required type (if necessary from a String).
`Object` | `convertIfNecessary(Object value, Class requiredType, MethodParameter methodParam)` Convert the value to the required type (if necessary from a String).
`protected void` | `doBind(MutablePropertyValues mpvs)` Actual implementation of the binding process, working with the passed-in MutablePropertyValues instance.
`PropertyEditor` | `findCustomEditor(Class requiredType, String propertyPath)` Find a custom property editor for the given type and property.
`String[]` | `getAllowedFields()` Return the fields that should be allowed for binding.
`BindingErrorProcessor` | `getBindingErrorProcessor()` Return the strategy for processing binding errors.
`BindingResult` | `getBindingResult()` Return the BindingResult instance created by this DataBinder.
`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 ConfigurablePropertyAccessor` | `getPropertyAccessor()` Return the underlying PropertyAccessor of this binder's BindingResult.
`protected PropertyEditorRegistry` | `getPropertyEditorRegistry()` Return the underlying TypeConverter of this binder's BindingResult.
`String[]` | `getRequiredFields()` Return the fields that are required for each binding process.
`protected SimpleTypeConverter` | `getSimpleTypeConverter()` Return this binder's underlying SimpleTypeConverter.
`Object` | `getTarget()` Return the wrapped target object.
`protected TypeConverter` | `getTypeConverter()` Return the underlying TypeConverter of this binder's BindingResult.
`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` | `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)` 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` | `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 `PropertyAccessException`s.
`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.

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

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

### 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 ConfigurablePropertyAccessor getPropertyAccessor()

  Return the underlying PropertyAccessor of this binder's BindingResult.

### getSimpleTypeConverter

    protected SimpleTypeConverter getSimpleTypeConverter()

  Return this binder's underlying SimpleTypeConverter.

### getPropertyEditorRegistry

    protected PropertyEditorRegistry getPropertyEditorRegistry()

  Return the underlying TypeConverter of this binder's BindingResult.

### getTypeConverter

    protected 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

    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)`, `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)`, `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 `PropertyAccessException`s.

  Default is a DefaultBindingErrorProcessor.

  See Also:
    `DefaultBindingErrorProcessor`

### getBindingErrorProcessor

    public BindingErrorProcessor getBindingErrorProcessor()

  Return the strategy for processing binding errors.

### registerCustomEditor

    public void registerCustomEditor(Class requiredType,
                                     PropertyEditor propertyEditor)

  Description copied from interface: `PropertyEditorRegistry`
  Register the given custom property editor for all properties of the given type.

  Specified by:
    `registerCustomEditor` in interface `PropertyEditorRegistry`
  Parameters:
    `requiredType` - the type of the property
    `propertyEditor` - the editor to register

### registerCustomEditor

    public void registerCustomEditor(Class requiredType,
                                     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 (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.

  Specified by:
    `registerCustomEditor` in interface `PropertyEditorRegistry`
  Parameters:
    `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

### findCustomEditor

    public PropertyEditor findCustomEditor(Class requiredType,
                                           String propertyPath)

  Description copied from interface: `PropertyEditorRegistry`
  Find a custom property editor for the given type and property.

  Specified by:
    `findCustomEditor` in interface `PropertyEditorRegistry`
  Parameters:
    `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
  Returns:
    the registered editor, or `null` if none

### convertIfNecessary

    public Object convertIfNecessary(Object value,
                                     Class 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. 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.

  Specified by:
    `convertIfNecessary` in interface `TypeConverter`
  Parameters:
    `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)
  Returns:
    the new value, possibly the result of type conversion
  Throws:
    `TypeMismatchException` - if type conversion failed
  See Also:
    `PropertyEditor.setAsText(String)`, `PropertyEditor.getValue()`

### convertIfNecessary

    public Object convertIfNecessary(Object value,
                                     Class requiredType,
                                     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. 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.

  Specified by:
    `convertIfNecessary` in interface `TypeConverter`
  Parameters:
    `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`)
  Returns:
    the new value, possibly the result of type conversion
  Throws:
    `TypeMismatchException` - if type conversion failed
  See Also:
    `PropertyEditor.setAsText(String)`, `PropertyEditor.getValue()`

### 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:
    `pvs` - property values to bind
  See Also:
    `doBind(org.springframework.beans.MutablePropertyValues)`

### doBind

    protected void doBind(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(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(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(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)`

### 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()`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| The Spring Framework
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002-2008 The Spring Framework.