Permalink
Browse files

Improved documentation on how to convert collections with ConversionS…

…ervice

Issue: SPR-11432
  • Loading branch information...
1 parent 7a6ec69 commit 264d7b9c98018aee517b2c14bbfd0ff05e000706 @jhoeller jhoeller committed Mar 10, 2014
Showing with 39 additions and 7 deletions.
  1. +39 −7 src/asciidoc/index.adoc
View
@@ -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.
+

0 comments on commit 264d7b9

Please sign in to comment.