org.modelmapper

Class PropertyMap<S,D>

java.lang.Object

org.modelmapper.PropertyMap<S,D>

Type Parameters:

S - source type

D - destination type

public abstract class PropertyMap<S,D>
extends Object

A PropertyMap defines mappings between properties for a particular source and 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.source("person.name"));

Or alternatively:

    map(source("person.name")).getCustomer().setName(null);

Field Summary

Fields

Modifier and Type	Field and Description
D	destination The destination instance to be used in a mapping declaration.
S	source The source instance to be used in a mapping declaration.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PropertyMap() Creates a new PropertyMap for the source and destination types S and D.
protected	PropertyMap(Class<S> sourceType, Class<D> destinationType) Creates a new PropertyMap for the sourceType and destinationType.

Method Summary

Methods

Modifier and Type	Method and Description
protected abstract void	configure() Called by ModelMapper to configure mappings as defined in the PropertyMap.
protected D	map() Defines a mapping to a destination.
protected D	map(Object subject) Defines a mapping for the subject.
protected void	map(Object source, Object destination) Defines a mapping from the source to the destination.
protected D	skip() Specifies that mapping for the destination property be skipped during the mapping process.
protected void	skip(Object destination) Specifies that mapping to the destination be skipped during the mapping process.
protected void	skip(Object source, Object destination) Specifies that mapping from the source to the destination be skipped during the mapping process.
protected <T> T	source(String sourcePropertyPath) Used for mapping a sourcePropertyPath to a destination.
protected MapExpression<D>	using(Converter<?,?> converter) Specifies the converter to use for converting to the destination property hierarchy.
protected ProviderExpression<S,D>	when(Condition<?,?> condition) Specifies the condition that must apply in order for mapping to take place for a particular destination property hierarchy.
protected ConverterExpression<S,D>	with(Provider<?> provider) Specifies a provider to be used for providing instances of the mapped property.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

source

public S 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

public D 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 Detail

PropertyMap

protected PropertyMap()

Creates a new PropertyMap for the source and destination types S and D.

Throws:

IllegalArgumentException - if S and D are not declared

PropertyMap

protected PropertyMap(Class<S> sourceType,
           Class<D> destinationType)

Creates a new PropertyMap for the sourceType and destinationType.

Method Detail

configure

protected abstract void configure()

Called by ModelMapper to configure mappings as defined in the PropertyMap.

map

protected final D map()

Defines a mapping to a destination. See the EDSL examples.

Throws:

IllegalStateException - if called from outside the context of configure().

map

protected final D map(Object subject)

Defines a mapping for the subject. See the See the EDSL examples.

Parameters:

subject - to map

Throws:

IllegalStateException - if called from outside the context of configure().

map

protected final void map(Object source,
       Object destination)

Defines a mapping from the source to the destination. See the See the EDSL examples.

Parameters:

source - to map from

destination - to map to

Throws:

IllegalStateException - if called from outside the context of configure().

skip

protected final D 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 of configure().

skip

protected final void skip(Object destination)

Specifies that mapping to the destination be skipped during the mapping process. See the EDSL examples.

Parameters:

destination - to skip

Throws:

IllegalStateException - if called from outside the context of configure().

skip

protected final void skip(Object source,
        Object destination)

Specifies that mapping from the source to the destination be skipped during the mapping process. See the EDSL examples at PropertyMap. See the EDSL examples.

Parameters:

source - to skip

destination - to skip

Throws:

IllegalStateException - if called from outside the context of configure().

source

protected <T> T source(String sourcePropertyPath)

Used for mapping a sourcePropertyPath to a destination. See the EDSL examples.

Throws:

IllegalStateException - if called from outside the context of configure().

using

protected final MapExpression<D> using(Converter<?,?> converter)

Specifies the converter to use for converting to the destination property hierarchy. When used with deep mapping the converter 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 of configure().

when

protected final ProviderExpression<S,D> when(Condition<?,?> condition)

Specifies the condition 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 of configure().

with

protected final ConverterExpression<S,D> with(Provider<?> provider)

Specifies a provider to be used for providing instances of the mapped property. When used with deep mapping the provider 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 of configure().