mapstruct · filiphr · Jul 12, 2018 · Jul 8, 2018 · chris922 · Jul 12, 2018
diff --git a/core-common/src/main/java/org/mapstruct/BeanMapping.java b/core-common/src/main/java/org/mapstruct/BeanMapping.java
@@ -97,4 +97,23 @@
      * @since 1.3
      */
     String[] ignoreUnmappedSourceProperties() default {};
+
+    /**
+     * The information that should be used for the builder mappings. This can be used to define custom build methods
+     * for the builder strategy that one uses.
+     *
+     * If no builder is defined the builder given via {@link MapperConfig#builder()} or {@link Mapper#builder()}
+     * will be applied.
+     * <p>
+     * NOTE: In case no builder is defined here, in {@link Mapper} or {@link MapperConfig} and there is a single
+     * build method, then that method would be used.
+     * <p>
+     * If the builder is defined and there is a single method that does not match the name of the finisher than
+     * a compile error will occurs
+     *
+     * @return the builder information for the method level
+     *
+     * @since 1.3
+     */
+    Builder builder() default @Builder;
 }
diff --git a/core-common/src/main/java/org/mapstruct/Builder.java b/core-common/src/main/java/org/mapstruct/Builder.java
@@ -0,0 +1,45 @@
+/**
+ *  Copyright 2012-2017 Gunnar Morling (http://www.gunnarmorling.de/)
+ *  and/or other contributors as indicated by the @authors tag. See the
+ *  copyright.txt file in the distribution for a full listing of all
+ *  contributors.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package org.mapstruct;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.mapstruct.util.Experimental;
+
+/**
+ * Configuration of builders, e.g. the name of the final build method.
+ *
+ * @author Filip Hrisafov
+ *
+ * @since 1.3
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target({})
+@Experimental
+public @interface Builder {
+
+    /**
+     * The name of the build method that needs to be invoked on the builder to create the type being build
+     *
+     * @return the method that needs to tbe invoked on the builder
+     */
+    String buildMethod() default "build";
+}
diff --git a/core-common/src/main/java/org/mapstruct/Mapper.java b/core-common/src/main/java/org/mapstruct/Mapper.java
@@ -18,15 +18,15 @@
  */
 package org.mapstruct;
 
-import static org.mapstruct.NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
-
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 import org.mapstruct.factory.Mappers;
 
+import static org.mapstruct.NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
+
 /**
  * Marks an interface or abstract class as a mapper and activates the generation of a implementation of that type via
  * MapStruct.
@@ -200,4 +200,22 @@
      */
     boolean disableSubMappingMethodsGeneration() default false;
 
+    /**
+     * The information that should be used for the builder mappings. This can be used to define custom build methods
+     * for the builder strategy that one uses.
+     *
+     * If no builder is defined the builder given via {@link MapperConfig#builder()} will be applied.
+     *
+     * <p>
+     * NOTE: In case no builder is defined here, in {@link BeanMapping} or {@link MapperConfig} and there is a single
+     * build method, then that method would be used.
+     * <p>
+     * If the builder is defined and there is a single method that does not match the name of the finisher than
+     * a compile error will occurs
+     *
+     * @return the builder information
+     *
+     * @since 1.3
+     */
+    Builder builder() default @Builder;
 }
diff --git a/core-common/src/main/java/org/mapstruct/MapperConfig.java b/core-common/src/main/java/org/mapstruct/MapperConfig.java
@@ -18,15 +18,15 @@
  */
 package org.mapstruct;
 
-import static org.mapstruct.NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
-
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 import org.mapstruct.factory.Mappers;
 
+import static org.mapstruct.NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
+
 /**
  * Marks a class or interface as configuration source for generated mappers. This allows to share common configurations
  * between several mapper classes.
@@ -186,4 +186,24 @@ MappingInheritanceStrategy mappingInheritanceStrategy()
      * @since 1.2
      */
     boolean disableSubMappingMethodsGeneration() default false;
+
+    /**
+     * The information that should be used for the builder mappings. This can be used to define custom build methods
+     * for the builder strategy that one uses.
+     *
+     * <p>
+     * Can be overridden by {@link MapperConfig#builder()}.
+     *
+     * <p>
+     * NOTE: In case no builder is defined here, in {@link BeanMapping} or {@link Mapper} and there is a single
+     * build method, then that method would be used.
+     * <p>
+     * If the builder is defined and there is a single method that does not match the name of the finisher than
+     * a compile error will occurs
+     *
+     * @return the builder information
+     *
+     * @since 1.3
+     */
+    Builder builder() default @Builder;
 }
