From 5727d20ce3c165ad468a0be5ed10a881ddc170b9 Mon Sep 17 00:00:00 2001 From: Nikolas Charalambidis Date: Wed, 4 Nov 2020 21:39:06 +0100 Subject: [PATCH] #2258 Fixes vague description of @Default and @ConstructorProperties annotations --- ...er-14-third-party-api-integration.asciidoc | 41 +++++++++++++++++++ .../chapter-3-defining-a-mapper.asciidoc | 6 +-- .../mapstruct-reference-guide.asciidoc | 4 +- 3 files changed, 47 insertions(+), 4 deletions(-) create mode 100644 documentation/src/main/asciidoc/chapter-14-third-party-api-integration.asciidoc diff --git a/documentation/src/main/asciidoc/chapter-14-third-party-api-integration.asciidoc b/documentation/src/main/asciidoc/chapter-14-third-party-api-integration.asciidoc new file mode 100644 index 000000000..03e18167e --- /dev/null +++ b/documentation/src/main/asciidoc/chapter-14-third-party-api-integration.asciidoc @@ -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 { + +} +---- +==== \ No newline at end of file diff --git a/documentation/src/main/asciidoc/chapter-3-defining-a-mapper.asciidoc b/documentation/src/main/asciidoc/chapter-3-defining-a-mapper.asciidoc index 54a0dbd70..acdfd9817 100644 --- a/documentation/src/main/asciidoc/chapter-3-defining-a-mapper.asciidoc +++ b/documentation/src/main/asciidoc/chapter-3-defining-a-mapper.asciidoc @@ -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 <>) 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 <>) 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 <>) then this annotation will be used to get the names of the parameters. [NOTE] ==== diff --git a/documentation/src/main/asciidoc/mapstruct-reference-guide.asciidoc b/documentation/src/main/asciidoc/mapstruct-reference-guide.asciidoc index 1aa08b17b..b83c874c5 100644 --- a/documentation/src/main/asciidoc/mapstruct-reference-guide.asciidoc +++ b/documentation/src/main/asciidoc/mapstruct-reference-guide.asciidoc @@ -44,4 +44,6 @@ include::chapter-11-reusing-mapping-configurations.asciidoc[] include::chapter-12-customizing-mapping.asciidoc[] -include::chapter-13-using-mapstruct-spi.asciidoc[] \ No newline at end of file +include::chapter-13-using-mapstruct-spi.asciidoc[] + +include::chapter-14-third-party-api-integration.asciidoc[] \ No newline at end of file