GitHub - dancer1325/mapstruct: An annotation processor for generating type-safe bean mappers

MapStruct - Java bean mappings, the easy way!

What is MapStruct?

== Java annotation processor
- goal
  - generation of mappers -- for -- Java bean classes
    - type-safe
    - performant
- allows
  - alternative to write mapping code by hand / can be
    - tedious
    - error-prone
- features
  - type conversions
    - sensible defaults
    - many
- vs mapping frameworks | runtime
  - Fast execution
    - Reason: 🧠use plain method invocations -- instead of -- reflection 🧠
  - Compile-time type safety
    - ONLY objects and attributes / mapping to each other -- can be -- mapped
  - Self-contained code
    - == NO runtime dependencies
  - Clear error reports | build time, if
    - mappings are incomplete
      - == NOT ALL target properties -- are -- mapped
    - mappings are incorrect
      - == can NOT find a proper mapping method or type conversion
  - Easily debuggable mapping code
how does it work?
- declare a mapper interface / will map between 2 types
```
@Mapper
public interface CarMapper {

    CarMapper INSTANCE = Mappers.getMapper( CarMapper.class );

    @Mapping(target = "seatCount", source = "numberOfSeats")
    CarDto carToCarDto(Car car);
}
```
- once you compile it -> MapStruct -- will generate an -- implementation of this interface /
  - for mapping between source and target objects -- uses -- plain Java method invocations (NO reflection)
  - properties are mapped
    - by default, if source's property name == target's property name
    - & customized -- via -- annotations (Example: @Mapping)

Requirements

Java v1.8+

Using MapStruct

works -- via --
- CL builds (plain javac, via Maven, Gradle, Ant, etc.)
  - if you do NOT use a dependency management tool -> you can obtain a distribution bundle from | Releases
- IDEs
  - Eclipse, a dedicated plug-in is in development / provides content assist for
    - annotation attributes
    - quick fixes
  - IntelliJ, a dedicated plug-in

Maven

add | your "pom.xml"
- ALL dependencies are available | Maven Central

...
<properties>
    <org.mapstruct.version>1.6.2</org.mapstruct.version>
</properties>
...
<dependencies>
    <dependency>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct</artifactId>
        <version>${org.mapstruct.version}</version>
    </dependency>
</dependencies>
...
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.13.0</version>
            <configuration>
                <source>17</source>
                <target>17</target>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>${org.mapstruct.version}</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>
...

Gradle

add | "build.gradle"

plugins {
    ...
    id "com.diffplug.eclipse.apt" version "3.26.0" // Only for Eclipse
}

dependencies {
    ...
    implementation 'org.mapstruct:mapstruct:1.6.2'

    annotationProcessor 'org.mapstruct:mapstruct-processor:1.6.2'
    testAnnotationProcessor 'org.mapstruct:mapstruct-processor:1.6.2' // if you are using mapstruct in test code
}
...

Documentation and getting help

Building Mapstruct from Source

requirements
- Java v11+
- Maven
ways
- ./mvnw clean install
- ./mvnw clean install -DskipDistribution=true
  - if you want to skip the distribution module

Importing into IDE

requirements
- enable annotation processing | IDE
  - Reason: 🧠MapStruct, to generate mapping gems for its own annotations -- uses the -- gem annotation processor 🧠

IntelliJ

requirements
- IntelliJ v2018.2.x+
  - Reason: 🧠needed support for maven-compiler-plugin 's annotationProcessors 🧠
Enable annotation processing in IntelliJ (Build, Execution, Deployment -> Compiler -> Annotation Processors)

Eclipse

install m2e_apt

Licensing

MapStruct is licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0.