Hey guys! Today, we're diving deep into the world of Spring ModelMapper and exploring how to implement custom mappings. ModelMapper is a fantastic library that simplifies the process of mapping objects in Java, especially within Spring applications. But sometimes, the default mapping conventions just don't cut it. That's where custom mappings come in handy! Let's get started and see how we can make ModelMapper dance to our tune.

Understanding the Basics of ModelMapper

Before we jump into custom mappings, let's quickly recap what ModelMapper is all about. At its core, ModelMapper is an object-to-object mapper that automatically copies data from a source object to a destination object. It uses reflection to analyze the source and destination classes and intelligently maps fields with the same names and types. This reduces boilerplate code and makes your data transfer objects (DTOs) much cleaner.

For example, suppose you have an Employee entity and an EmployeeDTO. ModelMapper can automatically map the firstName, lastName, and email fields from Employee to EmployeeDTO without you writing any explicit mapping code. This is super useful when you have simple mappings.

However, real-world applications often involve more complex scenarios. What if your Employee entity has a field named dateOfBirth, but your EmployeeDTO has a field named birthDate? Or what if you need to combine data from multiple source fields into a single destination field? That's where custom mappings become essential.

To use ModelMapper, you first need to add it to your project. If you're using Maven, you can add the following dependency to your pom.xml:

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

For Gradle, you can add the following to your build.gradle:

dependencies {
    implementation 'org.modelmapper:modelmapper:3.1.0'
}

Once you've added the dependency, you can create a ModelMapper instance in your Spring configuration. Here’s a basic setup:

@Configuration
public class ModelMapperConfig {

    @Bean
    public ModelMapper modelMapper() {
        return new ModelMapper();
    }
}

This configuration makes ModelMapper available for injection into your Spring components. Now, let’s move on to the exciting part: custom mappings!

Diving into Custom Mappings

Custom mappings in ModelMapper allow you to define exactly how fields should be mapped between source and destination objects. There are several ways to define custom mappings, each suited for different scenarios. Let's explore some of the most common techniques.

Using addMappings()

The addMappings() method is one of the most straightforward ways to define custom mappings. It allows you to specify a mapping configuration using a PropertyMap. This is particularly useful when you need to map fields with different names or perform simple transformations.

Here's an example:

Suppose you have an Employee entity with a dateOfBirth field and an EmployeeDTO with a birthDate field. You can define a custom mapping like this:

ModelMapper modelMapper = new ModelMapper();
modelMapper.addMappings(new PropertyMap<Employee, EmployeeDTO>() {
    @Override
    protected void configure() {
        map(source.getDateOfBirth(), destination.getBirthDate());
    }
});

In this example, the map() method specifies that the dateOfBirth field from the Employee object should be mapped to the birthDate field in the EmployeeDTO object. The source and destination objects refer to instances of Employee and EmployeeDTO, respectively. This approach is clean and easy to understand for simple field renames.

Let's break down the code:

• ModelMapper modelMapper = new ModelMapper();: Creates a new instance of ModelMapper.
• modelMapper.addMappings(new PropertyMap<Employee, EmployeeDTO>() { ... });: Adds a new mapping configuration for the Employee to EmployeeDTO mapping.
• @Override protected void configure() { ... }: Overrides the configure() method to define the custom mapping logic.
• map(source.getDateOfBirth(), destination.getBirthDate());: Specifies the mapping between the dateOfBirth field in the source object and the birthDate field in the destination object.

Using Converter Interface

For more complex transformations, you can use the Converter interface. This interface allows you to define a custom conversion logic that can be applied during the mapping process. This is especially useful when you need to perform data manipulation or aggregation during the mapping.

For example, suppose you want to combine the firstName and lastName fields from the Employee entity into a single fullName field in the EmployeeDTO. You can define a custom converter like this:

Converter<Employee, EmployeeDTO> employeeConverter = new AbstractConverter<Employee, EmployeeDTO>() {
    @Override
    protected EmployeeDTO convert(Employee source) {
        EmployeeDTO destination = new EmployeeDTO();
        destination.setFullName(source.getFirstName() + " " + source.getLastName());
        return destination;
    }
};

modelMapper.addConverter(employeeConverter);

In this example, the convert() method takes an Employee object as input and returns an EmployeeDTO object. Inside the convert() method, we create a new EmployeeDTO object and set the fullName field by concatenating the firstName and lastName fields from the Employee object. This approach gives you complete control over the mapping process.

Here’s a breakdown:

• Converter<Employee, EmployeeDTO> employeeConverter = new AbstractConverter<Employee, EmployeeDTO>() { ... };: Creates a new converter that converts from Employee to EmployeeDTO.
• @Override protected EmployeeDTO convert(Employee source) { ... }: Overrides the convert() method to define the custom conversion logic.
• EmployeeDTO destination = new EmployeeDTO();: Creates a new instance of EmployeeDTO.
• destination.setFullName(source.getFirstName() + " " + source.getLastName());: Sets the fullName field in the destination object by concatenating the firstName and lastName fields from the source object.
• return destination;: Returns the converted EmployeeDTO object.
• modelMapper.addConverter(employeeConverter);: Registers the converter with ModelMapper.

