ModelMapper for Java: The Complete Guide to Automatic Object Mapping

1. What is ModelMapper and Why Do You Need It?

ModelMapper is a powerful Java library designed to automatically convert (map) objects of one type into objects of another type. In modern development, especially when using a layered architecture (Controller → Service → Repository), developers constantly face the need to copy data between DTOs (Data Transfer Objects), database entities, VOs (Value Objects), and other POJOs. Writing this code manually is tedious, error-prone work that leads to code bloat and reduced readability.

ModelMapper's primary goal is to free developers from writing boilerplate code like source.getField() → target.setField(). The library analyzes class structures (fields, getters/setters) and automatically matches them using naming conventions (convention over configuration). It supports nested objects, collections, inheritance, and complex transformations, making it an indispensable tool in enterprise Java applications.

ModelMapper is especially useful in these scenarios:

• Application Layers: Converting entities to DTOs and back for data transfer via REST APIs.
• Microservices: Mapping between objects from different services.
• Refactoring: When class structures change, you only need to update the mapping in one place.
• Testing: Quickly creating test data based on existing objects.

2. Installation

ModelMapper is distributed via Maven Central. To install it, add the dependency to your pom.xml (for Maven) or build.gradle (for Gradle) file.

Maven (pom.xml):

<dependency>
    <groupId>org.modelmapper</groupId>
    <artifactId>modelmapper</artifactId>
    <version>3.2.0</version>
</dependency>

Gradle (build.gradle):

implementation 'org.modelmapper:modelmapper:3.2.0'

Note: Version 3.2.0 is current as of this writing. Always check for the latest version on MVNRepository.

3. Quick Start — Minimal Working Example

Let's look at a simple example: we have a UserEntity class (database entity) and a UserDTO class (data transfer object).

// Source class (Entity)
public class UserEntity {
    private Long id;
    private String firstName;
    private String lastName;
    private String email;

    // Constructors, getters, and setters
    public UserEntity() {}
    public UserEntity(Long id, String firstName, String lastName, String email) {
        this.id = id;
        this.firstName = firstName;
        this.lastName = lastName;
        this.email = email;
    }

    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    public String getFirstName() { return firstName; }
    public void setFirstName(String firstName) { this.firstName = firstName; }
    public String getLastName() { return lastName; }
    public void setLastName(String lastName) { this.lastName = lastName; }
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
}

// Target class (DTO)
public class UserDTO {
    private Long id;
    private String fullName; // Note: field name is different
    private String emailAddress;

    // Constructors, getters, and setters
    public UserDTO() {}
    public Long getId() { return id; }
    public void