Improved documentation on how to convert collections with ConversionService

Issue: SPR-11432
This commit is contained in:
Juergen Hoeller 2014-03-10 18:18:29 +01:00
parent 7a6ec69523
commit 264d7b9c98
1 changed files with 39 additions and 7 deletions

View File

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