@ -1,20 +1,20 @@
[[beans -binding]] [[data -binding]]
= Data Binding = Data Binding
Data binding is useful for binding user input to a target object where user input is a map 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 `DataBinder` is the main class that supports this, and it provides two ways to bind user
input: input:
- xref:beans -constructor-binding[Constructor binding] - bind user input to a public dat a - xref:data-binding -constructor-binding[Constructor binding] - bind user input to a
constructor, looking up constructor argument values in the user input. 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 - xref:data-binding-property-binding[Property binding] - bind user input to setters,
user input to properties of the target object structure. matching keys from the user input to properties of the target object structure.
You can apply both constructor and property binding or only one. You can apply both constructor and property binding or only one.
[[beans -constructor-binding]] [[data-binding -constructor-binding]]
== Constructor Binding == Constructor Binding
To use 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 parameters or fields if present. If necessary, you can also configure a `NameResolver` on
`DataBinder` to customize the argument name to use. `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 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 manner, but through a nested property path. That means constructor binding creates both
the target object and any objects it contains. 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`. after the call to `construct`.
[[data-binding-property-binding]]
[[beans-beans]]
== Property Binding with `BeanWrapper` == Property Binding with `BeanWrapper`
The `org.springframework.beans` package adheres to the JavaBeans standard. 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. perform actions on that bean, such as setting and retrieving properties.
[[data-binding-conventions]]
[[beans-beans-conventions]]
=== Setting and Getting Basic and Nested Properties === Setting and Getting Basic and Nested Properties
Setting and getting properties is done through the `setPropertyValue` and Setting and getting properties is done through the `setPropertyValue` and
`getPropertyValue` overloaded method variants of `BeanWrapper`. See their Javadoc for `getPropertyValue` overloaded method variants of `BeanWrapper`. See their Javadoc for
details. The below table shows some examples of these conventions: details. The below table shows some examples of these conventions:
[[beans-beans -conventions-properties-tbl]] [[data-binding -conventions-properties-tbl]]
.Examples of properties .Examples of properties
|=== |===
| Expression| Explanation | 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 (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` the `BeanWrapper` directly. If you use only the `DataBinder` and the `BeanFactory`
and their default implementations, you should skip ahead to the 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 The following two example classes use the `BeanWrapper` to get and set
properties: properties:
@ -239,9 +236,8 @@ Kotlin::
====== ======
[[data-binding-conversion]]
[[beans-beans-conversion]] == ``PropertyEditor``s
== ``PropertyEditor``'s
Spring uses the concept of a `PropertyEditor` to effect the conversion between an Spring uses the concept of a `PropertyEditor` to effect the conversion between an
`Object` and a `String`. It can be handy `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 still register your own variant to override the default one. The following table describes
the various `PropertyEditor` implementations that Spring provides: the various `PropertyEditor` implementations that Spring provides:
[[beans-beans -property-editors-tbl]] [[data-binding -property-editors-tbl]]
.Built-in `PropertyEditor` Implementations .Built-in `PropertyEditor` Implementations
[cols="30%,70%"] [cols="30%,70%"]
|=== |===
@ -426,8 +422,8 @@ Kotlin::
====== ======
[[beans-beans -conversion-customeditor-registration]] [[data-binding -conversion-customeditor-registration]]
=== Custom ``PropertyEditor``' s === Custom ``PropertyEditor``s
When setting bean properties as string values, a Spring IoC container ultimately uses 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 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 Note that all bean factories and application contexts automatically use a number of
built-in property editors, through their use of a `BeanWrapper` to built-in property editors, through their use of a `BeanWrapper` to
handle property conversions. The standard property editors that the `BeanWrapper` 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 Additionally, ``ApplicationContext``s also override or add additional editors to handle
resource lookups in a manner appropriate to the specific application context type. 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
</bean> </bean>
---- ----
[[beans-beans -conversion-customeditor-registration-per]] [[data-binding -conversion-customeditor-registration-per]]
=== `PropertyEditorRegistrar` === `PropertyEditorRegistrar`
Another mechanism for registering property editors with the Spring container is to 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` `PropertyEditorRegistry`, an interface that is implemented by the Spring `BeanWrapper`
(and `DataBinder`). `PropertyEditorRegistrar` instances are particularly convenient (and `DataBinder`). `PropertyEditorRegistrar` instances are particularly convenient
when used in conjunction with `CustomEditorConfigurer` (described 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 called `setPropertyEditorRegistrars(..)`. `PropertyEditorRegistrar` instances added
to a `CustomEditorConfigurer` in this fashion can easily be shared with `DataBinder` and 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 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` 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 registration code be encapsulated in a class and then shared amongst as many controllers
as needed. as needed.
Sam Brannen
5 months ago