Using Provider Interface

The Provider interface is another powerful tool for custom mappings. It allows you to define a custom logic for creating the destination object. This is particularly useful when you need to initialize the destination object with specific values or when the destination object requires special handling.

For example, suppose you want to create a new EmployeeDTO object with a default status of "Active" whenever an Employee object is mapped. You can define a custom provider like this:

Provider<EmployeeDTO> employeeProvider = new Provider<EmployeeDTO>() {
    @Override
    public EmployeeDTO get(ProvisionRequest<EmployeeDTO> request) {
        EmployeeDTO destination = new EmployeeDTO();
        destination.setStatus("Active");
        return destination;
    }
};

modelMapper.getConfiguration().setProvider(employeeProvider);

In this example, the get() method is called whenever ModelMapper needs to create a new EmployeeDTO object. Inside the get() method, we create a new EmployeeDTO object and set the status field to "Active". This ensures that every EmployeeDTO object created by ModelMapper will have the default status set.

Let's break it down:

• Provider<EmployeeDTO> employeeProvider = new Provider<EmployeeDTO>() { ... };: Creates a new provider that provides instances of EmployeeDTO.
• @Override public EmployeeDTO get(ProvisionRequest<EmployeeDTO> request) { ... }: Overrides the get() method to define the custom object creation logic.
• EmployeeDTO destination = new EmployeeDTO();: Creates a new instance of EmployeeDTO.
• destination.setStatus("Active");: Sets the status field in the destination object to "Active".
• return destination;: Returns the newly created EmployeeDTO object.
• modelMapper.getConfiguration().setProvider(employeeProvider);: Registers the provider with ModelMapper.

Combining Custom Mappings

The real power of ModelMapper custom mappings comes from combining these techniques. You can use addMappings(), Converter, and Provider together to handle complex mapping scenarios. For example, you might use a Provider to initialize the destination object, a Converter to perform data transformations, and addMappings() to map specific fields.

Practical Examples

Let’s look at some practical examples to illustrate how these custom mapping techniques can be applied in real-world scenarios.

Example 1: Mapping Address Information

Suppose you have an Employee entity with separate fields for street, city, and country, and you want to map this information to a single address field in the EmployeeDTO. You can use a Converter to combine these fields:

Converter<Employee, EmployeeDTO> employeeConverter = new AbstractConverter<Employee, EmployeeDTO>() {
    @Override
    protected EmployeeDTO convert(Employee source) {
        EmployeeDTO destination = new EmployeeDTO();
        String address = source.getStreet() + ", " + source.getCity() + ", " + source.getCountry();
        destination.setAddress(address);
        return destination;
    }
};

modelMapper.addConverter(employeeConverter);

Example 2: Mapping Date Formats

Suppose you have a dateOfBirth field in the Employee entity that is stored as a java.util.Date, and you want to map it to a birthDate field in the EmployeeDTO that is stored as a String in a specific format. You can use a Converter to format the date:

Converter<Date, String> dateConverter = new AbstractConverter<Date, String>() {
    private final SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");

    @Override
    protected String convert(Date source) {
        return dateFormat.format(source);
    }
};

modelMapper.addConverter(dateConverter);

modelMapper.addMappings(new PropertyMap<Employee, EmployeeDTO>() {
    @Override
    protected void configure() {
        using(dateConverter).map(source.getDateOfBirth(), destination.getBirthDate());
    }
});

Example 3: Handling Null Values

Sometimes, you may want to handle null values differently during the mapping process. For example, you might want to set a default value for a field in the destination object if the corresponding field in the source object is null. You can use a Converter to achieve this:

Converter<String, String> nullConverter = new AbstractConverter<String, String>() {
    @Override
    protected String convert(String source) {
        return source == null ? "N/A" : source;
    }
};

modelMapper.addConverter(nullConverter);

modelMapper.addMappings(new PropertyMap<Employee, EmployeeDTO>() {
    @Override
    protected void configure() {
        using(nullConverter).map(source.getEmail(), destination.getEmail());
    }
});

Best Practices for Custom Mappings

To make the most of ModelMapper custom mappings, here are some best practices to keep in mind:

• Keep it simple: Use custom mappings only when necessary. If the default mapping conventions work, stick with them.
• Use descriptive names: Give your converters and providers descriptive names that clearly indicate their purpose.
• Write unit tests: Always write unit tests to ensure that your custom mappings are working correctly.
• Document your mappings: Add comments to your code to explain the purpose of each custom mapping.
• Avoid complex logic: If your mapping logic becomes too complex, consider refactoring it into separate methods or classes.

Conclusion

Spring ModelMapper is a powerful tool for simplifying object-to-object mapping in Java applications. By using custom mappings, you can handle complex mapping scenarios and tailor the mapping process to your specific needs. Whether you're renaming fields, performing data transformations, or handling null values, ModelMapper provides the flexibility and control you need to get the job done. So go ahead, give it a try, and see how much time and effort you can save! Happy coding! Remember these techniques, and you’ll be mapping like a pro in no time!