third_codes/mapstruct
1
0
Fork 0
mirror of https://github.com/mapstruct/mapstruct.git synced 2025-07-12 00:00:08 +08:00
Code Issues Packages Projects Releases Wiki Activity

#2258 Fixes vague description of @Default and @ConstructorProperties annotations

Browse Source
This commit is contained in:
Nikolas Charalambidis 2020-11-04 21:39:06 +01:00 committed by Filip Hrisafov
parent e8713fb432
commit 5727d20ce3
3 changed files with 47 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
documentation/src/main/asciidoc/chapter-14-third-party-api-integration.asciidoc Normal file
View File

@ -0,0 +1,41 @@
[[third-party-api-integration]]
== Third-party API integration
[[non-shipped-annotations]]
=== Non-shipped annotations
There are various use-cases you must resolve ambiguity for MapStruct to use a correct piece of code.
However, the primary goal of MapStruct is to focus on bean mapping without polluting the entity code.
For that reason, MapStruct is flexible enough to interact with already defined annotations from third-party libraries.
The requirement to enable this behavior is to match the _name_ of such annotation.
Hence, we say that annotation can be _from any package_.
The annotations _named_ `@ConstructorProperties` and `@Default` are currently examples of this kind of annotation.
[WARNING]
====
If such named third-party annotation exists, it does not guarantee its `@Target` matches with the intended placement.
Be aware of placing a third-party annotation just for sake of mapping is not recommended as long as it might lead to unwanted side effects caused by that library.
====
A very common case is that no third-party dependency imported to your project provides such annotation or is inappropriate for use as already described.
In such cases create your own annotation, for example:
====
[source, java, linenums]
[subs="verbatim,attributes"]
----
package foo.support.mapstruct;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target(ElementType.CONSTRUCTOR)
@Retention(RetentionPolicy.CLASS)
public @interface Default {
}
----
====

6
documentation/src/main/asciidoc/chapter-3-defining-a-mapper.asciidoc
View File

@ -537,10 +537,10 @@ When doing a mapping MapStruct checks if there is a builder for the type being m
If there is no builder, then MapStruct looks for a single accessible constructor.
When there are multiple constructors then the following is done to pick the one which should be used:
* If a constructor is annotated with an annotation named `@Default` (from any package) it will be used.
* If a constructor is annotated with an annotation _named_ `@Default` (from any package, see <<non-shipped-annotations>>) it will be used.
* If a single public constructor exists then it will be used to construct the object, and the other non public constructors will be ignored.
* If a parameterless constructor exists then it will be used to construct the object, and the other constructors will be ignored.
* If there are multiple eligible constructors then there will be a compilation error due to ambiguous constructors. In order to break the ambiguity an annotation named `@Default` (from any package) can used.
* If there are multiple eligible constructors then there will be a compilation error due to ambiguous constructors. In order to break the ambiguity an annotation _named_ `@Default` (from any package, see <<non-shipped-annotations>>) can used.
.Deciding which constructor to use
====
@ -585,7 +585,7 @@ public class Van {
====
When using a constructor then the names of the parameters of the constructor will be used and matched to the target properties.
When the constructor has an annotation named `@ConstructorProperties` (from any package) then this annotation will be used to get the names of the parameters.
When the constructor has an annotation _named_ `@ConstructorProperties` (from any package, see <<non-shipped-annotations>>) then this annotation will be used to get the names of the parameters.
[NOTE]
====

4
documentation/src/main/asciidoc/mapstruct-reference-guide.asciidoc
View File

@ -44,4 +44,6 @@ include::chapter-11-reusing-mapping-configurations.asciidoc[]
include::chapter-12-customizing-mapping.asciidoc[]
include::chapter-13-using-mapstruct-spi.asciidoc[]
include::chapter-13-using-mapstruct-spi.asciidoc[]
include::chapter-14-third-party-api-integration.asciidoc[]