mapstruct#73 Add support for using constructor arguments when instantiating mapping targets

By default the constructor argument names are used to extract the target properties.
If a constructor is annotated with an annotation named `@ConstructorProperties` (from any package) then it would be used to extract the target properties.

If a mapping target has a parameterless empty constructor it would be used to instantiate the target.
When there are multiple constructors then an annotation named `@Default` (from any package) can be used to mark a constructor that should be used by default when instantiating the target.

Supports mapping into Java 14 Records and Kotlin data classes out of the box

Author: filiphr

build-config/src/main/resources/build-config/checkstyle.xml

@@ -122,9 +122,6 @@
 
         <!-- Checks for Size Violations.                    -->
         <!-- See http://checkstyle.sf.net/config_sizes.html -->
-        <module name="MethodLength">
-            <property name="max" value="200"/>
-        </module>
         <module name="ParameterNumber">
             <property name="max" value="10"/>
         </module>

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

@@ -528,3 +528,80 @@ Otherwise, you would need to write a custom `BuilderProvider`
 ====
 In case you want to disable using builders then you can use the `NoOpBuilderProvider` by creating a `org.mapstruct.ap.spi.BuilderProvider` file in the `META-INF/services` directory with `org.mapstruct.ap.spi.NoOpBuilderProvider` as it's content.
 ====
+
+[[mapping-with-constructors]]
+=== Using Constructors
+
+MapStruct supports using constructors for mapping target types.
+When doing a mapping MapStruct checks if there is a builder for the type being mapped.
+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 parameterless constructor exists then it would be used to construct the object, and the other constructors will be ignored
+* If there are multiple constructors then the one annotated with annotation named `@Default` (from any package) will be used
+
+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.
+
+[NOTE]
+====
+When an object factory method or a method annotated with `@ObjectFactory` exists, it will take precedence over any constructor defined in the target.
+The target object constructor will not be used in that case.
+====
+
+
+.Person with constructor parameters
+====
+[source, java, linenums]
+[subs="verbatim,attributes"]
+----
+public class Person {
+
+    private final String name;
+    private final String surname;
+
+    public Person(String name, String surname) {
+        this.name = name;
+        this.surname = surname;
+    }
+}
+----
+====
+
+.Person With Constructor Mapper definition
+====
+[source, java, linenums]
+[subs="verbatim,attributes"]
+----
+public interface PersonMapper {
+
+    Person map(PersonDto dto);
+}
+----
+====
+
+.Generated mapper with constructor
+====
+[source, java, linenums]
+[subs="verbatim,attributes"]
+----
+// GENERATED CODE
+public class PersonMapperImpl implements PersonMapper {
+
+    public Person map(PersonDto dto) {
+        if (dto == null) {
+            return null;
+        }
+
+        String name;
+        String surname;
+        name = dto.getName();
+        surname = dto.getSurname();
+
+        Person person = new Person( name, surname );
+
+        return person;
+    }
+}
+----
+====

documentation/src/main/asciidoc/chapter-5-data-type-conversions.asciidoc

@@ -174,6 +174,12 @@ During the generation of automatic sub-mapping methods <<shared-configurations>>
 Follow issue https://github.com/mapstruct/mapstruct/issues/1086[#1086] for more information.
 ====
 
+[NOTE]
+====
+Constructor properties of the target object are also considered as target properties.
+You can read more about that in <<mapping-with-constructors>>
+====
+
 [[controlling-nested-bean-mappings]]
 === Controlling nested bean mappings
 

integrationtest/src/test/java/org/mapstruct/itest/tests/MavenIntegrationTest.java

