MapStruct is a code generator that greatly simplifies the implementation of mappings between Java bean types based on a convention over configuration approach.
The generated mapping code uses plain method invocations and thus is fast, type-safe and easy to understand.
Why?
Multi-layered applications often require to map between different object models (e.g. entities and DTOs). Writing such mapping code is a tedious and error-prone task. MapStruct aims at simplifying this work by automating it as much as possible.
In contrast to other mapping frameworks MapStruct generates bean mappings at compile-time which ensures a high performance, allows for fast developer feedback and thorough error checking.
How?
MapStruct is an annotation processor which is plugged into the Java compiler and can be used in command-line builds (Maven, Gradle etc.) as well as from within your preferred IDE.
MapStruct uses sensible defaults but steps out of your way when it comes to configuring or implementing special behavior.
Latest News
MapStruct 1.6.3 bug fix released
It is my pleasure to announce the 1.6.3 bug fix release of MapStruct. This release includes 3 bug fixes. You may wonder where the Blog Post for 1.6.2 is. There was no blog post as we released it immediately after 1.6.1 due to a regression in the 1.6.1 release, when using Java records.
With this release we support the use of the Java 19 LinkedHashSet and LinkedHashMap factory methods.
Redundant if condition in Java record mapping with RETURN_DEFAULT strategy (#3747) Stackoverflow with Immutables custom builder (#3370) Unused import of java.
It is my pleasure to announce the 1.6.1 bug fix release of MapStruct.
This release includes 1 enhancement and 8 bug fixes, including some regressions introduced in 1.6.0.
With this release we support the use of the Java 19 LinkedHashSet and LinkedHashMap factory methods.
It is my pleasure to announce the next official release of MapStruct Spring Extensions.
What started out as a StackOverflow question turned into its
own (sub-)project within the MapStruct organization.
Changes in this release:
TypeDescriptors will now be kept as fields in generated ConversionServiceAdapters which can speed up the conversion
process. Thanks to Jesse Bonzo for this contribution.
The generated ConverterScan
so far used the legacy @PostConstruct annotation from the deprecated javax.annotation package underneath. Thanks
to Jeff Schnitzer’s contribution, the generator now checks for the availability of
the “new” jakarta.annotation.PostConstruct annotation and will prefer this if it’s available. For reasons of backwards
compatibility, javax.annotation.PostConstruct is the fallback.
Including the annotations and extensions defined in this project will generate a class acting as bridge between
MapStruct’s conventions and Spring'
s ConversionService API
that in turn can be added to any Mapper’s uses attribute. See
the examples for details.
The following shows how to map two objects using MapStruct.
Let's assume we have a class representing cars (e.g. a JPA entity) and an accompanying data transfer object (DTO).
Both types are rather similar, only the seat count attributes have different names and the type attribute is of a special enum type in the Car class but is a plain string in the DTO.
The @Mapper annotation 1 marks the interface as mapping interface and lets the MapStruct processor kick in during compilation.
The actual mapping method 2 expects the source object as parameter and returns the target object. Its name can be freely chosen.
For attributes with different names in source and target object, the @Mapping annotation can be used to configure the names.
Where required and possible a type conversion will be executed for attributes with different types in source and target, e.g. the type attribute will be converted from the enumeration type into a string.
Of course there can be multiple mapping methods in one interface, for all of which an implementation will be generated by MapStruct.
An instance of the interface implementation can be retrieved from the Mappers class. By convention, the interface declares a member INSTANCE3, providing clients access to the mapper implementation.
Using the mapper
Based on the mapper interface, clients can perform object mappings in a very easy and type-safe manner:
@Test
public void shouldMapCarToDto() {
//given
Car car = new Car( "Morris", 5, CarType.SEDAN );
//when
CarDto carDto = CarMapper.INSTANCE.carToCarDto( car );
//then
assertThat( carDto ).isNotNull();
assertThat( carDto.getMake() ).isEqualTo( "Morris" );
assertThat( carDto.getSeatCount() ).isEqualTo( 5 );
assertThat( carDto.getType() ).isEqualTo( "SEDAN" );
}
Tell me more!
You like what you see? Then check out the reference documentation to learn how to get started with MapStruct and which advanced features there are. In case you need help or want to propose a new feature just drop by on the GitHub Discussions.
You want to contribute to the development of MapStruct? That's great, this page has all the information you need.