diff --git a/documentation/src/main/asciidoc/mapstruct-reference-guide.asciidoc b/documentation/src/main/asciidoc/mapstruct-reference-guide.asciidoc
@@ -639,6 +639,12 @@ The default implementation of the `BuilderProvider` assumes the following:
 So for example `Person` has a public static method that returns `PersonBuilder`.
 * The builder type has a parameterless public method (build method) that returns the type being build
 In our example `PersonBuilder` has a method returning `Person`.
+* In case there are multiple build methods, MapStruct will look for a method called `build` if such methods exists
+than this would be used, otherwise a compilation error would be created.
+* A specific build method can be defined by using `@Builder` within: `@BeanMapping`, `@Mapper` or `@MapperConfig`
+* In case there are multiple builder creation methods that satisfy the above conditions then a `MoreThanOneBuilderCreationMethodException`
+will be thrown from the `DefaultBuilderProvider` SPI.
+In case of a `MoreThanOneBuilderCreationMethodException` MapStruct will write a warning in the compilation and not use any builder.
 
 If such type is found then MapStruct will use that type to perform the mapping to (i.e. it will look for setters into that type).
 To finish the mapping MapStruct generates code that will invoke the build method of the builder.

diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/BeanMappingMethod.java b/processor/src/main/java/org/mapstruct/ap/internal/model/BeanMappingMethod.java
@@ -287,7 +287,7 @@ private MethodReference getFinalizerMethod(Type resultType) {
                 return null;
             }
 
-            return MethodReference.forMethodCall( builderType.getBuildMethod() );
+            return BuilderFinisherMethodResolver.getBuilderFinisherMethod( method, builderType, ctx );
         }
 
         /**

diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/BuilderFinisherMethodResolver.java b/processor/src/main/java/org/mapstruct/ap/internal/model/BuilderFinisherMethodResolver.java
@@ -0,0 +1,101 @@
+/**
+ *  Copyright 2012-2017 Gunnar Morling (http://www.gunnarmorling.de/)
+ *  and/or other contributors as indicated by the @authors tag. See the
+ *  copyright.txt file in the distribution for a full listing of all
+ *  contributors.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package org.mapstruct.ap.internal.model;
+
+import java.util.Collection;
+import javax.lang.model.element.ExecutableElement;
+
+import org.mapstruct.ap.internal.model.common.BuilderType;
+import org.mapstruct.ap.internal.model.source.BeanMapping;
+import org.mapstruct.ap.internal.model.source.Method;
+import org.mapstruct.ap.internal.prism.BuilderPrism;
+import org.mapstruct.ap.internal.util.MapperConfiguration;
+import org.mapstruct.ap.internal.util.Message;
+import org.mapstruct.ap.internal.util.Strings;
+
+import static org.mapstruct.ap.internal.util.Collections.first;
+
+/**
+ * @author Filip Hrisafov
+ */
+public class BuilderFinisherMethodResolver {
+
+    private static final String DEFAULT_BUILD_METHOD_NAME = "build";
+
+    private BuilderFinisherMethodResolver() {
+    }
+
+    public static MethodReference getBuilderFinisherMethod(Method method, BuilderType builderType,
+        MappingBuilderContext ctx) {
+        Collection<ExecutableElement> buildMethods = builderType.getBuildMethods();
+        if ( buildMethods.isEmpty() ) {
+            //If we reach this method this should never happen
+            return null;
+        }
+
+        BuilderPrism builderMapping = builderMappingPrism( method, ctx );
+        if ( builderMapping == null && buildMethods.size() == 1 ) {
+            return MethodReference.forMethodCall( first( buildMethods ).getSimpleName().toString() );
+        }
+        else {
+            String buildMethodPattern = DEFAULT_BUILD_METHOD_NAME;
+            if ( builderMapping != null ) {
+                buildMethodPattern = builderMapping.buildMethod();
+            }
+            for ( ExecutableElement buildMethod : buildMethods ) {
+                String methodName = buildMethod.getSimpleName().toString();
+                if ( methodName.matches( buildMethodPattern ) ) {
+                    return MethodReference.forMethodCall( methodName );
+                }
+            }
+
+            if ( builderMapping == null ) {
+                ctx.getMessager().printMessage(
+                    method.getExecutable(),
+                    Message.BUILDER_NO_BUILD_METHOD_FOUND_DEFAULT,
+                    buildMethodPattern,
+                    builderType.getBuilder(),
+                    builderType.getBuildingType(),
+                    Strings.join( buildMethods, ", " )
+                );
+            }
+            else {
+                ctx.getMessager().printMessage(
+                    method.getExecutable(),
+                    builderMapping.mirror,
+                    Message.BUILDER_NO_BUILD_METHOD_FOUND,
+                    buildMethodPattern,
+                    builderType.getBuilder(),
+                    builderType.getBuildingType(),
+                    Strings.join( buildMethods, ", " )
+                );
+            }
+        }
+
+        return null;
+    }
+
+    private static BuilderPrism builderMappingPrism(Method method, MappingBuilderContext ctx) {
+        BeanMapping beanMapping = method.getMappingOptions().getBeanMapping();
+        if ( beanMapping != null && beanMapping.getBuilder() != null ) {
+            return beanMapping.getBuilder();
+        }
+        return MapperConfiguration.getInstanceOn( ctx.getMapperTypeElement() ).getBuilderPrism();
+    }
+}
diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/common/BuilderType.java b/processor/src/main/java/org/mapstruct/ap/internal/model/common/BuilderType.java
@@ -18,6 +18,7 @@
  */
 package org.mapstruct.ap.internal.model.common;
 
