How to customize ModelMapper

I want to use ModelMapper to convert entity to DTO and back. Mostly it works, but how do I customize it. It has has so many options that it's hard to figure out where to start. What's best practice?

I'll answer it myself below, but if another answer is better I'll accept it.

First here are some links

• modelmapper getting started
• api doc
• blog post
• random code examples

My impression of mm is that it is very well engineered. The code is solid and a pleasure to read. However, the documentation is very terse, with very few examples. Also the api is confusing because there seems to be 10 ways to do anything, and no indication of why you’d do it one way or another.

There are two alternatives: Dozer is the most popular, and Orika gets good reviews for ease of use.

Assuming you still want to use mm, here’s what I’ve learned about it.

The main class, ModelMapper, should be a singleton in your app. For me, that meant a @Bean using Spring. It works out of the box for simple cases. For example, suppose you have two classes:

class DogData
{
    private String name;
    private int mass;
}

class DogInfo
{
    private String name;
    private boolean large;
}

with appropriate getters/setters. You can do this:

    ModelMapper mm = new ModelMapper();
    DogData dd = new DogData();
    dd.setName("fido");
    dd.setMass(70);
    DogInfo di = mm.map(dd, DogInfo.class);

and the "name" will be copied from dd to di.

There are many ways to customize mm, but first you need to understand how it works.

The mm object contains a TypeMap for each ordered pair of types, such as <DogInfo, DogData> and <DogData, DogInfo> would be two TypeMaps.

Each TypeMap contains a PropertyMap with a list of mappings. So in the example the mm will automatically create a TypeMap<DogData, DogInfo> that contains a PropertyMap that has a single mapping.

We can write this

    TypeMap<DogData, DogInfo> tm = mm.getTypeMap(DogData.class, DogInfo.class);
    List<Mapping> list = tm.getMappings();
    for (Mapping m : list)
    {
        System.out.println(m);
    }

and it will output

PropertyMapping[DogData.name -> DogInfo.name]

When you call mm.map() this is what it does,

1. see if the TypeMap exists yet, if not create the TypeMap for the <S, D> source/destination types
2. call the TypeMap Condition, if it returns FALSE, do nothing and STOP
3. call the TypeMap Provider to construct a new destination object if necessary
4. call the TypeMap PreConverter if it has one
5. do one of the following:
   • if the TypeMap has a custom Converter, call it
   • or, generate a PropertyMap (based on Configuration flags plus any custom mappings that were added), and use it (Note: the TypeMap also has optional custom Pre/PostPropertyConverters that I think will run at this point before and after each mapping.)
6. call the TypeMap PostConverter if it has one

Caveat: This flowchart is sort of documented but I had to guess a lot, so it might not be all correct!

You can customize every single step of this process. But the two most common are

• step 5a. – write custom TypeMap Converter, or
• step 5b. – write custom Property Mapping.

Here is a sample of a custom TypeMap Converter:

    Converter<DogData, DogInfo> myConverter = new Converter<DogData, DogInfo>()
    {
        public DogInfo convert(MappingContext<DogData, DogInfo> context)
        {
            DogData s = context.getSource();
            DogInfo d = context.getDestination();
            d.setName(s.getName());
            d.setLarge(s.getMass() > 25);
            return d;
        }
    };

    mm.addConverter(myConverter);

Note the converter is one-way. You have to write another if you want to customize DogInfo to DogData.

Here is a sample of a custom PropertyMap:

    Converter<Integer, Boolean> convertMassToLarge = new Converter<Integer, Boolean>()
    {
        public Boolean convert(MappingContext<Integer, Boolean> context)
        {
            // If the dog weighs more than 25, then it must be large
            return context.getSource() > 25;
        }
    };

    PropertyMap<DogData, DogInfo> mymap = new PropertyMap<DogData, DogInfo>()
    {
        protected void configure()
        {
            // Note: this is not normal code. It is "EDSL" so don't get confused
            map(source.getName()).setName(null);
            using(convertMassToLarge).map(source.getMass()).setLarge(false);
        }
    };

    mm.addMappings(mymap);

The pm.configure function is really funky. It’s not actual code. It is dummy EDSL code that gets interpreted somehow. For instance the parameter to the setter is not relevant, it is just a placeholder. You can do lots of stuff in here, such as

• when(condition).map(getter).setter
• when(condition).skip().setter – safely ignore field.
• using(converter).map(getter).setter – custom field converter
• with(provider).map(getter).setter – custom field constructor

Note the custom mappings are added to the default mappings, so you do not need, for example, to specify

            map(source.getName()).setName(null);

in your custom PropertyMap.configure().

In this example, I had to write a Converter to map Integer to Boolean. In most cases this will not be necessary because mm will automatically convert Integer to String, etc.

I'm told you can also create mappings using Java 8 lambda expressions. I tried, but I could not figure it out.

Final Recommendations and Best Practice

By default mm uses MatchingStrategies.STANDARD which is dangerous. It can easily choose the wrong mapping and cause strange, hard to find bugs. And what if next year someone else adds a new column to the database? So don't do it. Make sure you use STRICT mode:

    mm.getConfiguration().setMatchingStrategy(MatchingStrategies.STRICT);

Always write unit tests and ensure that all mappings are validated.

    DogInfo di = mm.map(dd, DogInfo.class);
    mm.validate();   // make sure nothing in the destination is accidentally skipped

Fix any validation failures with mm.addMappings() as shown above.

Put all your mappings in a central place, where the mm singleton is created.