From 85647ff33660aeb96d929df5fd605f1e432bee4c Mon Sep 17 00:00:00 2001 From: Keith Donald Date: Mon, 12 Oct 2009 19:14:45 +0000 Subject: [PATCH] spring 3 object mapping ref docs git-svn-id: https://src.springframework.org/svn/spring-framework/trunk@2088 50f2f4bb-b051-0410-bef5-90022cba6387 --- spring-framework-reference/src/validation.xml | 306 +++++++++++++++++- 1 file changed, 297 insertions(+), 9 deletions(-) diff --git a/spring-framework-reference/src/validation.xml b/spring-framework-reference/src/validation.xml index 8d12b2ae8a4..5ea50ecbe60 100644 --- a/spring-framework-reference/src/validation.xml +++ b/spring-framework-reference/src/validation.xml @@ -752,21 +752,21 @@ 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 SPI to implement type conversion logic, as well as an API to execute type conversions at runtime. + 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 public API may also be used anywhere in your application where type conversion is needed. -
- Converter SPI +
+ Converter API - The SPI to implement type conversion logic is simple and strongly typed: + The API to implement type conversion logic is simple and strongly typed: { - T convert(S source) throws Exception; + T convert(S source); }]]> @@ -774,7 +774,7 @@ public interface Converter { 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 Exception if conversion fails. - An IllegalArgumentException is often thrown to report an invalid source value. + An IllegalArgumentException should be thrown to report an invalid source value. Take care to ensure your Converter implementation is thread-safe. @@ -827,7 +827,7 @@ public class StringToEnumFactory implements ConverterFactory { this.enumType = enumType; } - public T convert(String source) throws Exception { + public T convert(String source) { return (T) Enum.valueOf(this.enumType, source.trim()); } } @@ -837,8 +837,7 @@ public class StringToEnumFactory implements ConverterFactory { ConversionService API The ConversionService defines a public API for executing type conversion logic at runtime. - Converters are always executed behind this API. - User code should not depend on the Converter SPI. + Converters are often executed behind this facade interface:
+
+ Spring 3 Object Mapping + + There are scenarios, particularly in large message-oriented business applications, where data and object transformation is required. + For example, consider a complex Web Service where there a separation exists between the data exchange model and the internal domain model used to structure business logic. + In cases like this, a general-purpose data mapping facility can be useful for automating the mapping between these disparate models. + Spring 3 introduces such a facility built on the Spring Expression Language (SpEl). + This facility is described in this section. + +
+ Mapper API + + The API to implement data mapping logic is simple and strongly typed: + + { + + T map(S source, T target); + +}]]> + + To create your own Mapper, simply implement the interface above. + Parameterize S as the type you are mapping from, and T as the type you are mapping to. + The source and target arguments provided to you should never be null. + Your Mapper may throw any RuntimeException if mapping fails. + Take care to ensure your Mapper implementation is thread-safe. + + + Consider the following hand-coded Mapper example: + + +public class PersonDtoPersonMapper implements Mapper<PersonDto, Person> { + + public Person map(PersonDto source, Person target) { + String[] names = source.getName().split(" "); + target.setFirstName(names[0]); + target.setLastName(names[1]); + return target; + } + +} + + In this trivial example, the Mapper simply maps the PersonDto's name property to the Person's firstName and lastName properties. + The fully mapped Person object is then returned. + +
+
+ General-purpose SpelMapper Implementation + + A general purpose object Mapper implementation exists in the org.springframework.mapping.support package named SpelMapper. + Built on the flexible Spring Expression Language (SpEL), this Mapper is capable of mapping between objects of all types, including JavaBeans, Arrays, Collections, and Maps. + It is also extensible and allows additional MappableTypes to be configured. + +
+ Usage + + To use a SpelMapper with its default configuration, simply construct one and call map: + + + + + By default, SpelMapper will map the fields on the source and target that have the same names. + If the field types differ, the mapping system will attempt a type coersion using Spring 3's type conversion system. + Nested bean properties are mapped recursively using the same algorithm. + Any mapping failures will trigger a MappingException to be thrown. + If there are multiple failures, they will be collected and returned in the MappingException thrown to the caller. + + + To illustrate this default behavior, consider the following source object type: + + + + + And the following target object type: + + + + + Used in the following test case: + + + + + In this example, the number, name, and address properties are automatically mapped since they are present on both the source and target objects. + The AccountDto's address property is a JavaBean, so its nested properties are also recursively mapped. + Recursively, the street and zip properties are automatically mapped since they are both present on the nested AddressDto and Address objects. + Nothing is mapped to the Address's city and state properties since these properties do not exist on the AddressDto source. + +
+
+ Registering Explicit Mappings + + When default mapping rules are not sufficient, explicit mapping rules can be registered by calling one of the mapper.addMapping(...) method variants. + Explicit mapping rules always override the default. + For example, suppose you need to map AccountDto.name to Account.fullName. + Since the two property names are not the same, default auto-mapping would never be performed. + Handle a situation like this by explicitly registering a mapping rule: + + + + + In this example, the name property will be mapped to the fullName property when the mapper is executed. + No default mapping will be performed for the name since an explicit mapping rule has been configured for this property. + +
+ Forcing Explicit Mappings + + You can require that all mapping rules must be defined explicitly by disabling the "auto mapping" feature: + + + +
+
+
+ Registering Custom Field Converters + + Sometimes you need to apply field specific type conversion or data transformation logic when mapping a value. + Do this by registering a converter with a Mapping: + + () { + public String convert(String value) { + // do transformation + // return transformed value + } +}); +]]> + +
+
+ Ignoring Fields + + Sometimes you need to exclude a specific field on a source object from being mapped. + Do this by marking a mapping as excluded: + + + +
+
+ Registering Custom Type Converters + + You can also install Converters to coerse values of different types in a custom way. + Do this by obtaining the mapper's ConverterRegistry: + + () { + public Date convert(String value) { + // do conversion + // return transformed value + } +}); +]]> + + + The example Converter above will be invoked anytime a String property is mapped to a Date property. + +
+
+ Registering Custom Nested Mappers + + When mapping between two large object graphs, you may need to register explicit mapping rules for nested bean properties. + Do this by adding a nested Mapper: + + () { + public Address map(AddressDto source, Address target) { + // do target bean mapping here + return target; + } +}); +]]> + + + The example above registers a nested Mapper that will map nested AddressDto properties to nested Address properties. + This particular nested Mapper is "hand-coded", but it could have easily been another generic SpelMapper instance. + addNestedMapper is a convenience method for registering a Converter that delegates to a Mapper. + +
+
+ Registering New Mappable Types + + By default, SpelMapper can map between JavaBean (Object), Collection, Array, and Map object structures. + The supported set of MappableTypes is extensible. + For example, you may wish to implement custom support for mapping XML element structures. + + + To implement your own custom MappableType, implement the MappableType interface: + + { + + boolean isInstance(Object object); + + Set getFields(T object); + + EvaluationContext getEvaluationContext(T object, ConversionService conversionService); + +} +]]> + + + To plugin your custom MappableType, inject a custom MappableTypeFactory into your SpelMapper: + + + + + + The Spring team encourages you to contribute any generally useful MappableType extensions back to the community. + Do this by filing a JIRA issue at jira.springframework.org. + + +
+
+
+ Further Reading + + Consult the JavaDocs of org.springframework.mapping.support.SpelMapper for more information on the implementation options. + + + Dozer is another general-purpose object mapper available in the open source Java community. + Check it out at dozer.sourceforge.net. + +
+
\ No newline at end of file