diff --git a/framework-docs/modules/ROOT/nav.adoc b/framework-docs/modules/ROOT/nav.adoc index f8389c3fdcf..02e9bc8dd16 100644 --- a/framework-docs/modules/ROOT/nav.adoc +++ b/framework-docs/modules/ROOT/nav.adoc @@ -40,8 +40,8 @@ ** xref:core/resources.adoc[] ** xref:core/validation.adoc[] *** xref:core/validation/validator.adoc[] -*** xref:core/validation/beans-beans.adoc[] -*** xref:core/validation/conversion.adoc[] +*** xref:core/validation/data-binding.adoc[] +*** xref:core/validation/error-code-resolution.adoc[] *** xref:core/validation/convert.adoc[] *** xref:core/validation/format.adoc[] *** xref:core/validation/format-configuring-formatting-globaldatetimeformat.adoc[] diff --git a/framework-docs/modules/ROOT/pages/core/validation/beans-beans.adoc b/framework-docs/modules/ROOT/pages/core/validation/data-binding.adoc similarity index 95% rename from framework-docs/modules/ROOT/pages/core/validation/beans-beans.adoc rename to framework-docs/modules/ROOT/pages/core/validation/data-binding.adoc index d522a57c990..67390508849 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/beans-beans.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/data-binding.adoc @@ -1,20 +1,20 @@ -[[beans-binding]] +[[data-binding]] = Data Binding Data binding is useful for binding user input to a target object where user input is a map -with property paths as keys, following xref:beans-beans-conventions[JavaBeans conventions]. +with property paths as keys, following xref:data-binding-conventions[JavaBeans conventions]. `DataBinder` is the main class that supports this, and it provides two ways to bind user input: -- xref:beans-constructor-binding[Constructor binding] - bind user input to a public data -constructor, looking up constructor argument values in the user input. -- xref:beans-beans[Property binding] - bind user input to setters, matching keys from the -user input to properties of the target object structure. +- xref:data-binding-constructor-binding[Constructor binding] - bind user input to a + public data constructor, looking up constructor argument values in the user input. +- xref:data-binding-property-binding[Property binding] - bind user input to setters, + matching keys from the user input to properties of the target object structure. You can apply both constructor and property binding or only one. -[[beans-constructor-binding]] +[[data-binding-constructor-binding]] == Constructor Binding To use constructor binding: @@ -32,7 +32,7 @@ WebFlux support a custom name mapping through the `@BindParam` annotation on con parameters or fields if present. If necessary, you can also configure a `NameResolver` on `DataBinder` to customize the argument name to use. -xref:beans-beans-conventions[Type conversion] is applied as needed to convert user input. +xref:data-binding-conventions[Type conversion] is applied as needed to convert user input. If the constructor parameter is an object, it is constructed recursively in the same manner, but through a nested property path. That means constructor binding creates both the target object and any objects it contains. @@ -46,9 +46,7 @@ If the target is created successfully, then `target` is set to the created insta after the call to `construct`. - - -[[beans-beans]] +[[data-binding-property-binding]] == Property Binding with `BeanWrapper` The `org.springframework.beans` package adheres to the JavaBeans standard. @@ -74,15 +72,14 @@ The way the `BeanWrapper` works is partly indicated by its name: it wraps a bean perform actions on that bean, such as setting and retrieving properties. - -[[beans-beans-conventions]] +[[data-binding-conventions]] === Setting and Getting Basic and Nested Properties Setting and getting properties is done through the `setPropertyValue` and `getPropertyValue` overloaded method variants of `BeanWrapper`. See their Javadoc for details. The below table shows some examples of these conventions: -[[beans-beans-conventions-properties-tbl]] +[[data-binding-conventions-properties-tbl]] .Examples of properties |=== | Expression| Explanation @@ -106,7 +103,7 @@ details. The below table shows some examples of these conventions: (This next section is not vitally important to you if you do not plan to work with the `BeanWrapper` directly. If you use only the `DataBinder` and the `BeanFactory` and their default implementations, you should skip ahead to the -xref:core/validation/beans-beans.adoc#beans-beans-conversion[section on `PropertyEditors`].) +xref:core/validation/data-binding.adoc#data-binding-conversion[section on `PropertyEditors`].) The following two example classes use the `BeanWrapper` to get and set properties: @@ -239,9 +236,8 @@ Kotlin:: ====== - -[[beans-beans-conversion]] -== ``PropertyEditor``'s +[[data-binding-conversion]] +== ``PropertyEditor``s Spring uses the concept of a `PropertyEditor` to effect the conversion between an `Object` and a `String`. It can be handy @@ -272,7 +268,7 @@ package. Most, (but not all, as indicated in the following table) are, by defaul still register your own variant to override the default one. The following table describes the various `PropertyEditor` implementations that Spring provides: -[[beans-beans-property-editors-tbl]] +[[data-binding-property-editors-tbl]] .Built-in `PropertyEditor` Implementations [cols="30%,70%"] |=== @@ -426,8 +422,8 @@ Kotlin:: ====== -[[beans-beans-conversion-customeditor-registration]] -=== Custom ``PropertyEditor``'s +[[data-binding-conversion-customeditor-registration]] +=== Custom ``PropertyEditor``s When setting bean properties as string values, a Spring IoC container ultimately uses standard JavaBeans `PropertyEditor` implementations to convert these strings to the complex type of the @@ -451,7 +447,7 @@ where it can be automatically detected and applied. Note that all bean factories and application contexts automatically use a number of built-in property editors, through their use of a `BeanWrapper` to handle property conversions. The standard property editors that the `BeanWrapper` -registers are listed in the xref:core/validation/beans-beans.adoc#beans-beans-conversion[previous section]. +registers are listed in the xref:core/validation/data-binding.adoc#data-binding-conversion[previous section]. Additionally, ``ApplicationContext``s also override or add additional editors to handle resource lookups in a manner appropriate to the specific application context type. @@ -569,7 +565,7 @@ Finally, the following example shows how to use `CustomEditorConfigurer` to regi ---- -[[beans-beans-conversion-customeditor-registration-per]] +[[data-binding-conversion-customeditor-registration-per]] === `PropertyEditorRegistrar` Another mechanism for registering property editors with the Spring container is to @@ -580,7 +576,7 @@ You can write a corresponding registrar and reuse it in each case. `PropertyEditorRegistry`, an interface that is implemented by the Spring `BeanWrapper` (and `DataBinder`). `PropertyEditorRegistrar` instances are particularly convenient when used in conjunction with `CustomEditorConfigurer` (described -xref:core/validation/beans-beans.adoc#beans-beans-conversion-customeditor-registration[here]), which exposes a property +xref:core/validation/data-binding.adoc#data-binding-conversion-customeditor-registration[here]), which exposes a property called `setPropertyEditorRegistrars(..)`. `PropertyEditorRegistrar` instances added to a `CustomEditorConfigurer` in this fashion can easily be shared with `DataBinder` and Spring MVC controllers. Furthermore, it avoids the need for synchronization on custom @@ -703,7 +699,3 @@ This style of `PropertyEditor` registration can lead to concise code (the implem of the `@InitBinder` method is only one line long) and lets common `PropertyEditor` registration code be encapsulated in a class and then shared amongst as many controllers as needed. - - - - diff --git a/framework-docs/modules/ROOT/pages/core/validation/conversion.adoc b/framework-docs/modules/ROOT/pages/core/validation/error-code-resolution.adoc similarity index 90% rename from framework-docs/modules/ROOT/pages/core/validation/conversion.adoc rename to framework-docs/modules/ROOT/pages/core/validation/error-code-resolution.adoc index 37c62169572..c90b9a75964 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/conversion.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/error-code-resolution.adoc @@ -1,7 +1,7 @@ -[[validation-conversion]] -= Resolving Codes to Error Messages +[[validation-error-code-resolution]] += Resolving Error Codes to Error Messages -We covered databinding and validation. This section covers outputting messages that correspond +We covered data binding and validation. This section covers outputting messages that correspond to validation errors. In the example shown in the xref:core/validation/validator.adoc[preceding section], we rejected the `name` and `age` fields. If we want to output the error messages by using a `MessageSource`, we can do so using the error code we provide when rejecting the field @@ -23,6 +23,3 @@ in the javadoc of {spring-framework-api}/validation/DefaultMessageCodesResolver.html[`DefaultMessageCodesResolver`], respectively. - - - diff --git a/framework-docs/modules/ROOT/pages/core/validation/validator.adoc b/framework-docs/modules/ROOT/pages/core/validation/validator.adoc index 1d446814a10..4d795bf898f 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/validator.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/validator.adoc @@ -1,5 +1,5 @@ [[validator]] -= Validation by Using Spring's Validator Interface += Validation Using Spring's Validator Interface Spring features a `Validator` interface that you can use to validate objects. The `Validator` interface works by using an `Errors` object so that, while validating, diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/modelattrib-method-args.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/modelattrib-method-args.adoc index 632377c7b97..f350dea004e 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/modelattrib-method-args.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/modelattrib-method-args.adoc @@ -43,7 +43,7 @@ request parameters. Argument names are determined through runtime-retained param names in the bytecode. By default, both constructor and property -xref:core/validation/beans-beans.adoc#beans-binding[data binding] are applied. However, +xref:core/validation/data-binding.adoc[data binding] are applied. However, model object design requires careful consideration, and for security reasons it is recommended either to use an object tailored specifically for web binding, or to apply constructor binding only. If property binding must still be used, then _allowedFields_ diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc index d9808acc054..cd4c2c95d47 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc @@ -78,7 +78,7 @@ Kotlin:: ====== By default, both constructor and property -xref:core/validation/beans-beans.adoc#beans-binding[data binding] are applied. However, +xref:core/validation/data-binding.adoc[data binding] are applied. However, model object design requires careful consideration, and for security reasons it is recommended either to use an object tailored specifically for web binding, or to apply constructor binding only. If property binding must still be used, then _allowedFields_ diff --git a/framework-docs/modules/ROOT/partials/web/web-data-binding-model-design.adoc b/framework-docs/modules/ROOT/partials/web/web-data-binding-model-design.adoc index 74fe12d51bb..6300e15f645 100644 --- a/framework-docs/modules/ROOT/partials/web/web-data-binding-model-design.adoc +++ b/framework-docs/modules/ROOT/partials/web/web-data-binding-model-design.adoc @@ -1,4 +1,4 @@ -xref:core/validation/beans-beans.adoc#beans-binding[Data binding] for web requests involves +xref:core/validation/data-binding.adoc[Data binding] for web requests involves binding request parameters to a model object. By default, request parameters can be bound to any public property of the model object, which means malicious clients can provide extra values for properties that exist in the model object graph, but are not expected to @@ -39,7 +39,7 @@ the properties required for the input: ---- Another good practice is to apply -xref:core/validation/beans-beans.adoc#beans-constructor-binding[constructor binding], +xref:core/validation/data-binding.adoc#data-binding-constructor-binding[constructor binding], which uses only the request parameters it needs for constructor arguments, and any other input is ignored. This is in contrast to property binding which by default binds every request parameter for which there is a matching property.