diff --git a/org.springframework.core/src/test/java/org/springframework/core/convert/support/DefaultConversionTests.java b/org.springframework.core/src/test/java/org/springframework/core/convert/support/DefaultConversionTests.java index 7d0992d5372..6d1a9e5becb 100644 --- a/org.springframework.core/src/test/java/org/springframework/core/convert/support/DefaultConversionTests.java +++ b/org.springframework.core/src/test/java/org/springframework/core/convert/support/DefaultConversionTests.java @@ -36,6 +36,8 @@ import java.util.Locale; import java.util.Map; import java.util.Set; +import junit.framework.Assert; + import org.junit.Test; import org.springframework.core.convert.ConversionFailedException; import org.springframework.core.convert.ConversionService; @@ -47,6 +49,22 @@ public class DefaultConversionTests { private ConversionService conversionService = ConversionServiceFactory.getDefault(); + @Test + @SuppressWarnings("unchecked") + public void testUnmodifiableListConversion() { + List stringList = new ArrayList(); + stringList.add("foo"); + stringList.add("bar"); + + List frozenList = Collections.unmodifiableList(stringList); + + List converted = conversionService.convert(frozenList, List.class); + + // The converted list should contain all the elements in the original list + Assert.assertEquals(frozenList, converted); + Assert.assertNotSame(frozenList, converted); + } + @Test public void testStringToCharacter() { assertEquals(Character.valueOf('1'), conversionService.convert("1", Character.class)); diff --git a/spring-framework-reference/src/validation.xml b/spring-framework-reference/src/validation.xml index b6ff11256c8..d007c459f94 100644 --- a/spring-framework-reference/src/validation.xml +++ b/spring-framework-reference/src/validation.xml @@ -752,17 +752,17 @@ public final class CustomPropertyEditorRegistrar implements PropertyEditorRegist Spring 3 Type Conversion Spring 3 introduces a core.convert package that provides a general type conversion system. - The system defines an API to implement type conversion logic, as well as an API to execute type conversions at runtime. - Within a Spring container, if configured, this system can be used as an alternative to PropertyEditors to convert externalized bean property value strings to required property types. + The system defines an SPI to implement type conversion logic, as well as an API to execute type conversions at runtime. + Within a Spring container, this system can be used as an alternative to PropertyEditors to convert externalized bean property value strings to required property types. The public API may also be used anywhere in your application where type conversion is needed.
- Converter API + Converter SPI - The API to implement type conversion logic is simple and strongly typed: + The SPI to implement type conversion logic is simple and strongly typed: { @@ -778,13 +778,14 @@ public interface Converter { Take care to ensure your Converter implementation is thread-safe. - Several converter implementations are provided in the core.convert.converters package as a convenience. + 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: - package org.springframework.core.convert.converters; + +package org.springframework.core.convert.support; -public class StringToInteger implements Converter<String, Integer> { +final class StringToInteger implements Converter<String, Integer> { public Integer convert(String source) { return Integer.valueOf(source); @@ -795,10 +796,10 @@ public class StringToInteger implements Converter<String, Integer> {
ConverterFactory - When you need to centralize the conversion logic for an entire class hierarchy, for example, when converting from String to java.lang.Enum objects, implement a ConverterFactory: + When you need to centralize the conversion logic for an entire class hierarchy, for example, when converting from String to java.lang.Enum objects, implement ConverterFactory: { @@ -813,17 +814,19 @@ public interface ConverterFactory { Consider the StringToEnum ConverterFactory as an example: { +package org.springframework.core.convert.support; + +final class StringToEnumConverterFactory implements ConverterFactory { public Converter getConverter(Class targetType) { - return new StringToEnum(targetType); + return new StringToEnumConverter(targetType); } - private final class StringToEnum implements Converter { + private final class StringToEnumConverter implements Converter { private Class enumType; - public StringToEnum(Class enumType) { + public StringToEnumConverter(Class enumType) { this.enumType = enumType; } @@ -832,29 +835,93 @@ public class StringToEnumFactory implements ConverterFactory { } } }]]> -
+
+
+ GenericConverter + + When you require a sophisticated Converter implementation, consider the GenericConverter interface. + With a more flexible but less strongly typed signature, a GenericConverter supports converting between multiple source and target types. + In addition, a GenericConverter makes available source and target field context you can use when implementing your conversion logic. + Such context allows a type conversion to be driven by a field annotation, or generic information declared on a field signature. + + [][] getConvertibleTypes(); + + Object convert(Object source, TypeDescriptor sourceType, TypeDescriptor targetType); + +}]]> + + + To implement a GenericConverter, have getConvertibleTypes() return the supported source->target type pairs. + Then implement convert(Object, TypeDescriptor, TypeDescriptor) to implement your conversion logic. + The source TypeDescriptor provides access to the source field holding the value being converted. + The target TypeDescriptor provides access to the target field where the converted value will be set. + + + A good example of a GenericConverter is a converter that converts between a Java Array and a Collection. + Such an ArrayToCollectionConverter introspects the field that declares the target Collection type to resolve the Collection's element type. + This allows each element in the source array to be converted to the Collection element type before the Collection is set on the target field. + + + + Because GenericConverter is a more complex SPI interface, only use it when you need it. + Favor Converter or ConverterFactory for basic type conversion needs. + + +
+ ConditionalGenericConverter + + Sometimes you only want a Converter to execute if a specific condition holds true. + For example, you might only want to execute a Converter if a specific annotation is present on the target field. + Or you might only want to execute a Converter if a specific method, such as static valueOf method, is defined on the target class. + ConditionalGenericConverter is an subinterface of GenericConverter that allows you to define such custom matching criteria: + + + + + A good example of a ConditionalGenericConverter is an EntityConverter that converts between an persistent entity identifier and an entity reference. + Such a EntityConverter might only match if the target entity type declares a static finder method e.g. findAccount(Long). + You would perform such a finder method check in the implementation of matches(TypeDescriptor, TypeDescriptor). + +
+
ConversionService API - The ConversionService defines a public API for executing type conversion logic at runtime. + The ConversionService defines a unified API for executing type conversion logic at runtime. Converters are often executed behind this facade interface: sourceType, Class targetType); T convert(Object source, Class targetType); + + boolean canConvert(TypeDescriptor sourceType, TypeDescriptor targetType); + + Object convert(Object source, TypeDescriptor sourceType, TypeDescriptor targetType); }]]> Most ConversionService implementations also implement ConverterRegistry, which provides an SPI for registering converters. - Internally, a ConversionService implementation delegates to its registered Converters and ConverterFactories to carry out type conversion logic. + Internally, a ConversionService implementation delegates to its registered converters to carry out type conversion logic. - Two ConversionService implementations are provided with the system in the core.convert.support package. - GenericConversionService is a generic implementation designed to be explicitly configured, either programatically or declaratively as a Spring bean. - DefaultConversionService is a subclass that pre-registers the common Converters in the core.converter package as a convenience. + A robust ConversionService implementation is provided in the core.convert.support package. + GenericConversionService is the general-purpose implementation suitable for use in most environments. + ConversionServiceFactory provides a convenient factory for creating common ConversionService configurations.
@@ -871,16 +938,18 @@ public interface ConversionService { - To register the DefaultConversionService with Spring, simply configure it as a bean with the id conversionService: + To register a default ConversionService with Spring, add the following bean definition with id conversionService: ]]> +]]> - To override the default set of converters with your own custom converter(s), set the converters property: + A default ConversionService can convert betweenstrings, numbers, enums, collections, maps, and other common types. + To suppliment or override the default converters with your own custom converter(s), set the converters property. + Property values may implement either of the Converter, ConverterFactory, or GenericConverter interfaces. +