Unify the API for configuring mapping behaviour #1735
Description
Currently the configuration in the MapStruct API is split into multiple different annotations which have different priority and is duplicated between them. Currently almost all methods in @Mapper and @MapperConfig are duplicated, @BeanMapping shares a lot of the methods as well and @IterableMapping and @MapMapping have something in common. This are currently the methods across them:
| method | @MapperConfig |
@Mapper |
@BeanMapping |
|---|---|---|---|
uses |
✅ | ✅ | ❌ |
imports |
✅(added on master) | ✅ | |
unmappedSourcePolicy |
✅ | ✅ | |
unmappedTargetPolicy |
✅ | ✅ | |
typeConversionPolicy |
✅ | ✅ | |
componentModel |
✅ | ✅ | ❌ |
implementationName |
✅ | ✅ | ❌ |
implementationPackage |
✅ | ✅ | ❌ |
collectionMappingPolicy |
✅ | ✅ | |
nullValueMappingPolicy |
✅ | ✅ | ✅ |
nullValuePropertyMappingPolicy |
✅ | ✅ | ✅ |
nullValueCheckStrategy |
✅ | ✅ | ✅ |
injectionStrategy |
✅ | ✅ | ❌ |
disableSubMappingMethods |
✅ | ✅ | |
builder |
✅ | ✅ | ✅ |
Legend:
✅ - Present
❌ - Not present and not needed
For 2.0 perhaps we should extract a single new API annotation that would allow people to use it on classes and methods. Not sure what the name of the annotation should be. Maybe @MappingOptions, or @MappingConfig. This annotation should have all methods that affect a mapping (i.e. everything that is with ✅and @BeanMapping.
It will still be possible to apply this annotation on a @MapperConfig, @Mapper or a method. The precedence will still be the same as now.
The methods that would go in the new annotation will not be present in the @MapperConfig, @Mapper and @BeanMapping annotations anymore.
It would be good to hear from our community and users what they think about this.