Deep Dive into MapStruct, Project Lombok and Spring

MapStruct, Project Lombok, and Spring are three of the most commonly used tools in Java development, each offering their unique features and advantages. Here’s a comprehensive guide on how to configure and use these tools to boost your Java coding efficiency.

What is MapStruct?

MapStruct is a Java-based, annotation-driven code generator that follows the convention-over-configuration approach. It simplifies the implementation of mappings between Java bean types by generating mapping code during the compile-time. As a result, it provides early feedback about erroneous mappings, ensures excellent performance, and produces clean, easily understandable, and debuggable code with no runtime dependencies.

Advantages of MapStruct

MapStruct excels in transforming data models, particularly when you need to convert an entity model to a DTO (Data Transfer Object) or vice versa. These conversions are common in many applications, especially in multi-layered architectures like Hexagonal or Clean Architecture. Doing this manually can be time-consuming, error-prone, and hard to maintain. MapStruct automates this conversion process with minimal overhead.

How to Set Up MapStruct with Maven

Setting up MapStruct with Maven involves editing your pom.xml file to include MapStruct’s dependencies and the maven-compiler-plugin to your project. Below is a sample configuration:

<project xmlns="http://maven.apache.org/POM/4.0.0" ... >
    <!-- rest of your configuration -->

    <properties>
        <!-- MapStruct version -->
        <org.mapstruct.version>1.5.5.Final</org.mapstruct.version>
    </properties>

    <dependencies>
        <!-- MapStruct dependency -->
        <dependency>
            <groupId>org.mapstruct</groupId>
            <artifactId>mapstruct</artifactId>
            <version>${org.mapstruct.version}</version>
        </dependency>
    </dependencies>

    <build>
        <pluginManagement>
            <plugins>
                <!-- Maven compiler plugin configuration -->
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-compiler-plugin</artifactId>
                    <version>3.8.1</version>
                    <configuration>
                        <source>1.8</source>
                        <target>1.8</target>
                        <annotationProcessorPaths>
                            <path>
                                <groupId>org.mapstruct</groupId>
                                <artifactId>mapstruct-processor</artifactId>
                                <version>${org.mapstruct.version}</version>
                            </path>
                        </annotationProcessorPaths>
                    </configuration>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>
</project>

How to Set Up MapStruct with Gradle

Setting up MapStruct with Gradle is similar to Maven. You need to modify your build.gradle file to include the dependencies and the necessary configurations for MapStruct. Below is an example of how you can configure a Gradle project with MapStruct:

plugins {
    id 'java'
}

repositories {
    mavenCentral()
}

ext {
    mapstructVersion = "1.5.5.Final"
}

dependencies {
    implementation "org.mapstruct:mapstruct:${mapstructVersion}"
    annotationProcessor "org.mapstruct:mapstruct-processor:${mapstructVersion}"
}

sourceCompatibility = JavaVersion.VERSION_1_8

Integration with IDEs

Eclipse:

For Eclipse, you need to install the m2e-apt plugin, which automatically applies the annotation processor settings. Add <m2e.apt.activation>jdt_apt</m2e.apt.activation> to your pom.xml properties if you’re working with Maven.

For Gradle, add the com.diffplug.eclipse.apt plugin to your Gradle project configuration. You also need to install the MapStruct Eclipse Plugin, which you can obtain from the Eclipse Marketplace or by dragging the plugin icon into your running Eclipse workspace.

IntelliJ IDEA:

IntelliJ IDEA’s configuration varies depending on your Maven or Gradle project setup. You might need to configure the annotation processor manually in your project settings if IntelliJ doesn’t pick it up automatically. An IntelliJ plugin for MapStruct is also available in the JetBrains plugins repository.

Making MapStruct Play Nicely with Project Lombok

Project Lombok is a Java library that brings in a series of handy features like automatically adding getters, setters, equals, hashcode, toString methods, and more into your POJO classes, thus reducing the amount of boilerplate code you need to write and maintain.

To integrate Lombok with MapStruct, you’ll need to modify your project’s build configuration, either in Maven or Gradle.

Maven Integration:

For Maven users, add the following dependencies to your pom.xml file:

<properties>
    <org.projectlombok.version>1.18.20</org.projectlombok.version>
    <lombok-mapstruct-binding.version>0.2.0</lombok-mapstruct-binding.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>${org.projectlombok.version}</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>${org.projectlombok.version}</version>
                    </path>
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok-mapstruct-binding</artifactId>
                        <version>${lombok-mapstruct-binding.version}</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

This configuration makes sure that Lombok and MapStruct work together properly, where Lombok runs before MapStruct, allowing MapStruct to use the getters, setters, and other methods generated by Lombok.

Gradle Integration:

For Gradle users, you will need to modify your build.gradle file as follows:

ext {
    lombokVersion = "1.18.20"
    lombokMapstructBindingVersion = "0.2.0"
}

dependencies {
    compileOnly "org.projectlombok:lombok:${lombokVersion}"
    annotationProcessor "org.projectlombok:lombok:${lombokVersion}"
    annotationProcessor "org.projectlombok:lombok-mapstruct-binding:${lombokMapstructBindingVersion}"
}

