Package org.modelmapper

Class 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 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 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 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.

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

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