程序包 cn.taketoday.web.bind

类 WebDataBinder

java.lang.Object
cn.taketoday.validation.DataBinder
cn.taketoday.web.bind.WebDataBinder
所有已实现的接口:
cn.taketoday.beans.PropertyEditorRegistry, cn.taketoday.beans.TypeConverter
直接已知子类:
ServletRequestDataBinder
public class WebDataBinder extends cn.taketoday.validation.DataBinder
Special DataBinder for data binding from web request parameters to JavaBean objects. Designed for web environments, but not dependent on the Servlet API; serves as base class for more specific DataBinder variants, such as ServletRequestDataBinder.

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 Infra Web MVC and Infra WebFlux in the reference manual.

Includes support for field markers which address a common problem with HTML checkboxes and select options: detecting that a field was part of the form, but did not generate a request parameter because it was empty. A field marker allows to detect that state and reset the corresponding bean property accordingly. Default values, for parameters that are otherwise not present, can specify a value for the field other then empty.

Can also used for manual data binding in custom web controllers or interceptors that build on Infra RequestContext implementation. Simply instantiate a WebDataBinder for each binding process, and invoke bind with the current RequestContext as argument: 

 
 MyBean myBean = new MyBean();
 // apply binder to custom target object
 WebDataBinder binder = new WebDataBinder(myBean);
 // register custom editors, if desired
 binder.registerCustomEditor(...);
 // trigger actual binding of request parameters
 binder.bind(request);
 // optionally evaluate binding errors
 Errors errors = binder.getErrors();
 // ...
