@ -1454,292 +1454,4 @@ public class MyController {
</section>
</section>
</section>
<sectionid="org.springframework.mapping">
<title>Spring 3 Object Mapping</title>
<para>
There are scenarios, particularly in large message-oriented business applications, where object transformation is required.
For example, consider a complex Web Service where there is a separation between the data exchange model and the internal domain model used to structure business logic.
In cases like this, a general-purpose object-to-object mapping facility can be useful for automating the mapping between these disparate models.
Spring 3 introduces such a facility built on the <linklinkend="expressions-intro">Spring Expression Language</link> (SpEL).
This facility is described in this section.
</para>
<sectionid="mapping-Mapping-API">
<title>Mapper API</title>
<para>
The API to implement object mapping logic is simple and strongly typed:
</para>
<programlistinglanguage="java"><![CDATA[
package org.springframework.mapping;
public interface Mapper<S,T> {
T map(S source, T target);
}]]></programlisting>
<para>
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.
</para>
<para>
Consider the following hand-coded Mapper example:
</para>
<programlistinglanguage="java">
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;
}
}</programlisting>
<para>
In this trivial example, the Mapper maps the PersonDto's <literal>name</literal> property to the Person's <literal>firstName</literal> and <literal>lastName</literal> properties.
A general purpose object-to-object mapping system exists in the <classname>org.springframework.mapping.support</classname> package.
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>
<sectionid="mapping.SpelMapper-usage">
<title>Usage</title>
<para>
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:
By default, the defaultMapper 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 conversion using Spring 3's <linklinkend="core.convert">type conversion system</link>.
Nested bean properties are mapped recursively.
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.
</para>
<para>
To illustrate this default behavior, consider the following source object type:
</para>
<programlistinglanguage="java"><![CDATA[
public class CreateAccountDto {
private String number;
private String name;
private AddressDto address;
public static class AddressDto {
private String street;
private String zip;
}
}]]></programlisting>
<para>
And the following target object type:
</para>
<programlistinglanguage="java"><![CDATA[
public class Account {
private Long number;
private String name;
private Address address;
public static class Address {
private String street;
private String city
private String state;
private String zip;
}
}]]></programlisting>
<para>
Now mapped in the following service method:
</para>
<programlistinglanguage="java"><![CDATA[
public void createAccount(CreateAccountDto dto) {
Account account = (Account) MapperFactory.getDefaultMapper().map(dto, new Account());
// work with the mapped account instance
}]]>
</programlisting>
<para>
In this example, the <literal>number</literal>, <literal>name</literal>, and <literal>address</literal> properties are automatically mapped since they are present on both the source and target objects.
The AccountDto's <literal>address</literal> property is a JavaBean, so its nested properties are also recursively mapped.
Recursively, the <literal>street</literal> and <literal>zip</literal> properties are automatically mapped since they are both present on the nested AddressDto and Address objects.
Nothing is mapped to the Address's <literal>city</literal> and <literal>state</literal> properties since these properties do not exist on the AddressDto source.
</para>
</section>
<sectionid="mapping.SpelMapper-Explicit">
<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 rule.
The MapperBuilder provides a fluent API for registering object-to-object Mapping rules:
<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:
</para>
<programlistinglanguage="java"><![CDATA[
builder.addMapping("name", new Mapper<String,Person>() {
public Person map(String name, Person person) {
String[] names = name.split(" ");
person.setFirstName(names[0]);
person.setLastName(names[1]);
return person;
}
});]]>
</programlisting>
<para>
In the example above, the first part of the <literal>name</literal> field will be mapped to the <literal>firstName</literal> field and the second part will be mapped to the <literal>lastName</literal> field.
No default mapping will be performed for <literal>name</literal> since an explicit mapping rule has been configured for this field.
<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:
</para>
<programlistinglanguage="java"><![CDATA[
builder.addMapping(new String[] { "activationDay", "activationTime" }, new Mapper<CreateAccountDto,AccountDto>() {
public Account map(CreateAccountDto dto, Account account) {
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> or <literal>activationTime</literal> since an explicit mapping rule has been configured for these fields.
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:
Consult the JavaDocs of <classname>MapperFactory</classname> and <classname>MapperBuilder</classname> in the <filename>org.springframework.mapping.support</filename> package for more information on the available configuration options.
</para>
<para>
Dozer is another general-purpose object mapper available in the open source Java community.
Check it out at <ulinkurl="http://dozer.sourceforge.net">dozer.sourceforge.net</ulink>.
Keith Donald
15 years ago