Improved documentation on how to convert collections with ConversionService
Issue: SPR-11432
This commit is contained in:
parent
7a6ec69523
commit
264d7b9c98
|
|
@ -9758,16 +9758,20 @@ The SPI to implement type conversion logic is simple and strongly typed:
|
|||
}
|
||||
----
|
||||
|
||||
To create your own Converter, simply implement the interface above. Parameterize S as
|
||||
the type you are converting from, and T as the type you are converting to. For each call
|
||||
to convert(S), the source argument is guaranteed to be NOT null. Your Converter may
|
||||
throw any unchecked exception if conversion fails. An `IllegalArgumentException` should
|
||||
be thrown to report an invalid source value. Take care to ensure your Converter implementation
|
||||
is thread-safe.
|
||||
To create your own converter, simply implement the interface above. Parameterize `S`
|
||||
as the type you are converting from, and `T` as the type you are converting to. Such a
|
||||
converter can also be applied transparently if a collection or array of `S` needs to be
|
||||
converted to an array or collection of `T`, provided that a delegating array/collection
|
||||
converter has been registered as well (which `DefaultConversionService` does by default).
|
||||
|
||||
For each call to `convert(S)`, the source argument is guaranteed to be NOT null. Your
|
||||
Converter may throw any unchecked exception if conversion fails; specifically, an
|
||||
`IllegalArgumentException` should be thrown to report an invalid source value.
|
||||
Take care to ensure that your `Converter` implementation is thread-safe.
|
||||
|
||||
Several converter implementations are provided in the `core.convert.support` package as
|
||||
a convenience. These include converters from Strings to Numbers and other common types.
|
||||
Consider `StringToInteger` as an example Converter implementation:
|
||||
Consider `StringToInteger` as an example for a typical `Converter` implementation:
|
||||
|
||||
[source,java,indent=0]
|
||||
[subs="verbatim,quotes"]
|
||||
|
|
@ -10014,6 +10018,34 @@ it like you would for any other bean:
|
|||
}
|
||||
----
|
||||
|
||||
For most use cases, the `convert` method specifying the _targetType_ can be used but it
|
||||
will not work with more complex types such as a collection of a parameterized element.
|
||||
If you want to convert a `List` of `Integer` to a `List` of `String` programmatically,
|
||||
for instance, you need to provide a formal definition of the source and target types.
|
||||
|
||||
Fortunately, `TypeDescriptor` provides various options to make that straightforward:
|
||||
|
||||
[source,java,indent=0]
|
||||
[subs="verbatim,quotes"]
|
||||
----
|
||||
DefaultConversionService cs = new DefaultConversionService();
|
||||
|
||||
List<Integer> input = ....
|
||||
cs.convert(input,
|
||||
TypeDescriptor.forObject(input), // List<Integer> type descriptor
|
||||
TypeDescriptor.collection(List.class, TypeDescriptor.valueOf(String.class)));
|
||||
----
|
||||
|
||||
Note that `DefaultConversionService` registers converters automatically which are
|
||||
appropriate for most environments. This includes collection converters, scalar
|
||||
converters, and also basic `Object` to `String` converters. The same converters can
|
||||
be registered with any `ConverterRegistry` using the _static_ `addDefaultConverters`
|
||||
method on the `DefaultConversionService` class.
|
||||
|
||||
Converters for value types will be reused for arrays and collections, so there is
|
||||
no need to create a specific converter to convert from a `Collection` of `S` to a
|
||||
`Collection` of `T`, assuming that standard collection handling is appropriate.
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue