Skip to content

Commit ef270ca

Browse files
filiphrfiliphr
authored
mapstruct#1479 Add support for Builders with multiple build methods (mapstruct#1498)
* Add new @builder annotation for defining a build method * When there are multiple build methods look for a method named `build` and if found use it * If @builder is defined than look for a build method with the defined method * When a type has multiple builder creation methods throw an exception and don't use the builder Defaulting to a method named `build` will make sure that a correct method is selected for: * FreeBuilder - it has two methods: `build` and `buildPartial` * Protobuf - it has three methods: `getDefaultInstanceForType`, `build` and `buildPartial`
1 parent 62ffa3f commit ef270ca

30 files changed

Lines changed: 1109 additions & 58 deletions

‎core-common/src/main/java/org/mapstruct/BeanMapping.java‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,4 +97,23 @@
9797
* @since 1.3
9898
*/
9999
String[] ignoreUnmappedSourceProperties() default {};
100+
101+
/**
102+
* The information that should be used for the builder mappings. This can be used to define custom build methods
103+
* for the builder strategy that one uses.
104+
*
105+
* If no builder is defined the builder given via {@link MapperConfig#builder()} or {@link Mapper#builder()}
106+
* will be applied.
107+
* <p>
108+
* NOTE: In case no builder is defined here, in {@link Mapper} or {@link MapperConfig} and there is a single
109+
* build method, then that method would be used.
110+
* <p>
111+
* If the builder is defined and there is a single method that does not match the name of the finisher than
112+
* a compile error will occurs
113+
*
114+
* @return the builder information for the method level
115+
*
116+
* @since 1.3
117+
*/
118+
Builder builder() default @Builder;
100119
}

‎core-common/src/main/java/org/mapstruct/Builder.java‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
/**
2+
* Copyright 2012-2017 Gunnar Morling (http://www.gunnarmorling.de/)
3+
* and/or other contributors as indicated by the @authors tag. See the
4+
* copyright.txt file in the distribution for a full listing of all
5+
* contributors.
6+
*
7+
* Licensed under the Apache License, Version 2.0 (the "License");
8+
* you may not use this file except in compliance with the License.
9+
* You may obtain a copy of the License at
10+
*
11+
* http://www.apache.org/licenses/LICENSE-2.0
12+
*
13+
* Unless required by applicable law or agreed to in writing, software
14+
* distributed under the License is distributed on an "AS IS" BASIS,
15+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
* See the License for the specific language governing permissions and
17+
* limitations under the License.
18+
*/
19+
package org.mapstruct;
20+
21+
import java.lang.annotation.Retention;
22+
import java.lang.annotation.RetentionPolicy;
23+
import java.lang.annotation.Target;
24+
25+
import org.mapstruct.util.Experimental;
26+
27+
/**
28+
* Configuration of builders, e.g. the name of the final build method.
29+
*
30+
* @author Filip Hrisafov
31+
*
32+
* @since 1.3
33+
*/
34+
@Retention(RetentionPolicy.CLASS)
35+
@Target({})
36+
@Experimental
37+
public @interface Builder {
38+
39+
/**
40+
* The name of the build method that needs to be invoked on the builder to create the type being build
41+
*
42+
* @return the method that needs to tbe invoked on the builder
43+
*/
44+
String buildMethod() default "build";
45+
}

‎core-common/src/main/java/org/mapstruct/Mapper.java‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,15 +18,15 @@
1818
*/
1919
package org.mapstruct;
2020

21-
import static org.mapstruct.NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
22-
2321
import java.lang.annotation.ElementType;
2422
import java.lang.annotation.Retention;
2523
import java.lang.annotation.RetentionPolicy;
2624
import java.lang.annotation.Target;
2725

2826
import org.mapstruct.factory.Mappers;
2927

28+
import static org.mapstruct.NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
29+
3030
/**
3131
* Marks an interface or abstract class as a mapper and activates the generation of a implementation of that type via
3232
* MapStruct.
@@ -200,4 +200,22 @@
200200
*/
201201
boolean disableSubMappingMethodsGeneration() default false;
202202

203+
/**
204+
* The information that should be used for the builder mappings. This can be used to define custom build methods
205+
* for the builder strategy that one uses.
206+
*
207+
* If no builder is defined the builder given via {@link MapperConfig#builder()} will be applied.
208+
*
209+
* <p>
210+
* NOTE: In case no builder is defined here, in {@link BeanMapping} or {@link MapperConfig} and there is a single
211+
* build method, then that method would be used.
212+
* <p>
213+
* If the builder is defined and there is a single method that does not match the name of the finisher than
214+
* a compile error will occurs
215+
*
216+
* @return the builder information
217+
*
218+
* @since 1.3
219+
*/
220+
Builder builder() default @Builder;
203221
}

‎core-common/src/main/java/org/mapstruct/MapperConfig.java‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,15 +18,15 @@
1818
*/
1919
package org.mapstruct;
2020

21-
import static org.mapstruct.NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
22-
2321
import java.lang.annotation.ElementType;
2422
import java.lang.annotation.Retention;
2523
import java.lang.annotation.RetentionPolicy;
2624
import java.lang.annotation.Target;
2725

2826
import org.mapstruct.factory.Mappers;
2927

28+
import static org.mapstruct.NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
29+
3030
/**
3131
* Marks a class or interface as configuration source for generated mappers. This allows to share common configurations
3232
* between several mapper classes.
@@ -186,4 +186,24 @@ MappingInheritanceStrategy mappingInheritanceStrategy()
186186
* @since 1.2
187187
*/
188188
boolean disableSubMappingMethodsGeneration() default false;
189+
190+
/**
191+
* The information that should be used for the builder mappings. This can be used to define custom build methods
192+
* for the builder strategy that one uses.
193+
*
194+
* <p>
195+
* Can be overridden by {@link MapperConfig#builder()}.
196+
*
197+
* <p>
198+
* NOTE: In case no builder is defined here, in {@link BeanMapping} or {@link Mapper} and there is a single
199+
* build method, then that method would be used.
200+
* <p>
201+
* If the builder is defined and there is a single method that does not match the name of the finisher than
202+
* a compile error will occurs
203+
*
204+
* @return the builder information
205+
*
206+
* @since 1.3
207+
*/
208+
Builder builder() default @Builder;
189209
}

‎documentation/src/main/asciidoc/mapstruct-reference-guide.asciidoc‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -639,6 +639,12 @@ The default implementation of the `BuilderProvider` assumes the following:
639639
So for example `Person` has a public static method that returns `PersonBuilder`.
640640
* The builder type has a parameterless public method (build method) that returns the type being build
641641
In our example `PersonBuilder` has a method returning `Person`.
642+
* In case there are multiple build methods, MapStruct will look for a method called `build` if such methods exists
643+
than this would be used, otherwise a compilation error would be created.
644+
* A specific build method can be defined by using `@Builder` within: `@BeanMapping`, `@Mapper` or `@MapperConfig`
645+
* In case there are multiple builder creation methods that satisfy the above conditions then a `MoreThanOneBuilderCreationMethodException`
646+
will be thrown from the `DefaultBuilderProvider` SPI.
647+
In case of a `MoreThanOneBuilderCreationMethodException` MapStruct will write a warning in the compilation and not use any builder.
642648

643649
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).
644650
To finish the mapping MapStruct generates code that will invoke the build method of the builder.

‎processor/src/main/java/org/mapstruct/ap/internal/model/BeanMappingMethod.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -287,7 +287,7 @@ private MethodReference getFinalizerMethod(Type resultType) {
287287
return null;
288288
}
289289

290-
return MethodReference.forMethodCall( builderType.getBuildMethod() );
290+
return BuilderFinisherMethodResolver.getBuilderFinisherMethod( method, builderType, ctx );
291291
}
292292

293293
/**

‎processor/src/main/java/org/mapstruct/ap/internal/model/BuilderFinisherMethodResolver.java‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
/**
2+
* Copyright 2012-2017 Gunnar Morling (http://www.gunnarmorling.de/)
3+
* and/or other contributors as indicated by the @authors tag. See the
4+
* copyright.txt file in the distribution for a full listing of all
5+
* contributors.
6+
*
7+
* Licensed under the Apache License, Version 2.0 (the "License");
8+
* you may not use this file except in compliance with the License.
9+
* You may obtain a copy of the License at
10+
*
11+
* http://www.apache.org/licenses/LICENSE-2.0
12+
*
13+
* Unless required by applicable law or agreed to in writing, software
14+
* distributed under the License is distributed on an "AS IS" BASIS,
15+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
* See the License for the specific language governing permissions and
17+
* limitations under the License.
18+
*/
19+
package org.mapstruct.ap.internal.model;
20+
21+
import java.util.Collection;
22+
import javax.lang.model.element.ExecutableElement;
23+
24+
import org.mapstruct.ap.internal.model.common.BuilderType;
25+
import org.mapstruct.ap.internal.model.source.BeanMapping;
26+
import org.mapstruct.ap.internal.model.source.Method;
27+
import org.mapstruct.ap.internal.prism.BuilderPrism;
28+
import org.mapstruct.ap.internal.util.MapperConfiguration;
29+
import org.mapstruct.ap.internal.util.Message;
30+
import org.mapstruct.ap.internal.util.Strings;
31+
32+
import static org.mapstruct.ap.internal.util.Collections.first;
33+
34+
/**
35+
* @author Filip Hrisafov
36+
*/
37+
public class BuilderFinisherMethodResolver {
38+
39+
private static final String DEFAULT_BUILD_METHOD_NAME = "build";
40+
41+
private BuilderFinisherMethodResolver() {
42+
}
43+
44+
public static MethodReference getBuilderFinisherMethod(Method method, BuilderType builderType,
45+
MappingBuilderContext ctx) {
46+
Collection<ExecutableElement> buildMethods = builderType.getBuildMethods();
47+
if ( buildMethods.isEmpty() ) {
48+
//If we reach this method this should never happen
49+
return null;
50+
}
51+
52+
BuilderPrism builderMapping = builderMappingPrism( method, ctx );
53+
if ( builderMapping == null && buildMethods.size() == 1 ) {
54+
return MethodReference.forMethodCall( first( buildMethods ).getSimpleName().toString() );
55+
}
56+
else {
57+
String buildMethodPattern = DEFAULT_BUILD_METHOD_NAME;
58+
if ( builderMapping != null ) {
59+
buildMethodPattern = builderMapping.buildMethod();
60+
}
61+
for ( ExecutableElement buildMethod : buildMethods ) {
62+
String methodName = buildMethod.getSimpleName().toString();
63+
if ( methodName.matches( buildMethodPattern ) ) {
64+
return MethodReference.forMethodCall( methodName );
65+
}
66+
}
67+
68+
if ( builderMapping == null ) {
69+
ctx.getMessager().printMessage(
70+
method.getExecutable(),
71+
Message.BUILDER_NO_BUILD_METHOD_FOUND_DEFAULT,
72+
buildMethodPattern,
73+
builderType.getBuilder(),
74+
builderType.getBuildingType(),
75+
Strings.join( buildMethods, ", " )
76+
);
77+
}
78+
else {
79+
ctx.getMessager().printMessage(
80+
method.getExecutable(),
81+
builderMapping.mirror,
82+
Message.BUILDER_NO_BUILD_METHOD_FOUND,
83+
buildMethodPattern,
84+
builderType.getBuilder(),
85+
builderType.getBuildingType(),
86+
Strings.join( buildMethods, ", " )
87+
);
88+
}
89+
}
90+
91+
return null;
92+
}
93+
94+
private static BuilderPrism builderMappingPrism(Method method, MappingBuilderContext ctx) {
95+
BeanMapping beanMapping = method.getMappingOptions().getBeanMapping();
96+
if ( beanMapping != null && beanMapping.getBuilder() != null ) {
97+
return beanMapping.getBuilder();
98+
}
99+
return MapperConfiguration.getInstanceOn( ctx.getMapperTypeElement() ).getBuilderPrism();
100+
}
101+
}

