Skip to content
An annotation processor for generating type-safe bean mappers
Java FreeMarker
Branch: master
Clone or download

Latest commit

filiphr Add EnumTransformationStrategy SPI (#2089)
Add a new custom EnumTransformationStrategy SPI which can be used for providing custom way of name based mapping for enums.

Add 4 out of the box transformation strategies:

* prefix - add a prefix to the name based enum mapping
* stripPrefix - remove a prefix from the name based enum mapping
* suffix - add a suffix to the name based enum mapping
* stripSuffix - remove a suffix from the name based enum mapping

This can be achieved by using the new `EnumMapping`

e.g.

Add suffix `_TYPE` to all enums:

`@EnumMapping(nameTransformationStrategy = "suffix", configuration = "_TYPE")`

With this it would be possible to achieve what is needed in #796, #1220, #1789.
Latest commit 7b5a549 May 18, 2020

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows Add dedicated action for Java EA builds and update main CI to use onl… May 17, 2020
.mvn/wrapper #2019 Setup GitHub Actions Mar 7, 2020
build-config #73 Add support for using constructor arguments when instantiating ma… Apr 26, 2020
core-jdk8 [maven-release-plugin] prepare for next development iteration Feb 10, 2019
core Add EnumTransformationStrategy SPI (#2089) May 18, 2020
distribution [maven-release-plugin] prepare for next development iteration Feb 10, 2019
documentation Add EnumTransformationStrategy SPI (#2089) May 18, 2020
etc #2019 Setup GitHub Actions Mar 7, 2020
integrationtest #73 Add support for using constructor arguments when instantiating ma… Apr 26, 2020
parent Add myself as developer May 17, 2020
processor Add EnumTransformationStrategy SPI (#2089) May 18, 2020
.codecov.yml Disable codecov/patch statuses May 23, 2017
.gitattributes Automatically handling line endings May 13, 2013
.gitignore #1857 Use flatten-maven-plugin to remove test dependencies from relea… May 17, 2020
CONTRIBUTING.md #2019 Setup GitHub Actions Mar 7, 2020
ISSUE_TEMPLATE.md #1616 Adding an issue template to streamline answers Sep 26, 2018
LICENSE.txt #1411 Update copyright header on all files Jul 15, 2018
copyright.txt #1420 Add support for Gradle incremental annotation processing (#1971) Dec 8, 2019
mvnw #2019 Setup GitHub Actions Mar 7, 2020
mvnw.cmd #2019 Setup GitHub Actions Mar 7, 2020
pom.xml [maven-release-plugin] prepare for next development iteration Feb 10, 2019
readme.md #2019 Setup GitHub Actions Mar 7, 2020

readme.md

MapStruct - Java bean mappings, the easy way!

Latest Stable Version Latest Version License

Build Status Coverage Status Gitter Code Quality: Java Total Alerts

What is MapStruct?

MapStruct is a Java annotation processor for the generation of type-safe and performant mappers for Java bean classes. It saves you from writing mapping code by hand, which is a tedious and error-prone task. The generator comes with sensible defaults and many built-in type conversions, but it steps out of your way when it comes to configuring or implementing special behavior.

Compared to mapping frameworks working at runtime, MapStruct offers the following advantages:

  • Fast execution by using plain method invocations instead of reflection
  • Compile-time type safety. Only objects and attributes mapping to each other can be mapped, so there's no accidental mapping of an order entity into a customer DTO, etc.
  • Self-contained code—no runtime dependencies
  • Clear error reports at build time if:
    • mappings are incomplete (not all target properties are mapped)
    • mappings are incorrect (cannot find a proper mapping method or type conversion)
  • Easily debuggable mapping code (or editable by hand—e.g. in case of a bug in the generator)

To create a mapping between two types, declare a mapper class like this:

@Mapper
public interface CarMapper {

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

    @Mapping(source = "numberOfSeats", target = "seatCount")
    CarDto carToCarDto(Car car);
}

At compile time MapStruct will generate an implementation of this interface. The generated implementation uses plain Java method invocations for mapping between source and target objects, i.e. no reflection is involved. By default, properties are mapped if they have the same name in source and target, but you can control this and many other aspects using @Mapping and a handful of other annotations.

Requirements

MapStruct requires Java 1.8 or later.

Using MapStruct

MapStruct works in command line builds (plain javac, via Maven, Gradle, Ant, etc.) and IDEs.

For Eclipse, a dedicated plug-in is in development (see https://github.com/mapstruct/mapstruct-eclipse). It goes beyond what's possible with an annotation processor, providing content assist for annotation attributes, quick fixes and more.

For IntelliJ the plug-in is available within the IntelliJ marketplace (see https://plugins.jetbrains.com/plugin/10036-mapstruct-support).

Maven

For Maven-based projects, add the following to your POM file in order to use MapStruct (the dependencies are available at Maven Central):

...
<properties>
    <org.mapstruct.version>1.3.1.Final</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.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>
</build>
...

Gradle

For Gradle, you need something along the following lines:

plugins {
    ...
    id 'net.ltgt.apt' version '0.15'
}

// You can integrate with your IDEs.
// See more details: https://github.com/tbroyer/gradle-apt-plugin#usage-with-ides
apply plugin: 'net.ltgt.apt-idea'
apply plugin: 'net.ltgt.apt-eclipse'

dependencies {
    ...
    compile 'org.mapstruct:mapstruct:1.3.1.Final'

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

If you don't work with a dependency management tool, you can obtain a distribution bundle from SourceForge.

Documentation and getting help

To learn more about MapStruct, refer to the project homepage. The reference documentation covers all provided functionality in detail. If you need help, come and join the mapstruct-users group.

Building from Source

MapStruct uses Maven for its build. Java 8 is required for building MapStruct from source. To build the complete project, run

mvn clean install

from the root of the project directory. To skip the distribution module, run

mvn clean install -DskipDistribution=true

Importing into IDE

MapStruct uses the gem annotation processor to generate mapping gems for it's own annotations. Therefore for seamless integration within an IDE annotation processing needs to be enabled.

IntelliJ

Make sure that you have at least IntelliJ 2018.2.x (needed since support for annotationProcessors from the maven-compiler-plugin is from that version). Enable annotation processing in IntelliJ (Build, Execution, Deployment -> Compiler -> Annotation Processors)

Eclipse

Make sure that you have the m2e_apt plugin installed.

Links

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 http://www.apache.org/licenses/LICENSE-2.0.

You can’t perform that action at this time.