• What is MapStruct?
• Requirements
• Using MapStruct
• Maven
• Gradle
• Documentation and getting help
• Building from Source
• Links
• Licensing

• == 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)

• Java v1.8+

• 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

• 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>
...

• 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
}
...

• reference documentation
• Discussions

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

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

• 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)

• install m2e_apt

• Homepage
• Source code
• Downloads
• Issue tracker
• User group
• CI build

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.