‎processor/src/main/java/org/mapstruct/ap/internal/model/common/BuilderType.java‎

Lines changed: 10 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
*/
1919
package org.mapstruct.ap.internal.model.common;
2020

21+
import java.util.Collection;
2122
import javax.lang.model.element.ExecutableElement;
2223
import javax.lang.model.type.TypeMirror;
2324
import javax.lang.model.util.Types;
@@ -33,20 +34,20 @@ public class BuilderType {
3334
private final Type owningType;
3435
private final Type buildingType;
3536
private final ExecutableElement builderCreationMethod;
36-
private final ExecutableElement buildMethod;
37+
private final Collection<ExecutableElement> buildMethods;
3738

3839
private BuilderType(
3940
Type builder,
4041
Type owningType,
4142
Type buildingType,
4243
ExecutableElement builderCreationMethod,
43-
ExecutableElement buildMethod
44+
Collection<ExecutableElement> buildMethods
4445
) {
4546
this.builder = builder;
4647
this.owningType = owningType;
4748
this.buildingType = buildingType;
4849
this.builderCreationMethod = builderCreationMethod;
49-
this.buildMethod = buildMethod;
50+
this.buildMethods = buildMethods;
5051
}
5152

5253
/**
@@ -87,18 +88,17 @@ public ExecutableElement getBuilderCreationMethod() {
8788
}
8889

8990
/**
90-
* The name of the method that needs to be invoked on the builder to create the type being built.
91-
*
92-
* @return the name of the method that needs to be invoked on the type that is being built
91+
* The build methods that can be invoked to create the type being built.
92+
* @return the build methods that can be invoked to create the type being built
9393
*/
94-
public String getBuildMethod() {
95-
return buildMethod.getSimpleName().toString();
94+
public Collection<ExecutableElement> getBuildMethods() {
95+
return buildMethods;
9696
}
9797

9898
public BuilderInfo asBuilderInfo() {
9999
return new BuilderInfo.Builder()
100100
.builderCreationMethod( this.builderCreationMethod )
101-
.buildMethod( this.buildMethod )
101+
.buildMethod( this.buildMethods )
102102
.build();
103103
}
104104

@@ -107,11 +107,6 @@ public static BuilderType create(BuilderInfo builderInfo, Type typeToBuild, Type
107107
if ( builderInfo == null ) {
108108
return null;
109109
}
110-
ExecutableElement buildMethod = builderInfo.getBuildMethod();
111-
if ( !typeUtils.isAssignable( buildMethod.getReturnType(), typeToBuild.getTypeMirror() ) ) {
112-
//TODO throw error
113-
throw new IllegalArgumentException( "Build return type is not assignable" );
114-
}
115110

116111
Type builder = typeFactory.getType( builderInfo.getBuilderCreationMethod().getReturnType() );
117112
ExecutableElement builderCreationMethod = builderInfo.getBuilderCreationMethod();
@@ -133,7 +128,7 @@ else if ( typeUtils.isSameType( builder.getTypeMirror(), builderCreationOwner )
133128
owner,
134129
typeToBuild,
135130
builderCreationMethod,
136-
buildMethod
131+
builderInfo.getBuildMethods()
137132
);
138133
}
139134
}

0 commit comments

Comments
 (0)