Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
filiphr merged 4 commits into from
Nov 4, 2020
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
932d2b0
#2258 Fixes vague description of @Default and @ConstructorProperties …
nikolas-charalambidis Oct 31, 2020
a46eb23
#2258 Introduces a new chapter Third-Party API integration
nikolas-charalambidis Oct 31, 2020
dce6c24
#2258 Removes misleading sentence
nikolas-charalambidis Nov 1, 2020
5c23e4a
#2258 Removes misleading sentence
nikolas-charalambidis Nov 4, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions documentation/src/main/asciidoc/chapter-14-third-party-api-integration.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 changes: 3 additions & 3 deletions documentation/src/main/asciidoc/chapter-3-defining-a-mapper.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
====
Expand Down Expand Up @@ -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]
====
Expand Down
4 changes: 3 additions & 1 deletion documentation/src/main/asciidoc/mapstruct-reference-guide.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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[]