How It Works
ModelMapper consists of two separate processes: the matching process, where a source and destination type’s properties are matched to each other, and the mapping process where matched property values are converted from a source to destination object. A further description of these processes follows.
The matching process uses conventions configured in a
TypeMap to determine which source and destination properties match each other. The process works by identifying eligible properties, transforming and tokenizing their names, then using those tokens to determine source to destination matches.
Property eligibility is determined in two steps. First, if field matching is enabled then fields that are accessible according to the configured AccessLevel and that are named according to the configured NamingConvention are eligible. Similarly, methods are eligible based on configured AccessLevels and NamingConventions. Eligible methods take precedence over fields with the same transformed property name.
Additionally, only source methods with zero parameters and a non-
void return type are eligible, and destination methods with one parameter and a
void return type are eligible.
Prior to matching, NameTransformers are used to transform property names to their simple property name, so that source and destination properties that are named according to different conventions can be matched. For example: Consider a source object with a
getPerson method and a destination object with a
setPerson method. In order for these to be matched, a
NameTransformer is used to transform the method names to
NameTransformer implementations will transform names according to the same convention as a
NamingConvention, and are therefore usually configured together - such as with JavaBeans.
After transformation, NameTokenizers are used to tokenize class and property names for matching.
MatchingStrategies are used to determine whether source and destination properties match based on their name and class name tokens. Different strategies can allow for more loose or strict matching of tokens.
For matching strategies that are inexact, it is possible that multiple source properties may match the same destination property. When this occurs, the matching engine attempts to resolve the ambiguity by finding the closest match among the duplicates.
If the ambiguity cannot be resolved, a ConfigurationException is thrown, except when the
MatchingConfiguration is set to
ignoreAmbiguity in which case the destination property will simply be skipped during the mapping process.
The process for mapping a source to a destination object is as follows:
- If a
TypeMapexists for the source and destination types, mapping will occur according to the
Mappings defined in the
- Else if a
Converterexists that is capable of converting the source object to the destination type, mapping will occur using the
- Else a new
TypeMapis created for the source and destination types, and mapping will occur according to the implicit
Mappings captured in the