从以下版本开始:
4.0 2022/3/2 16:28
作者:
Juergen Hoeller, Scott Andrews, Brian Clozel, Harry Yang
另请参阅:

  • 嵌套类概要

    嵌套类
    修饰符和类型
    类
    说明
    protected static class 
    WebDataBinder.RequestValueResolver
    Resolver that looks up values to bind in a ServletRequest.

    从类继承的嵌套类/接口 cn.taketoday.validation.DataBinder

    cn.taketoday.validation.DataBinder.NameResolver, cn.taketoday.validation.DataBinder.ValueResolver

  • 字段概要

    字段
    修饰符和类型
    字段
    说明
    private boolean
    bindEmptyMultipartFiles
     
    static final String
    DEFAULT_FIELD_DEFAULT_PREFIX
    Default prefix that field default parameters start with, followed by the field name: e.g. "!
    static final String
    DEFAULT_FIELD_MARKER_PREFIX
    Default prefix that field marker parameters start with, followed by the field name: e.g.
    private String
    fieldDefaultPrefix
     
    private String
    fieldMarkerPrefix
     

    从类继承的字段 cn.taketoday.validation.DataBinder

    DEFAULT_AUTO_GROW_COLLECTION_LIMIT, DEFAULT_OBJECT_NAME, logger

  • 构造器概要

    构造器
    构造器
    说明
    WebDataBinder(Object target)
    Create a new WebDataBinder instance, with default object name.
    WebDataBinder(Object target, String objectName)
    Create a new WebDataBinder instance.

  • 方法概要

    修饰符和类型
    方法
    说明
    protected void
    adaptEmptyArrayIndices(cn.taketoday.beans.PropertyValues values)
    Check for property values with names that end on "[]".
    void
    bind(RequestContext request)
    Bind the parameters of the given request to this binder's target, also binding multipart files in case of a multipart request.
    protected void
    bindMultipart(Map<String,List<MultipartFile>> multipartFiles, cn.taketoday.beans.PropertyValues mpvs)
    Bind all multipart files contained in the given request, if any (in case of a multipart request).
    protected void
    checkFieldDefaults(cn.taketoday.beans.PropertyValues values)
    Check the given property values for field defaults, i.e. for fields that start with the field default prefix.
    protected void
    checkFieldMarkers(cn.taketoday.beans.PropertyValues values)
    Check the given property values for field markers, i.e. for fields that start with the field marker prefix.
    void
    closeNoCatch()
    Treats errors as fatal.
    void
    construct(RequestContext request)
    Use a default or single data constructor to create the target by binding request parameters, multipart files, or parts to constructor args.
    protected void
    doBind(cn.taketoday.beans.PropertyValues values)
    This implementation performs a field default and marker check before delegating to the superclass binding process.
    Object
    getEmptyValue(Class<?> fieldType)
    Determine an empty value for the specified field.
    protected Object
    getEmptyValue(String field, Class<?> fieldType)
    Determine an empty value for the specified field.
    String
    getFieldDefaultPrefix()
    Return the prefix for parameters that mark default fields.
    String
    getFieldMarkerPrefix()
    Return the prefix for parameters that mark potentially empty fields.
    cn.taketoday.beans.PropertyValues
    getValuesToBind(RequestContext request)
    method to obtain the values for data binding.
    boolean
    isBindEmptyMultipartFiles()
    Return whether to bind empty MultipartFile parameters.
    protected Object
    resolvePrefixValue(String name, Class<?> type, BiFunction<String,Class<?>,Object> resolver)
    Check if a value can be resolved if getFieldDefaultPrefix() or getFieldMarkerPrefix() is prepended.
    void
    setBindEmptyMultipartFiles(boolean bindEmptyMultipartFiles)
    Set whether to bind empty MultipartFile parameters.
    void
    setFieldDefaultPrefix(String fieldDefaultPrefix)
    Specify a prefix that can be used for parameters that indicate default value fields, having "prefix + field" as name.
    void
    setFieldMarkerPrefix(String fieldMarkerPrefix)
    Specify a prefix that can be used for parameters that mark potentially empty fields, having "prefix + field" as name.

    从类继承的方法 cn.taketoday.validation.DataBinder

    addCustomFormatter, addCustomFormatter, addCustomFormatter, addValidators, applyPropertyValues, bind, checkAllowedFields, checkRequiredFields, close, construct, convertIfNecessary, convertIfNecessary, convertIfNecessary, convertIfNecessary, createBeanPropertyBindingResult, createDirectFieldBindingResult, findCustomEditor, getAllowedFields, getAutoGrowCollectionLimit, getBindingErrorProcessor, getBindingResult, getConversionService, getDisallowedFields, getInternalBindingResult, getNameResolver, getObjectName, getPropertyAccessor, getPropertyEditorRegistry, getRequiredFields, getSimpleTypeConverter, getTarget, getTargetType, getTypeConverter, getValidator, getValidators, getValidatorsToApply, initBeanPropertyAccess, initDirectFieldAccess, isAllowed, isAutoGrowNestedPaths, isDeclarativeBinding, isIgnoreInvalidFields, isIgnoreUnknownFields, registerCustomEditor, registerCustomEditor, replaceValidators, setAllowedFields, setAutoGrowCollectionLimit, setAutoGrowNestedPaths, setBindingErrorProcessor, setConversionService, setDeclarativeBinding, setDisallowedFields, setExcludedValidators, setIgnoreInvalidFields, setIgnoreUnknownFields, setMessageCodesResolver, setNameResolver, setRequiredFields, setTargetType, setValidator, shouldNotBindPropertyValues, validate, validate

    从类继承的方法 java.lang.Object

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

  • 字段详细资料

    • DEFAULT_FIELD_MARKER_PREFIX

      public static final String DEFAULT_FIELD_MARKER_PREFIX
      Default prefix that field marker parameters start with, followed by the field name: e.g. "_subscribeToNewsletter" for a field "subscribeToNewsletter".

      Such a marker parameter indicates that the field was visible, that is, existed in the form that caused the submission. If no corresponding field value parameter was found, the field will be reset. The value of the field marker parameter does not matter in this case; an arbitrary value can be used. This is particularly useful for HTML checkboxes and select options.

      另请参阅:

    • DEFAULT_FIELD_DEFAULT_PREFIX

      public static final String DEFAULT_FIELD_DEFAULT_PREFIX
      Default prefix that field default parameters start with, followed by the field name: e.g. "!subscribeToNewsletter" for a field "subscribeToNewsletter".

      Default parameters differ from field markers in that they provide a default value instead of an empty value.

      另请参阅:

    • fieldMarkerPrefix

      @Nullable private String fieldMarkerPrefix

    • fieldDefaultPrefix

      @Nullable private String fieldDefaultPrefix

    • bindEmptyMultipartFiles

      private boolean bindEmptyMultipartFiles

  • 构造器详细资料

    • WebDataBinder

      public WebDataBinder(@Nullable Object target)
      Create a new WebDataBinder 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)
      另请参阅:
      • DataBinder.DEFAULT_OBJECT_NAME

    • WebDataBinder

      public WebDataBinder(@Nullable Object target, String objectName)
      Create a new WebDataBinder 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

  • 方法详细资料

    • setFieldMarkerPrefix

      public void setFieldMarkerPrefix(@Nullable String fieldMarkerPrefix)
      Specify a prefix that can be used for parameters that mark potentially empty fields, having "prefix + field" as name. Such a marker parameter is checked by existence: You can send any value for it, for example "visible". This is particularly useful for HTML checkboxes and select options.

      Default is "_", for "_FIELD" parameters (e.g. "_subscribeToNewsletter"). Set this to null if you want to turn off the empty field check completely.

      HTML checkboxes only send a value when they're checked, so it is not possible to detect that a formerly checked box has just been unchecked, at least not with standard HTML means.

      One way to address this is to look for a checkbox parameter value if you know that the checkbox has been visible in the form, resetting the checkbox if no value found. In Framework web MVC, this typically happens in a custom onBind implementation.

      This auto-reset mechanism addresses this deficiency, provided that a marker parameter is sent for each checkbox field, like "_subscribeToNewsletter" for a "subscribeToNewsletter" field. As the marker parameter is sent in any case, the data binder can detect an empty field and automatically reset its value.

      另请参阅:

    • getFieldMarkerPrefix

      @Nullable public String getFieldMarkerPrefix()
      Return the prefix for parameters that mark potentially empty fields.

    • setFieldDefaultPrefix

      public void setFieldDefaultPrefix(@Nullable String fieldDefaultPrefix)
      Specify a prefix that can be used for parameters that indicate default value fields, having "prefix + field" as name. The value of the default field is used when the field is not provided.

      Default is "!", for "!FIELD" parameters (e.g. "!subscribeToNewsletter"). Set this to null if you want to turn off the field defaults completely.

      HTML checkboxes only send a value when they're checked, so it is not possible to detect that a formerly checked box has just been unchecked, at least not with standard HTML means. A default field is especially useful when a checkbox represents a non-boolean value.

      The presence of a default parameter preempts the behavior of a field marker for the given field.

      另请参阅:

    • getFieldDefaultPrefix

      @Nullable public String getFieldDefaultPrefix()
      Return the prefix for parameters that mark default fields.

    • setBindEmptyMultipartFiles

      public void setBindEmptyMultipartFiles(boolean bindEmptyMultipartFiles)
      Set whether to bind empty MultipartFile parameters. Default is "true".

      Turn this off if you want to keep an already bound MultipartFile when the user resubmits the form without choosing a different file. Else, the already bound MultipartFile will be replaced by an empty MultipartFile holder.

      另请参阅:

    • isBindEmptyMultipartFiles

      public boolean isBindEmptyMultipartFiles()
      Return whether to bind empty MultipartFile parameters.

    • resolvePrefixValue

      @Nullable protected Object resolvePrefixValue(String name, Class<?> type, BiFunction<String,Class<?>,Object> resolver)
      Check if a value can be resolved if getFieldDefaultPrefix() or getFieldMarkerPrefix() is prepended.
      参数:
      name - the name of the value to resolve
      type - the type of value expected
      resolver - delegate resolver to use for the checks
      返回:
      the resolved value, or null

    • doBind

      protected void doBind(cn.taketoday.beans.PropertyValues values)
      This implementation performs a field default and marker check before delegating to the superclass binding process.
      覆盖:
      doBind 在类中 cn.taketoday.validation.DataBinder
      另请参阅:

    • checkFieldDefaults

      protected void checkFieldDefaults(cn.taketoday.beans.PropertyValues values)
      Check the given property values for field defaults, i.e. for fields that start with the field default prefix.

      The existence of a field defaults indicates that the specified value should be used if the field is otherwise not present.

      参数:
      values - the property values to be bound (can be modified)
      另请参阅:

    • checkFieldMarkers

      protected void checkFieldMarkers(cn.taketoday.beans.PropertyValues values)
      Check the given property values for field markers, i.e. for fields that start with the field marker prefix.

      The existence of a field marker indicates that the specified field existed in the form. If the property values do not contain a corresponding field value, the field will be considered as empty and will be reset appropriately.

      参数:
      values - the property values to be bound (can be modified)
      另请参阅:

    • adaptEmptyArrayIndices

      protected void adaptEmptyArrayIndices(cn.taketoday.beans.PropertyValues values)
      Check for property values with names that end on "[]". This is used by some clients for array syntax without an explicit index value. If such values are found, drop the brackets to adapt to the expected way of expressing the same for data binding purposes.
      参数:
      values - the property values to be bound (can be modified)

    • getEmptyValue

      @Nullable protected Object getEmptyValue(String field, @Nullable Class<?> fieldType)
      Determine an empty value for the specified field.

      The default implementation delegates to getEmptyValue(Class) if the field type is known, otherwise falls back to null.

      参数:
      field - the name of the field
      fieldType - the type of the field
      返回:
      the empty value (for most fields: null)

    • getEmptyValue

      @Nullable public Object getEmptyValue(Class<?> fieldType)
      Determine an empty value for the specified field.

      The default implementation returns:

      • Boolean.FALSE for boolean fields
      • an empty array for array types
      • Collection implementations for Collection types
      • Map implementations for Map types
      • else, null is used as default
      参数:
      fieldType - the type of the field
      返回:
      the empty value (for most fields: null)

    • construct

      public void construct(RequestContext request)
      Use a default or single data constructor to create the target by binding request parameters, multipart files, or parts to constructor args.

      After the call, use DataBinder.getBindingResult() to check for bind errors. If there are none, the target is set, and bind(RequestContext) can be called for further initialization via setters.

      参数:
      request - the request to bind

    • bind

      public void bind(RequestContext request)
      Bind the parameters of the given request to this binder's target, also binding multipart files in case of a multipart request.

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

      Multipart files are bound via their parameter name, just like normal HTTP parameters: i.e. "uploadedFile" to an "uploadedFile" bean property, invoking a "setUploadedFile" setter method.

      The type of the target property for a multipart file can be Part, MultipartFile, byte[], or String. The latter two receive the contents of the uploaded file; all metadata like original file name, content type, etc are lost in those cases.

      参数:
      request - the request with parameters to bind (can be multipart)
      另请参阅:

    • getValuesToBind

      public cn.taketoday.beans.PropertyValues getValuesToBind(RequestContext request)
      method to obtain the values for data binding.
      参数:
      request - the current exchange
      返回:
      a map of bind values

    • bindMultipart

      protected void bindMultipart(Map<String,List<MultipartFile>> multipartFiles, cn.taketoday.beans.PropertyValues mpvs)
      Bind all multipart files contained in the given request, if any (in case of a multipart request). To be called by subclasses.

      Multipart files will only be added to the property values if they are not empty or if we're configured to bind empty multipart files too.

      参数:
      multipartFiles - a Map of field name String to MultipartFile object
      mpvs - the property values to be bound (can be modified)
      另请参阅:

    • closeNoCatch

      public void closeNoCatch() throws cn.taketoday.validation.BindException
      Treats errors as fatal.

      Use this method only if it's an error if the input isn't valid. This might be appropriate if all input is from dropdowns, for example.

      抛出:
      cn.taketoday.validation.BindException - if binding errors have been encountered