PropertyMap (ModelMapper 3.1.1-SNAPSHOT API)

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.

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

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected abstract void`	`configure()` Called by ModelMapper to configure mappings as defined in the PropertyMap.
`protected Object`	`destination(String destinationPropertyPath)`
`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().
  - destination
```
protected Object destination(String destinationPropertyPath)
```
  - 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().

Class PropertyMap<S,D>

Mapping EDSL

Mapping

Deep mapping

Skipping properties

Converters

Conditional mapping

Providers

String based mappings

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

source

destination

Constructor Detail

PropertyMap

PropertyMap

Method Detail

configure

map

map

map

skip

skip

skip

source

destination

using

when

with