This configuration ensures Lombok is applied during the compilation process, and the Lombok annotations are processed before MapStruct’s, so MapStruct can access the methods generated by Lombok.

Annotation Placement:

When using Lombok and MapStruct together in your code, the order of annotations is important. You must place Lombok’s annotations (@Data, @Getter, @Setter, etc.) before MapStruct’s @Mapper or @MapperConfig in your classes.

This ensures that the Lombok’s code generation takes place before MapStruct’s, allowing MapStruct to use the code generated by Lombok.

Working with IDEs:

Most modern IDEs (Eclipse, IntelliJ) can handle Lombok out of the box or offer plugins for Lombok support. However, sometimes manual configuration is necessary. For IntelliJ, you need to enable annotation processing and install the Lombok Plugin. In Eclipse, you might have to install the Lombok plugin and make sure your m2e settings are correct.

Remember, always verify your setup by checking whether Lombok’s generated methods are recognized by your IDE without any errors.

With Lombok and MapStruct working together, your codebase will become less cluttered and more manageable, freeing you to focus on implementing the business logic of your application.

Making MapStruct Play Nicely with Spring

MapStruct plays well with Spring framework and can be used to generate Spring beans by setting the component model to “spring” in the @Mapper annotation.

@Mapper(componentModel = "spring")
public interface CarMapper {
    // define your mapping methods here
}

After setting the componentModel to “spring”, the generated mapper will be a singleton bean that can be injected into other beans using Spring’s DI mechanism.

Example Use Cases Covering Various Features

Basic Mapping:

MapStruct can automatically map properties with the same name and compatible types.

@Mapper
public interface SourceTargetMapper {
    Target toTarget(Source s);
}

Nested Mapping:

MapStruct supports nested source and target properties. It can generate mapping methods for nested properties if the names follow the JavaBeans convention.

@Mapper
public interface OrderMapper {
    OrderDto orderToOrderDto(Order order);
}

Update Mapping:

If you have an existing target object and want to update it, you can use @MappingTarget annotation.

@Mapper
public interface PersonMapper {
    void updatePersonDto(@MappingTarget PersonDto personDto, Person person);
}

Collection Mapping:

MapStruct can generate implementations for methods that map collections.

@Mapper
public interface CarMapper {
    List<CarDto> carsToCarDtos(List<Car> cars);
}

Conditional Mapping:

MapStruct supports conditional methods that decide at runtime whether to perform a mapping or not.

@Mapper
public interface CarMapper {
    @AfterMapping
    default void setCarType(@MappingTarget CarDto carDto, Car car) {
        if (car.getEngine().getHorsePower() > 300) {
            carDto.setType(CarType.SPORTS_CAR);
        } else {
            carDto.setType(CarType.NORMAL_CAR);
        }
    }
}

Custom Converters:

MapStruct allows you to define custom converters for specific types.

@Mapper
public abstract class CarMapper {
    @Mapping(source = "numberOfSeats", target = "seatCount")
    public abstract CarDto carToCarDto(Car car);

    protected String mapFuelType(FuelType fuelType) {
        return fuelType.getFuelType();
    }
}

Mapping Inheritance:

MapStruct can map classes that follow inheritance hierarchy. If you have a superclass and subclasses, MapStruct will correctly map superclass properties and allow you to define specific mappings for subclasses.

@Mapper
public interface VehicleMapper {
    VehicleDto vehicleToVehicleDto(Vehicle vehicle);
    CarDto carToCarDto(Car car);
}

Custom Naming Strategies:

You might sometimes need to adapt the source property’s name to a different format in the target class. MapStruct provides a Builder pattern with a fluent API that supports custom naming strategies.

@Mapper(builder = @Builder(builderClassName = "Builder", buildMethodName = "create"))
public interface CustomNamingMapper {
    @Mapping(target = "nameInTarget", source = "nameInSource")
    CustomTarget sourceToTarget(CustomSource source);
}

Reversing Mappings:

MapStruct also allows you to generate mappings in the opposite direction. You can use @InheritInverseConfiguration to create methods that map target to source objects.

@Mapper
public interface ReverseMapper {
    @Mapping(target = "name", source = "fullName")
    Source targetToSource(Target target);
    
    @InheritInverseConfiguration
    Target sourceToTarget(Source source);
}

Mapping with null or default values:

In certain scenarios, you might need to set a default value when the source property is null. MapStruct provides a @ValueMappings annotation that helps you handle this.

@Mapper
public interface DefaultValueMapper {
    @ValueMappings({
        @ValueMapping(source = "null", target = "DEFAULT"),
        @ValueMapping(source = "SPECIAL", target = "SPECIAL"),
        // other mappings
    })
    Target sourceToTarget(Source source);
}

Conclusion

MapStruct, with its simplicity, reliability, and robustness, can significantly streamline the data transfer process in your Java applications. Paired with the Spring framework for DI and Lombok for reducing boilerplate code, it can considerably improve the maintainability of your code.

While the examples above cover many of MapStruct’s features, the library offers even more. If you need advanced features like context-based mappings, mapping lifecycle callbacks, or using decorators for custom mapping logic, I recommend you explore the official MapStruct documentation.

Remember, the aim here is to make your code more straightforward, readable, and maintainable. Always choose tools and libraries that serve this purpose and fit your project’s needs. Happy coding!