@@ -107,6 +107,14 @@ void protobufBuilderTest() {
     void recordsTest() {
     }
 
+    @ProcessorTest(baseDir = "kotlinDataTest", processorTypes = {
+        ProcessorTest.ProcessorType.JAVAC
+    }, forkJvm = true)
+    // We have to fork the jvm because there is an NPE in com.intellij.openapi.util.SystemInfo.getRtVersion
+    // and the kotlin-maven-plugin uses that. See also https://youtrack.jetbrains.com/issue/IDEA-238907
+    void kotlinDataTest() {
+    }
+
     @ProcessorTest(baseDir = "simpleTest")
     void simpleTest() {
     }

integrationtest/src/test/java/org/mapstruct/itest/testutil/extension/ProcessorInvocationInterceptor.java

@@ -71,6 +71,9 @@ private void doExecute(ExtensionContext extensionContext) throws Exception {
         }
         else {
             verifier = new Verifier( destination.getCanonicalPath() );
+            if ( processorTestContext.isForkJvm() ) {
+                verifier.setForkJvm( true );
+            }
         }
 
         List<String> goals = new ArrayList<>( 3 );

integrationtest/src/test/java/org/mapstruct/itest/testutil/extension/ProcessorTest.java

@@ -106,4 +106,7 @@ ProcessorType[] processorTypes() default {
      * @return the {@link CommandLineEnhancer} implementation. Must have a default constructor.
      */
     Class<? extends CommandLineEnhancer> commandLineEnhancer() default CommandLineEnhancer.class;
+
+    boolean forkJvm() default false;
+
 }

integrationtest/src/test/java/org/mapstruct/itest/testutil/extension/ProcessorTestContext.java

@@ -13,13 +13,16 @@ public class ProcessorTestContext {
     private final String baseDir;
     private final ProcessorTest.ProcessorType processor;
     private final Class<? extends ProcessorTest.CommandLineEnhancer> cliEnhancerClass;
+    private final boolean forkJvm;
 
     public ProcessorTestContext(String baseDir,
         ProcessorTest.ProcessorType processor,
-        Class<? extends ProcessorTest.CommandLineEnhancer> cliEnhancerClass) {
+        Class<? extends ProcessorTest.CommandLineEnhancer> cliEnhancerClass,
+        boolean forkJvm) {
         this.baseDir = baseDir;
         this.processor = processor;
         this.cliEnhancerClass = cliEnhancerClass;
+        this.forkJvm = forkJvm;
     }
 
     public String getBaseDir() {
@@ -33,4 +36,8 @@ public ProcessorTest.ProcessorType getProcessor() {
     public Class<? extends ProcessorTest.CommandLineEnhancer> getCliEnhancerClass() {
         return cliEnhancerClass;
     }
+
+    public boolean isForkJvm() {
+        return forkJvm;
+    }
 }

integrationtest/src/test/java/org/mapstruct/itest/testutil/extension/ProcessorTestTemplateInvocationContextProvider.java

@@ -34,7 +34,8 @@ public Stream<TestTemplateInvocationContext> provideTestTemplateInvocationContex
             .map( processorType -> new ProcessorTestTemplateInvocationContext( new ProcessorTestContext(
                 processorTest.baseDir(),
                 processorType,
-                processorTest.commandLineEnhancer()
+                processorTest.commandLineEnhancer(),
+                processorTest.forkJvm()
             ) ) );
     }
 }

integrationtest/src/test/resources/kotlinDataTest/pom.xml

@@ -0,0 +1,102 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Copyright MapStruct Authors.
+
+    Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.mapstruct</groupId>
+        <artifactId>mapstruct-it-parent</artifactId>
+        <version>1.0.0</version>
+        <relativePath>../pom.xml</relativePath>
+    </parent>
+
+    <artifactId>kotlinDataTest</artifactId>
+    <packaging>jar</packaging>
+
+    <properties>
+        <kotlin.version>1.3.70</kotlin.version>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.jetbrains.kotlin</groupId>
+            <artifactId>kotlin-stdlib</artifactId>
+            <version>${kotlin.version}</version>
+        </dependency>
+    </dependencies>
+
+    <profiles>
+        <profile>
+            <id>generate-via-compiler-plugin</id>
+            <activation>
+                <activeByDefault>false</activeByDefault>
+            </activation>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>org.jetbrains.kotlin</groupId>
+                        <artifactId>kotlin-maven-plugin</artifactId>
+                        <version>${kotlin.version}</version>
+                        <executions>
+                            <execution>
+                                <id>compile</id>
+                                <goals> <goal>compile</goal> </goals>
+                                <configuration>
+                                    <sourceDirs>
+                                        <sourceDir>\${project.basedir}/src/main/kotlin</sourceDir>
+                                        <sourceDir>\${project.basedir}/src/main/java</sourceDir>
+                                    </sourceDirs>
+                                </configuration>
+                            </execution>
+                            <execution>
+                                <id>test-compile</id>
+                                <goals> <goal>test-compile</goal> </goals>
+                                <configuration>
+                                    <sourceDirs>
+                                        <sourceDir>\${project.basedir}/src/test/kotlin</sourceDir>
+                                        <sourceDir>\${project.basedir}/src/test/java</sourceDir>
+                                    </sourceDirs>
+                                </configuration>
+                            </execution>
+                        </executions>
+                    </plugin>
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-compiler-plugin</artifactId>
+                        <executions>
+                            <!-- Replacing default-compile as it is treated specially by maven -->
+                            <execution>
+                                <id>default-compile</id>
+                                <phase>none</phase>
+                            </execution>
+                            <!-- Replacing default-testCompile as it is treated specially by maven -->
+                            <execution>
+                                <id>default-testCompile</id>
+                                <phase>none</phase>
+                            </execution>
+                            <execution>
+                                <id>java-compile</id>
+                                <phase>compile</phase>
+                                <goals> <goal>compile</goal> </goals>
+                            </execution>
+                            <execution>
+                                <id>java-test-compile</id>
+                                <phase>test-compile</phase>
+                                <goals> <goal>testCompile</goal> </goals>
+                            </execution>
+                        </executions>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+    </profiles>
+
+</project>

integrationtest/src/test/resources/kotlinDataTest/src/main/java/org/mapstruct/itest/kotlin/data/CustomerEntity.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.itest.kotlin.data;
+
+/**
+ * @author Filip Hrisafov
+ */
+public class CustomerEntity {
+
+    private String name;
+    private String mail;
+
+    public String getName() {
+        return name;
+    }
+
+    public void setName(String name) {
+        this.name = name;
+    }
+
+    public String getMail() {
+        return mail;
+    }
+
+    public void setMail(String mail) {
+        this.mail = mail;
+    }
+}

integrationtest/src/test/resources/kotlinDataTest/src/main/java/org/mapstruct/itest/kotlin/data/CustomerMapper.java

@@ -0,0 +1,27 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.itest.kotlin.data;
+
+import org.mapstruct.InheritInverseConfiguration;
+import org.mapstruct.Mapper;
+import org.mapstruct.Mapping;
+import org.mapstruct.factory.Mappers;
+
+/**
+ * @author Filip Hrisafov
+ */
+@Mapper
+public interface CustomerMapper {
+
+    CustomerMapper INSTANCE = Mappers.getMapper( CustomerMapper.class );
+
+    @Mapping(target = "mail", source = "email")
+    CustomerEntity fromRecord(CustomerDto record);
+
+    @InheritInverseConfiguration
+    CustomerDto toRecord(CustomerEntity entity);
+
+}

integrationtest/src/test/resources/kotlinDataTest/src/main/kotlin/org/mapstruct/itest/kotlin/data/CustomerDto.kt

@@ -0,0 +1,10 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.itest.kotlin.data;
+
+data class CustomerDto(var name: String?, var email: String?) {
+
+}

integrationtest/src/test/resources/kotlinDataTest/src/test/java/org/mapstruct/itest/kotlin/data/KotlinDataTest.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.itest.kotlin.data;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.junit.Test;
+import org.mapstruct.itest.kotlin.data.CustomerDto;
+import org.mapstruct.itest.kotlin.data.CustomerEntity;
+import org.mapstruct.itest.kotlin.data.CustomerMapper;
+
+public class KotlinDataTest {
+
+    @Test
+    public void shouldMapData() {
+        CustomerEntity customer = CustomerMapper.INSTANCE.fromRecord( new CustomerDto( "Kermit", "[email protected]" ) );
+
+        assertThat( customer ).isNotNull();
+        assertThat( customer.getName() ).isEqualTo( "Kermit" );
+        assertThat( customer.getMail() ).isEqualTo( "[email protected]" );
+    }
+
+    @Test
+    public void shouldMapIntoData() {
+        CustomerEntity entity = new CustomerEntity();
+        entity.setName( "Kermit" );
+        entity.setMail( "[email protected]" );
+
+        CustomerDto customer = CustomerMapper.INSTANCE.toRecord( entity );
+
+        assertThat( customer ).isNotNull();
+        assertThat( customer.getName() ).isEqualTo( "Kermit" );
+        assertThat( customer.getEmail() ).isEqualTo( "[email protected]" );
+    }
+}