diff --git a/src/asciidoc/index.adoc b/src/asciidoc/index.adoc index 731b1aca0a..ef7dc0ab2a 100644 --- a/src/asciidoc/index.adoc +++ b/src/asciidoc/index.adoc @@ -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 input = .... + cs.convert(input, + TypeDescriptor.forObject(input), // List 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. +