#1532 using fields and constructor fragments optimizing DataTypeFactory usage

processor/src/main/java/org/mapstruct/ap/internal/model/AbstractMappingMethodBuilder.java

@@ -37,7 +37,7 @@ public abstract class AbstractMappingMethodBuilder<B extends AbstractMappingMeth
         }
 
         String name = getName( sourceType, targetType );
-        name = Strings.getSaveVariableName( name, ctx.getNamesOfMappingsToGenerate() );
+        name = Strings.getSafeVariableName( name, ctx.getNamesOfMappingsToGenerate() );
         ForgedMethodHistory history = null;
         if ( method instanceof ForgedMethod ) {
             history = ( (ForgedMethod) method ).getHistory();

processor/src/main/java/org/mapstruct/ap/internal/model/AnnotatedConstructor.java

@@ -5,6 +5,7 @@
  */
 package org.mapstruct.ap.internal.model;
 
+import java.util.Collections;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
@@ -19,17 +20,52 @@ import org.mapstruct.ap.internal.model.common.Type;
  */
 public class AnnotatedConstructor extends ModelElement implements Constructor {
 
-    private final String name;
+    private String name;
     private final List<AnnotationMapperReference> mapperReferences;
     private final List<Annotation> annotations;
-    private final boolean publicEmptyConstructor;
+    private final NoArgumentConstructor noArgumentConstructor;
+    private final Set<SupportingConstructorFragment> fragments;
 
-    public AnnotatedConstructor(String name, List<AnnotationMapperReference> mapperReferences,
+    public static AnnotatedConstructor forComponentModels(String name,
-                                List<Annotation> annotations, boolean publicEmptyConstructor) {
+                                                          List<AnnotationMapperReference> mapperReferences,
+                                                          List<Annotation> annotations,
+                                                          Constructor constructor,
+                                                          boolean includeNoArgConstructor) {
+
+        NoArgumentConstructor noArgumentConstructor = null;
+        if ( constructor instanceof NoArgumentConstructor ) {
+            noArgumentConstructor = (NoArgumentConstructor) constructor;
+        }
+        NoArgumentConstructor noArgConstructorToInBecluded = null;
+        Set<SupportingConstructorFragment> fragmentsToBeIncluded = Collections.emptySet();
+        if ( includeNoArgConstructor ) {
+            if ( noArgumentConstructor != null ) {
+                noArgConstructorToInBecluded = noArgumentConstructor;
+            }
+            else {
+                noArgConstructorToInBecluded = new NoArgumentConstructor( name, fragmentsToBeIncluded );
+            }
+        }
+        else if ( noArgumentConstructor != null ) {
+            fragmentsToBeIncluded = noArgumentConstructor.getFragments();
+        }
+        return new AnnotatedConstructor(
+            name,
+            mapperReferences,
+            annotations,
+            noArgConstructorToInBecluded,
+            fragmentsToBeIncluded
+        );
+    }
+
+    private AnnotatedConstructor(String name, List<AnnotationMapperReference> mapperReferences,
+                                 List<Annotation> annotations, NoArgumentConstructor noArgumentConstructor,
+                                 Set<SupportingConstructorFragment> fragments) {
         this.name = name;
         this.mapperReferences = mapperReferences;
         this.annotations = annotations;
-        this.publicEmptyConstructor = publicEmptyConstructor;
+        this.noArgumentConstructor = noArgumentConstructor;
+        this.fragments = fragments;
     }
 
     @Override
@@ -60,7 +96,11 @@ public class AnnotatedConstructor extends ModelElement implements Constructor {
         return annotations;
     }
 
-    public boolean isPublicEmptyConstructor() {
+    public NoArgumentConstructor getNoArgumentConstructor() {
-        return publicEmptyConstructor;
+        return noArgumentConstructor;
+    }
+
+    public Set<SupportingConstructorFragment> getFragments() {
+        return fragments;
     }
 }

processor/src/main/java/org/mapstruct/ap/internal/model/ContainerMappingMethod.java

@@ -41,8 +41,8 @@ public abstract class ContainerMappingMethod extends NormalTypeMappingMethod {
         this.elementAssignment = parameterAssignment;
         this.loopVariableName = loopVariableName;
         this.selectionParameters = selectionParameters;
-        this.index1Name = Strings.getSaveVariableName( "i", existingVariables );
+        this.index1Name = Strings.getSafeVariableName( "i", existingVariables );
-        this.index2Name = Strings.getSaveVariableName( "j", existingVariables );
+        this.index2Name = Strings.getSafeVariableName( "j", existingVariables );
     }
 
     public Parameter getSourceParameter() {

processor/src/main/java/org/mapstruct/ap/internal/model/ContainerMappingMethodBuilder.java

@@ -73,7 +73,7 @@ public abstract class ContainerMappingMethodBuilder<B extends ContainerMappingMe
         Type targetElementType = getElementType( resultType );
 
         String loopVariableName =
-            Strings.getSaveVariableName( sourceElementType.getName(), method.getParameterNames() );
+            Strings.getSafeVariableName( sourceElementType.getName(), method.getParameterNames() );
 
         SourceRHS sourceRHS = new SourceRHS(
             loopVariableName,

processor/src/main/java/org/mapstruct/ap/internal/model/Decorator.java

@@ -133,7 +133,7 @@ public class Decorator extends GeneratedType {
     @SuppressWarnings( "checkstyle:parameternumber" )
     private Decorator(TypeFactory typeFactory, String packageName, String name, Type decoratorType,
                       String interfacePackage, String interfaceName, List<MappingMethod> methods,
-                      List<? extends Field> fields, Options options, VersionInformation versionInformation,
+                      List<Field> fields, Options options, VersionInformation versionInformation,
                       Accessibility accessibility, SortedSet<Type> extraImports,
                       DecoratorConstructor decoratorConstructor) {
         super(

processor/src/main/java/org/mapstruct/ap/internal/model/DefaultMapperReference.java

@@ -37,7 +37,7 @@ public class DefaultMapperReference extends MapperReference {
             importTypes.add( typeFactory.getType( "org.mapstruct.factory.Mappers" ) );
         }
 
-        String variableName = Strings.getSaveVariableName(
+        String variableName = Strings.getSafeVariableName(
             type.getName(),
             otherMapperReferences
         );

processor/src/main/java/org/mapstruct/ap/internal/model/Field.java

@@ -5,7 +5,9 @@
  */
 package org.mapstruct.ap.internal.model;
 
+import java.util.ArrayList;
 import java.util.Collections;
+import java.util.List;
 import java.util.Set;
 
 import org.mapstruct.ap.internal.model.common.ModelElement;
@@ -115,4 +117,12 @@ public class Field extends ModelElement {
             (other.variableName != null) : !this.variableName.equals( other.variableName ) );
     }
 
+    public static List<String> getFieldNames(Set<Field> fields) {
+        List<String> names = new ArrayList<String>( fields.size() );
+        for ( Field field : fields ) {
+            names.add( field.getVariableName() );
+        }
+        return names;
+    }
+
 }

processor/src/main/java/org/mapstruct/ap/internal/model/GeneratedType.java

@@ -44,7 +44,7 @@ public abstract class GeneratedType extends ModelElement {
     private final boolean suppressGeneratorVersionComment;
     private final VersionInformation versionInformation;
     private final Accessibility accessibility;
-    private List<? extends Field> fields;
+    private List<Field> fields;
     private Constructor constructor;
 
     /**
@@ -56,7 +56,7 @@ public abstract class GeneratedType extends ModelElement {
     // CHECKSTYLE:OFF
     protected GeneratedType(TypeFactory typeFactory, String packageName, String name, String superClassName,
                             String interfacePackage, String interfaceName, List<MappingMethod> methods,
-                            List<? extends Field> fields, Options options, VersionInformation versionInformation,
+                            List<Field> fields, Options options, VersionInformation versionInformation,
                             Accessibility accessibility, SortedSet<Type> extraImportedTypes, Constructor constructor) {
         this.packageName = packageName;
         this.name = name;
@@ -123,11 +123,11 @@ public abstract class GeneratedType extends ModelElement {
         return methods;
     }
 
-    public List<? extends Field> getFields() {
+    public List<Field> getFields() {
         return fields;
     }
 
-    public void setFields(List<? extends Field> fields) {
+    public void setFields(List<Field> fields) {
         this.fields = fields;
     }
 

processor/src/main/java/org/mapstruct/ap/internal/model/LifecycleCallbackMethodReference.java

@@ -42,7 +42,7 @@ public class LifecycleCallbackMethodReference extends MethodReference {
         this.methodResultType = containingMethod.getResultType();
 
         if ( hasReturnType() ) {
-            this.targetVariableName = Strings.getSaveVariableName( "target", existingVariableNames );
+            this.targetVariableName = Strings.getSafeVariableName( "target", existingVariableNames );
             existingVariableNames.add( this.targetVariableName );
         }
         else {

processor/src/main/java/org/mapstruct/ap/internal/model/MapMappingMethod.java

@@ -266,21 +266,21 @@ public class MapMappingMethod extends NormalTypeMappingMethod {
     }
 
     public String getKeyVariableName() {
-        return Strings.getSaveVariableName(
+        return Strings.getSafeVariableName(
             "key",
             getParameterNames()
         );
     }
 
     public String getValueVariableName() {
-        return Strings.getSaveVariableName(
+        return Strings.getSafeVariableName(
             "value",
             getParameterNames()
         );
     }
 
     public String getEntryVariableName() {
-        return Strings.getSaveVariableName(
+        return Strings.getSafeVariableName(
             "entry",
             getParameterNames()
         );

processor/src/main/java/org/mapstruct/ap/internal/model/Mapper.java

@@ -6,6 +6,7 @@
 package org.mapstruct.ap.internal.model;
 
 import java.util.List;
+import java.util.Set;
 import java.util.SortedSet;
 
 import javax.lang.model.element.Element;
@@ -34,15 +35,14 @@ public class Mapper extends GeneratedType {
 
     private final boolean customPackage;
     private final boolean customImplName;
-    private final List<MapperReference> referencedMappers;
     private Decorator decorator;
 
     @SuppressWarnings( "checkstyle:parameternumber" )
     private Mapper(TypeFactory typeFactory, String packageName, String name, String superClassName,
                    String interfacePackage, String interfaceName, boolean customPackage, boolean customImplName,
                    List<MappingMethod> methods, Options options, VersionInformation versionInformation,
-                   Accessibility accessibility, List<MapperReference> referencedMappers, Decorator decorator,
+                   Accessibility accessibility, List<Field> fields, Constructor constructor,
-                   SortedSet<Type> extraImportedTypes) {
+                   Decorator decorator, SortedSet<Type> extraImportedTypes ) {
 
         super(
             typeFactory,
@@ -52,17 +52,16 @@ public class Mapper extends GeneratedType {
             interfacePackage,
             interfaceName,
             methods,
-            referencedMappers,
+            fields,
             options,
             versionInformation,
             accessibility,
             extraImportedTypes,
-            null
+            constructor
         );
         this.customPackage = customPackage;
         this.customImplName = customImplName;
 
-        this.referencedMappers = referencedMappers;
         this.decorator = decorator;
     }
 
@@ -71,7 +70,8 @@ public class Mapper extends GeneratedType {
         private TypeFactory typeFactory;
         private TypeElement element;
         private List<MappingMethod> mappingMethods;
-        private List<MapperReference> mapperReferences;
+        private List<Field> fields;
+        private Set<SupportingConstructorFragment> fragments;
         private SortedSet<Type> extraImportedTypes;
 
         private Elements elementUtils;
@@ -93,8 +93,13 @@ public class Mapper extends GeneratedType {
             return this;
         }
 
-        public Builder mapperReferences(List<MapperReference> mapperReferences) {
+        public Builder fields(List<Field> fields) {
-            this.mapperReferences = mapperReferences;
+            this.fields = fields;
+            return this;
+        }
+
+        public Builder constructorFragments(Set<SupportingConstructorFragment>  fragments) {
+            this.fragments = fragments;
             return this;
         }
 
@@ -146,7 +151,10 @@ public class Mapper extends GeneratedType {
 
             String elementPackage = elementUtils.getPackageOf( element ).getQualifiedName().toString();
             String packageName = implPackage.replace( PACKAGE_NAME_PLACEHOLDER, elementPackage );
-
+            Constructor constructor = null;
+            if ( !fragments.isEmpty() ) {
+                constructor = new NoArgumentConstructor( implementationName, fragments );
+            }
             return new Mapper(
                 typeFactory,
                 packageName,
@@ -160,15 +168,13 @@ public class Mapper extends GeneratedType {
                 options,
                 versionInformation,
                 Accessibility.fromModifiers( element.getModifiers() ),
-                mapperReferences,
+                fields,
+                constructor,
                 decorator,
                 extraImportedTypes
             );
         }
-    }
 
-    public List<MapperReference> getReferencedMappers() {
-        return referencedMappers;
     }
 
     public Decorator getDecorator() {

processor/src/main/java/org/mapstruct/ap/internal/model/MappingBuilderContext.java

@@ -37,7 +37,7 @@ import org.mapstruct.ap.spi.MappingExclusionProvider;
  * <ul>
  * <li>Input for the building process, such as the source model (mapping methods found) and mapper references.</li>
  * <li>Required factory, utility, reporting methods for building the mappings.</li>
- * <li>Means to harbor results produced by the builders, such as forged- and virtual mapping methods that should be
+ * <li>Means to harbor results produced by the builders, such as forged- and supported mapping methods that should be
  * generated in a later stage.</li>
  * </ul>
  *
@@ -94,7 +94,7 @@ public class MappingBuilderContext {
                                        SelectionParameters selectionParameters, SourceRHS sourceRHS,
                                        boolean preferUpdateMethods);
 
-        Set<VirtualMappingMethod> getUsedVirtualMappings();
+        Set<SupportingMappingMethod> getUsedSupportedMappings();
     }
 
     private final TypeFactory typeFactory;
@@ -209,8 +209,8 @@ public class MappingBuilderContext {
         return existingMappingMethod;
     }
 
-    public Set<VirtualMappingMethod> getUsedVirtualMappings() {
+    public Set<SupportingMappingMethod> getUsedSupportedMappings() {
-        return mappingResolver.getUsedVirtualMappings();
+        return mappingResolver.getUsedSupportedMappings();
     }
 
     /**

processor/src/main/java/org/mapstruct/ap/internal/model/MappingMethod.java

@@ -5,7 +5,7 @@
  */
 package org.mapstruct.ap.internal.model;
 
-import static org.mapstruct.ap.internal.util.Strings.getSaveVariableName;
+import static org.mapstruct.ap.internal.util.Strings.getSafeVariableName;
 import static org.mapstruct.ap.internal.util.Strings.join;
 
 import java.util.ArrayList;
@@ -91,12 +91,12 @@ public abstract class MappingMethod extends ModelElement {
             return targetParameter.getName();
         }
         else if ( getResultType().isArrayType() ) {
-            String name = getSaveVariableName( getResultType().getComponentType().getName() + "Tmp", existingVarNames );
+            String name = getSafeVariableName( getResultType().getComponentType().getName() + "Tmp", existingVarNames );
             existingVarNames.add( name );
             return name;
         }
         else {
-            String name = getSaveVariableName( getResultType().getName(), existingVarNames );
+            String name = getSafeVariableName( getResultType().getName(), existingVarNames );
             existingVarNames.add( name );
             return name;
         }

processor/src/main/java/org/mapstruct/ap/internal/model/NestedPropertyMappingMethod.java

@@ -58,7 +58,7 @@ public class NestedPropertyMappingMethod extends MappingMethod {
             final List<Type> thrownTypes = new ArrayList<Type>();
             List<SafePropertyEntry> safePropertyEntries = new ArrayList<SafePropertyEntry>();
             for ( PropertyEntry propertyEntry : propertyEntries ) {
-                String safeName = Strings.getSaveVariableName( propertyEntry.getName(), existingVariableNames );
+                String safeName = Strings.getSafeVariableName( propertyEntry.getName(), existingVariableNames );
                 safePropertyEntries.add( new SafePropertyEntry( propertyEntry, safeName ) );
                 existingVariableNames.add( safeName );
                 thrownTypes.addAll( ctx.getTypeFactory().getThrownTypes(

processor/src/main/java/org/mapstruct/ap/internal/model/NoArgumentConstructor.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.ap.internal.model;
+
+import java.util.Collections;
+import java.util.Set;
+
+import org.mapstruct.ap.internal.model.common.ModelElement;
+import org.mapstruct.ap.internal.model.common.Type;
+
+/**
+ * Represents a constructor that is used for constructor injection.
+ *
+ * @author Sjaak Derksen
+ */
+public class NoArgumentConstructor extends ModelElement implements Constructor {
+
+    private final String name;
+    private final Set<SupportingConstructorFragment> fragments;
+
+    public NoArgumentConstructor(String name, Set<SupportingConstructorFragment> fragments) {
+        this.name = name;
+        this.fragments = fragments;
+    }
+
+    @Override
+    public Set<Type> getImportTypes() {
+        return Collections.emptySet();
+    }
+
+    @Override
+    public String getName() {
+        return name;
+    }
+
+    public Set<SupportingConstructorFragment> getFragments() {
+        return fragments;
+    }
+}

processor/src/main/java/org/mapstruct/ap/internal/model/PropertyMapping.java

@@ -511,7 +511,7 @@ public class PropertyMapping extends ModelElement {
 
                 // forge a method from the parameter type to the last entry type.
                 String forgedName = Strings.joinAndCamelize( sourceReference.getElementNames() );
-                forgedName = Strings.getSaveVariableName( forgedName, ctx.getNamesOfMappingsToGenerate() );
+                forgedName = Strings.getSafeVariableName( forgedName, ctx.getNamesOfMappingsToGenerate() );
                 ForgedMethod methodRef = new ForgedMethod(
                     forgedName,
                     sourceReference.getParameter().getType(),
@@ -601,7 +601,7 @@ public class PropertyMapping extends ModelElement {
         private ForgedMethod prepareForgedMethod(Type sourceType, Type targetType, SourceRHS source,
                                                  ExecutableElement element, String suffix) {
             String name = getName( sourceType, targetType );
-            name = Strings.getSaveVariableName( name, ctx.getNamesOfMappingsToGenerate() );
+            name = Strings.getSafeVariableName( name, ctx.getNamesOfMappingsToGenerate() );
 
             // copy mapper configuration from the source method, its the same mapper
             MapperConfiguration config = method.getMapperConfiguration();
@@ -647,7 +647,7 @@ public class PropertyMapping extends ModelElement {
             }
 
             String name = getName( sourceType, targetType );
-            name = Strings.getSaveVariableName( name, ctx.getNamesOfMappingsToGenerate() );
+            name = Strings.getSafeVariableName( name, ctx.getNamesOfMappingsToGenerate() );
 
             List<Parameter> parameters = new ArrayList<Parameter>( method.getContextParameters() );
             Type returnType;

processor/src/main/java/org/mapstruct/ap/internal/model/SupportingConstructorFragment.java

@@ -0,0 +1,85 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.ap.internal.model;
+
+import java.util.Collections;
+import java.util.Set;
+
+import org.mapstruct.ap.internal.model.common.ModelElement;
+import org.mapstruct.ap.internal.model.common.Type;
+import org.mapstruct.ap.internal.model.source.builtin.BuiltInConstructorFragment;
+
+/**
+ * A mapper instance field, initialized as null
+ *
+ * @author Sjaak Derksen
+ */
+public class SupportingConstructorFragment extends ModelElement {
+
+    private final String templateName;
+    private final SupportingMappingMethod definingMethod;
+
+    public SupportingConstructorFragment(SupportingMappingMethod definingMethod,
+                                         BuiltInConstructorFragment constructorFragment) {
+        this.templateName = getTemplateNameForClass( constructorFragment.getClass() );
+        this.definingMethod = definingMethod;
+    }
+
+    @Override
+    public String getTemplateName() {
+        return templateName;
+    }
+
+    @Override
+    public Set<Type> getImportTypes() {
+        return Collections.emptySet();
+    }
+
+    public SupportingMappingMethod getDefiningMethod() {
+        return definingMethod;
+    }
+
+    @Override
+    public int hashCode() {
+        final int prime = 31;
+        int result = 1;
+        result = prime * result + ( ( templateName == null ) ? 0 : templateName.hashCode() );
+        return result;
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if ( this == obj ) {
+            return true;
+        }
+        if ( obj == null ) {
+            return false;
+        }
+        if ( getClass() != obj.getClass() ) {
+            return false;
+        }
+        SupportingConstructorFragment other = (SupportingConstructorFragment) obj;
+        if ( templateName == null ) {
+            if ( other.templateName != null ) {
+                return false;
+            }
+        }
+        else if ( !templateName.equals( other.templateName ) ) {
+            return false;
+        }
+        return true;
+    }
+
+    public static void addAllFragmentsIn(Set<SupportingMappingMethod> supportingMappingMethods,
+                                         Set<SupportingConstructorFragment> targets) {
+        for ( SupportingMappingMethod supportingMappingMethod : supportingMappingMethods ) {
+            SupportingConstructorFragment fragment = supportingMappingMethod.getSupportingConstructorFragment();
+            if ( fragment != null ) {
+                targets.add( supportingMappingMethod.getSupportingConstructorFragment() );
+            }
+        }
+    }
+}

processor/src/main/java/org/mapstruct/ap/internal/model/SupportingField.java

@@ -0,0 +1,76 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.ap.internal.model;
+
+import java.util.Set;
+
+import org.mapstruct.ap.internal.model.source.builtin.BuiltInFieldReference;
+
+/**
+ * supports the
+ *
+ * @author Sjaak Derksen
+ */
+public class SupportingField extends Field {
+
+    private final String templateName;
+    private final SupportingMappingMethod definingMethod;
+
+    public SupportingField(SupportingMappingMethod definingMethod, BuiltInFieldReference fieldReference, String name) {
+        super( fieldReference.getType(), name, true );
+        this.templateName = getTemplateNameForClass( fieldReference.getClass() );
+        this.definingMethod = definingMethod;
+    }
+
+    @Override
+    public String getTemplateName() {
+        return templateName;
+    }
+
+    public SupportingMappingMethod getDefiningMethod() {
+        return definingMethod;
+    }
+
+    @Override
+    public int hashCode() {
+        final int prime = 31;
+        int result = 1;
+        result = prime * result + ( ( templateName == null ) ? 0 : templateName.hashCode() );
+        return result;
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if ( this == obj ) {
+            return true;
+        }
+        if ( obj == null ) {
+            return false;
+        }
+        if ( getClass() != obj.getClass() ) {
+            return false;
+        }
+        SupportingField other = (SupportingField) obj;
+        if ( templateName == null ) {
+            if ( other.templateName != null ) {
+                return false;
+            }
+        }
+        else if ( !templateName.equals( other.templateName ) ) {
+            return false;
+        }
+        return true;
+    }
+
+    public static void addAllFieldsIn(Set<SupportingMappingMethod> supportingMappingMethods, Set<Field> targets) {
+        for ( SupportingMappingMethod supportingMappingMethod : supportingMappingMethods ) {
+            Field field = supportingMappingMethod.getSupportingField();
+            if ( field != null ) {
+                targets.add( supportingMappingMethod.getSupportingField() );
+            }
+        }
+    }
+}

processor/src/main/java/org/mapstruct/ap/internal/model/SupportingMappingMethod.java

@@ -8,29 +8,79 @@ package org.mapstruct.ap.internal.model;
 import java.util.Set;
 
 import org.mapstruct.ap.internal.model.common.Type;
+import org.mapstruct.ap.internal.model.source.builtin.BuiltInFieldReference;
 import org.mapstruct.ap.internal.model.source.builtin.BuiltInMethod;
+import org.mapstruct.ap.internal.model.source.builtin.NewDatatypeFactoryConstructorFragment;
+import org.mapstruct.ap.internal.util.Strings;
 
 /**
  * A mapping method which is not based on an actual method declared in the original mapper interface but is added as
  * private method to map a certain source/target type combination. Based on a {@link BuiltInMethod}.
  *
+ * Specific templates all point to this class, for instance:
+ * {@link org.mapstruct.ap.internal.model.source.builtin.XmlGregorianCalendarToCalendar},
+ * but also used fields and constructor elements, e.g.
+ * {@link org.mapstruct.ap.internal.model.source.builtin.FinalField} and
+ * {@link NewDatatypeFactoryConstructorFragment}
+ *
  * @author Gunnar Morling
  */
-public class VirtualMappingMethod extends MappingMethod {
+public class SupportingMappingMethod extends MappingMethod {
 
     private final String templateName;
     private final Set<Type> importTypes;
+    private final Field supportingField;
+    private final SupportingConstructorFragment supportingConstructorFragment;
 
-    public VirtualMappingMethod(BuiltInMethod method) {
+    public SupportingMappingMethod(BuiltInMethod method, Set<Field> existingFields) {
         super( method );
         this.importTypes = method.getImportTypes();
         this.templateName = getTemplateNameForClass( method.getClass() );
+        if ( method.getFieldReference() != null ) {
+            this.supportingField = getSafeField( method.getFieldReference(), existingFields );
+        }
+        else {
+            this.supportingField = null;
+        }
+        if ( method.getConstructorFragment() != null ) {
+            this.supportingConstructorFragment = new SupportingConstructorFragment(
+                this,
+                method.getConstructorFragment()
+            );
+        }
+        else {
+            this.supportingConstructorFragment = null;
+        }
     }
 
-    public VirtualMappingMethod(HelperMethod method) {
+    private Field getSafeField(BuiltInFieldReference ref, Set<Field> existingFields) {
+        Field result = null;
+        String name = ref.getVariableName();
+        for ( Field existingField : existingFields ) {
+            if ( existingField.getType().equals( ref.getType() ) ) {
+                // field type already exist, use that one
+                return existingField;
+            }
+        }
+        for ( Field existingField : existingFields ) {
+            if ( existingField.getVariableName().equals( ref.getVariableName() ) ) {
+                // field with name exist, however its a wrong type
+                name = Strings.getSafeVariableName( name, Field.getFieldNames( existingFields ) );
+            }
+        }
+        if ( result == null ) {
+            result = new SupportingField( this, ref, name );
+        }
+
+        return result;
+    }
+
+    public SupportingMappingMethod(HelperMethod method) {
         super( method );
         this.importTypes = method.getImportTypes();
         this.templateName = getTemplateNameForClass( method.getClass() );
+        this.supportingField = null;
+        this.supportingConstructorFragment = null;
     }
 
     @Override
@@ -66,6 +116,14 @@ public class VirtualMappingMethod extends MappingMethod {
         throw new IllegalArgumentException( "No type for given name '" + name + "' found in 'importTypes'." );
     }
 
+    public Field getSupportingField() {
+        return supportingField;
+    }
+
+    public SupportingConstructorFragment getSupportingConstructorFragment() {
+        return supportingConstructorFragment;
+    }
+
     @Override
     public int hashCode() {
         final int prime = 31;
@@ -85,7 +143,7 @@ public class VirtualMappingMethod extends MappingMethod {
         if ( getClass() != obj.getClass() ) {
             return false;
         }
-        VirtualMappingMethod other = (VirtualMappingMethod) obj;
+        SupportingMappingMethod other = (SupportingMappingMethod) obj;
         if ( templateName == null ) {
             if ( other.templateName != null ) {
                 return false;

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

@@ -69,7 +69,7 @@ public class SourceRHS extends ModelElement implements Assignment {
 
     @Override
     public String createLocalVarName(String desiredName) {
-        String result = Strings.getSaveVariableName( desiredName, existingVariableNames );
+        String result = Strings.getSafeVariableName( desiredName, existingVariableNames );
         existingVariableNames.add( result );
         return result;
     }

processor/src/main/java/org/mapstruct/ap/internal/model/source/ForgedMethod.java

@@ -87,7 +87,7 @@ public class ForgedMethod implements Method {
                         ParameterProvidedMethods parameterProvidedMethods, ForgedMethodHistory history,
                         MappingOptions mappingOptions, boolean forgedNameBased) {
         String sourceParamName = Strings.decapitalize( sourceType.getName() );
-        String sourceParamSafeName = Strings.getSaveVariableName( sourceParamName );
+        String sourceParamSafeName = Strings.getSafeVariableName( sourceParamName );
 
         this.parameters = new ArrayList<Parameter>( 1 + additionalParameters.size() );
         Parameter sourceParameter = new Parameter( sourceParamSafeName, sourceType );

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/AbstractToXmlGregorianCalendar.java

@@ -0,0 +1,57 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.ap.internal.model.source.builtin;
+
+import java.util.Set;
+import javax.xml.datatype.DatatypeConfigurationException;
+import javax.xml.datatype.DatatypeFactory;
+import javax.xml.datatype.XMLGregorianCalendar;
+
+import org.mapstruct.ap.internal.model.common.Type;
+import org.mapstruct.ap.internal.model.common.TypeFactory;
+import org.mapstruct.ap.internal.util.Strings;
+
+import static org.mapstruct.ap.internal.util.Collections.asSet;
+
+/**
+ * @author Sjaak Derksen
+ */
+public abstract class AbstractToXmlGregorianCalendar extends BuiltInMethod {
+
+    private final Type returnType;
+    private final Set<Type> importTypes;
+    private final Type dataTypeFactoryType;
+
+    public AbstractToXmlGregorianCalendar(TypeFactory typeFactory) {
+        this.returnType = typeFactory.getType( XMLGregorianCalendar.class );
+        this.dataTypeFactoryType = typeFactory.getType( DatatypeFactory.class );
+        this.importTypes = asSet(
+            returnType,
+            dataTypeFactoryType,
+            typeFactory.getType( DatatypeConfigurationException.class )
+        );
+    }
+
+    @Override
+    public Set<Type> getImportTypes() {
+        return importTypes;
+    }
+
+    @Override
+    public Type getReturnType() {
+        return returnType;
+    }
+
+    @Override
+    public BuiltInFieldReference getFieldReference() {
+        return new FinalField( dataTypeFactoryType, Strings.decapitalize( DatatypeFactory.class.getSimpleName() ) );
+    }
+
+    @Override
+    public BuiltInConstructorFragment getConstructorFragment() {
+        return new NewDatatypeFactoryConstructorFragment( );
+    }
+}

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/BuiltInConstructorFragment.java

@@ -0,0 +1,12 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.ap.internal.model.source.builtin;
+
+/**
+ * ConstructorFragments are 'code snippets' added to the constructor to initialize fields used by {@link BuiltInMethod}
+ */
+public interface BuiltInConstructorFragment {
+}

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/BuiltInFieldReference.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.ap.internal.model.source.builtin;
+
+import org.mapstruct.ap.internal.model.common.Type;
+
+/**
+ * reference used by BuiltInMethod to create an additional field in the mapper.
+ */
+public interface BuiltInFieldReference {
+
+    /**
+     *
+     * @return variable name of the field
+     */
+    String getVariableName();
+
+    /**
+     *
+     * @return type of the field
+     */
+    Type getType();
+
+}

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/BuiltInMethod.java

@@ -5,14 +5,11 @@
  */
 package org.mapstruct.ap.internal.model.source.builtin;
 
-import static org.mapstruct.ap.internal.util.Collections.first;
-
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collections;
 import java.util.List;
 import java.util.Set;
-
 import javax.lang.model.element.ExecutableElement;
 
 import org.mapstruct.ap.internal.conversion.SimpleConversion;
@@ -26,6 +23,8 @@ import org.mapstruct.ap.internal.model.source.ParameterProvidedMethods;
 import org.mapstruct.ap.internal.util.MapperConfiguration;
 import org.mapstruct.ap.internal.util.Strings;
 
+import static org.mapstruct.ap.internal.util.Collections.first;
+
 /**
  * Represents a "built-in" mapping method which will be added as private method to the generated mapper. Built-in
  * methods are used in cases where a {@link SimpleConversion} doesn't suffice, e.g. as several lines of source code or a
@@ -275,4 +274,13 @@ public abstract class BuiltInMethod implements Method {
     public MappingOptions getMappingOptions() {
         return MappingOptions.empty();
     }
+
+    public BuiltInFieldReference getFieldReference() {
+        return null;
+    }
+
+    public BuiltInConstructorFragment getConstructorFragment() {
+        return null;
+    }
+
 }

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/CalendarToXmlGregorianCalendar.java

@@ -5,45 +5,38 @@
  */
 package org.mapstruct.ap.internal.model.source.builtin;
 
-import static org.mapstruct.ap.internal.util.Collections.asSet;
-
 import java.util.Calendar;
 import java.util.GregorianCalendar;
 import java.util.Set;
 
-import javax.xml.datatype.DatatypeConfigurationException;
-import javax.xml.datatype.DatatypeFactory;
-import javax.xml.datatype.XMLGregorianCalendar;
-
 import org.mapstruct.ap.internal.model.common.Parameter;
 import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.common.TypeFactory;
 
+import static org.mapstruct.ap.internal.util.Collections.asSet;
+
 /**
  * @author Sjaak Derksen
  */
-public class CalendarToXmlGregorianCalendar extends BuiltInMethod {
+public class CalendarToXmlGregorianCalendar extends AbstractToXmlGregorianCalendar {
 
     private final Parameter parameter;
-    private final Type returnType;
     private final Set<Type> importTypes;
 
     public CalendarToXmlGregorianCalendar(TypeFactory typeFactory) {
+        super( typeFactory );
         this.parameter = new Parameter( "cal ", typeFactory.getType( Calendar.class ) );
-        this.returnType = typeFactory.getType( XMLGregorianCalendar.class );
-
         this.importTypes = asSet(
-            returnType,
             parameter.getType(),
-            typeFactory.getType( DatatypeFactory.class ),
+            typeFactory.getType( GregorianCalendar.class )
-            typeFactory.getType( GregorianCalendar.class ),
-            typeFactory.getType( DatatypeConfigurationException.class )
         );
     }
 
     @Override
     public Set<Type> getImportTypes() {
-        return importTypes;
+        Set<Type> result = super.getImportTypes();
+        result.addAll( this.importTypes );
+        return result;
     }
 
     @Override
@@ -51,8 +44,4 @@ public class CalendarToXmlGregorianCalendar extends BuiltInMethod {
         return parameter;
     }
 
-    @Override
-    public Type getReturnType() {
-        return returnType;
-    }
 }

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/CalendarToZonedDateTime.java

@@ -5,8 +5,6 @@
  */
 package org.mapstruct.ap.internal.model.source.builtin;
 
-import static org.mapstruct.ap.internal.util.Collections.asSet;
-
 import java.time.ZonedDateTime;
 import java.util.Calendar;
 import java.util.Set;
@@ -16,6 +14,8 @@ import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.common.TypeFactory;
 import org.mapstruct.ap.internal.util.JavaTimeConstants;
 
+import static org.mapstruct.ap.internal.util.Collections.asSet;
+
 /**
  * {@link BuiltInMethod} for mapping between {@link Calendar} and {@link ZonedDateTime}.
  * <p>

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/DateToXmlGregorianCalendar.java

@@ -5,45 +5,38 @@
  */
 package org.mapstruct.ap.internal.model.source.builtin;
 
-import static org.mapstruct.ap.internal.util.Collections.asSet;
-
 import java.util.Date;
 import java.util.GregorianCalendar;
 import java.util.Set;
 
-import javax.xml.datatype.DatatypeConfigurationException;
-import javax.xml.datatype.DatatypeFactory;
-import javax.xml.datatype.XMLGregorianCalendar;
-
 import org.mapstruct.ap.internal.model.common.Parameter;
 import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.common.TypeFactory;
 
+import static org.mapstruct.ap.internal.util.Collections.asSet;
+
 /**
  * @author Sjaak Derksen
  */
-public class DateToXmlGregorianCalendar extends BuiltInMethod {
+public class DateToXmlGregorianCalendar extends AbstractToXmlGregorianCalendar {
 
     private final Parameter parameter;
-    private final Type returnType;
     private final Set<Type> importTypes;
 
     public DateToXmlGregorianCalendar(TypeFactory typeFactory) {
+        super( typeFactory );
         this.parameter = new Parameter( "date", typeFactory.getType( Date.class ) );
-        this.returnType = typeFactory.getType( XMLGregorianCalendar.class );
-
         this.importTypes = asSet(
-            returnType,
             parameter.getType(),
-            typeFactory.getType( GregorianCalendar.class ),
+            typeFactory.getType( GregorianCalendar.class )
-            typeFactory.getType( DatatypeFactory.class ),
-            typeFactory.getType( DatatypeConfigurationException.class )
         );
     }
 
     @Override
     public Set<Type> getImportTypes() {
-        return importTypes;
+        Set<Type> result = super.getImportTypes();
+        result.addAll( this.importTypes );
+        return result;
     }
 
     @Override
@@ -51,8 +44,4 @@ public class DateToXmlGregorianCalendar extends BuiltInMethod {
         return parameter;
     }
 
-    @Override
-    public Type getReturnType() {
-        return returnType;
-    }
 }

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/FinalField.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.ap.internal.model.source.builtin;
+
+import org.mapstruct.ap.internal.model.common.Type;
+
+/**
+ * A mapper instance field, initialized as null
+ *
+ * @author Sjaak Derksen
+ */
+public class FinalField implements BuiltInFieldReference {
+
+    private final Type type;
+    private String variableName;
+
+    public FinalField(Type type, String variableName) {
+        this.type = type;
+        this.variableName = variableName;
+    }
+
+    @Override
+    public String getVariableName() {
+        return variableName;
+    }
+
+    @Override
+    public Type getType() {
+        return type;
+    }
+
+}

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/JaxbElemToValue.java

@@ -5,16 +5,15 @@
  */
 package org.mapstruct.ap.internal.model.source.builtin;
 
-import static org.mapstruct.ap.internal.util.Collections.asSet;
-
 import java.util.Set;
-
 import javax.xml.bind.JAXBElement;
 
 import org.mapstruct.ap.internal.model.common.Parameter;
 import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.common.TypeFactory;
 
+import static org.mapstruct.ap.internal.util.Collections.asSet;
+
 /**
  * @author Sjaak Derksen
  */

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/JodaDateTimeToXmlGregorianCalendar.java

@@ -5,14 +5,8 @@
  */
 package org.mapstruct.ap.internal.model.source.builtin;
 
-import static org.mapstruct.ap.internal.util.Collections.asSet;
-
 import java.util.Set;
 
-import javax.xml.datatype.DatatypeConfigurationException;
-import javax.xml.datatype.DatatypeFactory;
-import javax.xml.datatype.XMLGregorianCalendar;
-
 import org.mapstruct.ap.internal.model.common.Parameter;
 import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.common.TypeFactory;
@@ -21,30 +15,20 @@ import org.mapstruct.ap.internal.util.JodaTimeConstants;
 /**
  * @author Sjaak Derksen
  */
-public class JodaDateTimeToXmlGregorianCalendar extends BuiltInMethod {
+public class JodaDateTimeToXmlGregorianCalendar extends AbstractToXmlGregorianCalendar {
 
     private final Parameter parameter;
-    private final Type returnType;
-    private final Set<Type> importTypes;
 
     public JodaDateTimeToXmlGregorianCalendar(TypeFactory typeFactory) {
-        this.parameter = new Parameter(
+        super( typeFactory );
-            "dt",
+        this.parameter = new Parameter("dt", typeFactory.getType( JodaTimeConstants.DATE_TIME_FQN ) );
-            typeFactory.getType( JodaTimeConstants.DATE_TIME_FQN )
-        );
-        this.returnType = typeFactory.getType( XMLGregorianCalendar.class );
-
-        this.importTypes = asSet(
-            returnType,
-            parameter.getType(),
-            typeFactory.getType( DatatypeFactory.class ),
-            typeFactory.getType( DatatypeConfigurationException.class )
-        );
     }
 
     @Override
     public Set<Type> getImportTypes() {
-        return importTypes;
+        Set<Type> result = super.getImportTypes();
+        result.add( parameter.getType() );
+        return result;
     }
 
     @Override
@@ -52,8 +36,4 @@ public class JodaDateTimeToXmlGregorianCalendar extends BuiltInMethod {
         return parameter;
     }
 
-    @Override
-    public Type getReturnType() {
-        return returnType;
-    }
 }

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/JodaLocalDateTimeToXmlGregorianCalendar.java

@@ -5,48 +5,38 @@
  */
 package org.mapstruct.ap.internal.model.source.builtin;
 
-import static org.mapstruct.ap.internal.util.Collections.asSet;
-
 import java.util.Set;
-
-import javax.xml.datatype.DatatypeConfigurationException;
 import javax.xml.datatype.DatatypeConstants;
-import javax.xml.datatype.DatatypeFactory;
-import javax.xml.datatype.XMLGregorianCalendar;
 
 import org.mapstruct.ap.internal.model.common.Parameter;
 import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.common.TypeFactory;
 import org.mapstruct.ap.internal.util.JodaTimeConstants;
 
+import static org.mapstruct.ap.internal.util.Collections.asSet;
+
 /**
  * @author Sjaak Derksen
  */
-public class JodaLocalDateTimeToXmlGregorianCalendar extends BuiltInMethod {
+public class JodaLocalDateTimeToXmlGregorianCalendar extends AbstractToXmlGregorianCalendar {
 
     private final Parameter parameter;
-    private final Type returnType;
     private final Set<Type> importTypes;
 
     public JodaLocalDateTimeToXmlGregorianCalendar(TypeFactory typeFactory) {
-        this.parameter = new Parameter(
+        super( typeFactory );
-            "dt",
+        this.parameter = new Parameter( "dt", typeFactory.getType( JodaTimeConstants.LOCAL_DATE_TIME_FQN ) );
-            typeFactory.getType( JodaTimeConstants.LOCAL_DATE_TIME_FQN )
-        );
-        this.returnType = typeFactory.getType( XMLGregorianCalendar.class );
-
         this.importTypes = asSet(
-            returnType,
             parameter.getType(),
-            typeFactory.getType( DatatypeConstants.class ),
+            typeFactory.getType( DatatypeConstants.class )
-            typeFactory.getType( DatatypeFactory.class ),
-            typeFactory.getType( DatatypeConfigurationException.class )
         );
     }
 
     @Override
     public Set<Type> getImportTypes() {
-        return importTypes;
+        Set<Type> result = super.getImportTypes();
+        result.addAll( importTypes );
+        return result;
     }
 
     @Override
@@ -54,8 +44,4 @@ public class JodaLocalDateTimeToXmlGregorianCalendar extends BuiltInMethod {
         return parameter;
     }
 
-    @Override
-    public Type getReturnType() {
-        return returnType;
-    }
 }

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/JodaLocalDateToXmlGregorianCalendar.java

@@ -5,48 +5,38 @@
  */
 package org.mapstruct.ap.internal.model.source.builtin;
 
-import static org.mapstruct.ap.internal.util.Collections.asSet;
-
 import java.util.Set;
-
-import javax.xml.datatype.DatatypeConfigurationException;
 import javax.xml.datatype.DatatypeConstants;
-import javax.xml.datatype.DatatypeFactory;
-import javax.xml.datatype.XMLGregorianCalendar;
 
 import org.mapstruct.ap.internal.model.common.Parameter;
 import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.common.TypeFactory;
 import org.mapstruct.ap.internal.util.JodaTimeConstants;
 
+import static org.mapstruct.ap.internal.util.Collections.asSet;
+
 /**
  * @author Sjaak Derksen
  */
-public class JodaLocalDateToXmlGregorianCalendar extends BuiltInMethod {
+public class JodaLocalDateToXmlGregorianCalendar extends AbstractToXmlGregorianCalendar {
 
     private final Parameter parameter;
-    private final Type returnType;
     private final Set<Type> importTypes;
 
     public JodaLocalDateToXmlGregorianCalendar(TypeFactory typeFactory) {
-        this.parameter = new Parameter(
+        super( typeFactory );
-            "dt",
+        this.parameter = new Parameter( "dt", typeFactory.getType( JodaTimeConstants.LOCAL_DATE_FQN ) );
-            typeFactory.getType( JodaTimeConstants.LOCAL_DATE_FQN )
-        );
-        this.returnType = typeFactory.getType( XMLGregorianCalendar.class );
-
         this.importTypes = asSet(
-            returnType,
             parameter.getType(),
-            typeFactory.getType( DatatypeConstants.class ),
+            typeFactory.getType( DatatypeConstants.class )
-            typeFactory.getType( DatatypeFactory.class ),
-            typeFactory.getType( DatatypeConfigurationException.class )
         );
     }
 
     @Override
     public Set<Type> getImportTypes() {
-        return importTypes;
+        Set<Type> result = super.getImportTypes();
+        result.addAll( importTypes );
+        return result;
     }
 
     @Override
@@ -54,8 +44,4 @@ public class JodaLocalDateToXmlGregorianCalendar extends BuiltInMethod {
         return parameter;
     }
 
-    @Override
-    public Type getReturnType() {
-        return returnType;
-    }
 }

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/JodaLocalTimeToXmlGregorianCalendar.java

@@ -5,48 +5,38 @@
  */
 package org.mapstruct.ap.internal.model.source.builtin;
 
-import static org.mapstruct.ap.internal.util.Collections.asSet;
-
 import java.util.Set;
-
-import javax.xml.datatype.DatatypeConfigurationException;
 import javax.xml.datatype.DatatypeConstants;
-import javax.xml.datatype.DatatypeFactory;
-import javax.xml.datatype.XMLGregorianCalendar;
 
 import org.mapstruct.ap.internal.model.common.Parameter;
 import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.common.TypeFactory;
 import org.mapstruct.ap.internal.util.JodaTimeConstants;
 
+import static org.mapstruct.ap.internal.util.Collections.asSet;
+
 /**
  * @author Sjaak Derksen
  */
-public class JodaLocalTimeToXmlGregorianCalendar extends BuiltInMethod {
+public class JodaLocalTimeToXmlGregorianCalendar extends AbstractToXmlGregorianCalendar {
 
     private final Parameter parameter;
-    private final Type returnType;
     private final Set<Type> importTypes;
 
     public JodaLocalTimeToXmlGregorianCalendar(TypeFactory typeFactory) {
-        this.parameter = new Parameter(
+        super( typeFactory );
-            "dt",
+        this.parameter = new Parameter( "dt", typeFactory.getType( JodaTimeConstants.LOCAL_TIME_FQN ) );
-            typeFactory.getType( JodaTimeConstants.LOCAL_TIME_FQN )
-        );
-        this.returnType = typeFactory.getType( XMLGregorianCalendar.class );
-
         this.importTypes = asSet(
-            returnType,
             parameter.getType(),
-            typeFactory.getType( DatatypeConstants.class ),
+            typeFactory.getType( DatatypeConstants.class )
-            typeFactory.getType( DatatypeFactory.class ),
-            typeFactory.getType( DatatypeConfigurationException.class )
         );
     }
 
     @Override
     public Set<Type> getImportTypes() {
-        return importTypes;
+        Set<Type> result = super.getImportTypes();
+        result.addAll( importTypes );
+        return result;
     }
 
     @Override
@@ -54,8 +44,4 @@ public class JodaLocalTimeToXmlGregorianCalendar extends BuiltInMethod {
         return parameter;
     }
 
-    @Override
-    public Type getReturnType() {
-        return returnType;
-    }
 }

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/LocalDateToXmlGregorianCalendar.java

@@ -5,53 +5,43 @@
  */
 package org.mapstruct.ap.internal.model.source.builtin;
 
-import static org.mapstruct.ap.internal.util.Collections.asSet;
-
 import java.time.LocalDate;
 import java.util.Set;
-
-import javax.xml.datatype.DatatypeConfigurationException;
 import javax.xml.datatype.DatatypeConstants;
-import javax.xml.datatype.DatatypeFactory;
-import javax.xml.datatype.XMLGregorianCalendar;
 
 import org.mapstruct.ap.internal.model.common.Parameter;
 import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.common.TypeFactory;
 
+import static org.mapstruct.ap.internal.util.Collections.asSet;
+
 /**
  * @author Gunnar Morling
  */
-public class LocalDateToXmlGregorianCalendar extends BuiltInMethod {
+public class LocalDateToXmlGregorianCalendar extends AbstractToXmlGregorianCalendar {
 
     private final Parameter parameter;
-    private final Type returnType;
     private final Set<Type> importTypes;
 
     public LocalDateToXmlGregorianCalendar(TypeFactory typeFactory) {
+        super( typeFactory );
         this.parameter = new Parameter( "localDate", typeFactory.getType( LocalDate.class ) );
-        this.returnType = typeFactory.getType( XMLGregorianCalendar.class );
         this.importTypes = asSet(
-                returnType,
                 parameter.getType(),
-                typeFactory.getType( DatatypeFactory.class ),
-                typeFactory.getType( DatatypeConfigurationException.class ),
                 typeFactory.getType( DatatypeConstants.class )
         );
     }
 
+    @Override
+    public Set<Type> getImportTypes() {
+        Set<Type> result = super.getImportTypes();
+        result.addAll( importTypes );
+        return result;
+    }
+
     @Override
     public Parameter getParameter() {
         return parameter;
     }
 
-    @Override
-    public Type getReturnType() {
-        return returnType;
-    }
-
-    @Override
-    public Set<Type> getImportTypes() {
-        return importTypes;
-    }
 }

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/NewDatatypeFactoryConstructorFragment.java

@@ -0,0 +1,12 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.ap.internal.model.source.builtin;
+
+public class NewDatatypeFactoryConstructorFragment implements BuiltInConstructorFragment {
+
+    public NewDatatypeFactoryConstructorFragment() {
+    }
+}

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/StringToXmlGregorianCalendar.java

@@ -5,49 +5,43 @@
  */
 package org.mapstruct.ap.internal.model.source.builtin;
 
-import static org.mapstruct.ap.internal.util.Collections.asSet;
-
 import java.text.DateFormat;
 import java.text.ParseException;
 import java.text.SimpleDateFormat;
 import java.util.GregorianCalendar;
 import java.util.Set;
 
-import javax.xml.datatype.DatatypeConfigurationException;
-import javax.xml.datatype.DatatypeFactory;
-import javax.xml.datatype.XMLGregorianCalendar;
-
 import org.mapstruct.ap.internal.model.common.ConversionContext;
 import org.mapstruct.ap.internal.model.common.Parameter;
 import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.common.TypeFactory;
 
+import static org.mapstruct.ap.internal.util.Collections.asSet;
+
 /**
  * @author Sjaak Derksen
  */
-public class StringToXmlGregorianCalendar extends BuiltInMethod {
+public class StringToXmlGregorianCalendar extends AbstractToXmlGregorianCalendar {
 
     private final Parameter parameter;
-    private final Type returnType;
     private final Set<Type> importTypes;
 
     public StringToXmlGregorianCalendar(TypeFactory typeFactory) {
+        super( typeFactory );
         this.parameter = new Parameter( "date", typeFactory.getType( String.class ) );
-        this.returnType = typeFactory.getType( XMLGregorianCalendar.class );
         this.importTypes = asSet(
-            returnType,
             typeFactory.getType( GregorianCalendar.class ),
             typeFactory.getType( SimpleDateFormat.class ),
             typeFactory.getType( DateFormat.class ),
-            typeFactory.getType( ParseException.class ),
+            typeFactory.getType( ParseException.class )
-            typeFactory.getType( DatatypeFactory.class ),
-            typeFactory.getType( DatatypeConfigurationException.class )
         );
     }
 
     @Override
     public Set<Type> getImportTypes() {
-        return importTypes;
+        Set<Type> result = super.getImportTypes();
+        result.addAll( importTypes );
+        return result;
     }
 
     @Override
@@ -55,11 +49,6 @@ public class StringToXmlGregorianCalendar extends BuiltInMethod {
         return parameter;
     }
 
-    @Override
-    public Type getReturnType() {
-        return returnType;
-    }
-
     @Override
     public String getContextParameter(ConversionContext conversionContext) {
         return conversionContext.getDateFormat() != null ? "\"" + conversionContext.getDateFormat() + "\"" : "null";

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/XmlGregorianCalendarToCalendar.java

@@ -5,17 +5,16 @@
  */
 package org.mapstruct.ap.internal.model.source.builtin;
 
-import static org.mapstruct.ap.internal.util.Collections.asSet;
-
 import java.util.Calendar;
 import java.util.Set;
-
 import javax.xml.datatype.XMLGregorianCalendar;
 
 import org.mapstruct.ap.internal.model.common.Parameter;
 import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.common.TypeFactory;
 
+import static org.mapstruct.ap.internal.util.Collections.asSet;
+
 /**
  * @author Sjaak Derksen
  */

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/XmlGregorianCalendarToDate.java

@@ -5,17 +5,16 @@
  */
 package org.mapstruct.ap.internal.model.source.builtin;
 
-import static org.mapstruct.ap.internal.util.Collections.asSet;
-
 import java.util.Date;
 import java.util.Set;
-
 import javax.xml.datatype.XMLGregorianCalendar;
 
 import org.mapstruct.ap.internal.model.common.Parameter;
 import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.common.TypeFactory;
 
+import static org.mapstruct.ap.internal.util.Collections.asSet;
+
 /**
  * @author Sjaak Derksen
  */

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/XmlGregorianCalendarToJodaDateTime.java

@@ -5,8 +5,6 @@
  */
 package org.mapstruct.ap.internal.model.source.builtin;
 
-import static org.mapstruct.ap.internal.util.Collections.asSet;
-
 import java.util.Set;
 import javax.xml.datatype.DatatypeConstants;
 import javax.xml.datatype.XMLGregorianCalendar;
@@ -16,6 +14,8 @@ import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.common.TypeFactory;
 import org.mapstruct.ap.internal.util.JodaTimeConstants;
 
+import static org.mapstruct.ap.internal.util.Collections.asSet;
+
 /**
  * @author Sjaak Derksen
  */

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/XmlGregorianCalendarToJodaLocalDate.java

@@ -5,8 +5,6 @@
  */
 package org.mapstruct.ap.internal.model.source.builtin;
 
-import static org.mapstruct.ap.internal.util.Collections.asSet;
-
 import java.util.Set;
 import javax.xml.datatype.DatatypeConstants;
 import javax.xml.datatype.XMLGregorianCalendar;
@@ -16,6 +14,8 @@ import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.common.TypeFactory;
 import org.mapstruct.ap.internal.util.JodaTimeConstants;
 
+import static org.mapstruct.ap.internal.util.Collections.asSet;
+
 /**
  * @author Sjaak Derksen
  */

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/XmlGregorianCalendarToJodaLocalDateTime.java

@@ -5,8 +5,6 @@
  */
 package org.mapstruct.ap.internal.model.source.builtin;
 
-import static org.mapstruct.ap.internal.util.Collections.asSet;
-
 import java.util.Set;
 import javax.xml.datatype.DatatypeConstants;
 import javax.xml.datatype.XMLGregorianCalendar;
@@ -16,6 +14,8 @@ import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.common.TypeFactory;
 import org.mapstruct.ap.internal.util.JodaTimeConstants;
 
+import static org.mapstruct.ap.internal.util.Collections.asSet;
+
 /**
  * @author Sjaak Derksen
  */

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/XmlGregorianCalendarToJodaLocalTime.java

@@ -5,8 +5,6 @@
  */
 package org.mapstruct.ap.internal.model.source.builtin;
 
-import static org.mapstruct.ap.internal.util.Collections.asSet;
-
 import java.util.Set;
 import javax.xml.datatype.DatatypeConstants;
 import javax.xml.datatype.XMLGregorianCalendar;
@@ -16,6 +14,8 @@ import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.common.TypeFactory;
 import org.mapstruct.ap.internal.util.JodaTimeConstants;
 
+import static org.mapstruct.ap.internal.util.Collections.asSet;
+
 /**
  * @author Sjaak Derksen
  */

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/XmlGregorianCalendarToLocalDate.java

@@ -5,17 +5,16 @@
  */
 package org.mapstruct.ap.internal.model.source.builtin;
 
-import static org.mapstruct.ap.internal.util.Collections.asSet;
-
 import java.time.LocalDate;
 import java.util.Set;
-
 import javax.xml.datatype.XMLGregorianCalendar;
 
 import org.mapstruct.ap.internal.model.common.Parameter;
 import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.common.TypeFactory;
 
+import static org.mapstruct.ap.internal.util.Collections.asSet;
+
 /**
  * @author Gunnar Morling
  */

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/XmlGregorianCalendarToString.java

@@ -5,12 +5,9 @@
  */
 package org.mapstruct.ap.internal.model.source.builtin;
 
-import static org.mapstruct.ap.internal.util.Collections.asSet;
-
 import java.text.SimpleDateFormat;
 import java.util.Date;
 import java.util.Set;
-
 import javax.xml.datatype.XMLGregorianCalendar;
 
 import org.mapstruct.ap.internal.model.common.ConversionContext;
@@ -18,6 +15,8 @@ import org.mapstruct.ap.internal.model.common.Parameter;
 import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.common.TypeFactory;
 
+import static org.mapstruct.ap.internal.util.Collections.asSet;
+
 /**
  * @author Sjaak Derksen
  */

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/ZonedDateTimeToCalendar.java

@@ -5,8 +5,6 @@
  */
 package org.mapstruct.ap.internal.model.source.builtin;
 
-import static org.mapstruct.ap.internal.util.Collections.asSet;
-
 import java.time.ZonedDateTime;
 import java.util.Calendar;
 import java.util.Set;
@@ -17,6 +15,8 @@ import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.common.TypeFactory;
 import org.mapstruct.ap.internal.util.JavaTimeConstants;
 
+import static org.mapstruct.ap.internal.util.Collections.asSet;
+
 /**
  * {@link BuiltInMethod} for mapping between {@link Calendar} and {@link ZonedDateTime}.
  * <p>

processor/src/main/java/org/mapstruct/ap/internal/model/source/builtin/ZonedDateTimeToXmlGregorianCalendar.java

@@ -8,9 +8,6 @@ package org.mapstruct.ap.internal.model.source.builtin;
 import java.time.ZonedDateTime;
 import java.util.GregorianCalendar;
 import java.util.Set;
-import javax.xml.datatype.DatatypeConfigurationException;
-import javax.xml.datatype.DatatypeFactory;
-import javax.xml.datatype.XMLGregorianCalendar;
 
 import org.mapstruct.ap.internal.model.common.Parameter;
 import org.mapstruct.ap.internal.model.common.Type;
@@ -21,28 +18,26 @@ import static org.mapstruct.ap.internal.util.Collections.asSet;
 /**
  * @author Christian Bandowski
  */
-public class ZonedDateTimeToXmlGregorianCalendar extends BuiltInMethod {
+public class ZonedDateTimeToXmlGregorianCalendar extends AbstractToXmlGregorianCalendar {
 
     private final Parameter parameter;
-    private final Type returnType;
     private final Set<Type> importTypes;
 
     public ZonedDateTimeToXmlGregorianCalendar(TypeFactory typeFactory) {
+        super( typeFactory );
         this.parameter = new Parameter( "zdt ", typeFactory.getType( ZonedDateTime.class ) );
-        this.returnType = typeFactory.getType( XMLGregorianCalendar.class );
 
         this.importTypes = asSet(
-            returnType,
             parameter.getType(),
-            typeFactory.getType( DatatypeFactory.class ),
+            typeFactory.getType( GregorianCalendar.class )
-            typeFactory.getType( GregorianCalendar.class ),
-            typeFactory.getType( DatatypeConfigurationException.class )
         );
     }
 
     @Override
     public Set<Type> getImportTypes() {
-        return importTypes;
+        Set<Type> result = super.getImportTypes();
+        result.addAll( importTypes );
+        return result;
     }
 
     @Override
@@ -50,8 +45,4 @@ public class ZonedDateTimeToXmlGregorianCalendar extends BuiltInMethod {
         return parameter;
     }
 
-    @Override
-    public Type getReturnType() {
-        return returnType;
-    }
 }

processor/src/main/java/org/mapstruct/ap/internal/processor/AnnotationBasedComponentModelProcessor.java

@@ -63,12 +63,15 @@ public abstract class AnnotationBasedComponentModelProcessor implements ModelEle
         }
 
         List<Annotation> annotations = getMapperReferenceAnnotations();
-        ListIterator<MapperReference> iterator = mapper.getReferencedMappers().listIterator();
+        ListIterator<Field> iterator = mapper.getFields().listIterator();
 
         while ( iterator.hasNext() ) {
-            MapperReference reference = iterator.next();
+
-            iterator.remove();
+            Field reference = iterator.next();
-            iterator.add( replacementMapperReference( reference, annotations, injectionStrategy ) );
+            if ( reference instanceof  MapperReference ) {
+                iterator.remove();
+                iterator.add( replacementMapperReference( reference, annotations, injectionStrategy ) );
+            }
         }
 
         if ( injectionStrategy == InjectionStrategyPrism.CONSTRUCTOR ) {
@@ -97,8 +100,18 @@ public abstract class AnnotationBasedComponentModelProcessor implements ModelEle
         decorator.setFields( replacement );
     }
 
+    private List<MapperReference> toMapperReferences(List<Field> fields) {
+        List<MapperReference> mapperReferences = new ArrayList<MapperReference>(  );
+        for ( Field field : fields ) {
+            if ( field instanceof  MapperReference ) {
+                mapperReferences.add( (MapperReference) field );
+            }
+        }
+        return mapperReferences;
+    }
+
     private void buildConstructors(Mapper mapper) {
-        if ( !mapper.getReferencedMappers().isEmpty() ) {
+        if ( !toMapperReferences( mapper.getFields() ).isEmpty() ) {
             AnnotatedConstructor annotatedConstructor = buildAnnotatedConstructorForMapper( mapper );
 
             if ( !annotatedConstructor.getMapperReferences().isEmpty() ) {
@@ -117,10 +130,11 @@ public abstract class AnnotationBasedComponentModelProcessor implements ModelEle
     }
 
     private AnnotatedConstructor buildAnnotatedConstructorForMapper(Mapper mapper) {
+        List<MapperReference> mapperReferences = toMapperReferences( mapper.getFields() );
         List<AnnotationMapperReference> mapperReferencesForConstructor =
-            new ArrayList<AnnotationMapperReference>( mapper.getReferencedMappers().size() );
+            new ArrayList<AnnotationMapperReference>( mapperReferences.size() );
 
-        for ( MapperReference mapperReference : mapper.getReferencedMappers() ) {
+        for ( MapperReference mapperReference : mapperReferences ) {
             if ( mapperReference.isUsed() ) {
                 mapperReferencesForConstructor.add( (AnnotationMapperReference) mapperReference );
             }
@@ -130,11 +144,13 @@ public abstract class AnnotationBasedComponentModelProcessor implements ModelEle
 
         removeDuplicateAnnotations( mapperReferencesForConstructor, mapperReferenceAnnotations );
 
-        return new AnnotatedConstructor(
+        return AnnotatedConstructor.forComponentModels(
             mapper.getName(),
             mapperReferencesForConstructor,
             mapperReferenceAnnotations,
-            additionalPublicEmptyConstructor() );
+            mapper.getConstructor(),
+            additionalPublicEmptyConstructor()
+        );
     }
 
     private AnnotatedConstructor buildAnnotatedConstructorForDecorator(Decorator decorator) {
@@ -151,13 +167,16 @@ public abstract class AnnotationBasedComponentModelProcessor implements ModelEle
 
         removeDuplicateAnnotations( mapperReferencesForConstructor, mapperReferenceAnnotations );
 
-        return new AnnotatedConstructor(
+        return AnnotatedConstructor.forComponentModels(
             decorator.getName(),
             mapperReferencesForConstructor,
             mapperReferenceAnnotations,
-            additionalPublicEmptyConstructor() );
+            decorator.getConstructor(),
+            additionalPublicEmptyConstructor()
+        );
     }
 
+
     /**
      * Removes duplicate constructor parameter annotations. If an annotation is already present on the constructor, it
      * does not have be defined on the constructor parameter, too. For example, for CDI, the javax.inject.Inject
@@ -204,7 +223,7 @@ public abstract class AnnotationBasedComponentModelProcessor implements ModelEle
      * @param injectionStrategyPrism strategy for injection
      * @return the mapper reference replacing the original one
      */
-    protected MapperReference replacementMapperReference(Field originalReference, List<Annotation> annotations,
+    protected Field replacementMapperReference(Field originalReference, List<Annotation> annotations,
                                                          InjectionStrategyPrism injectionStrategyPrism) {
         boolean finalField =
             injectionStrategyPrism == InjectionStrategyPrism.CONSTRUCTOR && !additionalPublicEmptyConstructor();

processor/src/main/java/org/mapstruct/ap/internal/processor/MapperCreationProcessor.java

@@ -7,8 +7,10 @@ package org.mapstruct.ap.internal.processor;
 
 import java.util.ArrayList;
 import java.util.Collections;
+import java.util.LinkedHashSet;
 import java.util.LinkedList;
 import java.util.List;
+import java.util.Set;
 import java.util.SortedSet;
 import java.util.TreeSet;
 import javax.lang.model.element.ExecutableElement;
@@ -26,6 +28,7 @@ import org.mapstruct.ap.internal.model.Decorator;
 import org.mapstruct.ap.internal.model.DefaultMapperReference;
 import org.mapstruct.ap.internal.model.DelegatingMethod;
 import org.mapstruct.ap.internal.model.EnumMappingMethod;
+import org.mapstruct.ap.internal.model.Field;
 import org.mapstruct.ap.internal.model.IterableMappingMethod;
 import org.mapstruct.ap.internal.model.MapMappingMethod;
 import org.mapstruct.ap.internal.model.Mapper;
@@ -33,6 +36,7 @@ import org.mapstruct.ap.internal.model.MapperReference;
 import org.mapstruct.ap.internal.model.MappingBuilderContext;
 import org.mapstruct.ap.internal.model.MappingMethod;
 import org.mapstruct.ap.internal.model.StreamMappingMethod;
+import org.mapstruct.ap.internal.model.SupportingConstructorFragment;
 import org.mapstruct.ap.internal.model.ValueMappingMethod;
 import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.common.TypeFactory;
@@ -56,6 +60,8 @@ import org.mapstruct.ap.internal.util.Message;
 import org.mapstruct.ap.internal.util.Strings;
 import org.mapstruct.ap.internal.version.VersionInformation;
 
+import static org.mapstruct.ap.internal.model.SupportingConstructorFragment.addAllFragmentsIn;
+import static org.mapstruct.ap.internal.model.SupportingField.addAllFieldsIn;
 import static org.mapstruct.ap.internal.util.Collections.first;
 import static org.mapstruct.ap.internal.util.Collections.join;
 
@@ -139,15 +145,26 @@ public class MapperCreationProcessor implements ModelElementProcessor<List<Sourc
     }
 
     private Mapper getMapper(TypeElement element, MapperConfiguration mapperConfig, List<SourceMethod> methods) {
-        List<MapperReference> mapperReferences = mappingContext.getMapperReferences();
+
         List<MappingMethod> mappingMethods = getMappingMethods( mapperConfig, methods );
-        mappingMethods.addAll( mappingContext.getUsedVirtualMappings() );
+        mappingMethods.addAll( mappingContext.getUsedSupportedMappings() );
         mappingMethods.addAll( mappingContext.getMappingsToGenerate() );
 
+        // handle fields
+        List<Field> fields = new ArrayList<Field>( mappingContext.getMapperReferences() );
+        Set<Field> supportingFieldSet = new LinkedHashSet<Field>(  );
+        addAllFieldsIn( mappingContext.getUsedSupportedMappings(), supportingFieldSet );
+        fields.addAll( supportingFieldSet );
+
+        // handle constructorfragments
+        Set<SupportingConstructorFragment> constructorFragments = new LinkedHashSet<SupportingConstructorFragment>();
+        addAllFragmentsIn( mappingContext.getUsedSupportedMappings(), constructorFragments );
+
         Mapper mapper = new Mapper.Builder()
             .element( element )
             .mappingMethods( mappingMethods )
-            .mapperReferences( mapperReferences )
+            .fields( fields )
+            .constructorFragments(  constructorFragments )
             .options( options )
             .versionInformation( versionInformation )
             .decorator( getDecorator( element, methods, mapperConfig.implementationName(),

processor/src/main/java/org/mapstruct/ap/internal/processor/creation/MappingResolverImpl.java

@@ -25,11 +25,13 @@ import javax.lang.model.util.Types;
 
 import org.mapstruct.ap.internal.conversion.ConversionProvider;
 import org.mapstruct.ap.internal.conversion.Conversions;
+import org.mapstruct.ap.internal.model.Field;
 import org.mapstruct.ap.internal.model.HelperMethod;
 import org.mapstruct.ap.internal.model.MapperReference;
 import org.mapstruct.ap.internal.model.MappingBuilderContext.MappingResolver;
 import org.mapstruct.ap.internal.model.MethodReference;
-import org.mapstruct.ap.internal.model.VirtualMappingMethod;
+import org.mapstruct.ap.internal.model.SupportingField;
+import org.mapstruct.ap.internal.model.SupportingMappingMethod;
 import org.mapstruct.ap.internal.model.common.Assignment;
 import org.mapstruct.ap.internal.model.common.ConversionContext;
 import org.mapstruct.ap.internal.model.common.DefaultConversionContext;
@@ -73,7 +75,7 @@ public class MappingResolverImpl implements MappingResolver {
      * Private methods which are not present in the original mapper interface and are added to map certain property
      * types.
      */
-    private final Set<VirtualMappingMethod> usedVirtualMappings = new HashSet<VirtualMappingMethod>();
+    private final Set<SupportingMappingMethod> usedSupportedMappings = new HashSet<SupportingMappingMethod>();
 
     public MappingResolverImpl(FormattingMessager messager, Elements elementUtils, Types typeUtils,
                                TypeFactory typeFactory, List<Method> sourceModel,
@@ -110,8 +112,8 @@ public class MappingResolverImpl implements MappingResolver {
     }
 
     @Override
-    public Set<VirtualMappingMethod> getUsedVirtualMappings() {
+    public Set<SupportingMappingMethod> getUsedSupportedMappings() {
-        return usedVirtualMappings;
+        return usedSupportedMappings;
     }
 
     private MapperReference findMapperReference(Method method) {
@@ -134,10 +136,10 @@ public class MappingResolverImpl implements MappingResolver {
         private final boolean savedPreferUpdateMapping;
         private final FormattingParameters formattingParameters;
 
-        // resolving via 2 steps creates the possibillity of wrong matches, first builtin method matches,
+        // resolving via 2 steps creates the possibility of wrong matches, first builtin method matches,
-        // second doesn't. In that case, the first builtin method should not lead to a virtual method
+        // second doesn't. In that case, the first builtin method should not lead to a supported method
         // so this set must be cleared.
-        private final Set<VirtualMappingMethod> virtualMethodCandidates;
+        private final Set<SupportingMappingMethod> supportingMethodCandidates;
 
         private ResolvingAttempt(List<Method> sourceModel, Method mappingMethod,
             FormattingParameters formattingParameters, SourceRHS sourceRHS, SelectionCriteria criteria) {
@@ -147,7 +149,7 @@ public class MappingResolverImpl implements MappingResolver {
             this.formattingParameters =
                 formattingParameters == null ? FormattingParameters.EMPTY : formattingParameters;
             this.sourceRHS = sourceRHS;
-            this.virtualMethodCandidates = new HashSet<VirtualMappingMethod>();
+            this.supportingMethodCandidates = new HashSet<SupportingMappingMethod>();
             this.selectionCriteria = criteria;
             this.savedPreferUpdateMapping = criteria.isPreferUpdateMapping();
         }
@@ -204,21 +206,21 @@ public class MappingResolverImpl implements MappingResolver {
             Assignment builtInMethod = resolveViaBuiltInMethod( sourceType, targetType );
             if ( builtInMethod != null ) {
                 builtInMethod.setAssignment( sourceRHS );
-                usedVirtualMappings.addAll( virtualMethodCandidates );
+                usedSupportedMappings.addAll( supportingMethodCandidates );
                 return builtInMethod;
             }
 
             // 2 step method, first: method(method(source))
             referencedMethod = resolveViaMethodAndMethod( sourceType, targetType );
             if ( referencedMethod != null ) {
-                usedVirtualMappings.addAll( virtualMethodCandidates );
+                usedSupportedMappings.addAll( supportingMethodCandidates );
                 return referencedMethod;
             }
 
             // 2 step method, then: method(conversion(source))
             referencedMethod = resolveViaConversionAndMethod( sourceType, targetType );
             if ( referencedMethod != null ) {
-                usedVirtualMappings.addAll( virtualMethodCandidates );
+                usedSupportedMappings.addAll( supportingMethodCandidates );
                 return referencedMethod;
             }
 
@@ -228,7 +230,7 @@ public class MappingResolverImpl implements MappingResolver {
             // 2 step method, finally: conversion(method(source))
             conversion = resolveViaMethodAndConversion( sourceType, targetType );
             if ( conversion != null ) {
-                usedVirtualMappings.addAll( virtualMethodCandidates );
+                usedSupportedMappings.addAll( supportingMethodCandidates );
                 return conversion;
             }
 
@@ -252,7 +254,7 @@ public class MappingResolverImpl implements MappingResolver {
 
             // add helper methods required in conversion
             for ( HelperMethod helperMethod : conversionProvider.getRequiredHelperMethods( ctx ) ) {
-                usedVirtualMappings.add( new VirtualMappingMethod( helperMethod ) );
+                usedSupportedMappings.add( new SupportingMappingMethod( helperMethod ) );
             }
             return conversionProvider.to( ctx );
         }
@@ -282,7 +284,12 @@ public class MappingResolverImpl implements MappingResolver {
                 getBestMatch( builtInMethods.getBuiltInMethods(), sourceType, targetType );
 
             if ( matchingBuiltInMethod != null ) {
-                virtualMethodCandidates.add( new VirtualMappingMethod( matchingBuiltInMethod.getMethod() ) );
+
+                Set<Field> allUsedFields = new HashSet<Field>( mapperReferences );
+                SupportingField.addAllFieldsIn( supportingMethodCandidates, allUsedFields );
+                SupportingMappingMethod supportingMappingMethod =
+                    new SupportingMappingMethod( matchingBuiltInMethod.getMethod(), allUsedFields );
+                supportingMethodCandidates.add( supportingMappingMethod );
                 ConversionContext ctx = new DefaultConversionContext(
                     typeFactory,
                     messager,
@@ -337,7 +344,7 @@ public class MappingResolverImpl implements MappingResolver {
                     }
                     else {
                         // both should match;
-                        virtualMethodCandidates.clear();
+                        supportingMethodCandidates.clear();
                         methodRefY = null;
                     }
                 }
@@ -374,7 +381,7 @@ public class MappingResolverImpl implements MappingResolver {
                     }
                     else {
                         // both should match
-                        virtualMethodCandidates.clear();
+                        supportingMethodCandidates.clear();
                         methodRefY = null;
                     }
                 }
@@ -417,7 +424,7 @@ public class MappingResolverImpl implements MappingResolver {
                     }
                     else {
                         // both should match;
-                        virtualMethodCandidates.clear();
+                        supportingMethodCandidates.clear();
                         conversionYRef = null;
                     }
                 }

processor/src/main/java/org/mapstruct/ap/internal/util/Strings.java

@@ -127,8 +127,8 @@ public class Strings {
         return string == null || string.isEmpty();
     }
 
-    public static String getSaveVariableName(String name, String... existingVariableNames) {
+    public static String getSafeVariableName(String name, String... existingVariableNames) {
-        return getSaveVariableName( name, Arrays.asList( existingVariableNames ) );
+        return getSafeVariableName( name, Arrays.asList( existingVariableNames ) );
     }
 
     /**
@@ -141,7 +141,7 @@ public class Strings {
      * @return a variable name based on the given original name, not conflicting with any of the given other names or
      * any Java keyword; starting with a lower-case letter
      */
-    public static String getSaveVariableName(String name, Collection<String> existingVariableNames) {
+    public static String getSafeVariableName(String name, Collection<String> existingVariableNames) {
         name = decapitalize( sanitizeIdentifierName( name ) );
         name = joinAndCamelize( extractParts( name ) );
 

processor/src/main/resources/org/mapstruct/ap/internal/model/AnnotatedConstructor.ftl

@@ -1,20 +1,24 @@
-<#--
+ <#--
 
     Copyright MapStruct Authors.
 
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
-<#if publicEmptyConstructor>
+ <#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.AnnotatedConstructor" -->
-public ${name}() {
+ <#if noArgumentConstructor??>
-}
+     <@includeModel object=noArgumentConstructor/>
 </#if>
 
 <#list annotations as annotation>
     <#nt><@includeModel object=annotation/>
 </#list>
 public ${name}(<#list mapperReferences as mapperReference><#list mapperReference.annotations as annotation><@includeModel object=annotation/> </#list><@includeModel object=mapperReference.type/> ${mapperReference.variableName}<#if mapperReference_has_next>, </#if></#list>) {
+    <#if noArgumentConstructor?? && !noArgumentConstructor.fragments.empty>this();</#if>
     <#list mapperReferences as mapperReference>
         this.${mapperReference.variableName} = ${mapperReference.variableName};
     </#list>
+     <#list fragments as fragment>
+         <#nt><@includeModel object=fragment/>
+    </#list>
 }

processor/src/main/resources/org/mapstruct/ap/internal/model/Annotation.ftl

@@ -5,4 +5,5 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.Annotation" -->
 @<@includeModel object=type/><#if (properties?size > 0) >(<#list properties as property>${property}<#if property_has_next>, </#if></#list>)</#if>

processor/src/main/resources/org/mapstruct/ap/internal/model/AnnotationMapperReference.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.AnnotationMapperReference" -->
 <#if includeAnnotationsOnField>
     <#list annotations as annotation>
         <#nt><@includeModel object=annotation/>

processor/src/main/resources/org/mapstruct/ap/internal/model/BeanMappingMethod.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.BeanMappingMethod" -->
 <#if overridden>@Override</#if>
 <#lt>${accessibility.keyword} <@includeModel object=returnType/> ${name}(<#list parameters as param><@includeModel object=param/><#if param_has_next>, </#if></#list>)<@throws/> {
     <#assign targetType = resultType />

processor/src/main/resources/org/mapstruct/ap/internal/model/DecoratorConstructor.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.DecoratorConstructor" -->
 public ${name}() {
     this( new ${delegateName}() );
 }

processor/src/main/resources/org/mapstruct/ap/internal/model/DefaultMapperReference.ftl

@@ -5,4 +5,5 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.DefaultMapperReference" -->
 private final <@includeModel object=type/> ${variableName} = <#if annotatedMapper>Mappers.getMapper( <@includeModel object=type/>.class );<#else>new <@includeModel object=type/>();</#if>

processor/src/main/resources/org/mapstruct/ap/internal/model/DelegatingMethod.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.DelegatingMethod" -->
 @Override
 public <@includeModel object=returnType/> ${name}(<#list parameters as param><@includeModel object=param/><#if param_has_next>, </#if></#list>) <@throws/> {
     <#if returnType.name != "void">return </#if>delegate.${name}( <#list parameters as param>${param.name}<#if param_has_next>, </#if></#list> );

processor/src/main/resources/org/mapstruct/ap/internal/model/EnumMappingMethod.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.EnumMappingMethod" -->
 @Override
 public <@includeModel object=returnType/> ${name}(<#list parameters as param><@includeModel object=param/><#if param_has_next>, </#if></#list>) {
     <#list beforeMappingReferencesWithoutMappingTarget as callback>

processor/src/main/resources/org/mapstruct/ap/internal/model/Field.ftl

@@ -5,4 +5,5 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.Field" -->
 private final <@includeModel object=type/> ${variableName};

processor/src/main/resources/org/mapstruct/ap/internal/model/GeneratedType.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.GeneratedType" -->
 <#if hasPackageName()>
 package ${packageName};
 </#if>

processor/src/main/resources/org/mapstruct/ap/internal/model/IterableCreation.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.IterableCreation" -->
 <@compress single_line=true>
     <#if factoryMethod??>
         <@includeModel object=factoryMethod targetType=resultType/>

processor/src/main/resources/org/mapstruct/ap/internal/model/IterableMappingMethod.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.IterableMappingMethod" -->
 <#if overridden>@Override</#if>
 <#lt>${accessibility.keyword} <@includeModel object=returnType/> ${name}(<#list parameters as param><@includeModel object=param/><#if param_has_next>, </#if></#list>)<@throws/> {
     <#list beforeMappingReferencesWithoutMappingTarget as callback>

processor/src/main/resources/org/mapstruct/ap/internal/model/LifecycleCallbackMethodReference.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.LifecycleCallbackMethodReference" -->
 <@compress single_line=true>
     <#if hasReturnType()>
         <@includeModel object=methodResultType /> ${targetVariableName} =

processor/src/main/resources/org/mapstruct/ap/internal/model/MapMappingMethod.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.MapMappingMethod" -->
 <#if overridden>@Override</#if>
 <#lt>${accessibility.keyword} <@includeModel object=returnType /> ${name}(<#list parameters as param><@includeModel object=param/><#if param_has_next>, </#if></#list>)<@throws/> {
     <#list beforeMappingReferencesWithoutMappingTarget as callback>

processor/src/main/resources/org/mapstruct/ap/internal/model/MethodReference.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.MethodReference" -->
 <@compress single_line=true>
     <#-- method is either internal to the mapper class, or external (via uses) declaringMapper!=null -->
     <#if declaringMapper??>

processor/src/main/resources/org/mapstruct/ap/internal/model/NestedPropertyMappingMethod.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.NestedPropertyMappingMethod" -->
 <#lt>private <@includeModel object=returnType/> ${name}(<#list parameters as param><@includeModel object=param/><#if param_has_next>, </#if></#list>)<@throws/> {
     if ( ${sourceParameter.name} == null ) {
         return ${returnType.null};

processor/src/main/resources/org/mapstruct/ap/internal/model/NoArgumentConstructor.ftl

@@ -0,0 +1,13 @@
+ <#--
+
+    Copyright MapStruct Authors.
+
+    Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+
+-->
+ <#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.NoArgumentConstructor" -->
+public ${name}() {
+ <#list fragments as fragment>
+     <#nt><@includeModel object=fragment/>
+ </#list>
+ }

processor/src/main/resources/org/mapstruct/ap/internal/model/PropertyMapping.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.PropertyMapping" -->
 <@includeModel object=assignment
                targetBeanName=ext.targetBeanName
                existingInstanceMapping=ext.existingInstanceMapping

processor/src/main/resources/org/mapstruct/ap/internal/model/ServicesEntry.ftl

@@ -5,4 +5,5 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.ServicesEntry" -->
 ${implementationPackage}.${implementationName}

processor/src/main/resources/org/mapstruct/ap/internal/model/StreamMappingMethod.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.StreamMappingMethod" -->
 <#if overridden>@Override</#if>
 <#lt>${accessibility.keyword} <@includeModel object=returnType/> ${name}(<#list parameters as param><@includeModel object=param/><#if param_has_next>, </#if></#list>)<@throws/> {
     <#--TODO does it even make sense to do a callback if the result is a Stream, as they are immutable-->

processor/src/main/resources/org/mapstruct/ap/internal/model/TypeConversion.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.TypeConversion" -->
 <@compress single_line=true>
 ${openExpression}<@_assignment/>${closeExpression}
 <#macro _assignment>

processor/src/main/resources/org/mapstruct/ap/internal/model/ValueMappingMethod.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.ValueMappingMethod" -->
 <#if overridden>@Override</#if>
 <#lt>${accessibility.keyword} <@includeModel object=returnType/> ${name}(<#list parameters as param><@includeModel object=param/><#if param_has_next>, </#if></#list>) {
     <#list beforeMappingReferencesWithoutMappingTarget as callback>

processor/src/main/resources/org/mapstruct/ap/internal/model/assignment/AdderWrapper.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.assignment.AdderWrapper" -->
 <#import "../macro/CommonMacros.ftl" as lib>
 <@lib.handleExceptions>
   if ( ${sourceReference} != null ) {

processor/src/main/resources/org/mapstruct/ap/internal/model/assignment/ArrayCopyWrapper.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.assignment.ArrayCopyWrapper" -->
 <#import "../macro/CommonMacros.ftl" as lib>
 <@lib.handleExceptions>
     <@lib.sourceLocalVarAssignment/>

processor/src/main/resources/org/mapstruct/ap/internal/model/assignment/EnumConstantWrapper.ftl

@@ -5,4 +5,5 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.assignment.EnumConstantWrapper" -->
 ${ext.targetType.name}.${assignment}

processor/src/main/resources/org/mapstruct/ap/internal/model/assignment/ExistingInstanceSetterWrapperForCollectionsAndMaps.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.assignment.ExistingInstanceSetterWrapperForCollectionsAndMaps" -->
 <#import "../macro/CommonMacros.ftl" as lib>
 <@lib.sourceLocalVarAssignment/>
 <@lib.handleExceptions>

processor/src/main/resources/org/mapstruct/ap/internal/model/assignment/GetterWrapperForCollectionsAndMaps.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.assignment.GetterWrapperForCollectionsAndMaps" -->
 <#import "../macro/CommonMacros.ftl" as lib>
 <@lib.sourceLocalVarAssignment/>
 if ( ${ext.targetBeanName}.${ext.targetWriteAccessorName}<@lib.handleWriteAccesing /> != null ) {

processor/src/main/resources/org/mapstruct/ap/internal/model/assignment/Java8FunctionWrapper.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.assignment.Java8FunctionWrapper" -->
 <#assign sourceVarName><#if assignment.sourceLocalVarName?? >${assignment.sourceLocalVarName}<#else>${assignment.sourceReference}</#if></#assign>
 <#if (thrownTypes?size == 0) >
     <#compress>

processor/src/main/resources/org/mapstruct/ap/internal/model/assignment/LocalVarWrapper.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.assignment.LocalVarWrapper" -->
 <#if (thrownTypes?size == 0) >
     <#if !ext.isTargetDefined?? ><@includeModel object=ext.targetType/></#if> ${ext.targetWriteAccessorName} = <@_assignment/>;
 <#else>

processor/src/main/resources/org/mapstruct/ap/internal/model/assignment/SetterWrapper.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.assignment.SetterWrapper" -->
 <#import "../macro/CommonMacros.ftl" as lib>
 <@lib.handleExceptions>
     <@lib.sourceLocalVarAssignment/>

processor/src/main/resources/org/mapstruct/ap/internal/model/assignment/SetterWrapperForCollectionsAndMaps.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.assignment.SetterWrapperForCollectionsAndMaps" -->
 <#import "../macro/CommonMacros.ftl" as lib>
 <@lib.sourceLocalVarAssignment/>
 <@lib.handleExceptions>

processor/src/main/resources/org/mapstruct/ap/internal/model/assignment/SetterWrapperForCollectionsAndMapsWithNullCheck.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.assignment.SetterWrapperForCollectionsAndMapsWithNullCheck" -->
 <#import "../macro/CommonMacros.ftl" as lib>
 <@lib.sourceLocalVarAssignment/>
 <@lib.handleExceptions>

processor/src/main/resources/org/mapstruct/ap/internal/model/assignment/UpdateWrapper.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.assignment.UpdateWrapper" -->
 <#import '../macro/CommonMacros.ftl' as lib >
 <@lib.handleExceptions>
   <#if includeSourceNullCheck>

processor/src/main/resources/org/mapstruct/ap/internal/model/common/Parameter.ftl

@@ -5,4 +5,5 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.common.Parameter" -->
 <@includeModel object=type asVarArgs=varArgs/> ${name}

processor/src/main/resources/org/mapstruct/ap/internal/model/common/SourceRHS.ftl

@@ -5,4 +5,5 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.common.SourceRHS" -->
 <#if sourceLocalVarName??>${sourceLocalVarName}<#else>${sourceReference}</#if>

processor/src/main/resources/org/mapstruct/ap/internal/model/common/Type.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.common.Type" -->
 <@compress single_line=true>
     <#if wildCardExtendsBound>
         ? extends <@includeModel object=typeBound />

processor/src/main/resources/org/mapstruct/ap/internal/model/source/builtin/CalendarToXmlGregorianCalendar.ftl

@@ -5,17 +5,13 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.SupportingMappingMethod" -->
 private <@includeModel object=findType("XMLGregorianCalendar")/> ${name}( <@includeModel object=findType("Calendar")/> cal ) {
     if ( cal == null ) {
         return null;
     }
 
-    try {
+    <@includeModel object=findType("GregorianCalendar")/> gcal = new <@includeModel object=findType("GregorianCalendar")/>( cal.getTimeZone() );
-        <@includeModel object=findType("GregorianCalendar")/> gcal = new <@includeModel object=findType("GregorianCalendar")/>( cal.getTimeZone() );
+    gcal.setTimeInMillis( cal.getTimeInMillis() );
-        gcal.setTimeInMillis( cal.getTimeInMillis() );
+    return ${supportingField.variableName}.newXMLGregorianCalendar( gcal );
-        return <@includeModel object=findType("DatatypeFactory")/>.newInstance().newXMLGregorianCalendar( gcal );
-    }
-    catch ( <@includeModel object=findType("DatatypeConfigurationException")/> ex ) {
-        throw new RuntimeException( ex );
-    }
 }

processor/src/main/resources/org/mapstruct/ap/internal/model/source/builtin/CalendarToZonedDateTime.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.SupportingMappingMethod" -->
 private <@includeModel object=findType("ZonedDateTime")/> ${name}(<@includeModel object=findType("Calendar")/> cal) {
     if ( cal == null ) {
         return null;

processor/src/main/resources/org/mapstruct/ap/internal/model/source/builtin/DateToXmlGregorianCalendar.ftl

@@ -5,17 +5,13 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.SupportingMappingMethod" -->
 private <@includeModel object=findType("XMLGregorianCalendar")/> ${name}( <@includeModel object=findType("Date")/> date ) {
     if ( date == null ) {
         return null;
     }
 
-    try {
+    <@includeModel object=findType("GregorianCalendar")/> c = new <@includeModel object=findType("GregorianCalendar")/>();
-        <@includeModel object=findType("GregorianCalendar")/> c = new <@includeModel object=findType("GregorianCalendar")/>();
+    c.setTime( date );
-        c.setTime( date );
+    return ${supportingField.variableName}.newXMLGregorianCalendar( c );
-        return <@includeModel object=findType("DatatypeFactory")/>.newInstance().newXMLGregorianCalendar( c );
-    }
-    catch ( <@includeModel object=findType("DatatypeConfigurationException")/> ex ) {
-        throw new RuntimeException( ex );
-    }
 }

processor/src/main/resources/org/mapstruct/ap/internal/model/source/builtin/FinalField.ftl

@@ -0,0 +1,9 @@
+<#--
+
+    Copyright MapStruct Authors.
+
+    Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+
+-->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.SupportingField" -->
+private final <@includeModel object=type/> ${variableName};

processor/src/main/resources/org/mapstruct/ap/internal/model/source/builtin/JaxbElemToValue.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.SupportingMappingMethod" -->
 private <T> T ${name}( <@includeModel object=findType("JAXBElement") raw=true/><T> element ) {
     if ( element == null ) {
         return null;

processor/src/main/resources/org/mapstruct/ap/internal/model/source/builtin/JodaDateTimeToXmlGregorianCalendar.ftl

@@ -5,23 +5,18 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.SupportingMappingMethod" -->
 private <@includeModel object=findType("XMLGregorianCalendar")/> ${name}( <@includeModel object=findType("DateTime")/> dt ) {
     if ( dt == null ) {
         return null;
     }
-
+    return ${supportingField.variableName}.newXMLGregorianCalendar(
-    try {
+        dt.getYear(),
-        return <@includeModel object=findType("DatatypeFactory")/>.newInstance().newXMLGregorianCalendar(
+        dt.getMonthOfYear(),
-            dt.getYear(),
+        dt.getDayOfMonth(),
-            dt.getMonthOfYear(),
+        dt.getHourOfDay(),
-            dt.getDayOfMonth(),
+        dt.getMinuteOfHour(),
-            dt.getHourOfDay(),
+        dt.getSecondOfMinute(),
-            dt.getMinuteOfHour(),
+        dt.getMillisOfSecond(),
-            dt.getSecondOfMinute(),
+        dt.getZone().getOffset( null ) / 60000 );
-            dt.getMillisOfSecond(),
-            dt.getZone().getOffset( null ) / 60000 );
-    }
-    catch ( <@includeModel object=findType("DatatypeConfigurationException")/> ex ) {
-        throw new RuntimeException( ex );
-    }
 }

processor/src/main/resources/org/mapstruct/ap/internal/model/source/builtin/JodaLocalDateTimeToXmlGregorianCalendar.ftl

@@ -5,23 +5,19 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.SupportingMappingMethod" -->
 private <@includeModel object=findType("XMLGregorianCalendar")/> ${name}( <@includeModel object=findType("org.joda.time.LocalDateTime")/> dt ) {
     if ( dt == null ) {
         return null;
     }
 
-    try {
+    return  ${supportingField.variableName}.newXMLGregorianCalendar(
-        return <@includeModel object=findType("DatatypeFactory")/>.newInstance().newXMLGregorianCalendar(
+        dt.getYear(),
-            dt.getYear(),
+        dt.getMonthOfYear(),
-            dt.getMonthOfYear(),
+        dt.getDayOfMonth(),
-            dt.getDayOfMonth(),
+        dt.getHourOfDay(),
-            dt.getHourOfDay(),
+        dt.getMinuteOfHour(),
-            dt.getMinuteOfHour(),
+        dt.getSecondOfMinute(),
-            dt.getSecondOfMinute(),
+        dt.getMillisOfSecond(),
-            dt.getMillisOfSecond(),
+        <@includeModel object=findType("DatatypeConstants")/>.FIELD_UNDEFINED );
-            <@includeModel object=findType("DatatypeConstants")/>.FIELD_UNDEFINED );
-    }
-    catch ( <@includeModel object=findType("DatatypeConfigurationException")/> ex ) {
-        throw new RuntimeException( ex );
-    }
 }

processor/src/main/resources/org/mapstruct/ap/internal/model/source/builtin/JodaLocalDateToXmlGregorianCalendar.ftl

@@ -5,19 +5,15 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.SupportingMappingMethod" -->
 private <@includeModel object=findType("XMLGregorianCalendar")/> ${name}( <@includeModel object=findType("org.joda.time.LocalDate")/> dt ) {
     if ( dt == null ) {
         return null;
     }
 
-    try {
+    return ${supportingField.variableName}.newXMLGregorianCalendarDate(
-        return <@includeModel object=findType("DatatypeFactory")/>.newInstance().newXMLGregorianCalendarDate(
+        dt.getYear(),
-            dt.getYear(),
+        dt.getMonthOfYear(),
-            dt.getMonthOfYear(),
+        dt.getDayOfMonth(),
-            dt.getDayOfMonth(),
+        <@includeModel object=findType("DatatypeConstants")/>.FIELD_UNDEFINED );
-            <@includeModel object=findType("DatatypeConstants")/>.FIELD_UNDEFINED );
-    }
-    catch ( <@includeModel object=findType("DatatypeConfigurationException")/> ex ) {
-        throw new RuntimeException( ex );
-    }
 }

processor/src/main/resources/org/mapstruct/ap/internal/model/source/builtin/JodaLocalTimeToXmlGregorianCalendar.ftl

@@ -5,20 +5,17 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.SupportingMappingMethod" -->
 private <@includeModel object=findType("XMLGregorianCalendar")/> ${name}( <@includeModel object=findType("org.joda.time.LocalTime")/> dt ) {
     if ( dt == null ) {
         return null;
     }
 
-    try {
+    return ${supportingField.variableName}.newXMLGregorianCalendarTime(
-        return <@includeModel object=findType("DatatypeFactory")/>.newInstance().newXMLGregorianCalendarTime(
+        dt.getHourOfDay(),
-            dt.getHourOfDay(),
+        dt.getMinuteOfHour(),
-            dt.getMinuteOfHour(),
+        dt.getSecondOfMinute(),
-            dt.getSecondOfMinute(),
+        dt.getMillisOfSecond(),
-            dt.getMillisOfSecond(),
+        <@includeModel object=findType("DatatypeConstants")/>.FIELD_UNDEFINED );
-            <@includeModel object=findType("DatatypeConstants")/>.FIELD_UNDEFINED );
+
-    }
-    catch ( <@includeModel object=findType("DatatypeConfigurationException")/> ex ) {
-        throw new RuntimeException( ex );
-    }
 }

processor/src/main/resources/org/mapstruct/ap/internal/model/source/builtin/LocalDateToXmlGregorianCalendar.ftl

@@ -5,20 +5,15 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
-private static <@includeModel object=findType("XMLGregorianCalendar")/> ${name}( <@includeModel object=findType("java.time.LocalDate")/> localDate ) {
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.SupportingMappingMethod" -->
+private <@includeModel object=findType("XMLGregorianCalendar")/> ${name}( <@includeModel object=findType("java.time.LocalDate")/> localDate ) {
     if ( localDate == null ) {
         return null;
     }
 
-    try {
+    return ${supportingField.variableName}.newXMLGregorianCalendarDate(
-        return <@includeModel object=findType("DatatypeFactory")/>.newInstance().newXMLGregorianCalendarDate(
+        localDate.getYear(),
-            localDate.getYear(),
+        localDate.getMonthValue(),
-            localDate.getMonthValue(),
+        localDate.getDayOfMonth(),
-            localDate.getDayOfMonth(),
+        <@includeModel object=findType("DatatypeConstants")/>.FIELD_UNDEFINED );
-            <@includeModel object=findType("DatatypeConstants")/>.FIELD_UNDEFINED
-        );
-    }
-    catch ( <@includeModel object=findType("DatatypeConfigurationException")/> ex ) {
-        throw new RuntimeException( ex );
-    }
 }

processor/src/main/resources/org/mapstruct/ap/internal/model/source/builtin/NewDatatypeFactoryConstructorFragment.ftl

@@ -0,0 +1,14 @@
+<#--
+
+    Copyright MapStruct Authors.
+
+    Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+
+-->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.SupportingConstructorFragment" -->
+try {
+     ${definingMethod.supportingField.variableName} = <@includeModel object=definingMethod.supportingField.type/>.newInstance();
+}
+catch ( <@includeModel object=definingMethod.findType("DatatypeConfigurationException")/> ex ) {
+    throw new RuntimeException( ex );
+}

processor/src/main/resources/org/mapstruct/ap/internal/model/source/builtin/StringToXmlGregorianCalendar.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.SupportingMappingMethod" -->
 private <@includeModel object=findType("XMLGregorianCalendar")/> ${name}( String date, String dateFormat ) {
     if ( date == null ) {
         return null;
@@ -15,15 +16,12 @@ private <@includeModel object=findType("XMLGregorianCalendar")/> ${name}( String
             <@includeModel object=findType("DateFormat")/> df = new <@includeModel object=findType("SimpleDateFormat")/>( dateFormat );
             <@includeModel object=findType("GregorianCalendar")/> c = new <@includeModel object=findType("GregorianCalendar")/>();
             c.setTime( df.parse( date ) );
-            return <@includeModel object=findType("DatatypeFactory")/>.newInstance().newXMLGregorianCalendar( c );
+            return ${supportingField.variableName}.newXMLGregorianCalendar( c );
         }
         else {
-            return <@includeModel object=findType("DatatypeFactory")/>.newInstance().newXMLGregorianCalendar( date );
+            return ${supportingField.variableName}.newXMLGregorianCalendar( date );
         }
     }
-    catch ( <@includeModel object=findType("DatatypeConfigurationException")/> ex ) {
-        throw new RuntimeException( ex );
-    }
     catch ( <@includeModel object=findType("ParseException")/> ex ) {
         throw new RuntimeException( ex );
     }

processor/src/main/resources/org/mapstruct/ap/internal/model/source/builtin/XmlGregorianCalendarToCalendar.ftl

@@ -5,6 +5,7 @@
     Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
+<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.SupportingMappingMethod" -->
 private <@includeModel object=findType("Calendar")/> ${name}( <@includeModel object=findType("XMLGregorianCalendar")/> xcal ) {
     if ( xcal == null ) {
         return null;