Class PropertyMap<S,D>
- Type Parameters:
S
- source typeD
- destination type
To create a PropertyMap simply extend PropertyMap
, supplying type arguments to represent
the source type <S>
and destination type <D>
, then override the
configure()
method.
public class OrderMap extends PropertyMap<Order, OrderDTO>() { protected void configure() { map().setCustomer(source.getCustomerName()); map().address.setStreet(source.address.streetName); } };
Mapping EDSL
PropertyMap uses an Embedded Domain Specific Language (EDSL) to define how source and destination methods and values map to each other. The Mapping EDSL allows you to define mappings using actual code that references the source and destination properties you wish to map. Usage of the EDSL is demonstrated in the examples below.
Mapping
This example maps the destination type's setName
method to the source type's
getFirstName
method.
map().setName(source.getFirstName());This example maps the destination type's
setLastName
method to the source type's
surName
field.
map().setLastName(source.surName);Alternatively we can map the source type's
surName
field directly destination type's
lastName
field.
map(source.surName, destination.lastName);This example maps the destination type's
setEmployer
method to the constant
"Initech"
.
map().setEmployer("Initech");This example maps the constant
"Initech"
to destination type's employer
field.
map("Initech", destination.employer);Map statements can also be written to map methods whose types do not match:
map(source.getAge()).setAgeString(null);Similar for constant values:
map(21).setAgeString(null);Note: When a value is provided on the left-hand side of a
map
method, any value
provided on the right-hand side in a setter is not used.
Deep mapping
This example Maps the destination type's setAge
method to the source type's
getCustomer().getAge()
method hierarchy, allowing deep mapping to occur between the
source and destination methods.
map().setAge(source.getCustomer().getAge());This example maps the destination type's
getCustomer().setName()
method hierarchy to the
source type's getPerson().getFirstName()
property hierarchy.
map().getCustomer().setName(source.person.getFirstName());Note: In order to populate the destination object, deep mapping requires the
getCustomer
method to have a corresponding mutator, such as a setCustomer
method
or an accessible
customer
field.
We can also mix field references into either the source or destination when deep mapping.
map(source.customer.age, destination); map().customer.setName(source.getPerson().firstName);Deep mapping can also be performed for source properties or values whose types do not match the destination property’s type.
map(source.person.getAge()).setAgeString(null);
Skipping properties
This example specifies that the destination type's setName
method should be skipped
during the mapping process.
skip().setName(null);Note: Since the
setName
method is skipped the null
value is unused.
We can also skip the mapping of fields.
skip(destination.address);
Converters
This example specifies that the toUppercase
Converter
be used when mapping the
source type's getName
method to the destination type's setName
method:
using(toUppercase).map().setName(source.getName());We can also use a Converter to map fields:
using(toUppercase).map(source.name, destination.name);This example specifies that the
personToNameConverter
Converter
be used when
mapping the source object to the destination type's setName
method:
using(personToNameConverter).map(source).setName(null);Note: Since a
source
object is given the null
value passed to
setName()
is unused.
Conditional mapping
This example specifies that the isLocalAddress
Condition
must apply in order for
mapping to occur between the the the source type's getAddress
method and the destination
type's setAddress
method. If the condition does not apply, mapping to the
setAddress
method will be skipped.
when(isLocalAddress).map().setAddress(source.getAddress());We can also conditionally skip the mapping of fields.
when(notNull).skip(source.name, destination.name);This example specifies that the
Conditions.isNull
Condition
must apply in order
for mapping to the destination type's setAge
method to be skipped. If the
condition does not apply, mapping will occur from the the source type's getAge
method.
when(Conditions.isNull).skip().setAge(source.getAge());
Providers
This example specifies that the nameProvider
Provider
be used to provide
destination name instances when mapping the source type's getName
method to the
destination type's setName
.
with(nameProvider).map().setName(source.getName());
String based mappings
As an alternative to mapping properties via their setters and getters, you can also map properties using string references. While String based mappings are not refactoring-safe, they allow flexibility when dealing with models that do not have getters or setters.
map().getCustomer().setName(this.Or alternatively:source("person.name"));
map(source("person.name")).getCustomer().setName(null);
-
Field Summary
FieldsModifier and TypeFieldDescriptionThe destination instance to be used in a mapping declaration.The source instance to be used in a mapping declaration. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
Creates a new PropertyMap for the source and destination typesS
andD
.protected
PropertyMap
(Class<S> sourceType, Class<D> destinationType) Creates a new PropertyMap for thesourceType
anddestinationType
. -
Method Summary
Modifier and TypeMethodDescriptionprotected abstract void
Called by ModelMapper to configure mappings as defined in the PropertyMap.protected Object
destination
(String destinationPropertyPath) protected final D
map()
Defines a mapping to a destination.protected final D
Defines a mapping for thesubject
.protected final void
Defines a mapping from thesource
to thedestination
.protected final D
skip()
Specifies that mapping for the destination property be skipped during the mapping process.protected final void
Specifies that mapping to thedestination
be skipped during the mapping process.protected final void
Specifies that mapping from thesource
to thedestination
be skipped during the mapping process.protected <T> T
Used for mapping asourcePropertyPath
to a destination.protected final MapExpression<D>
Specifies theconverter
to use for converting to the destination property hierarchy.protected final ProviderExpression<S,
D> Specifies thecondition
that must apply in order for mapping to take place for a particular destination property hierarchy.protected final ConverterExpression<S,
D> Specifies a provider to be used for providing instances of the mapped property.
-
Field Details
-
source
The source instance to be used in a mapping declaration. See the EDSL examples.Throws: NullPointerException if dereferenced from outside the context of
configure()
. -
destination
The destination instance to be used in a mapping declaration. See the EDSL examples.Throws: NullPointerException if dereferenced from outside the context of
configure()
.
-
-
Constructor Details
-
PropertyMap
protected PropertyMap()Creates a new PropertyMap for the source and destination typesS
andD
.- Throws:
IllegalArgumentException
- ifS
andD
are not declared
-
PropertyMap
Creates a new PropertyMap for thesourceType
anddestinationType
.
-
-
Method Details
-
configure
protected abstract void configure()Called by ModelMapper to configure mappings as defined in the PropertyMap. -
map
Defines a mapping to a destination. See the EDSL examples.- Throws:
IllegalStateException
- if called from outside the context ofconfigure()
.
-
map
Defines a mapping for thesubject
. See the EDSL examples.- Parameters:
subject
- to map- Throws:
IllegalStateException
- if called from outside the context ofconfigure()
.
-
map
- Parameters:
source
- to map fromdestination
- to map to- Throws:
IllegalStateException
- if called from outside the context ofconfigure()
.
-
skip
Specifies that mapping for the destination property be skipped during the mapping process. See the EDSL examples.- Throws:
IllegalStateException
- if called from outside the context ofconfigure()
.
-
skip
Specifies that mapping to thedestination
be skipped during the mapping process. See the EDSL examples.- Parameters:
destination
- to skip- Throws:
IllegalStateException
- if called from outside the context ofconfigure()
.
-
skip
Specifies that mapping from thesource
to thedestination
be skipped during the mapping process. See the EDSL examples atPropertyMap
. See the EDSL examples.- Parameters:
source
- to skipdestination
- to skip- Throws:
IllegalStateException
- if called from outside the context ofconfigure()
.
-
source
Used for mapping asourcePropertyPath
to a destination. See the EDSL examples.- Throws:
IllegalStateException
- if called from outside the context ofconfigure()
.
-
destination
-
using
Specifies theconverter
to use for converting to the destination property hierarchy. When used with deep mapping theconverter
should convert to an instance of the last destination property. See the EDSL examples.- Parameters:
converter
- to use when mapping the property- Throws:
IllegalStateException
- if called from outside the context ofconfigure()
.
-
when
Specifies thecondition
that must apply in order for mapping to take place for a particular destination property hierarchy. See the EDSL examples.- Parameters:
condition
- that must apply when mapping the property- Throws:
IllegalStateException
- if called from outside the context ofconfigure()
.
-
with
Specifies a provider to be used for providing instances of the mapped property. When used with deep mapping theprovider
should provide an instance of the last destination property. See the EDSL examples.- Parameters:
provider
- to use for providing the destination property- Throws:
IllegalStateException
- if called from outside the context ofconfigure()
.
-