conditional mapping and polish

spring-framework-reference/src/validation.xml

@@ -1513,14 +1513,14 @@ public class PersonDtoPersonMapper implements Mapper<PersonDto, Person> {
 			<title>General-purpose SpelMapper Implementation</title>
 			<para>
 				A general purpose object-to-object mapping system exists in the <classname>org.springframework.mapping.support</classname> package.
-				Built on the flexible Spring Expression Language (SpEL), this system is capable of mapping between a variety of object types, including JavaBeans, Arrays, Collections, and Maps.
-				It can perform field-to-field, field-to-multi-field, and multi-field to field mappings.
-				It also can carry out type conversion and recursive mapping, often needed with rich object models.
+				Built on the Spring Expression Language (SpEL), this system is capable of mapping between a variety of object types, including JavaBeans, Arrays, Collections, and Maps.
+				It can perform field-to-field, field-to-multi-field, multi-field to field, and conditional mappings.
+				It also can carry out type conversion and recursive mapping, which are often required with rich object models.
 			</para>
 			<section id="mapping.SpelMapper-usage">
 				<title>Usage</title>
 				<para>
-					To obtain a general purpose object Mapper with its default configuration, simply call MappingFactory.getDefaultMapper().
+					To obtain a general purpose object Mapper with its default configuration, simply call <methodname>MappingFactory.getDefaultMapper()</methodname>.
 					Then invoke the Mapper by calling its <literal>map(Object, Object)</literal> operation:
 				</para>
 				<programlisting language="java"><![CDATA[
@@ -1599,7 +1599,7 @@ public void testDefaultSpelMappingBehavior() {
 				<title>Registering Explicit Mappings</title>
 				<para>
 					When default mapping rules are not sufficient, explicit mapping rules can be registered by obtaining a <classname>MapperBuilder</classname> and using it to construct a <classname>Mapper</classname>.
-					Explicit mapping rules always override the default.
+					Explicit mapping rules always override the default rule.
 					The MapperBuilder provides a fluent API for registering object-to-object Mapping rules:
 				</para>
 				<programlisting language="java"><![CDATA[
@@ -1614,8 +1614,8 @@ Mapper<PersonDto, Person> mapper =
 					<title>Mapping between two fields with different names</title>
 					<para>
 						Suppose you need to map <literal>AccountDto.name</literal> to <literal>Account.fullName</literal>.
-						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:
+						Since these two field names are not the same, the default auto-mapping rule would not apply.
+						Handle a requirement like this by explicitly registering a mapping rule:
 					</para>
 					<programlisting language="java"><![CDATA[
 builder.addMapping("name", "fullName")]]>
@@ -1626,7 +1626,7 @@ builder.addMapping("name", "fullName")]]>
 					</para>
 				</section>
 				<section id="mapping.SpelMapper-Explicit-singleFieldToMultipleField">
-					<title>Mapping a single field value to multiple fields</title>
+					<title>Mapping a single field to multiple fields</title>
 					<para>
 						Suppose you need to map <literal>PersonDto.name</literal> to <literal>Person.firstName</literal> and <literal>Person.lastName</literal>.
 						Handle a field-to-multi-field requirement like this by explicitly registering a mapping rule:
@@ -1647,7 +1647,7 @@ builder.addMapping("name", new Mapper<String, Person>() {
 					</para>
 				</section>
 				<section id="mapping.SpelMapper-Explicit-multipleFieldsToField">
-					<title>Mapping a single field value to multiple fields</title>
+					<title>Mapping multiple fields to a single field</title>
 					<para>
 						Suppose you need to map <literal>CreateAccountDto.activationDay</literal> and <literal>CreateAccountDto.activationTime</literal> to <literal>Account.activationDateTime</literal>.
 						Handle a multi-field-to-field requirement like this by explicitly registering a mapping rule:
@@ -1664,7 +1664,22 @@ builder.addMapping(new String[] { "activationDay", "activationTime" }, new Mappe
 					</programlisting>			
 					<para>
 						In the example above, the <literal>activationDay</literal> and <literal>activationTime</literal> fields are mapped to the single <literal>activationDateTime</literal> field.
-						No default mapping is performed for <literal>activationDay</literal> and <literal>activationTime</literal> since an explicit mapping rule has been configured for these fields.
+						No default mapping is performed for <literal>activationDay</literal> or <literal>activationTime</literal> since an explicit mapping rule has been configured for these fields.
+					</para>
+				</section>
+				<section id="mapping.SpelMapper-Explicit-conditionalMappings">
+					<title>Mapping conditionally</title>
+					<para>
+						Suppose you need to map <literal>Map.countryCode</literal> to <literal>PhoneNumber.countryCode</literal> only if the source Map contains a international phone number.
+						Handle conditional mapping requirements like this by explicitly registering a mapping rule:
+					</para>
+					<programlisting language="java"><![CDATA[
+builder.addConditionalMapping("countryCode", "international == 'true'");]]>
+					</programlisting>			
+					<para>
+						In the example above, the <literal>countryCode</literal> field will only be mapped if the international field is 'true'.
+						<literal>international == 'true'</literal> is a boolean expression that must evaluate to true for the mapping to be executed.
+						No default mapping is performed for <literal>countryCode</literal> since an explicit mapping rule has been configured for this field.
 					</para>
 				</section>
 				<section id="mapping.SpelMapper-Explicit-forcing">
@@ -1698,12 +1713,14 @@ builder.addMapping("name", "fullName").setConverter() { new Converter<String, St
 					Sometimes you need to exclude a specific field on a source object from being mapped.
 					Do this by marking one or more source fields as excluded:
 				</para>
-				<programlisting language="java">builder.setExcludedFields("name");</programlisting>
+				<programlisting language="java"><![CDATA[
+builder.setExcludedFields("name");]]>
+				</programlisting>
 			</section>
 			<section id="mapper.SpelMapper-CustomTypeConverters">
 				<title>Registering Custom Type Converters</title>
 				<para>
-					You may also install Converters to convert values of different types in a custom way:
+					You may also register custom Converters to convert values between mapped field of different types:
 				</para>
 				<programlisting language="java"><![CDATA[
 builder.addConverter(new Converter<String, Date>() {
@@ -1748,5 +1765,4 @@ builder.addNestedMapper(new Mapper<AddressDto, Address>() {
 			</para>
 		</section>	
 	</section>
-	
 </chapter>