+import java.util.Collection;
 import javax.lang.model.element.ExecutableElement;
 import javax.lang.model.type.TypeMirror;
 import javax.lang.model.util.Types;
@@ -33,20 +34,20 @@ public class BuilderType {
     private final Type owningType;
     private final Type buildingType;
     private final ExecutableElement builderCreationMethod;
-    private final ExecutableElement buildMethod;
+    private final Collection<ExecutableElement> buildMethods;
 
     private BuilderType(
         Type builder,
         Type owningType,
         Type buildingType,
         ExecutableElement builderCreationMethod,
-        ExecutableElement buildMethod
+        Collection<ExecutableElement> buildMethods
     ) {
         this.builder = builder;
         this.owningType = owningType;
         this.buildingType = buildingType;
         this.builderCreationMethod = builderCreationMethod;
-        this.buildMethod = buildMethod;
+        this.buildMethods = buildMethods;
     }
 
     /**
@@ -87,18 +88,17 @@ public ExecutableElement getBuilderCreationMethod() {
     }
 
     /**
-     * The name of the method that needs to be invoked on the builder to create the type being built.
-     *
-     * @return the name of the method that needs to be invoked on the type that is being built
+     * The build methods that can be invoked to create the type being built.
+     * @return the build methods that can be invoked to create the type being built
      */
-    public String getBuildMethod() {
-        return buildMethod.getSimpleName().toString();
+    public Collection<ExecutableElement> getBuildMethods() {
+        return buildMethods;
     }
 
     public BuilderInfo asBuilderInfo() {
         return new BuilderInfo.Builder()
             .builderCreationMethod( this.builderCreationMethod )
-            .buildMethod( this.buildMethod )
+            .buildMethod( this.buildMethods )
             .build();
     }
 
@@ -107,11 +107,6 @@ public static BuilderType create(BuilderInfo builderInfo, Type typeToBuild, Type
         if ( builderInfo == null ) {
             return null;
         }
-        ExecutableElement buildMethod = builderInfo.getBuildMethod();
-        if ( !typeUtils.isAssignable( buildMethod.getReturnType(), typeToBuild.getTypeMirror() ) ) {
-            //TODO throw error
-            throw new IllegalArgumentException( "Build return type is not assignable" );
-        }
 
         Type builder = typeFactory.getType( builderInfo.getBuilderCreationMethod().getReturnType() );
         ExecutableElement builderCreationMethod = builderInfo.getBuilderCreationMethod();
@@ -133,7 +128,7 @@ else if ( typeUtils.isSameType( builder.getTypeMirror(), builderCreationOwner )
             owner,
             typeToBuild,
             builderCreationMethod,
-            buildMethod
+            builderInfo.getBuildMethods()
         );
     }
 }
-Original file line number
+Diff line change
@@ Expand Up @@
                     return null;
                 }
-                return MethodReference.forMethodCall( builderType.getBuildMethod() );
+                return BuilderFinisherMethodResolver.getBuilderFinisherMethod( method, builderType, ctx );
             }
             /**
@@ Expand Down @@