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());
     }
   };
 

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 setEmployer method to the constant "Initech".

    map().setEmployer("Initech");

Map statements can also be written to accept a source property, allowing mapping to a destination whose type does not match the source property's type:

    map(source.getAge()).setAgeString(null);

Similar for constant values:

    map(21).setAgeString(null);

Note: Since the setAgeString method requires a value we simply pass in null which is unused.

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() method hierarchy.

    map().getCustomer().setName(source.getPerson().getFirstName());

Note: In order 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.

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.

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());

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());

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.

    withProvider(nameProvider).map().setName(source.getName());

Author:

Jonathan Halterman

Field Summary

S	source The source instance to be used in a mapping declaration.

Constructor Summary

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

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 source) Defines a mapping from the source to a destination.
protected D	skip() Specifies that mapping for the destination property be skipped during the mapping process.
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>	withProvider(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() .

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 source)

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

Parameters:

source - to map from

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().

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().

withProvider

protected final ConverterExpression<S,D> withProvider(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().