GitHub - mapstruct/mapstruct: An annotation processor for generating type-safe b...
source link: https://github.com/mapstruct/mapstruct
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
MapStruct - Java bean mappings, the easy way!
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(target = "seatCount", source = "numberOfSeats") 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.4.2.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 "com.diffplug.eclipse.apt" version "3.26.0" // Only for Eclipse } dependencies { ... compile 'org.mapstruct:mapstruct:1.4.2.Final' annotationProcessor 'org.mapstruct:mapstruct-processor:1.4.2.Final' testAnnotationProcessor 'org.mapstruct:mapstruct-processor:1.4.2.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.
Recommend
-
96
MapStruct is a pretty popular and well-maintained framework for object mapping. To summarize: it is capable of generating the mapping code among objects in different layers of an application.
-
34
Annotation processors can be useful as a hacky workaround to get some language feature into the Java language. The best example is Lombok, which enhances the Java language with quite a few annotation-based features. jOOQ also has an annotation p...
-
66
MpApt - Kotlin (Native/JS/JVM) Annotation Processor library Introduction 🙋...
-
9
For a small web project I recently had to consider how to generate secure tokens to prevent Cross Site Request Forgery (CSRF). I wanted to share...
-
7
1. Overview The Scala programming language has many ways to handle dependencies among types. The so-called “self-type” annotation allows us to declare dependencies using traits and the concept of mixins. In this tutorial, we...
-
6
Table of Contents最近基于工作上的需求调研了下 Java Annotation Processor 的使用方式,开篇博客记录下学习过程中遇到的坑。可以由于平时用到 Annotation 的场景特别少,因此能搜索到的教程特别有限,也希望文章在某种程度上填补部分空白吧。...
-
5
Understanding RBS, Ruby's new Type Annotation SystemRBS is the name of a new type syntax format language for Ruby. RBS lets you add type annotations to your Ruby code in files with a new extension cal...
-
4
@h3avrenAjay Singh RanaDreaming of Python... Under a sky in India...NEWABOUT PAGE...
-
4
🖌 The Guide To Your First Annotation Processor with KSP (And Becoming A Kotlin Artist)
-
2
Build your own framework using an annotation processor
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK