#3884 Ensure NullValuePropertyMappingStrategy.SET_TO_DEFAULT initializes empty collection/map when target is null

Signed-off-by: TangYang <tangyang9464@163.com>

.codecov.yml

@@ -0,0 +1,8 @@
+coverage:
+  status:
+    patch: off
+    project:
+      default:
+        # basic
+        threshold: 0.05
+comment: off

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: mapstruct
+open_collective: mapstruct

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,45 @@
+name: Bug report
+description: Create a report and help us improve
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please fill in all required fields with as many details as possible.
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: |
+        Describe what you were expecting MapStruct to do
+      placeholder: |
+        Here you can also add the generated code that you would like MapStruct to generate
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: |
+        Describe what you observed MapStruct did instead
+      placeholder: |
+        Here you can also add the generated code that MapStruct generated
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce the problem
+      description: |
+        - Share your mapping configuration
+        - An [MCVE (Minimal Complete Verifiable Example)](https://stackoverflow.com/help/minimal-reproducible-example) can be helpful to provide a complete reproduction case
+      placeholder: |
+        Share your MapStruct configuration
+    validations:
+      required: true
+  - type: input
+    id: mapstruct-version
+    attributes:
+      label: MapStruct Version
+      description: |
+        Which MapStruct version did you use?
+        Note: While you can obviously continue using older versions of MapStruct, it may well be that your bug is already fixed. If you're using an older version, please also try to reproduce the bug in the latest version of MapStruct before reporting it.
+      placeholder: ex. MapStruct 1.5.2
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,16 @@
+contact_links:
+  - name: MapStruct Discussions
+    url: https://github.com/mapstruct/mapstruct/discussions
+    about: Please use the MapStruct GitHub Discussions for open ended discussions and to reach out to the community.
+  - name: Stack Overflow
+    url: https://stackoverflow.com/questions/tagged/mapstruct
+    about: For questions about how to use MapStruct, consider asking your question on Stack Overflow, tagged [mapstruct].
+  - name: Documentation
+    url: https://mapstruct.org/documentation/stable/reference/html/
+    about: The MapStruct reference documentation.
+  - name: Gitter Chat
+    url: https://gitter.im/mapstruct/mapstruct-users
+    about: For realtime communication with the MapStruct community, consider writing in our Gitter chat room.
+  - name: MapStruct Examples
+    url: https://github.com/mapstruct/mapstruct-examples
+    about: Some examples of what can be achieved with MapStruct. (contributions are always welcome)

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,43 @@
+name: Feature Request
+description: Suggest an idea
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please describe the use-case you have. This will better help us understand the context in which you're looking for a new feature.
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use case
+      description: |
+        Please describe the use-case you have. This will better help us understand the context in which you're looking for a new feature.
+      placeholder: Describe the use-case here
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Generated Code
+      description: |
+        Please describe the possible generated code you'd like to see in MapStruct generate.
+        Please note, it's not always easy to describe a good solution. Describing the use-case above is much more important to us.
+      placeholder: Describe the possible solution here.
+    validations:
+      required: false
+  - type: textarea
+    id: workarounds
+    attributes:
+      label: Possible workarounds
+      description: |
+        Please describe the possible workarounds you've implemented to work around the lacking functionality.
+      placeholder: Describe the possible workarounds here.
+    validations:
+      required: false
+  - type: input
+    id: mapstruct-version
+    attributes:
+      label: MapStruct Version
+      description: What MapStruct version and edition did you try?
+      placeholder: ex. MapStruct 1.5.2
+    validations:
+      required: false

.github/scripts/update-website.sh

@@ -0,0 +1,82 @@
+#!/bin/bash
+#
+# Copyright MapStruct Authors.
+#
+# Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+#
+
+# env vars:
+# VERSION
+# GH_BOT_EMAIL
+
+# This script has been inspired by the JReleaser update-website.sh (https://github.com/jreleaser/jreleaser/blob/main/.github/scripts/update-website.sh)
+set -e
+
+function computePlainVersion() {
+  echo $1 | sed 's/\([[:digit:]]*\)\.\([[:digit:]]*\)\.\([[:digit:]]*\).*/\1.\2.\3/'
+}
+
+function computeMajorMinorVersion() {
+  echo $1 | sed 's/\([[:digit:]]*\)\.\([[:digit:]]*\).*/\1.\2/'
+}
+
+function isStable() {
+  local PLAIN_VERSION=$(computePlainVersion $1)
+  if [ "${PLAIN_VERSION}" == "$1" ]; then
+      echo "yes"
+  else
+      echo "no"
+  fi
+}
+
+STABLE=$(isStable $VERSION)
+MAJOR_MINOR_VERSION=$(computeMajorMinorVersion $VERSION)
+
+DEV_VERSION=`grep devVersion config.toml |  sed 's/.*"\(.*\)"/\1/'`
+MAJOR_MINOR_DEV_VERSION=$(computeMajorMinorVersion $DEV_VERSION)
+STABLE_VERSION=`grep stableVersion config.toml |  sed 's/.*"\(.*\)"/\1/'`
+MAJOR_MINOR_STABLE_VERSION=$(computeMajorMinorVersion $STABLE_VERSION)
+
+echo "📝 Updating versions"
+
+SEDOPTION="-i"
+if [[ "$OSTYPE" == "darwin"* ]]; then
+  SEDOPTION="-i ''"
+fi
+
+sed $SEDOPTION -e "s/^devVersion = \"\(.*\)\"/devVersion = \"${VERSION}\"/g" config.toml
+
+if [ "${STABLE}" == "yes" ]; then
+  sed $SEDOPTION -e "s/^stableVersion = \"\(.*\)\"/stableVersion = \"${VERSION}\"/g" config.toml
+  if [ "${MAJOR_MINOR_STABLE_VERSION}" != ${MAJOR_MINOR_VERSION} ]; then
+    echo "📝 Updating new stable version"
+    # This means that we have a new stable version and we need to change the order of the releases.
+    sed $SEDOPTION -e "s/^order = \(.*\)/order = 500/g" data/releases/${MAJOR_MINOR_VERSION}.toml
+    NEXT_STABLE_ORDER=$((`ls -1 data/releases | wc -l` - 2))
+    sed $SEDOPTION -e "s/^order = \(.*\)/order = ${NEXT_STABLE_ORDER}/g" data/releases/${MAJOR_MINOR_STABLE_VERSION}.toml
+    git add data/releases/${MAJOR_MINOR_STABLE_VERSION}.toml
+  fi
+elif [ "${MAJOR_MINOR_DEV_VERSION}" != "${MAJOR_MINOR_VERSION}" ]; then
+  echo "📝 Updating new dev version"
+  # This means that we are updating for a new dev version, but the last dev version is not the one that we are doing.
+  # Therefore, we need to update add the new data configuration
+  cp data/releases/${MAJOR_MINOR_DEV_VERSION}.toml data/releases/${MAJOR_MINOR_VERSION}.toml
+  sed $SEDOPTION -e "s/^order = \(.*\)/order = 1000/g" data/releases/${MAJOR_MINOR_VERSION}.toml
+fi
+
+sed $SEDOPTION -e "s/^name = \"\(.*\)\"/name = \"${VERSION}\"/g" data/releases/${MAJOR_MINOR_VERSION}.toml
+sed $SEDOPTION -e "s/^releaseDate = \(.*\)/releaseDate = $(date +%F)/g" data/releases/${MAJOR_MINOR_VERSION}.toml
+git add data/releases/${MAJOR_MINOR_VERSION}.toml
+git add config.toml
+
+echo "📝 Updating distribution resources"
+tar -xf tmp/mapstruct-${VERSION}-dist.tar.gz --directory tmp
+rm -rf static/documentation/${MAJOR_MINOR_VERSION}
+cp -R tmp/mapstruct-${VERSION}/docs static/documentation/${MAJOR_MINOR_VERSION}
+mv static/documentation/${MAJOR_MINOR_VERSION}/reference/html/mapstruct-reference-guide.html static/documentation/${MAJOR_MINOR_VERSION}/reference/html/index.html
+git add static/documentation/${MAJOR_MINOR_VERSION}
+
+git config --global user.email "${GH_BOT_EMAIL}"
+git config --global user.name "GitHub Action"
+git commit -a -m "Releasing version ${VERSION}"
+git push

.github/workflows/java-ea.yml

@@ -0,0 +1,21 @@
+name: Java EA
+
+on: [push]
+
+env:
+  MAVEN_ARGS: -V -B --no-transfer-progress -Dhttp.keepAlive=false -Dmaven.wagon.http.pool=false -Dmaven.wagon.httpconnectionManager.ttlSeconds=120
+
+jobs:
+  test_jdk_ea:
+    name: 'Linux JDK EA'
+    runs-on: ubuntu-latest
+    steps:
+      - name: 'Checkout'
+        uses: actions/checkout@v4
+      - name: 'Set up JDK'
+        uses: oracle-actions/setup-java@v1
+        with:
+          website: jdk.java.net
+          release: EA
+      - name: 'Test'
+        run: ./mvnw ${MAVEN_ARGS} -Djacoco.skip=true install -DskipDistribution=true

.github/workflows/macos.yml

@@ -0,0 +1,20 @@
+name: Mac OS CI
+
+on: push
+
+env:
+  MAVEN_ARGS: -V -B --no-transfer-progress -Dhttp.keepAlive=false -Dmaven.wagon.http.pool=false -Dmaven.wagon.httpconnectionManager.ttlSeconds=120
+
+jobs:
+  mac:
+    name: 'Mac OS'
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: 'Set up JDK 21'
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'zulu'
+          java-version: 21
+      - name: 'Test'
+        run: ./mvnw ${MAVEN_ARGS} install

.github/workflows/main.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on: [push, pull_request]
+
+env:
+  SONATYPE_USERNAME: ${{ secrets.SONATYPE_USERNAME }}
+  SONATYPE_PASSWORD: ${{ secrets.SONATYPE_PASSWORD }}
+  MAVEN_ARGS: -V -B --no-transfer-progress -Dhttp.keepAlive=false -Dmaven.wagon.http.pool=false -Dmaven.wagon.httpconnectionManager.ttlSeconds=120
+
+jobs:
+  test_jdk:
+    strategy:
+      fail-fast: false
+      matrix:
+        java: [21]
+    name: 'Linux JDK ${{ matrix.java }}'
+    runs-on: ubuntu-latest
+    steps:
+      - name: 'Checkout'
+        uses: actions/checkout@v4
+      - name: 'Set up JDK'
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'zulu'
+          java-version: ${{ matrix.java }}
+      - name: 'Test'
+        run: ./mvnw ${MAVEN_ARGS} -Djacoco.skip=${{ matrix.java != 21 }} install -DskipDistribution=${{ matrix.java != 21 }}
+      - name: 'Generate coverage report'
+        if: matrix.java == 21
+        run: ./mvnw jacoco:report
+      - name: 'Upload coverage to Codecov'
+        if: matrix.java == 21
+        uses: codecov/codecov-action@v2
+      - name: 'Publish Snapshots'
+        if: matrix.java == 21 && github.event_name == 'push' && github.ref == 'refs/heads/main' && github.repository == 'mapstruct/mapstruct'
+        run: ./mvnw -s etc/ci-settings.xml -DskipTests=true -DskipDistribution=true deploy
+  integration_test_jdk:
+    strategy:
+      fail-fast: false
+      matrix:
+        java: [ 8, 11, 17 ]
+    name: 'Linux JDK ${{ matrix.java }}'
+    runs-on: ubuntu-latest
+    steps:
+      - name: 'Checkout'
+        uses: actions/checkout@v4
+      - name: 'Set up JDK 21 for building everything'
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'zulu'
+          java-version: 21
+      - name: 'Install Processor'
+        run: ./mvnw ${MAVEN_ARGS} -DskipTests install -pl processor -am
+      - name: 'Set up JDK ${{ matrix.java }} for running integration tests'
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'zulu'
+          java-version: ${{ matrix.java }}
+      - name: 'Run integration tests'
+        run: ./mvnw ${MAVEN_ARGS} verify -pl integrationtest

.github/workflows/release.yml

@@ -0,0 +1,117 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Release version'
+        required: true
+      next:
+        description: 'Next version'
+        required: false
+
+jobs:
+  release:
+    # This job has been inspired by the moditect release (https://github.com/moditect/moditect/blob/main/.github/workflows/release.yml)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          java-version: 21
+          distribution: 'zulu'
+          cache: maven
+
+      - name: Set release version
+        id: version
+        run: |
+          RELEASE_VERSION=${{ github.event.inputs.version }}
+          NEXT_VERSION=${{ github.event.inputs.next }}
+          PLAIN_VERSION=`echo ${RELEASE_VERSION} | awk 'match($0, /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)/) { print substr($0, RSTART, RLENGTH); }'`
+          COMPUTED_NEXT_VERSION="${PLAIN_VERSION}-SNAPSHOT"
+          if [ -z $NEXT_VERSION ]
+          then
+            NEXT_VERSION=$COMPUTED_NEXT_VERSION
+          fi
+          ./mvnw -ntp -B versions:set versions:commit -DnewVersion=$RELEASE_VERSION -pl :mapstruct-parent -DgenerateBackupPoms=false
+          git config --global user.email "${{ vars.GH_BOT_EMAIL }}"
+          git config --global user.name "GitHub Action"
+          git commit -a -m "Releasing version $RELEASE_VERSION"
+          git push
+          echo "RELEASE_VERSION=$RELEASE_VERSION" >> $GITHUB_ENV
+          echo "NEXT_VERSION=$NEXT_VERSION" >> $GITHUB_ENV
+          echo "PLAIN_VERSION=$PLAIN_VERSION" >> $GITHUB_ENV
+
+      - name: Stage
+        run: |
+          export GPG_TTY=$(tty)
+          ./mvnw -ntp -B --file pom.xml \
+            -Dmaven.site.skip=true -Drelease=true -Ppublication,stage
+
+      - name: Release
+        env:
+          JRELEASER_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          JRELEASER_GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
+          JRELEASER_GPG_PUBLIC_KEY: ${{ secrets.GPG_PUBLIC_KEY }}
+          JRELEASER_GPG_SECRET_KEY: ${{ secrets.GPG_PRIVATE_KEY }}
+          JRELEASER_NEXUS2_MAVEN_CENTRAL_USERNAME: ${{ secrets.SONATYPE_USERNAME }}
+          JRELEASER_NEXUS2_MAVEN_CENTRAL_PASSWORD: ${{ secrets.SONATYPE_PASSWORD }}
+        run: |
+          ./mvnw -ntp -B --file pom.xml -pl :mapstruct-parent -Pjreleaser jreleaser:release
+
+      - name: JReleaser output
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: jreleaser-release
+          path: |
+            parent/target/jreleaser/trace.log
+            parent/target/jreleaser/output.properties
+
+      - name: Reset NEXT_RELEASE_CHANGELOG.md
+        run: |
+          echo -e "### Features\n\n### Enhancements\n\n### Bugs\n\n### Documentation\n\n### Build\n" > NEXT_RELEASE_CHANGELOG.md
+
+      - name: Set next version
+        run: |
+          ./mvnw -ntp -B versions:set versions:commit -DnewVersion=${{ env.NEXT_VERSION }} -pl :mapstruct-parent -DgenerateBackupPoms=false
+          sed -i -e "s@project.build.outputTimestamp>.*</project.build.outputTimestamp@project.build.outputTimestamp>\${git.commit.author.time}</project.build.outputTimestamp@g" parent/pom.xml
+          git config --global user.email "${{ vars.GH_BOT_EMAIL }}"
+          git config --global user.name "GitHub Action"
+          git commit -a -m "Next version ${{ env.NEXT_VERSION }}"
+          git push
+
+  update-website:
+    # This job has been inspired by the JReleaser update-website job (https://github.com/jreleaser/jreleaser/blob/main/.github/workflows/release.yml)
+    name: Update Website
+    needs: [release]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          repository: mapstruct/mapstruct.org
+          ref: main
+          fetch-depth: 0
+          token: ${{ secrets.GIT_WEBSITE_ACCESS_TOKEN }}
+
+      - name: Download assets
+        shell: bash
+        run: |
+          curl -sL https://raw.githubusercontent.com/mapstruct/mapstruct/main/.github/scripts/update-website.sh --output update-website.sh --create-dirs --output-dir tmp
+          curl -sL "https://github.com/mapstruct/mapstruct/releases/download/${VERSION}/mapstruct-${VERSION}-dist.tar.gz" --output mapstruct-${VERSION}-dist.tar.gz --create-dirs --output-dir tmp
+        env:
+          VERSION: ${{ github.event.inputs.version }}
+
+      - name: Commit
+        shell: bash
+        env:
+          VERSION: ${{ github.event.inputs.version }}
+          GH_BOT_EMAIL: ${{ vars.GH_BOT_EMAIL }}
+        run: |
+          chmod +x tmp/update-website.sh
+          tmp/update-website.sh

.github/workflows/windows.yml

@@ -0,0 +1,20 @@
+name: Windows CI
+
+on: push
+
+env:
+  MAVEN_ARGS: -V -B --no-transfer-progress -Dhttp.keepAlive=false -Dmaven.wagon.http.pool=false -Dmaven.wagon.httpconnectionManager.ttlSeconds=120
+
+jobs:
+  windows:
+    name: 'Windows'
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: 'Set up JDK 21'
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'zulu'
+          java-version: 21
+      - name: 'Test'
+        run: ./mvnw %MAVEN_ARGS% install

.gitignore

@@ -1,5 +1,6 @@
 # Eclipse
 .metadata
+.recommenders
 .classpath
 .project
 .settings
@@ -13,6 +14,14 @@
 *.iws
 .idea
 
+# Netbeans
+nb-configuration.xml
+
 # Build
-/*/target
+/**/target/
 test-output
+
+# Misc.
+.DS_Store
+checkstyle.cache
+.flattened-pom.xml

.mvn/wrapper/maven-wrapper.properties

@@ -0,0 +1,19 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+wrapperVersion=3.3.2
+distributionType=only-script
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.9/apache-maven-3.9.9-bin.zip

CONTRIBUTING.md

@@ -5,13 +5,15 @@ You love MapStruct but miss a certain feature? You found a bug and want to repor
 * Source code: [http://github.com/mapstruct/mapstruct](http://github.com/mapstruct/mapstruct)
 * Issue tracker: [https://github.com/mapstruct/mapstruct/issues](https://github.com/mapstruct/mapstruct/issues)
 * Discussions: Join the [mapstruct-users](https://groups.google.com/forum/?fromgroups#!forum/mapstruct-users) Google group
-* CI build: [https://mapstruct.ci.cloudbees.com](https://mapstruct.ci.cloudbees.com)
+* CI build: [https://github.com/mapstruct/mapstruct/actions/](https://github.com/mapstruct/mapstruct/actions)
 
 MapStruct follows the _Fork & Pull_ development approach. To get started just fork the [MapStruct repository](http://github.com/mapstruct/mapstruct) to your GitHub account and create a new topic branch for each change. Once you are done with your change, submit a [pull request](https://help.github.com/articles/using-pull-requests) against the MapStruct repo.
 
 When doing changes, keep the following best practices in mind:
 
 * Provide test cases
+* Use the code formatter for your IDE
+  * [IntelliJ Formatter](https://github.com/mapstruct/mapstruct/blob/master/etc/mapstruct.xml)
 * Update the [reference documentation](mapstruct.org/documentation) on [mapstruct.org](mapstruct.org) where required
 * Discuss new features you'd like to implement at the [Google group](https://groups.google.com/forum/?fromgroups#!forum/mapstruct-users) before getting started
 * Create one pull request per feature

LICENSE.txt

@@ -1,19 +1,6 @@
- Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- and/or other contributors as indicated by the @authors tag. See the
- copyright.txt file in the distribution for a full listing of all
- contributors.
+ Copyright MapStruct Authors.
 
- MapStruct is licensed under the Apache License, Version 2.0 (the
- "License"); you may not use this software except in compliance with the
- License. You may obtain a copy of the License at
-
-     http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
+ MapStruct is licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 ------------------------------------------------------------------------
 

NEXT_RELEASE_CHANGELOG.md

@@ -0,0 +1,29 @@
+### Features
+
+* Support for Java 21 Sequenced Collections (#3240)
+
+
+### Enhancements
+
+* Add support for locale parameter for numberFormat and dateFormat (#3628)
+* Detect Builder without a factory method (#3729) - With this if there is an inner class that ends with `Builder` and has a constructor with parameters, 
+it will be treated as a potential builder. 
+Builders through static methods on the type have a precedence.
+* Behaviour change: Warning when the target has no target properties (#1140)
+
+
+
+### Bugs
+
+* Improve error message when mapping non-iterable to array (#3786)
+
+### Documentation
+
+### Build
+
+### Behaviour Change
+
+#### Warning when the target has no target properties
+
+With this change, if the target bean does not have any target properties, a warning will be shown.
+This is like this to avoid potential mistakes by users, where they might think that the target bean has properties, but it does not.

build-config/pom.xml

@@ -1,22 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
 
- Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- and/or other contributors as indicated by the @authors tag. See the
- copyright.txt file in the distribution for a full listing of all
- contributors.
+    Copyright MapStruct Authors.
 
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
-     http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
+    Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
@@ -25,7 +12,7 @@
     <parent>
         <groupId>org.mapstruct</groupId>
         <artifactId>mapstruct-parent</artifactId>
-        <version>1.0.0.Beta3</version>
+        <version>1.7.0-SNAPSHOT</version>
         <relativePath>../parent/pom.xml</relativePath>
     </parent>
 
@@ -33,15 +20,7 @@
     <packaging>jar</packaging>
     <name>MapStruct Build Configuration</name>
 
-    <build>
-        <plugins>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-deploy-plugin</artifactId>
-                <configuration>
-                    <skip>true</skip>
-                </configuration>
-            </plugin>
-        </plugins>
-    </build>
+    <properties>
+        <maven.deploy.skip>true</maven.deploy.skip>
+    </properties>
 </project>

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

@@ -15,6 +15,8 @@
         <property name="basedir" value="${basedir}"/>
     -->
 
+    <property name="cacheFile" value="${checkstyle.cache.file}"/>
+
     <!-- Checks that each Java package has a Javadoc file used for commenting. -->
     <!-- See http://checkstyle.sf.net/config_javadoc.html#JavadocPackage       -->
     <!--
@@ -27,7 +29,16 @@
     <!-- See http://checkstyle.sf.net/config_misc.html#Translation -->
     <module name="Translation"/>
 
-    <module name="FileLength"/>
+    <module name="FileLength">
+        <property name="max" value="2500"/>
+    </module>
+
+    <module name="LineLength">
+        <property name="max" value="120"/>
+        <property name="fileExtensions" value="java" />
+    </module>
+
+    <module name="SuppressWithPlainTextCommentFilter"/>
 
     <!-- Following interprets the header file as regular expressions. -->
     <!-- <module name="RegexpHeader"/>                                -->
@@ -52,12 +63,15 @@
         <property name="message" value="Line has trailing spaces"/>
     </module>
 
+    <module name="RegexpSingleline">
+        <!-- do not allow a package declaration that contains ".target." or "target;"  -->
+        <property name="format" value="^package .*\.target[\.;]"/>
+        <property name="message" value="Do not use &quot;target&quot; as package name element"/>
+    </module>
+
     <module name="TreeWalker">
 
-        <property name="cacheFile" value="${checkstyle.cache.file}"/>
-
-        <!-- Required for SuppressionCommentFilter -->
-        <module name="FileContentsHolder"/>
+        <module name="SuppressWarningsHolder"/>
 
         <!-- Checks for Javadoc comments.                     -->
         <!-- See http://checkstyle.sf.net/config_javadoc.html -->
@@ -110,10 +124,6 @@
 
         <!-- Checks for Size Violations.                    -->
         <!-- See http://checkstyle.sf.net/config_sizes.html -->
-        <module name="LineLength">
-            <property name="max" value="120"/>
-        </module>
-        <module name="MethodLength"/>
         <module name="ParameterNumber">
             <property name="max" value="10"/>
         </module>
@@ -136,8 +146,15 @@
         </module>
         <module name="TypecastParenPad"/>
         <module name="WhitespaceAfter"/>
-        <module name="WhitespaceAround"/>
+        <module name="WhitespaceAround">
+            <property name="ignoreEnhancedForColon" value="false"/>
+        </module>
 
+        <module name="EmptyLineSeparator">
+            <property name="tokens" value="IMPORT, CLASS_DEF, INTERFACE_DEF, STATIC_INIT, INSTANCE_INIT, METHOD_DEF, CTOR_DEF, VARIABLE_DEF"/>
+            <property name="allowNoEmptyLineBetweenFields" value="true"/>
+            <property name="allowMultipleEmptyLines" value="false"/>
+        </module>
 
         <!-- Modifier Checks                                    -->
         <!-- See http://checkstyle.sf.net/config_modifiers.html -->
@@ -177,7 +194,10 @@
         <!-- <module name="FinalClass"/> -->
         <module name="HideUtilityClassConstructor"/>
         <module name="InterfaceIsType"/>
-        <module name="VisibilityModifier"/>
+        <module name="VisibilityModifier">
+            <property name="packageAllowed" value="true" />
+            <property name="protectedAllowed" value="true" />
+        </module>
 
 
         <!-- Miscellaneous other checks.                   -->
@@ -187,8 +207,9 @@
         <!-- <module name="TodoComment"/> -->
         <module name="UpperEll"/>
 
+        <module name="SuppressionCommentFilter"/>
     </module>
 
-    <module name="SuppressionCommentFilter"/>
+    <module name="SuppressWarningsFilter"/>
 
 </module>

build-config/src/main/resources/build-config/import-control.xml

@@ -10,8 +10,8 @@
         <!-- the annotation processor may not use the annotations or enums specified in org.mapstruct directly... -->
         <disallow pkg="org.mapstruct" exact-match="true" />
 
-        <subpackage name="prism">
-            <!-- ... with exception to the package org.mapstruct.ap.prism -->
+        <subpackage name="internal.gem">
+            <!-- ... with exception to the package org.mapstruct.ap.internal.gem -->
             <allow pkg=".*" regex="true" /> 
         </subpackage>
         <subpackage name="test">

copyright.txt

@@ -1,8 +1,73 @@
-Contributors
+Contributors
 ============
 
-Andreas Gudian
-Christian Schuster
-Gunnar Morling
-Sjaak Derksen
-Timo Eckhardt
+Alexandr Shalugin - https://github.com/shalugin
+Amine Touzani - https://github.com/ttzn
+Andreas Gudian - https://github.com/agudian
+Andrei Arlou - https://github.com/Captain1653
+Andres Jose Sebastian Rincon Gonzalez - https://github.com/stianrincon
+Arne Seime - https://github.com/seime
+Christian Bandowski - https://github.com/chris922
+Chris DeLashmutt - https://github.com/cdelashmutt-pivotal
+Christian Kosmowski - https://github.com/ckosmowski
+Christian Schuster - https://github.com/chschu
+Christophe Labouisse - https://github.com/ggtools
+Ciaran Liedeman - https://github.com/cliedeman
+Cindy Wang - https://github.com/birdfriend
+Cornelius Dirmeier - https://github.com/cornzy
+David Feinblum - https://github.com/dvfeinblum
+Darren Rambaud - https://github.com/xyzst
+Dekel Pilli - https://github.com/dekelpilli
+Dilip Krishnan - https://github.com/dilipkrish
+Dmytro Polovinkin - https://github.com/navpil
+Ewald Volkert - https://github.com/eforest
+Eric Martineau - https://github.com/ericmartineau
+Ewald Volkert - https://github.com/eforest
+Filip Hrisafov - https://github.com/filiphr
+Florian Tavares - https://github.com/neoXfire
+Gervais Blaise - https://github.com/gervaisb
+Gibou Damien - https://github.com/dmngb
+Gunnar Morling - https://github.com/gunnarmorling
+Ivo Smid - https://github.com/bedla
+Jason Bodnar - https://github.com/Blackbaud-JasonBodnar
+Jeroen van Wilgenburg - https://github.com/jvwilge
+Jeff Smyth - https://github.com/smythie86
+João Paulo Bassinello - https://github.com/jpbassinello
+Jonathan Kraska - https://github.com/jakraska
+Joshua Spoerri - https://github.com/spoerri
+Jude Niroshan - https://github.com/JudeNiroshan
+Justyna Kubica-Ledzion - https://github.com/JKLedzion
+Kemal Özcan - https://github.com/yekeoe
+Kevin Grüneberg - https://github.com/kevcodez
+Lukas Lazar - https://github.com/LukeLaz
+Nikolas Charalambidis - https://github.com/Nikolas-Charalambidis
+Michael Pardo - https://github.com/pardom
+Muhammad Usama - https://github.com/the-mgi
+Mustafa Caylak - https://github.com/luxmeter
+Oliver Ehrenmüller - https://github.com/greuelpirat
+Oliver Erhart - https://github.com/thunderhook
+Paul Strugnell - https://github.com/ps-powa
+Pascal Grün - https://github.com/pascalgn
+Pavel Makhov - https://github.com/streetturtle
+Peter Larson - https://github.com/pjlarson
+Remko Plantenga - https://github.com/sonata82
+Remo Meier - https://github.com/remmeier
+Richard Lea - https://github.com/chigix
+Saheb Preet Singh - https://github.com/sahebpreet
+Samuel Wright - https://github.com/samwright
+Sebastian Haberey - https://github.com/sebastianhaberey
+Sebastian Hasait - https://github.com/shasait
+Sean Huang - https://github.com/seanjob
+Sjaak Derksen - https://github.com/sjaakd
+Stefan May - https://github.com/osthus-sm
+Taras Mychaskiw - https://github.com/twentylemon
+Thibault Duperron - https://github.com/Zomzog
+Tomáš Poledný - https://github.com/Saljack
+Tobias Meggendorfer - https://github.com/incaseoftrouble
+Tillmann Gaida - https://github.com/Tillerino
+Timo Eckhardt - https://github.com/timoe
+Tomek Gubala - https://github.com/vgtworld
+Valentin Kulesh - https://github.com/unshare
+Vincent Alexander Beelte - https://github.com/grandmasterpixel
+Winter Andreas - https://github.dev/wandi34
+Xiu Hong Kooi - https://github.com/kooixh

core-common/pom.xml

@@ -1,77 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
-
- Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- and/or other contributors as indicated by the @authors tag. See the
- copyright.txt file in the distribution for a full listing of all
- contributors.
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
-     http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
-
--->
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-    <modelVersion>4.0.0</modelVersion>
-
-    <parent>
-        <groupId>org.mapstruct</groupId>
-        <artifactId>mapstruct-parent</artifactId>
-        <version>1.0.0.Beta3</version>
-        <relativePath>../parent/pom.xml</relativePath>
-    </parent>
-
-    <artifactId>mapstruct-common</artifactId>
-    <packaging>jar</packaging>
-    <name>MapStruct Core Common</name>
-
-    <properties>
-        <maven.javadoc.skip>true</maven.javadoc.skip>
-    </properties>
-
-    <dependencies>
-        <dependency>
-            <groupId>junit</groupId>
-            <artifactId>junit</artifactId>
-            <scope>test</scope>
-        </dependency>
-        <dependency>
-            <groupId>org.easytesting</groupId>
-            <artifactId>fest-assert</artifactId>
-            <scope>test</scope>
-        </dependency>
-    </dependencies>
-
-    <build>
-        <plugins>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-checkstyle-plugin</artifactId>
-                <executions>
-                    <execution>
-                        <id>check-style</id>
-                        <phase>verify</phase>
-                        <goals>
-                            <goal>checkstyle</goal>
-                        </goals>
-                    </execution>
-                </executions>
-            </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-deploy-plugin</artifactId>
-                <configuration>
-                    <skip>true</skip>
-                </configuration>
-            </plugin>
-        </plugins>
-    </build>
-</project>

core-common/src/main/java/org/mapstruct/CollectionMappingStrategy.java

@@ -1,62 +0,0 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
- *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- */
-package org.mapstruct;
-
-/**
- * Strategy for propagating the value of collection-typed properties from source to target.
- *
- * @author Sjaak Derksen
- */
-public enum CollectionMappingStrategy {
-
-    /**
-     * The setter of the target property will be used to propagate the value:
-     * {@code orderDto.setOrderLines( order.getOrderLines )}.
-     * <p>
-     * If no setter is available but a getter method, this will be used, under the assumption it has been initialized:
-     * {@code orderDto.getOrderLines().addAll( order.getOrderLines )}.
-     */
-    ACCESSOR_ONLY,
-
-    /**
-     * If present, the setter of the target property will be used to propagate the value:
-     * {@code orderDto.setOrderLines( order.getOrderLines )}.
-     * <p>
-     * If no setter but and adder method is present, that adder will be invoked for each element of the source
-     * collection: {@code order.addOrderLine( orderLine() )}.
-     * <p>
-     * If neither a setter nor an adder method but a getter for the target property is present, that getter will be
-     * used, assuming it returns an initialized collection: If no setter is available, MapStruct will first look for an
-     * adder method before resorting to a getter.
-     */
-    SETTER_PREFERRED,
-
-    /**
-     * Identical to {@link #SETTER_PREFERRED}, only that adder methods will be preferred over setter methods, if both
-     * are present for a given collection-typed property.
-     */
-    ADDER_PREFERRED,
-
-    /**
-     * If given via {@link Mapper#collectionMappingStrategy()}, causes the setting specified via
-     * {@link MapperConfig#collectionMappingStrategy()} to be applied, if present. Otherwise causes
-     * {@link #ACCESSOR_ONLY} to be applied.
-     */
-    DEFAULT;
-}

core-common/src/main/java/org/mapstruct/DecoratedWith.java

@@ -1,56 +0,0 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
- *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- */
-package org.mapstruct;
-
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-
-/**
- * Specifies a decorator to be applied to a generated mapper, which e.g. can be used to amend mappings performed by
- * generated mapping methods.
- * <p>
- * A typical decorator implementation will be an abstract class and only implement/override a subset of the methods of
- * the mapper type which it decorates. All methods not implemented or overridden by the decorator will be implemented by
- * the code generator.
- * <p>
- * If a constructor with a single parameter accepting the type of the decorated mapper is present, a delegate with
- * generated implementations of all the mapper methods will be passed to this constructor. A typical implementation will
- * store the passed delegate in a field of the decorator and make use of it in the decorator methods.
- * <p>
- * <b>NOTE:</b> The decorator feature is considered experimental and it may change in future releases. Currently
- * decorators are only supported for the default component model, not for the CDI and Spring models.
- *
- * @author Gunnar Morling
- */
-@Target(ElementType.TYPE)
-@Retention(RetentionPolicy.SOURCE)
-public @interface DecoratedWith {
-
-    /**
-     * The decorator type. Must extend or implement the mapper type to which it is applied.
-     * <p>
-     * The decorator type must either have a default constructor or a constructor with a single parameter accepting the
-     * type of the decorated mapper.
-     *
-     * @return the decorator type
-     */
-    Class<?> value();
-}

core-common/src/main/java/org/mapstruct/InheritInverseConfiguration.java

@@ -1,51 +0,0 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
- *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- */
-package org.mapstruct;
-
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-
-/**
- * Advises the code generator to apply all the {@link Mapping}s from an inverse mapping method to the annotated method
- * as well. An inverse mapping method is a method which has the annotated method's source type as target type (return
- * type or indicated through a parameter annotated with {@link MappingTarget}) and the annotated method's target type as
- * source type.
- * <p>
- * Any mappings given on the annotated method itself are added to those mappings inherited from the inverse method. In
- * case of a conflict local mappings take precedence over inherited mappings.
- * <p>
- * If more than one matching inverse method exists, the name of the method to inherit the configuration from must be
- * specified via {@link #name()}
- *
- * @author Sjaak Derksen
- */
-@Target( ElementType.METHOD )
-@Retention( RetentionPolicy.SOURCE )
-public @interface InheritInverseConfiguration {
-
-    /**
-     * The name of the inverse mapping method to inherit the mappings from. Needs only to be specified in case more than
-     * one inverse method with matching source and target type exists.
-     *
-     * @return The name of the inverse mapping method to inherit the mappings from.
-     */
-    String name() default "";
-}

core-common/src/main/java/org/mapstruct/IterableMapping.java

@@ -1,55 +0,0 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
- *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- */
-package org.mapstruct;
-
-import java.lang.annotation.Annotation;
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-import java.text.SimpleDateFormat;
-import java.util.Date;
-
-/**
- * Configures the mapping between two iterable types, e.g. {@code List<String>} and {@code List<Date>}.
- *
- * @author Gunnar Morling
- */
-@Target(ElementType.METHOD)
-@Retention(RetentionPolicy.SOURCE)
-public @interface IterableMapping {
-
-    /**
-     * A format string as processable by {@link SimpleDateFormat} if the annotated method maps from an iterable of
-     * {@code String} to an iterable {@link Date} or vice-versa. Will be ignored for all other element types.
-     *
-     * @return A date format string as processable by {@link SimpleDateFormat}.
-     */
-    String dateFormat();
-
-    /**
-     * A qualifier can be specified to aid the selection process of a suitable mapper. This is useful in case multiple
-     * mappers (hand written of internal) qualify and result in an 'Ambiguous mapping methods found' error.
-     *
-     * A qualifier is a custom annotation and can be placed on either a hand written mapper class or a method.
-     *
-     * @return the qualifiers
-     */
-    Class<? extends Annotation>[] qualifiedBy() default { };
-}

core-common/src/main/java/org/mapstruct/MapMapping.java

@@ -1,76 +0,0 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
- *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- */
-package org.mapstruct;
-
-import java.lang.annotation.Annotation;
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-import java.text.SimpleDateFormat;
-import java.util.Date;
-
-/**
- * Configures the mapping between two map types, e.g. {@code Map<String, String>} and {@code Map<Long, Date>}.
- *
- * @author Gunnar Morling
- */
-@Target(ElementType.METHOD)
-@Retention(RetentionPolicy.SOURCE)
-public @interface MapMapping {
-
-    /**
-     * A format string as processable by {@link SimpleDateFormat} if the annotated method maps from a map with key type
-     * {@code String} to an map with key type {@link Date} or vice-versa. Will be ignored for all other key types.
-     *
-     * @return A date format string as processable by {@link SimpleDateFormat}.
-     */
-    String keyDateFormat() default "";
-
-    /**
-     * A format string as processable by {@link SimpleDateFormat} if the annotated method maps from a map with value
-     * type {@code String} to an map with value type {@link Date} or vice-versa. Will be ignored for all other value
-     * types.
-     *
-     * @return A date format string as processable by {@link SimpleDateFormat}.
-     */
-    String valueDateFormat() default "";
-
-    /**
-     * A key value qualifier can be specified to aid the selection process of a suitable mapper. This is useful in
-     * case multiple mappers (hand written of internal) qualify and result in an 'Ambiguous mapping methods found'
-     * error.
-     *
-     * A qualifier is a custom annotation and can be placed on either a hand written mapper class or a method.
-     *
-     * @return the qualifiers
-     */
-    Class<? extends Annotation>[] keyQualifiedBy() default { };
-
-
-    /**
-     * A value qualifier can be specified to aid the selection process of a suitable mapper. This is useful in case
-     * multiple mappers (hand written of internal) qualify and result in an 'Ambiguous mapping methods found' error.
-     *
-     * A qualifier is a custom annotation and can be placed on either a hand written mapper class or a method.
-     *
-     * @return the qualifiers
-     */
-    Class<? extends Annotation>[] valueQualifiedBy() default { };
-}

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

@@ -1,115 +0,0 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
- *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- */
-package org.mapstruct;
-
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-
-import org.mapstruct.factory.Mappers;
-
-/**
- * Marks an interface as mapper interface and activates the generation of a
- * mapper implementation for that interface.
- *
- * @author Gunnar Morling
- */
-@Target(ElementType.TYPE)
-@Retention(RetentionPolicy.CLASS)
-public @interface Mapper {
-
-    /**
-     * The mapper types used by this mapper.
-     *
-     * @return The mapper types used by this mapper.
-     */
-    Class<?>[] uses() default { };
-
-    /**
-     * Additional types for which an import statement is to be added to the generated mapper implementation class.
-     * This allows to refer to those types from within mapping expressions given via {@link Mapping#expression()} using
-     * their simple name rather than their fully-qualified name.
-     *
-     * @return classes to add in the imports of the generated implementation.
-     */
-    Class<?>[] imports() default { };
-
-    /**
-     * How unmapped properties of the target type of a mapping should be
-     * reported. The method overrides an unmappedTargetPolicy set in a central
-     * configuration set by {@link #config() }
-     *
-     * @return The reporting policy for unmapped target properties.
-     */
-    ReportingPolicy unmappedTargetPolicy() default ReportingPolicy.DEFAULT;
-
-    /**
-     * Specifies the component model to which the generated mapper should
-     * adhere. Supported values are
-     * <ul>
-     * <li> {@code default}: the mapper uses no component model, instances are
-     * typically retrieved via {@link Mappers#getMapper(Class)}</li>
-     * <li>
-     * {@code cdi}: the generated mapper is an application-scoped CDI bean and
-     * can be retrieved via {@code @Inject}</li>
-     * <li>
-     * {@code spring}: the generated mapper is a Spring bean and
-     * can be retrieved via {@code @Autowired}</li>
-     * <li>
-     * {@code jsr330}: the generated mapper is annotated with {@code @Named} and
-     * can be retrieved via {@code @Inject}</li>
-     * </ul>
-     * The method overrides an unmappedTargetPolicy set in a central configuration set
-     * by {@link #config() }
-     *
-     * @return The component model for the generated mapper.
-     */
-    String componentModel() default "default";
-
-    /**
-     * A class annotated with {@link MapperConfig} which should be used as configuration template. Any settings given
-     * via {@link Mapper} will take precedence over the settings from the referenced configuration source. The list of
-     * referenced mappers will contain all mappers given via {@link Mapper#uses()} and {@link MapperConfig#uses()}.
-     *
-     * @return A class which should be used as configuration template.
-     */
-    Class<?> config() default void.class;
-
-    /**
-     * The strategy to be applied when propagating the value of collection-typed properties. By default, only JavaBeans
-     * accessor methods (setters or getters) will be used, but it is also possible to invoke a corresponding adder
-     * method for each element of the source collection (e.g. {@code orderDto.addOrderLine()}).
-     * <p>
-     * Any setting given for this attribute will take precedence over {@link MapperConfig#collectionMappingStrategy()},
-     * if present.
-     *
-     * @return The strategy applied when propagating the value of collection-typed properties.
-     */
-    CollectionMappingStrategy collectionMappingStrategy() default CollectionMappingStrategy.DEFAULT;
-
-    /**
-     * The strategy to be applied when {@code null} is passed as source value to the methods of this mapper. If no
-     * strategy is configured, the strategy given via {@link MapperConfig#nullValueMappingStrategy()} will be applied,
-     * using {@link NullValueMappingStrategy#RETURN_NULL} by default.
-     *
-     * @return The strategy to be applied when {@code null} is passed as source value to the methods of this mapper.
-     */
-    NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.DEFAULT;
-}

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

@@ -1,92 +0,0 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
- *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- */
-package org.mapstruct;
-
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-
-import org.mapstruct.factory.Mappers;
-
-/**
- * Marks a class-, interface-, enum declaration as (common) configuration.
- *
- * The {@link #unmappedTargetPolicy() } and {@link #componentModel() } can be overruled by a specific {@link Mapper}
- * annotation. {@link #uses() } will be used in addition to what is specified in the {@link Mapper} annotation.
- *
- * @author Sjaak Derksen
- */
-@Target(ElementType.TYPE)
-@Retention(RetentionPolicy.CLASS)
-public @interface MapperConfig {
-
-    /**
-     * The mapper types used by this mapper.
-     *
-     * @return The mapper types used by this mapper.
-     */
-    Class<?>[] uses() default { };
-
-    /**
-     * How unmapped properties of the target type of a mapping should be
-     * reported.
-     *
-     * @return The reporting policy for unmapped target properties.
-     */
-    ReportingPolicy unmappedTargetPolicy() default ReportingPolicy.WARN;
-
-    /**
-     * Specifies the component model to which the generated mapper should
-     * adhere. Supported values are
-     * <ul>
-     * <li> {@code default}: the mapper uses no component model, instances are
-     * typically retrieved via {@link Mappers#getMapper(Class)}</li>
-     * <li>
-     * {@code cdi}: the generated mapper is an application-scoped CDI bean and
-     * can be retrieved via {@code @Inject}</li>
-     * <li>
-     * {@code spring}: the generated mapper is a Spring bean and
-     * can be retrieved via {@code @Autowired}</li>
-     * <li>
-     * {@code jsr330}: the generated mapper is annotated with {@code @Named} and
-     * can be retrieved via {@code @Inject}</li>
-     * </ul>
-     *
-     * @return The component model for the generated mapper.
-     */
-    String componentModel() default "default";
-
-    /**
-     * The strategy to be applied when propagating the value of collection-typed properties. By default, only JavaBeans
-     * accessor methods (setters or getters) will be used, but it is also possible to invoke a corresponding adder
-     * method for each element of the source collection (e.g. {@code orderDto.addOrderLine()}).
-     *
-     * @return The strategy applied when propagating the value of collection-typed properties.
-     */
-    CollectionMappingStrategy collectionMappingStrategy() default CollectionMappingStrategy.DEFAULT;
-
-    /**
-     * The strategy to be applied when {@code null} is passed as source value to mapping methods. If no strategy is
-     * configured, {@link NullValueMappingStrategy#RETURN_NULL} will be used by default.
-     *
-     * @return The strategy to be applied when {@code null} is passed as source value to mapping methods.
-     */
-    NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.DEFAULT;
-}

core-common/src/main/java/org/mapstruct/MappingTarget.java

@@ -1,36 +0,0 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
- *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- */
-package org.mapstruct;
-
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-
-/**
- * Declares a parameter of a mapping method to be the target of the mapping.
- * <p>
- * Not more than one parameter can be declared as {@code MappingTarget}.
- *
- * @author Andreas Gudian
- */
-@Target(ElementType.PARAMETER)
-@Retention(RetentionPolicy.CLASS)
-public @interface MappingTarget {
-}

core-common/src/main/java/org/mapstruct/NullValueMapping.java

@@ -1,44 +0,0 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
- *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- */
-package org.mapstruct;
-
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-
-/**
- * Specifies how the annotated method should deal with {@code null} values.
- * <p>
- * If no strategy is configured explicitly for a given method, the configuration from the enclosing mapper will be
- * applied, using {@link NullValueMappingStrategy#RETURN_NULL} by default.
- *
- * @author Sjaak Derksen
- */
-@Target({ ElementType.METHOD })
-@Retention(RetentionPolicy.SOURCE)
-public @interface NullValueMapping {
-
-    /**
-     * The strategy for mapping null values.
-     *
-     * @return The strategy for mapping null values
-     */
-    NullValueMappingStrategy value();
-}

core-common/src/main/java/org/mapstruct/NullValueMappingStrategy.java

@@ -1,58 +0,0 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
- *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- */
-package org.mapstruct;
-
-/**
- * Strategy for dealing with {@code null} values passed to mapping methods.
- *
- * @author Sjaak Derksen
- */
-public enum NullValueMappingStrategy {
-
-    /**
-     * If {@code null} is passed to a mapping method, {@code null} will be returned. That's the default behavior if no
-     * alternative strategy is configured globally, for given mapper or method.
-     */
-    RETURN_NULL,
-
-    /**
-     * If {@code null} is passed to a mapping method, a default value will be returned. The value depends on the kind of
-     * the annotated method:
-     * <ul>
-     * <li>For bean mapping methods the target type will be instantiated and returned. Any properties of the target type
-     * which are mapped via {@link Mapping#expression()} or {@link Mapping#constant()} will be populated based on the
-     * given expression or constant. Note that expressions must be prepared to deal with {@code null} values in this
-     * case.</li>
-     * <li>For iterable mapping methods an empty collection will be returned.</li>
-     * <li>For map mapping methods an empty map will be returned.</li>
-     * </ul>
-     */
-    RETURN_DEFAULT,
-
-    /**
-     * When given via {@link Mapper#nullValueMappingStrategy()}, causes the setting specified via
-     * {@link MapperConfig#nullValueMappingStrategy()} to be applied, if present.
-     * <p>
-     * When given via {@link NullValueMapping#value()}, causes the setting specified via
-     * {@link Mapper#nullValueMappingStrategy() ()} to be applied, if present.
-     * <p>
-     * Otherwise causes {@link #RETURN_NULL} to be applied.
-     */
-    DEFAULT;
-}

core-common/src/main/java/org/mapstruct/Qualifier.java

@@ -1,50 +0,0 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
- *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- */
-package org.mapstruct;
-
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-
-/**
- * Declares an annotation type to be a qualifier. Qualifier annotations allow unambiguously identify a suitable mapping
- * method in case several methods qualify to map a bean property, iterable element etc.
- * <p>
- * For more info see:
- * <ul>
- * <li>{@link Mapping#qualifiedBy() }</li>
- * <li>{@link IterableMapping#qualifiedBy() }</li>
- * <li>{@link MapMapping#keyQualifiedBy() }</li>
- * <li>{@link MapMapping#valueQualifiedBy() }</li>
- * </ul>
- * Example:
- * <pre>
- * &#64;Qualifier
- * &#64;Target(ElementType.METHOD)
- * &#64;Retention(RetentionPolicy.SOURCE)
- * public &#64;interface EnglishToGerman {}
- * </pre>
- *
- * @author Sjaak Derksen
- */
-@Target( ElementType.ANNOTATION_TYPE )
-@Retention( RetentionPolicy.CLASS )
-public @interface Qualifier {
-}

core-common/src/main/java/org/mapstruct/ReportingPolicy.java

@@ -1,56 +0,0 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
- *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- */
-package org.mapstruct;
-
-import javax.tools.Diagnostic.Kind;
-
-/**
- * Policy for reporting issues occurring during the generation of a mapper
- * implementation.
- *
- * @author Gunnar Morling
- */
-public enum ReportingPolicy {
-
-    /**
-     * No report will be created for the given issue.
-     */
-    IGNORE,
-
-    /**
-     * A report with {@link Kind#WARNING} will be created for the given issue.
-     */
-    WARN,
-
-    /**
-     * A report with {@link Kind#ERROR} will be created for the given issue,
-     * causing the compilation to fail.
-     */
-    ERROR,
-
-    /**
-     * When given as value for {@link Mapper#unmappedTargetPolicy()}, the setting from the configuration source
-     * referenced via {@link Mapper#config()} will be applied.
-     * <p>
-     * Otherwise (no configuration source is referenced, or this value is given via
-     * {@link MapperConfig#unmappedTargetPolicy()}), a report with {@link Kind#WARNING} will be created for the given
-     * issue.
-     */
-    DEFAULT;
-}

core-common/src/main/java/org/mapstruct/TargetType.java

@@ -1,37 +0,0 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
- *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- */
-package org.mapstruct;
-
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-
-/**
- * Declares a parameter of a custom mapping method to be populated with the target type of the mapping.
- * <p>
- * Not more than one parameter can be declared as {@code TargetType} and that parameter needs to be of type
- * {@link Class} (may be parameterized), or a super-type of it.
- *
- * @author Andreas Gudian
- */
-@Target(ElementType.PARAMETER)
-@Retention(RetentionPolicy.CLASS)
-public @interface TargetType {
-}

core-common/src/main/java/org/mapstruct/factory/Mappers.java

@@ -1,84 +0,0 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
- *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- */
-package org.mapstruct.factory;
-
-import org.mapstruct.Mapper;
-
-/**
- * Factory for obtaining mapper instances if no explicit component model such as CDI is configured via
- * {@link Mapper#componentModel()}.
- * <p>
- * Mapper implementation types are expected to have the same fully qualified name as their interface type, with the
- * suffix {@code Impl} appended. When using this factory, mapper types - and any mappers they use - are instantiated by
- * invoking their public no-args constructor.
- * <p>
- * By convention, a single instance of each mapper is retrieved from the factory and exposed on the mapper interface
- * type by declaring a member named {@code INSTANCE} like this:
- *
- * <pre>
- * &#064;Mapper
- * public interface CustomerMapper {
- *
- *     CustomerMapper INSTANCE = Mappers.getMapper( CustomerMapper.class );
- *
- *     // mapping methods...
- * }
- * </pre>
- *
- * @author Gunnar Morling
- */
-public class Mappers {
-
-    private static final String IMPLEMENTATION_SUFFIX = "Impl";
-
-    private Mappers() {
-    }
-
-    /**
-     * Returns an instance of the given mapper type.
-     *
-     * @param clazz The type of the mapper to return.
-     * @param <T> The type of the mapper to create.
-     * @return An instance of the given mapper type.
-     */
-    public static <T> T getMapper(Class<T> clazz) {
-        try {
-
-            // Check that
-            // - clazz is an interface
-            // - the implementation type implements clazz
-            // - clazz is annotated with @Mapper
-            //
-            // Use privileged action
-            ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
-
-            if ( classLoader == null ) {
-                classLoader = Mappers.class.getClassLoader();
-            }
-
-            @SuppressWarnings("unchecked")
-            T mapper = (T) classLoader.loadClass( clazz.getName() + IMPLEMENTATION_SUFFIX ).newInstance();
-
-            return mapper;
-        }
-        catch ( Exception e ) {
-            throw new RuntimeException( e );
-        }
-    }
-}

core-common/src/main/java/org/mapstruct/factory/package-info.java

@@ -1,26 +0,0 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
- *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- */
-/**
- * <p>
- * Provides the {@link org.mapstruct.factory.Mappers} factory class for the retrieval of mapper instances if no
- * explicit component model such as CDI is configured via {@link org.mapstruct.Mapper#componentModel()}.
- * </p>
- *
- */
-package org.mapstruct.factory;

core-common/src/main/java/org/mapstruct/package-info.java

@@ -1,31 +0,0 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
- *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- */
-/**
- * <p>
- * MapStruct is a code generator which simplifies the implementation of mappings between Java bean types by generating
- * mapping code at compile time, following a convention-over-configuration approach. The generated code uses plain
- * method invocations and thus is fast and type-safe.
- * </p>
- * <p>
- * This package contains several annotations which allow to configure how mapper interfaces are generated.
- * </p>
- *
- * @see <a href="http://mapstruct.org/">MapStruct reference documentation</a>
- */
-package org.mapstruct;

core-common/src/test/java/org/mapstruct/MappersTest.java

@@ -1,40 +0,0 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
- *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- */
-package org.mapstruct;
-
-import static org.fest.assertions.Assertions.assertThat;
-
-import org.junit.Test;
-import org.mapstruct.factory.Mappers;
-import org.mapstruct.test.model.Foo;
-
-/**
- * Unit test for {@link Mappers}.
- *
- * @author Gunnar Morling
- */
-public class MappersTest {
-
-    @Test
-    public void shouldReturnImplementationInstance() {
-
-        Foo mapper = Mappers.getMapper( Foo.class );
-        assertThat( mapper ).isNotNull();
-    }
-}

core-common/src/test/java/org/mapstruct/test/model/Foo.java

@@ -1,23 +0,0 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
- *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- */
-package org.mapstruct.test.model;
-
-public interface Foo {
-
-}

core-common/src/test/java/org/mapstruct/test/model/FooImpl.java

@@ -1,23 +0,0 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
- *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- */
-package org.mapstruct.test.model;
-
-public class FooImpl implements Foo {
-
-}

core-jdk8/pom.xml

@@ -1,22 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
 
- Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- and/or other contributors as indicated by the @authors tag. See the
- copyright.txt file in the distribution for a full listing of all
- contributors.
+    Copyright MapStruct Authors.
 
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
-     http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
+    Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
@@ -25,130 +12,18 @@
     <parent>
         <groupId>org.mapstruct</groupId>
         <artifactId>mapstruct-parent</artifactId>
-        <version>1.0.0.Beta3</version>
+        <version>1.7.0-SNAPSHOT</version>
         <relativePath>../parent/pom.xml</relativePath>
     </parent>
 
     <artifactId>mapstruct-jdk8</artifactId>
-    <packaging>jar</packaging>
     <name>MapStruct Core JDK 8</name>
-    <description>MapStruct annotations to be used with JDK 8 and later</description>
+    <description>Deprecated MapStruct artifact containing annotations to be used with JDK 8 and later -
+        Relocated to mapstruct</description>
+    <distributionManagement>
+        <relocation>
+            <artifactId>mapstruct</artifactId>
+        </relocation>
+    </distributionManagement>
 
-    <properties>
-        <common.sources.dir>copied-common-sources</common.sources.dir>
-    </properties>
-
-    <dependencies>
-        <dependency>
-            <groupId>${project.groupId}</groupId>
-            <artifactId>mapstruct-common</artifactId>
-            <optional>true</optional>
-        </dependency>
-        <dependency>
-            <groupId>junit</groupId>
-            <artifactId>junit</artifactId>
-            <scope>test</scope>
-        </dependency>
-        <dependency>
-            <groupId>org.easytesting</groupId>
-            <artifactId>fest-assert</artifactId>
-            <scope>test</scope>
-        </dependency>
-    </dependencies>
-
-    <build>
-        <plugins>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-checkstyle-plugin</artifactId>
-                <executions>
-                    <execution>
-                        <id>check-style</id>
-                        <phase>verify</phase>
-                        <goals>
-                            <goal>checkstyle</goal>
-                        </goals>
-                    </execution>
-                </executions>
-            </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-source-plugin</artifactId>
-                <executions>
-                    <execution>
-                        <id>attach-sources</id>
-                        <phase>verify</phase>
-                        <goals>
-                            <goal>jar</goal>
-                        </goals>
-                    </execution>
-                </executions>
-            </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-compiler-plugin</artifactId>
-                <configuration>
-                    <source>1.8</source>
-                    <target>1.8</target>
-                </configuration>
-            </plugin>
-            <plugin>
-                <groupId>org.codehaus.mojo</groupId>
-                <artifactId>build-helper-maven-plugin</artifactId>
-                <executions>
-                    <execution>
-                        <id>add-copied-common-sources</id>
-                        <phase>generate-sources</phase>
-                        <goals>
-                            <goal>add-source</goal>
-                        </goals>
-                        <configuration>
-                            <sources>
-                                <source>${project.build.directory}/${common.sources.dir}</source>
-                            </sources>
-                        </configuration>
-                    </execution>
-                </executions>
-            </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-resources-plugin</artifactId>
-                <executions>
-                    <execution>
-                        <id>copy-resources</id>
-                        <phase>process-resources</phase>
-                        <goals>
-                            <goal>copy-resources</goal>
-                        </goals>
-                        <configuration>
-                            <outputDirectory>${project.build.directory}/${common.sources.dir}</outputDirectory>
-                            <resources>
-                                <resource>
-                                    <directory>${basedir}/../core-common/src/main/java</directory>
-                                    <filtering>false</filtering>
-                                </resource>
-                            </resources>
-                        </configuration>
-                    </execution>
-                    <execution>
-                        <id>copy-mapstruct-license</id>
-                        <phase>prepare-package</phase>
-                        <goals>
-                            <goal>copy-resources</goal>
-                        </goals>
-                        <configuration>
-                            <outputDirectory>${project.build.directory}/classes/META-INF</outputDirectory>
-                            <resources>
-                                <resource>
-                                    <directory>${basedir}/..</directory>
-                                    <filtering>false</filtering>
-                                    <include>LICENSE.txt</include>
-                                </resource>
-                            </resources>
-                        </configuration>
-                    </execution>
-                </executions>
-            </plugin>
-        </plugins>
-    </build>
 </project>

core-jdk8/src/main/java/org/mapstruct/Mapping.java

@@ -1,124 +0,0 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
- *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- */
-package org.mapstruct;
-
-import java.lang.annotation.Annotation;
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Repeatable;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-import java.text.SimpleDateFormat;
-import java.util.Date;
-
-/**
- * Configures the mapping of one bean attribute or enum constant.
- * <p>
- * The name of the mapped attribute or constant is to be specified via {@link #target()}. For mapped bean attributes it
- * is assumed by default that the attribute has the same name in the source bean. Alternatively, one of
- * {@link #source()}, {@link #expression()} or {@link #constant()} can be specified to define the property source.
- * <p>
- * In addition, the attributes {@link #dateFormat()} and {@link #qualifiedBy()} may be used to further define the
- * mapping.
- *
- * @author Gunnar Morling
- */
-@Repeatable(Mappings.class)
-@Retention(RetentionPolicy.SOURCE)
-@Target(ElementType.METHOD)
-public @interface Mapping {
-
-    /**
-     * The target name of the configured property as defined by the JavaBeans specification. The same target property
-     * must not be mapped more than once.
-     * <p>
-     * If used to map an enum constant, the name of the constant member is to be given. In this case, several values
-     * from the source enum may be mapped to the same value of the target enum.
-     *
-     * @return The target name of the configured property or enum constant
-     */
-    String target();
-
-    /**
-     * The source to use for this mapping. This can either be:
-     * <ol>
-     * <li>The source name of the configured property as defined by the JavaBeans specification.
-     * <p>
-     * This may either be a simple property name (e.g. "address") or a dot-separated property path (e.g. "address.city"
-     * or "address.city.name"). In case the annotated method has several source parameters, the property name must
-     * qualified with the parameter name, e.g. "addressParam.city".</li>
-     * <li>When no matching property is found, MapStruct looks for a matching parameter name instead.</li>
-     * <li>When used to map an enum constant, the name of the constant member is to be given.</li>
-     * </ol>
-     * Either this attribute or {@link #constant()} or {@link #expression()} may be specified for a given mapping.
-     *
-     * @return The source name of the configured property or enum constant.
-     */
-    String source() default "";
-
-    /**
-     * A format string as processable by {@link SimpleDateFormat} if the attribute is mapped from {@code String} to
-     * {@link Date} or vice-versa. Will be ignored for all other attribute types and when mapping enum constants.
-     *
-     * @return A date format string as processable by {@link SimpleDateFormat}.
-     */
-    String dateFormat() default "";
-
-    /**
-     * A constant {@link String} based on which the specified target property is to be set. If the designated target
-     * property is not of type {@code String}, the value will be converted by applying a matching conversion method or
-     * built-in conversion.
-     * <p>
-     * Either this attribute or {@link #source()} or {@link #expression()} may be specified for a given mapping.
-     *
-     * @return A constant {@code String} constant specifying the value for the designated target property
-     */
-    String constant() default "";
-
-    /**
-     * An expression {@link String} based on which the specified target property is to be set. The format is determined
-     * by a type of expression. For instance:
-     * {@code expression = "java(new org.example.TimeAndFormat( s.getTime(), s.getFormat() ))")} will insert the java
-     * expression in the designated {@link #target()} property.
-     * <p>
-     * Either this attribute or {@link #source()} or {@link #constant()} may be specified for a given mapping.
-     *
-     * @return A constant {@code String} constant specifying the value for the designated target property
-     */
-    String expression() default "";
-
-    /**
-     * Whether the property specified via {@link #target()} should be ignored by the generated mapping method or not.
-     * This can be useful when certain attributes should not be propagated from source or target or when properties in
-     * the target object are populated using a decorator and thus would be reported as unmapped target property by
-     * default.
-     *
-     * @return {@code true} if the given property should be ignored, {@code false} otherwise
-     */
-    boolean ignore() default false;
-
-    /**
-     * A qualifier can be specified to aid the selection process of a suitable mapper. This is useful in case multiple
-     * mapping methods (hand written or generated) qualify and thus would result in an 'Ambiguous mapping methods found'
-     * error. A qualifier is a custom annotation and can be placed on a hand written mapper class or a method.
-     *
-     * @return the qualifiers
-     */
-    Class<? extends Annotation>[] qualifiedBy() default { };
-}

core-jdk8/src/main/java/org/mapstruct/Mappings.java

@@ -1,41 +0,0 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
- *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- */
-package org.mapstruct;
-
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-
-/**
- * Configures the mappings of several bean attributes.
- *
- * @author Gunnar Morling
- */
-@Retention(RetentionPolicy.SOURCE)
-@Target(ElementType.METHOD)
-public @interface Mappings {
-
-    /**
-     * The configuration of the bean attributes.
-     *
-     * @return The configuration of the bean attributes.
-     */
-    Mapping[] value();
-}

core/pom.xml

@@ -1,22 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
 
- Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- and/or other contributors as indicated by the @authors tag. See the
- copyright.txt file in the distribution for a full listing of all
- contributors.
+    Copyright MapStruct Authors.
 
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
-     http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
+    Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 
 -->
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
@@ -25,7 +12,7 @@
     <parent>
         <groupId>org.mapstruct</groupId>
         <artifactId>mapstruct-parent</artifactId>
-        <version>1.0.0.Beta3</version>
+        <version>1.7.0-SNAPSHOT</version>
         <relativePath>../parent/pom.xml</relativePath>
     </parent>
 
@@ -33,24 +20,15 @@
     <packaging>jar</packaging>
     <name>MapStruct Core</name>
 
-    <properties>
-        <common.sources.dir>copied-common-sources</common.sources.dir>
-    </properties>
-
     <dependencies>
         <dependency>
-            <groupId>${project.groupId}</groupId>
-            <artifactId>mapstruct-common</artifactId>
-            <optional>true</optional>
-        </dependency>
-        <dependency>
-            <groupId>junit</groupId>
-            <artifactId>junit</artifactId>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
             <scope>test</scope>
         </dependency>
         <dependency>
-            <groupId>org.easytesting</groupId>
-            <artifactId>fest-assert</artifactId>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
             <scope>test</scope>
         </dependency>
     </dependencies>
@@ -83,44 +61,10 @@
                     </execution>
                 </executions>
             </plugin>
-            <plugin>
-                <groupId>org.codehaus.mojo</groupId>
-                <artifactId>build-helper-maven-plugin</artifactId>
-                <executions>
-                    <execution>
-                        <id>add-copied-common-sources</id>
-                        <phase>generate-sources</phase>
-                        <goals>
-                            <goal>add-source</goal>
-                        </goals>
-                        <configuration>
-                            <sources>
-                                <source>${project.build.directory}/${common.sources.dir}</source>
-                            </sources>
-                        </configuration>
-                    </execution>
-                </executions>
-            </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-resources-plugin</artifactId>
                 <executions>
-                    <execution>
-                        <id>copy-resources</id>
-                        <phase>process-resources</phase>
-                        <goals>
-                            <goal>copy-resources</goal>
-                        </goals>
-                        <configuration>
-                            <outputDirectory>${project.build.directory}/${common.sources.dir}</outputDirectory>
-                            <resources>
-                                <resource>
-                                    <directory>${basedir}/../core-common/src/main/java</directory>
-                                    <filtering>false</filtering>
-                                </resource>
-                            </resources>
-                        </configuration>
-                    </execution>
                     <execution>
                         <id>copy-mapstruct-license</id>
                         <phase>prepare-package</phase>
@@ -140,6 +84,27 @@
                     </execution>
                 </executions>
             </plugin>
+            <plugin>
+                <groupId>org.apache.felix</groupId>
+                <artifactId>maven-bundle-plugin</artifactId>
+                <configuration>
+                    <instructions>
+                        <Automatic-Module-Name>org.mapstruct</Automatic-Module-Name>
+                    </instructions>
+                </configuration>
+            </plugin>
+            <plugin>
+                <artifactId>maven-jar-plugin</artifactId>
+                <configuration>
+                    <archive>
+                        <manifestFile>${project.build.outputDirectory}/META-INF/MANIFEST.MF</manifestFile>
+                    </archive>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>com.github.siom79.japicmp</groupId>
+                <artifactId>japicmp-maven-plugin</artifactId>
+            </plugin>
         </plugins>
     </build>
 </project>

core/src/main/java/org/mapstruct/AfterMapping.java

@@ -0,0 +1,97 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks a method to be invoked at the end of a generated mapping method, right before the last {@code return} statement
+ * of the mapping method. The method can be implemented in an abstract mapper class, be declared in a type (class or
+ * interface) referenced in {@link Mapper#uses()}, or in a type used as {@code @}{@link Context} parameter in order to
+ * be used in a mapping method.
+ * <p>
+ * The method invocation is only generated if the return type of the method (if non-{@code void}) is assignable to the
+ * return type of the mapping method and all parameters can be <em>assigned</em> by the available source, target or
+ * context parameters of the mapping method:
+ * <ul>
+ * <li>A parameter annotated with {@code @}{@link MappingTarget} is populated with the target instance of the mapping.
+ * </li>
+ * <li>A parameter annotated with {@code @}{@link TargetType} is populated with the target type of the mapping.</li>
+ * <li>Parameters annotated with {@code @}{@link Context} are populated with the context parameters of the mapping
+ * method.</li>
+ * <li>Any other parameter is populated with a source parameter of the mapping.</li>
+ * </ul>
+ * <p>
+ * For non-{@code void} methods, the return value of the method invocation is returned as the result of the mapping
+ * method if it is not {@code null}.
+ * <p>
+ * All <em>after-mapping</em> methods that can be applied to a mapping method will be used. {@code @}{@link Qualifier} /
+ * {@code @}{@link Named} can be used to filter the methods to use.
+ * <p>
+ * The order of the method invocation is determined by their location of definition:
+ * <ol>
+ * <li>Methods declared on {@code @}{@link Context} parameters, ordered by the parameter order.</li>
+ * <li>Methods implemented in the mapper itself.</li>
+ * <li>Methods from types referenced in {@link Mapper#uses()}, in the order of the type declaration in the annotation.
+ * </li>
+ * <li>Methods declared in one type are used after methods declared in their super-type</li>
+ * </ol>
+ * <em>Important:</em> the order of methods declared within one type can not be guaranteed, as it depends on the
+ * compiler and the processing environment implementation.
+ * <p>
+ * Example:
+ *
+ * <pre>
+ * <code>
+ * &#64;AfterMapping
+ * public void calledWithoutArgs() {
+ *     // ...
+ * }
+ *
+ * &#64;AfterMapping
+ * public void calledWithSourceAndTargetType(SourceEntity anySource, &#64;TargetType Class&lt;?&gt; targetType) {
+ *     // ...
+ * }
+ *
+ * &#64;AfterMapping
+ * public void calledWithSourceAndTarget(Object anySource, &#64;MappingTarget TargetDto target) {
+ *     // ...
+ * }
+ *
+ * public abstract TargetDto toTargetDto(SourceEntity source);
+ *
+ * // generates:
+ *
+ * public TargetDto toTargetDto(SourceEntity source) {
+ *     if ( source == null ) {
+ *         return null;
+ *     }
+ *
+ *     TargetDto targetDto = new TargetDto();
+ *
+ *     // actual mapping code
+ *
+ *     calledWithoutArgs();
+ *     calledWithSourceAndTargetType( source, TargetDto.class );
+ *     calledWithSourceAndTarget( source, targetDto );
+ *
+ *     return targetDto;
+ * }
+ * </code>
+ * </pre>
+ *
+ * @author Andreas Gudian
+ * @see BeforeMapping
+ * @see Context
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.CLASS)
+public @interface AfterMapping {
+
+}

core/src/main/java/org/mapstruct/AnnotateWith.java

@@ -0,0 +1,176 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.Annotation;
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.CLASS;
+
+/**
+ * This can be used to have mapstruct generate additional annotations on classes/methods.
+ * <p>
+ * Examples based on the spring framework annotations.
+ * </p>
+ * Marking a class as `Lazy`:
+ *
+ * <pre><code>
+ * &#64;AnnotateWith( value = Lazy.class )
+ * &#64;Mapper
+ * public interface FooMapper {
+ *     // mapper code
+ * }
+ * </code></pre>
+ *
+ * The following code would be generated:
+ *
+ * <pre><code>
+ * &#64;Lazy
+ * public class FooMapperImpl implements FooMapper {
+ *     // mapper code
+ * }
+ * </code></pre>
+ * Setting the profile on the generated implementation:
+ *
+ * <pre><code>
+ * &#64;AnnotateWith( value = Profile.class, elements = @AnnotateWith.Element( strings = "prod" ) )
+ * &#64;Mapper
+ * public interface FooMapper {
+ *     // mapper code
+ * }
+ * </code></pre>
+ *
+ * The following code would be generated:
+ *
+ * <pre><code>
+ * &#64;Profile( value = "prod" )
+ * public class FooMapperImpl implements FooMapper {
+ *     // mapper code
+ * }
+ * </code></pre>
+ *
+ * @author Ben Zegveld
+ * @since 1.6
+ */
+@Repeatable( AnnotateWiths.class )
+@Retention( CLASS )
+@Target( { TYPE, METHOD, ANNOTATION_TYPE } )
+public @interface AnnotateWith {
+    /**
+     * @return the annotation class that needs to be added.
+     */
+    Class<? extends Annotation> value();
+
+    /**
+     * @return the annotation elements that are to be applied to this annotation.
+     */
+    Element[] elements() default {};
+
+    /**
+     * Used in combination with {@link AnnotateWith} to configure the annotation elements. Only 1 value type may be used
+     * within the same annotation at a time. For example mixing shorts and ints is not allowed.
+     *
+     * @author Ben Zegveld
+     * @since 1.6
+     */
+    @interface Element {
+        /**
+         * @return name of the annotation element.
+         */
+        String name() default "value";
+
+        /**
+         * cannot be used in conjunction with other value fields.
+         *
+         * @return short value(s) for the annotation element.
+         */
+        short[] shorts() default {};
+
+        /**
+         * cannot be used in conjunction with other value fields.
+         *
+         * @return byte value(s) for the annotation element.
+         */
+        byte[] bytes() default {};
+
+        /**
+         * cannot be used in conjunction with other value fields.
+         *
+         * @return int value(s) for the annotation element.
+         */
+        int[] ints() default {};
+
+        /**
+         * cannot be used in conjunction with other value fields.
+         *
+         * @return long value(s) for the annotation element.
+         */
+        long[] longs() default {};
+
+        /**
+         * cannot be used in conjunction with other value fields.
+         *
+         * @return float value(s) for the annotation element.
+         */
+        float[] floats() default {};
+
+        /**
+         * cannot be used in conjunction with other value fields.
+         *
+         * @return double value(s) for the annotation element.
+         */
+        double[] doubles() default {};
+
+        /**
+         * cannot be used in conjunction with other value fields.
+         *
+         * @return char value(s) for the annotation element.
+         */
+        char[] chars() default {};
+
+        /**
+         * cannot be used in conjunction with other value fields.
+         *
+         * @return boolean value(s) for the annotation element.
+         */
+        boolean[] booleans() default {};
+
+        /**
+         * cannot be used in conjunction with other value fields.
+         *
+         * @return string value(s) for the annotation element.
+         */
+        String[] strings() default {};
+
+        /**
+         * cannot be used in conjunction with other value fields.
+         *
+         * @return class value(s) for the annotation element.
+         */
+        Class<?>[] classes() default {};
+
+        /**
+         * only used in conjunction with the {@link #enums()} annotation element.
+         *
+         * @return the class of the enum.
+         */
+        Class<? extends Enum<?>> enumClass() default NullEnum.class;
+
+        /**
+         * cannot be used in conjunction with other value fields. {@link #enumClass()} is also required when using
+         * {@link #enums()}
+         *
+         * @return enum value(s) for the annotation element.
+         */
+        String[] enums() default {};
+
+    }
+}

core/src/main/java/org/mapstruct/AnnotateWiths.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.CLASS;
+
+/**
+ * This can be used to have mapstruct generate additional annotations on classes/methods.
+ *
+ * @author Ben Zegveld
+ * @since 1.6
+ */
+@Retention( CLASS )
+@Target( { TYPE, METHOD } )
+public @interface AnnotateWiths {
+
+    /**
+     * The configuration of the additional annotations.
+     *
+     * @return The configuration of the additional annotations.
+     */
+    AnnotateWith[] value();
+}

core/src/main/java/org/mapstruct/BeanMapping.java

@@ -0,0 +1,227 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.Annotation;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.mapstruct.control.MappingControl;
+
+import static org.mapstruct.NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
+import static org.mapstruct.SubclassExhaustiveStrategy.COMPILE_ERROR;
+
+/**
+ * Configures the mapping between two bean types.
+ * <p>
+ * Unless otherwise specified these properties are inherited to the generated bean mapping methods.
+ * <p>
+ * Either {@link #resultType()}, {@link #qualifiedBy()} or {@link #nullValueMappingStrategy()} must be specified.
+ * </p>
+ * <p><strong>Example:</strong> Determining the result type</p>
+ * <pre><code class='java'>
+ * // When result types have an inheritance relation, selecting either mapping method {@link Mapping} or factory method
+ * // {@link BeanMapping} can be become ambiguous. Parameter  {@link BeanMapping#resultType()} can be used.
+ * public class FruitFactory {
+ *     public Apple createApple() {
+ *         return new Apple();
+ *     }
+ *     public Orange createOrange() {
+ *         return new Orange();
+ *     }
+ * }
+ * &#64;Mapper(uses = FruitFactory.class)
+ * public interface FruitMapper {
+ *     &#64;BeanMapping(resultType = Apple.class)
+ *     Fruit toFruit(FruitDto fruitDto);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * public class FruitMapperImpl implements FruitMapper {
+ *      &#64;Override
+ *      public Fruit toFruit(FruitDto fruitDto) {
+ *          Apple fruit = fruitFactory.createApple();
+ *          // ...
+ *      }
+ * }
+ * </code></pre>
+ *
+ * @author Sjaak Derksen
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.CLASS)
+public @interface BeanMapping {
+
+    /**
+     * Specifies the result type of the factory method to be used in case several factory methods qualify.
+     * <p>
+     * <b>NOTE</b>: This property is not inherited to generated mapping methods
+     *
+     * @return the resultType to select
+     */
+    Class<?> resultType() default void.class;
+
+    /**
+     * A qualifier can be specified to aid the selection process of a suitable factory method or filtering applicable
+     * {@code @}{@link BeforeMapping} / {@code @}{@link AfterMapping} methods. This is useful in case multiple factory
+     * method (hand written of internal) qualify and result in an 'Ambiguous factory methods' error.
+     * <p>
+     * A qualifier is a custom annotation and can be placed on either a hand written mapper class or a method.
+     *
+     * @return the qualifiers
+     * @see Qualifier
+     */
+    Class<? extends Annotation>[] qualifiedBy() default {};
+
+    /**
+     * Similar to {@link #qualifiedBy()}, but used in combination with {@code @}{@link Named} in case no custom
+     * qualifier annotation is defined.
+     *
+     * @return the qualifiers
+     * @see Named
+     */
+    String[] qualifiedByName() default { };
+
+    /**
+     * The strategy to be applied when {@code null} is passed as source bean argument value to this bean mapping. If no
+     * strategy is configured, the strategy given via {@link MapperConfig#nullValueMappingStrategy()} or
+     * {@link Mapper#nullValueMappingStrategy()} will be applied, using {@link NullValueMappingStrategy#RETURN_NULL}
+     * by default.
+     *
+     * @return The strategy to be applied when {@code null} is passed as source value to the methods of this mapping.
+     */
+    NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
+
+    /**
+     * The strategy to be applied when a source bean property is {@code null} or not present. If no strategy is
+     * configured, the strategy given via {@link MapperConfig#nullValuePropertyMappingStrategy()} or
+     * {@link Mapper#nullValuePropertyMappingStrategy()} will be applied,
+     * {@link NullValuePropertyMappingStrategy#SET_TO_NULL} will be used by default.
+     *
+     * @since 1.3
+     *
+     * @return The strategy to be applied when {@code null} is passed as source property value or the source property
+     * is not present.
+     */
+    NullValuePropertyMappingStrategy nullValuePropertyMappingStrategy()
+        default NullValuePropertyMappingStrategy.SET_TO_NULL;
+
+    /**
+     * Determines when to include a null check on the source property value of a bean mapping.
+     *
+     * Can be overridden by the one on {@link MapperConfig}, {@link Mapper}  or {@link Mapping}.
+     *
+     * @return strategy how to do null checking
+     */
+    NullValueCheckStrategy nullValueCheckStrategy() default ON_IMPLICIT_CONVERSION;
+
+    /**
+     * Determines how to handle missing implementation for super classes when using the {@link SubclassMapping}.
+     *
+     * Overrides the setting on {@link MapperConfig} and {@link Mapper}.
+     *
+     * @return strategy to handle missing implementation combined with {@link SubclassMappings}.
+     *
+     * @since 1.5
+     */
+    SubclassExhaustiveStrategy subclassExhaustiveStrategy() default COMPILE_ERROR;
+
+    /**
+     * Specifies the exception type to be thrown when a missing subclass implementation is detected
+     * in combination with {@link SubclassMappings}, based on the {@link #subclassExhaustiveStrategy()}.
+     * <p>
+     * This exception will only be thrown when the {@code subclassExhaustiveStrategy} is set to
+     * {@link SubclassExhaustiveStrategy#RUNTIME_EXCEPTION}.
+     *
+     * @return the exception class to throw when missing implementations are found.
+     *         Defaults to {@link IllegalArgumentException}.
+     */
+    Class<? extends Exception> subclassExhaustiveException() default IllegalArgumentException.class;
+
+    /**
+     * Default ignore all mappings. All mappings have to be defined manually. No automatic mapping will take place. No
+     * warning will be issued on missing source or target properties.
+     *
+     * @return The ignore strategy (default false).
+     *
+     * @since 1.3
+     */
+    boolean ignoreByDefault() default false;
+
+    /**
+     * Unmapped source properties to be ignored. This could be used when {@link ReportingPolicy#WARN}
+     * or {@link ReportingPolicy#ERROR} is used for {@link Mapper#unmappedSourcePolicy()} or
+     * {@link MapperConfig#unmappedSourcePolicy()}. Listed properties will be ignored when composing the unmapped
+     * source properties report.
+     * <p>
+     * <b>NOTE</b>: This does not support ignoring nested source properties
+     * <p>
+     * <b>NOTE</b>: This property is not inherited to generated mapping methods
+     *
+     * @return The source properties that should be ignored when performing a report
+     *
+     * @since 1.3
+     */
+    String[] ignoreUnmappedSourceProperties() default {};
+
+    /**
+     * How unmapped properties of the source type of a mapping should be reported.
+     * If no policy is configured, the policy given via {@link MapperConfig#unmappedSourcePolicy()} or
+     * {@link Mapper#unmappedSourcePolicy()} will be applied, using {@link ReportingPolicy#IGNORE} by default.
+     *
+     * @return The reporting policy for unmapped source properties.
+     *
+     * @since 1.6
+     */
+    ReportingPolicy unmappedSourcePolicy() default ReportingPolicy.IGNORE;
+
+    /**
+     * How unmapped properties of the target type of a mapping should be reported.
+     * If no policy is configured, the policy given via {@link MapperConfig#unmappedTargetPolicy()} or
+     * {@link Mapper#unmappedTargetPolicy()} will be applied, using {@link ReportingPolicy#WARN} by default.
+     *
+     * @return The reporting policy for unmapped target properties.
+     *
+     * @since 1.5
+     */
+    ReportingPolicy unmappedTargetPolicy() default ReportingPolicy.WARN;
+
+    /**
+     * The information that should be used for the builder mappings. This can be used to define custom build methods
+     * for the builder strategy that one uses.
+     *
+     * If no builder is defined the builder given via {@link MapperConfig#builder()} or {@link Mapper#builder()}
+     * will be applied.
+     * <p>
+     * NOTE: In case no builder is defined here, in {@link Mapper} or {@link MapperConfig} and there is a single
+     * build method, then that method would be used.
+     * <p>
+     * If the builder is defined and there is a single method that does not match the name of the finisher than
+     * a compile error will occurs
+     *
+     * @return the builder information for the method level
+     *
+     * @since 1.3
+     */
+    Builder builder() default @Builder;
+
+    /**
+     * Allows detailed control over the mapping process.
+     *
+     * @return the mapping control
+     *
+     * @since 1.4
+     *
+     * @see org.mapstruct.control.DeepClone
+     * @see org.mapstruct.control.NoComplexMapping
+     * @see org.mapstruct.control.MappingControl
+     */
+    Class<? extends Annotation> mappingControl() default MappingControl.class;
+
+}

core/src/main/java/org/mapstruct/BeforeMapping.java

@@ -0,0 +1,100 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks a method to be invoked at the beginning of a generated mapping method. The method can be implemented in an
+ * abstract mapper class, be declared in a type (class or interface) referenced in {@link Mapper#uses()}, or in a type
+ * used as {@code @}{@link Context} parameter in order to be used in a mapping method.
+ * <p>
+ * The method invocation is only generated if the return type of the method (if non-{@code void}) is assignable to the
+ * return type of the mapping method and all parameters can be <em>assigned</em> by the available source, target or
+ * context parameters of the mapping method:
+ * <ul>
+ * <li>A parameter annotated with {@code @}{@link MappingTarget} is populated with the target instance of the mapping.
+ * </li>
+ * <li>A parameter annotated with {@code @}{@link TargetType} is populated with the target type of the mapping.</li>
+ * <li>Parameters annotated with {@code @}{@link Context} are populated with the context parameters of the mapping
+ * method.</li>
+ * <li>Any other parameter is populated with a source parameter of the mapping.</li>
+ * </ul>
+ * <p>
+ * For non-{@code void} methods, the return value of the method invocation is returned as the result of the mapping
+ * method if it is not {@code null}.
+ * <p>
+ * All <em>before-mapping</em> methods that can be applied to a mapping method will be used. {@code @}{@link Qualifier}
+ * / {@code @}{@link Named} can be used to filter the methods to use.
+ * <p>
+ * The order of the method invocation is determined by their their variant and their location of definition:
+ * <ol>
+ * <li>Methods without an {@code @}{@link MappingTarget} parameter are called before any null-checks on source
+ * parameters and constructing a new target bean.</li>
+ * <li>Methods with an {@code @}{@link MappingTarget} parameter are called after constructing a new target bean.</li>
+ * <li>Methods declared on {@code @}{@link Context} parameters, ordered by the parameter order.</li>
+ * <li>Methods implemented in the mapper itself.</li>
+ * <li>Methods from types referenced in {@link Mapper#uses()}, in the order of the type declaration in the annotation.
+ * </li>
+ * <li>Methods declared in one type are used after methods declared in their super-type</li>
+ * </ol>
+ * <em>Important:</em> the order of methods declared within one type can not be guaranteed, as it depends on the
+ * compiler and the processing environment implementation.
+ * <p>
+ * Example:
+ *
+ * <pre>
+ * <code>
+ * &#64;BeforeMapping
+ * public void calledWithoutArgs() {
+ *     // ...
+ * }
+ *
+ * &#64;BeforeMapping
+ * public void calledWithSourceAndTargetType(SourceEntity anySource, &#64;TargetType Class&lt;?&gt; targetType) {
+ *     // ...
+ * }
+ *
+ * &#64;BeforeMapping
+ * public void calledWithSourceAndTarget(Object anySource, &#64;MappingTarget TargetDto target) {
+ *     // ...
+ * }
+ *
+ * public abstract TargetDto toTargetDto(SourceEntity source);
+ *
+ * // generates:
+ *
+ * public TargetDto toTargetDto(SourceEntity source) {
+ *     calledWithoutArgs();
+ *     calledWithSourceAndTargetType( source, TargetDto.class );
+ *
+ *     if ( source == null ) {
+ *         return null;
+ *     }
+ *
+ *     TargetDto targetDto = new TargetDto();
+ *
+ *     calledWithSourceAndTarget( source, targetDto );
+ *
+ *     // actual mapping code
+ *
+ *     return targetDto;
+ * }
+ * </code>
+ * </pre>
+ *
+ * @author Andreas Gudian
+ * @see AfterMapping
+ * @see Context
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.CLASS)
+public @interface BeforeMapping {
+
+}

core/src/main/java/org/mapstruct/Builder.java

@@ -0,0 +1,66 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.mapstruct.util.Experimental;
+
+/**
+ * Configuration of builders, e.g. the name of the final build method.
+ *
+ * <p>
+ * <strong>Example:</strong> Using builder
+ * </p>
+ * <pre><code class='java'>
+ * // Mapper
+ * &#64;Mapper
+ * public interface SimpleBuilderMapper {
+ *      &#64;Mapping(target = "name", source = "fullName"),
+ *      &#64;Mapping(target = "job", constant = "programmer"),
+ *      SimpleImmutablePerson toImmutable(SimpleMutablePerson source);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * &#64;Override
+ * public SimpleImmutablePerson toImmutable(SimpleMutablePerson source) {
+ *      // name method can be changed with parameter {@link #buildMethod()}
+ *      Builder simpleImmutablePerson = SimpleImmutablePerson.builder();
+ *      simpleImmutablePerson.name( source.getFullName() );
+ *      simpleImmutablePerson.age( source.getAge() );
+ *      simpleImmutablePerson.address( source.getAddress() );
+ *      simpleImmutablePerson.job( "programmer" );
+ *      // ...
+ * }
+ * </code></pre>
+ *
+ * @author Filip Hrisafov
+ *
+ * @since 1.3
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target({})
+@Experimental
+public @interface Builder {
+
+    /**
+     * The name of the build method that needs to be invoked on the builder to create the type to be build
+     *
+     * @return the method that needs to tbe invoked on the builder
+     */
+    String buildMethod() default "build";
+
+    /**
+     * Toggling builders on / off. Builders are sometimes used solely for unit testing (fluent testdata)
+     * MapStruct will need to use the regular getters /setters in that case.
+     *
+     * @return when true, no builder patterns will be applied
+     */
+    boolean disableBuilder() default false;
+}

core/src/main/java/org/mapstruct/CollectionMappingStrategy.java

@@ -0,0 +1,99 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+/**
+ * Strategy for propagating the value of collection-typed properties from source to target.
+ * <p>
+ * In the table below, the dash {@code -} indicates a property name.
+ * Next, the trailing {@code s} indicates the plural form.
+ * The table explains the options and how they are applied to the presence / absence of a
+ * {@code set-s}, {@code add-} and / or {@code get-s} method on the target object.
+ * <table>
+ *     <caption>Collection mapping strategy options</caption>
+ *     <tr>
+ *         <th>Option</th>
+ *         <th>Only target set-s Available</th>
+ *         <th>Only target add- Available</th>
+ *         <th>Both set-s/add- Available</th>
+ *         <th>No set-s/add- Available</th>
+ *         <th>Existing Target ({@code @TargetType})</th>
+ *     </tr>
+ *     <tr>
+ *         <td>{@link #ACCESSOR_ONLY}</td>
+ *         <td>set-s</td>
+ *         <td>get-s</td>
+ *         <td>set-s</td>
+ *         <td>get-s</td>
+ *         <td>get-s</td>
+ *     </tr>
+ *     <tr>
+ *         <td>{@link #SETTER_PREFERRED}</td>
+ *         <td>set-s</td>
+ *         <td>add-</td>
+ *         <td>set-s</td>
+ *         <td>get-s</td>
+ *         <td>get-s</td>
+ *     </tr>
+ *     <tr>
+ *         <td>{@link #ADDER_PREFERRED}</td>
+ *         <td>set-s</td>
+ *         <td>add-</td>
+ *         <td>add-</td>
+ *         <td>get-s</td>
+ *         <td>get-s</td>
+ *     </tr>
+ *     <tr>
+ *         <td>{@link #TARGET_IMMUTABLE}</td>
+ *         <td>set-s</td>
+ *         <td>exception</td>
+ *         <td>set-s</td>
+ *         <td>exception</td>
+ *         <td>set-s</td>
+ *     </tr>
+ * </table>
+ *
+ * @author Sjaak Derksen
+ */
+public enum CollectionMappingStrategy {
+
+    /**
+     * The setter of the target property will be used to propagate the value:
+     * {@code orderDto.setOrderLines(order.getOrderLines)}.
+     * <p>
+     * If no setter is available but a getter method, this will be used, under the assumption it has been initialized:
+     * {@code orderDto.getOrderLines().addAll(order.getOrderLines)}. This will also be the case when using
+     * {@link MappingTarget} (updating existing instances).
+     */
+    ACCESSOR_ONLY,
+
+    /**
+     * If present, the setter of the target property will be used to propagate the value:
+     * {@code orderDto.setOrderLines(order.getOrderLines)}.
+     * <p>
+     * If no setter but and adder method is present, that adder will be invoked for each element of the source
+     * collection: {@code order.addOrderLine(orderLine() )}.
+     * <p>
+     * If neither a setter nor an adder method but a getter for the target property is present, that getter will be
+     * used, assuming it returns an initialized collection: If no setter is available, MapStruct will first look for an
+     * adder method before resorting to a getter.
+     */
+    SETTER_PREFERRED,
+
+    /**
+     * Identical to {@link #SETTER_PREFERRED}, only that adder methods will be preferred over setter methods, if both
+     * are present for a given collection-typed property.
+     */
+    ADDER_PREFERRED,
+
+    /**
+     * Identical to {@link #SETTER_PREFERRED}, however the target collection will not be cleared and accessed via
+     * addAll in case of updating existing bean instances, see: {@link MappingTarget}.
+     *
+     * Instead the target accessor (e.g. set) will be used on the target bean to set the collection.
+     */
+    TARGET_IMMUTABLE;
+}

core/src/main/java/org/mapstruct/Condition.java

@@ -0,0 +1,96 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This annotation marks a method as a <em>presence check method</em> to check for presence in beans
+ * or it can be used to define additional check methods for something like source parameters.
+ * <p>
+ * By default, bean properties are checked against {@code null} or using a presence check method in the source bean.
+ * If a presence check method is available then it will be used instead.
+ * <p>
+ * Presence check methods have to return {@code boolean}.
+ * The following parameters are accepted for the presence check methods:
+ *     <ul>
+ *         <li>The parameter with the value of the source property.
+ *         e.g. the value given by calling {@code getName()} for the name property of the source bean
+ *         - only possible when using the {@link ConditionStrategy#PROPERTIES}
+ *         </li>
+ *         <li>The mapping source parameter</li>
+ *         <li>{@code @}{@link Context} parameter</li>
+ *         <li>
+ *             {@code @}{@link TargetPropertyName} parameter -
+ *             only possible when using the {@link ConditionStrategy#PROPERTIES}
+ *         </li>
+ *         <li>
+ *             {@code @}{@link SourcePropertyName} parameter -
+ *             only possible when using the {@link ConditionStrategy#PROPERTIES}
+ *         </li>
+ *     </ul>
+ *
+ * <strong>Note:</strong> The usage of this annotation is <em>mandatory</em>
+ * for a method to be considered as a presence check method.
+ *
+ * <pre><code class='java'>
+ * public class PresenceCheckUtils {
+ *
+ *   &#64;Condition
+ *   public static boolean isNotEmpty(String value) {
+ *      return value != null &#38;&#38; !value.isEmpty();
+ *   }
+ * }
+ *
+ * &#64;Mapper(uses = PresenceCheckUtils.class)
+ * public interface MovieMapper {
+ *
+ *     MovieDto map(Movie movie);
+ * }
+ * </code></pre>
+ * <p>
+ * The following implementation of {@code MovieMapper} will be generated:
+ *
+ * <pre><code class='java'>
+ * public class MovieMapperImpl implements MovieMapper {
+ *
+ *     &#64;Override
+ *     public MovieDto map(Movie movie) {
+ *         if ( movie == null ) {
+ *             return null;
+ *         }
+ *
+ *         MovieDto movieDto = new MovieDto();
+ *
+ *         if ( PresenceCheckUtils.isNotEmpty( movie.getTitle() ) ) {
+ *             movieDto.setTitle( movie.getTitle() );
+ *         }
+ *
+ *         return movieDto;
+ *     }
+ * }
+ * </code></pre>
+ * <p>
+ * This annotation can also be used as a meta-annotation to define the condition strategy.
+ *
+ * @author Filip Hrisafov
+ * @see SourceParameterCondition
+ * @since 1.5
+ */
+@Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
+@Retention(RetentionPolicy.CLASS)
+public @interface Condition {
+
+    /**
+     * @return the places where the condition should apply to
+     * @since 1.6
+     */
+    ConditionStrategy[] appliesTo() default ConditionStrategy.PROPERTIES;
+
+}

core/src/main/java/org/mapstruct/ConditionStrategy.java

@@ -0,0 +1,23 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+/**
+ * Strategy for defining what to what a condition (check) method is applied to
+ *
+ * @author Filip Hrisafov
+ * @since 1.6
+ */
+public enum ConditionStrategy {
+    /**
+     * The condition method should be applied whether a property should be mapped.
+     */
+    PROPERTIES,
+    /**
+     * The condition method should be applied to check if a source parameters should be mapped.
+     */
+    SOURCE_PARAMETERS,
+}

core/src/main/java/org/mapstruct/Context.java

@@ -0,0 +1,181 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks a parameter of a method to be treated as <em>mapping context</em>. Such parameters are passed to other mapping
+ * methods, {@code @}{@link ObjectFactory} methods or {@code @}{@link BeforeMapping}/{@code @}{@link AfterMapping}
+ * methods when applicable and can thus be used in custom code.
+ * <p>
+ * The type of an {@code @Context} parameter is also inspected for
+ * {@code @}{@link BeforeMapping}/{@code @}{@link AfterMapping} methods, which are called on the provided context
+ * parameter value if applicable.
+ * <p>
+ * <strong>Note:</strong> no {@code null} checks are performed before calling before/after mapping methods or object
+ * factory methods on {@code @}{@link Context} annotated parameters. The caller needs to make sure that no {@code null}
+ * are passed in that case.
+ * <p>
+ * For generated code to call a method that is declared with {@code @Context} parameters, the declaration of the mapping
+ * method being generated needs to contain at least those (or assignable) {@code @Context} parameters as well. MapStruct
+ * will not create new instances of missing {@code @Context} parameters nor will it pass {@code null} instead.
+ * <p>
+ * <strong>Example 1:</strong> Using {@code @Context} parameters for passing data down to hand-written property mapping
+ * methods and {@code @}{@link BeforeMapping} methods:
+ *
+ * <pre>
+ * <code>
+ * // multiple &#64;Context parameters can be added
+ * public abstract CarDto toCar(Car car, &#64;Context VehicleRegistration context, &#64;Context Locale localeToUse);
+ *
+ * protected OwnerManualDto translateOwnerManual(OwnerManual ownerManual, &#64;Context Locale locale) {
+ *     // manually implemented logic to translate the OwnerManual with the given Locale
+ * }
+ *
+ * &#64;BeforeMapping
+ * protected void registerVehicle(Vehicle mappedVehicle, &#64;Context VehicleRegistration context) {
+ *     context.register( mappedVehicle );
+ * }
+ *
+ * &#64;BeforeMapping
+ * protected void notCalled(Vehicle mappedVehicle, &#64;Context DifferentMappingContextType context) {
+ *     // not called, because no context parameter of type DifferentMappingContextType is available
+ *     // within toCar(Car, VehicleRegistration, Locale)
+ * }
+ *
+ * // generates:
+ *
+ * public CarDto toCar(Car car, VehicleRegistration context, Locale localeToUse) {
+ *     registerVehicle( car, context );
+ *
+ *     if ( car == null ) {
+ *         return null;
+ *     }
+ *
+ *     CarDto carDto = new CarDto();
+ *
+ *     carDto.setOwnerManual( translateOwnerManual( car.getOwnerManual(), localeToUse );
+ *     // more generated mapping code
+ *
+ *     return carDto;
+ * }
+ * </code>
+ * </pre>
+ * <p>
+ * <strong>Example 2:</strong> Using an {@code @Context} parameter with a type that provides its own {@code @}
+ * {@link BeforeMapping} methods to handle cycles in Graph structures:
+ *
+ * <pre>
+ * <code>
+ * // type of the context parameter
+ * public class CyclicGraphContext {
+ *     private Map&lt;Object, Object&gt; knownInstances = new IdentityHashMap&lt;&gt;();
+ *
+ *     &#64;BeforeMapping
+ *     public &lt;T extends NodeDto&gt; T getMappedInstance(Object source, &#64;TargetType Class&lt;T&gt; targetType) {
+ *         return (T) knownInstances.get( source );
+ *     }
+ *
+ *     &#64;BeforeMapping
+ *     public void storeMappedInstance(Object source, &#64;MappingTarget NodeDto target) {
+ *         knownInstances.put( source, target );
+ *     }
+ * }
+ *
+ * &#64;Mapper
+ * public interface GraphMapper {
+ *     NodeDto toNodeDto(Node node, &#64;Context CyclicGraphContext cycleContext);
+ * }
+ *
+ *
+ * // generates:
+ *
+ * public NodeDto toNodeDto(Node node, CyclicGraphContext cycleContext) {
+ *     NodeDto target = cycleContext.getMappedInstance( node, NodeDto.class );
+ *     if ( target != null ) {
+ *         return target;
+ *     }
+ *
+ *     if ( node == null ) {
+ *         return null;
+ *     }
+ *
+ *     NodeDto nodeDto = new NodeDto();
+ *
+ *     cycleContext.storeMappedInstance( node, nodeDto );
+ *
+ *     nodeDto.setParent( toNodeDto( node.getParent(), cycleContext ) );
+ *     List&lt;NodeDto&gt; list = nodeListToNodeDtoList( node.getChildren(), cycleContext );
+ *     if ( list != null ) {
+ *         nodeDto.setChildren( list );
+ *     }
+ *
+ *     // more mapping code
+ *
+ *     return nodeDto;
+ * }
+ * </code>
+ * </pre>
+ * <p>
+ * <strong>Example 3:</strong> Using {@code @Context} parameters for creating an entity object by calling an
+ * {@code @}{@link ObjectFactory} methods:
+ *
+ * <pre>
+ * <code>
+ * // type of the context parameter
+ * public class ContextObjectFactory {
+ *     &#64;PersistenceContext(unitName = "my-unit")
+ *     private EntityManager em;
+ *
+ *     &#64;ObjectFactory
+ *     public Valve create( String id ) {
+ *        Query query = em.createNamedQuery("Valve.findById");
+ *        query.setParameter("id", id);
+ *        Valve result = query.getSingleResult();
+ *        if ( result != null ) {
+ *            result = new Valve( id );
+ *        }
+ *        return result;
+ *     }
+ *
+ * }
+ *
+ * &#64;Mapper
+ * public interface ContextWithObjectFactoryMapper {
+ *     Valve map(ValveDto dto, &#64;Context ContextObjectFactory factory, String id);
+ * }
+ *
+ *
+ * // generates:
+ * public class ContextWithObjectFactoryMapperImpl implements ContextWithObjectFactoryMapper {
+ *
+ *   &#64;Override
+ *   public Valve map(ValveDto dto, ContextObjectFactory factory, String id) {
+ *       if ( dto == null ) {
+ *           return null;
+ *       }
+ *
+ *       Valve valve = factory.create( id );
+ *
+ *       valve.setOneWay( dto.isOneWay() );
+ *
+ *       return valve;
+ *   }
+ * }
+ * </code>
+ * </pre>
+ * @author Andreas Gudian
+ * @since 1.2
+ */
+@Target(ElementType.PARAMETER)
+@Retention(RetentionPolicy.CLASS)
+public @interface Context {
+
+}

core/src/main/java/org/mapstruct/DecoratedWith.java

@@ -0,0 +1,160 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Specifies a decorator to be applied to a generated mapper, which e.g. can be used to amend mappings performed by
+ * generated mapping methods.
+ * <p>
+ * A typical decorator implementation will be an abstract class and only implement/override a subset of the methods of
+ * the mapper type which it decorates. All methods not implemented or overridden by the decorator will be implemented by
+ * the code generator by delegating to the generated mapper implementation.
+ * <p>
+ * <b>NOTE:</b> The usage of decorated mappers differs depending on the selected component model.
+ * <p>
+ * <b>NOTE:</b> This annotation is not supported for the component model {@code cdi}. Use CDI's own
+ * <a href="https://docs.jboss.org/cdi/spec/1.0/html/decorators.html">{@code @Decorator}</a> feature instead.
+ * </p>
+ * <h2>Examples</h2>
+ * <p>
+ * For the examples below, consider the following mapper declaration:
+ *
+ * <pre>
+ * &#64;Mapper(componentModel = "...")
+ * &#64;DecoratedWith(PersonMapperDecorator.class)
+ * public interface PersonMapper {
+ *
+ *     &#64;Mapping(target = "name", ignore = true)
+ *     PersonDto personToPersonDto(Person person);
+ *
+ *     AddressDto addressToAddressDto(Address address); // not touched by the decorator
+ * }
+ * </pre>
+ *
+ * <h3>1. Component model 'default'</h3>
+ * <h4>Referencing the original mapper in the decorator</h4>
+ * <p>
+ * If a constructor with a single parameter accepting the type of the decorated mapper is present, a delegate with
+ * generated implementations of all the mapper methods will be passed to this constructor. A typical implementation will
+ * store the passed delegate in a field of the decorator and make use of it in the decorator methods:
+ *
+ * <pre>
+ * public abstract class PersonMapperDecorator implements PersonMapper {
+ *
+ *     private PersonMapper delegate;
+ *
+ *     public PersonMapperDecorator(PersonMapper delegate) {
+ *         this.delegate = delegate;
+ *     }
+ *
+ *     &#64;Override
+ *     public PersonDto personToPersonDto(Person person) {
+ *         PersonDto dto = delegate.personToPersonDto( person );
+ *         dto.setName( person.getFirstName() + " " + person.getLastName() );
+ *
+ *         return dto;
+ *     }
+ * }
+ * </pre>
+ *
+ * <h4>Using the decorated mapper</h4>
+ * <p>
+ * Nothing special needs to be done. When using {@code Mappers.getMapper( PersonMapper.class )}, the <em>decorator</em>
+ * is returned, with the injected original mapper.
+ * <h3>2. Component model 'spring'</h3>
+ * <h4>Referencing the original mapper in the decorator</h4>
+ * <p>
+ * The generated implementation of the original mapper is annotated with the Spring annotation
+ * {@code @org.springframework.beans.factory.annotation.Qualifier("delegate")}. To autowire that bean in your decorator,
+ * add that qualifier annotation as well:
+ *
+ * <pre>
+ * public abstract class PersonMapperDecorator implements PersonMapper {
+ *
+ *     &#64;Autowired
+ *     &#64;org.springframework.beans.factory.annotation.Qualifier("delegate")
+ *     private PersonMapper delegate;
+ *
+ *     &#64;Override
+ *     public PersonDto personToPersonDto(Person person) {
+ *         PersonDto dto = delegate.personToPersonDto( person );
+ *         dto.setName( person.getFirstName() + " " + person.getLastName() );
+ *
+ *         return dto;
+ *     }
+ * }
+ * </pre>
+ *
+ * <h4>Using the decorated mapper in the decorator</h4>
+ * <p>
+ * The generated class that extends the decorator is annotated with Spring's {@code @Primary} annotation. To autowire
+ * the decorated mapper in the application, nothing special needs to be done:
+ *
+ * <pre>
+ * &#64;Autowired
+ * private PersonMapper personMapper; // injects the decorator, with the injected original mapper
+ * </pre>
+ *
+ * <h3>3. Component model 'jsr330' or 'jakarta'</h3>
+ * <h4>Referencing the original mapper</h4>
+ * <p>
+ * JSR 330 / Jakarta Inject doesn't specify qualifiers and only allows to specifically name the beans. Hence,
+ * the generated implementation of the original mapper is annotated with
+ * {@code @Named("fully-qualified-name-of-generated-impl")} and {@code @Singleton} (please note that when
+ * using a decorator, the class name of the mapper implementation ends with an underscore). To inject that bean in your
+ * decorator, add the same annotation to the delegate field (e.g. by copy/pasting it from the generated class):
+ *
+ * <pre>
+ * public abstract class PersonMapperDecorator implements PersonMapper {
+ *
+ *     &#64;Inject
+ *     &#64;javax.inject.Named("org.examples.PersonMapperImpl_")
+ *     private PersonMapper delegate;
+ *
+ *     &#64;Override
+ *     public PersonDto personToPersonDto(Person person) {
+ *         PersonDto dto = delegate.personToPersonDto( person );
+ *         dto.setName( person.getFirstName() + " " + person.getLastName() );
+ *
+ *         return dto;
+ *     }
+ * }
+ * </pre>
+ *
+ * <h4>Using the decorated mapper in the decorator</h4>
+ * <p>
+ * Unlike with the other component models, the usage site must be aware if a mapper is decorated or not, as for
+ * decorated mappers, the parameterless {@code @javax.inject.Named} annotation must be added to select the
+ * <em>decorator</em> to be injected:
+ *
+ * <pre>
+ * &#64;Inject
+ * &#64;javax.inject.Named
+ * private PersonMapper personMapper; // injects the decorator, with the injected original mapper
+ * </pre>
+ * <p>
+ *
+ * @author Gunnar Morling
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.CLASS)
+public @interface DecoratedWith {
+
+    /**
+     * The decorator type. Must be an abstract class that extends or implements the mapper type to which it is applied.
+     * <p>
+     * For component-model {@code default}, the decorator type must either have a default constructor or a constructor
+     * with a single parameter accepting the type of the decorated mapper.
+     *
+     * @return the decorator type
+     */
+    Class<?> value();
+}

core/src/main/java/org/mapstruct/EnumMapping.java

@@ -0,0 +1,156 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Configured the mapping between two value types.
+ * <p><strong>Example:</strong> Using a suffix for enums</p>
+ * <pre><code class='java'>
+ * public enum CheeseType {
+ *     BRIE,
+ *     ROQUEFORT
+ * }
+ *
+ * public enum CheeseTypeSuffixed {
+ *     BRIE_TYPE,
+ *     ROQUEFORT_TYPE
+ * }
+ *
+ * &#64;Mapper
+ * public interface CheeseMapper {
+ *
+ *     &#64;EnumMapping(nameTransformationStrategy = "suffix", configuration = "_TYPE")
+ *     CheeseTypeSuffixed map(Cheese cheese);
+ *
+ *     &#64;InheritInverseConfiguration
+ *     Cheese map(CheeseTypeSuffixed cheese);
+ *
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * public class CheeseMapperImpl implements CheeseMapper {
+ *
+ *     &#64;Override
+ *     public CheeseTypeSuffixed map(Cheese cheese) {
+ *         if ( cheese == null ) {
+ *             return null;
+ *         }
+ *
+ *         CheeseTypeSuffixed cheeseTypeSuffixed;
+ *
+ *         switch ( cheese ) {
+ *             case BRIE:
+ *                 cheeseTypeSuffixed = CheeseTypeSuffixed.BRIE_TYPE;
+ *                 break;
+ *             case ROQUEFORT:
+ *                 cheeseTypeSuffixed = CheeseTypeSuffixed.ROQUEFORT_TYPE;
+ *                 break;
+ *             default:
+ *                 throw new IllegalArgumentException( "Unexpected enum constant: " + cheese );
+ *         }
+ *
+ *         return cheeseTypeSuffixed;
+ *     }
+ *
+ *     &#64;Override
+ *     public Cheese map(CheeseTypeSuffixed cheese) {
+ *         if ( cheese == null ) {
+ *             return null;
+ *         }
+ *
+ *         CheeseType cheeseType;
+ *
+ *         switch ( cheese ) {
+ *             case BRIE_TYPE:
+ *                 cheeseType = CheeseType.BRIE;
+ *                 break;
+ *             case ROQUEFORT_TYPE:
+ *                 cheeseType = CheeseType.ROQUEFORT;
+ *                 break;
+ *             default:
+ *                 throw new IllegalArgumentException( "Unexpected enum constant: " + cheese );
+ *         }
+ *
+ *         return cheeseType;
+ *     }
+ * }
+ * </code></pre>
+ *
+ * @author Filip Hrisafov
+ * @since 1.4
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.CLASS)
+public @interface EnumMapping {
+
+    /**
+     * Specifies the name transformation strategy that should be used for implicit mapping between enums.
+     * Known strategies are:
+     * <ul>
+     *     <li>{@link MappingConstants#SUFFIX_TRANSFORMATION} - applies the given {@link #configuration()} as a
+     *     suffix to the source enum</li>
+     *     <li>{@link MappingConstants#STRIP_SUFFIX_TRANSFORMATION} - strips the given {@link #configuration()}
+     *     from the end of the source enum</li>
+     *     <li>{@link MappingConstants#PREFIX_TRANSFORMATION} - applies the given {@link #configuration()} as a
+     *     prefix to the source enum</li>
+     *     <li>{@link MappingConstants#STRIP_PREFIX_TRANSFORMATION} - strips the given {@link #configuration()} from
+     *     the start of the source enum</li>
+     *     <li>
+     *         {@link MappingConstants#CASE_TRANSFORMATION} - applies the given {@link #configuration()} case
+     *         transformation to the source enum. Supported configurations are:
+     *         <ul>
+     *             <li><i>upper</i> - Performs upper case transformation to the source enum</li>
+     *             <li><i>lower</i> - Performs lower case transformation to the source enum</li>
+     *             <li>
+     *                 <i>capital</i> - Performs capitalisation of the first character of every word in the source enum
+     *                 and everything else to lower case. A word is split by "_".
+     *             </li>
+     *         </ul>
+     *     </li>
+     * </ul>
+     *
+     * It is possible to use custom name transformation strategies by implementing the {@code
+     * EnumTransformationStrategy} SPI.
+     *
+     * @return the name transformation strategy
+     */
+    String nameTransformationStrategy() default "";
+
+    /**
+     * The configuration that should be passed on the appropriate name transformation strategy.
+     * e.g. a suffix that should be applied to the source enum when doing name based mapping.
+     *
+     * @return the configuration to use
+     */
+    String configuration() default "";
+
+    /**
+     * Exception that should be thrown by the generated code if no mapping matches.
+     * If no exception is configured, the exception given via {@link MapperConfig#unexpectedValueMappingException()} or
+     * {@link Mapper#unexpectedValueMappingException()} will be used, using {@link IllegalArgumentException} by default.
+     *
+     * <p>
+     * Note:
+     * <ul>
+     *     <li>
+     *      The defined exception should at least have a constructor with a {@link String} parameter.
+     *     </li>
+     *     <li>
+     *      If the defined exception is a checked exception then the enum mapping methods should have that exception
+     *      in the throws clause.
+     *     </li>
+     * </ul>
+     *
+     * @return the exception that should be used in the generated code
+     */
+    Class<? extends Exception> unexpectedValueMappingException() default IllegalArgumentException.class;
+}

core/src/main/java/org/mapstruct/Ignored.java

@@ -0,0 +1,67 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Configures the ignored of one bean attribute.
+ *
+ * <p>
+ * The name all attributes of for ignored is to be specified via {@link #targets()}.
+ * </p>
+ *
+ * <p>
+ * <strong>Example 1:</strong> Implicitly mapping fields with the same name:
+ * </p>
+ *
+ * <pre><code class='java'>
+ * // We need ignored Human.name and Human.lastName
+ * // we can use &#64;Ignored with parameters "name", "lastName" {@link #targets()}
+ * &#64;Mapper
+ * public interface HumanMapper {
+ *    &#64;Ignored( targets = { "name", "lastName" } )
+ *    HumanDto toHumanDto(Human human)
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates:
+ * &#64;Override
+ * public HumanDto toHumanDto(Human human) {
+ *    humanDto.setFullName( human.getFullName() );
+ *    // ...
+ * }
+ * </code></pre>
+ *
+ * @author Ivashin Aleksey
+ */
+@Repeatable(IgnoredList.class)
+@Retention(RetentionPolicy.CLASS)
+@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
+public @interface Ignored {
+
+    /**
+     * Whether the specified properties should be ignored by the generated mapping method.
+     * This can be useful when certain attributes should not be propagated from source to target or when properties in
+     * the target object are populated using a decorator and thus would be reported as unmapped target property by
+     * default.
+     *
+     * @return The target names of the configured properties that should be ignored
+     */
+    String[] targets();
+
+    /**
+     * The prefix that should be applied to all the properties specified via {@link #targets()}.
+     *
+     * @return The target prefix to be applied to the defined properties
+     */
+    String prefix() default "";
+
+}

core/src/main/java/org/mapstruct/IgnoredList.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Configures the ignored list for several bean attributes.
+ * <p>
+ * <strong>TIP: When using Java 8 or later, you can omit the {@code @IgnoredList}
+ * wrapper annotation and directly specify several {@code @Ignored} annotations on one method.</strong>
+ *
+ * <p>These two examples are equal.
+ * </p>
+ * <pre><code class='java'>
+ * // before Java 8
+ * &#64;Mapper
+ * public interface MyMapper {
+ *     &#64;IgnoredList({
+ *         &#64;Ignored(targets = { "firstProperty" } ),
+ *         &#64;Ignored(targets = { "secondProperty" } )
+ *     })
+ *     HumanDto toHumanDto(Human human);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // Java 8 and later
+ * &#64;Mapper
+ * public interface MyMapper {
+ *     &#64;Ignored(targets = { "firstProperty" } ),
+ *     &#64;Ignored(targets = { "secondProperty" } )
+ *     HumanDto toHumanDto(Human human);
+ * }
+ * </code></pre>
+ *
+ * @author Ivashin Aleksey
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE })
+public @interface IgnoredList {
+
+    /**
+     * The configuration of the bean attributes.
+     *
+     * @return The configuration of the bean attributes.
+     */
+    Ignored[] value();
+}

core/src/main/java/org/mapstruct/InheritConfiguration.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Advises the code generator to apply the configuration (as given via {@link Mapping}, {@link IterableMapping} etc.)
+ * from another mapping method (declared on the same mapper type) or prototype method (declared on a mapper config class
+ * referenced via {@link Mapper#config()}) to the annotated method as well.
+ * <p>
+ * If no method can be identified unambiguously as configuration source (i.e. several candidate methods with matching
+ * source and target type exist), the name of the method to inherit from must be specified via {@link #name()}.
+ * <p>
+ * {@link Mapping#expression()}, {@link Mapping#constant()}, {@link Mapping#defaultExpression()} and
+ * {@link Mapping#defaultValue()} are not inverse inherited
+ *
+ * <p>
+ * A typical use case is annotating an update method so it inherits all mappings from a corresponding "standard" mapping
+ * method:
+ *
+ * <pre>
+ * <code>
+ * &#64;Mappings({
+ *     &#64;Mapping(target="make", source="brand"),
+ *     &#64;Mapping(target="seatCount", source="numberOfSeats")
+ * })
+ * CarDto carToCarDto(Car car);
+ *
+ * &#64;InheritConfiguration
+ * void updateCarDto(Car car, &#64;MappingTarget CarDto carDto);
+ * </code>
+ * </pre>
+ *
+ * @author Sjaak Derksen
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.CLASS)
+public @interface InheritConfiguration {
+
+    /**
+     * The name of the mapping method to inherit the mappings from. Needs only to be specified in case more than one
+     * method with matching source and target type exists.
+     *
+     * @return The name of the mapping method to inherit the mappings from.
+     */
+    String name() default "";
+}

core/src/main/java/org/mapstruct/InheritInverseConfiguration.java

@@ -0,0 +1,90 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Advises the code generator to apply all the {@link Mapping}s from an inverse mapping method to the annotated method
+ * as well. An inverse mapping method is a method which has the annotated method's source type as target type (return
+ * type or indicated through a parameter annotated with {@link MappingTarget}) and the annotated method's target type as
+ * source type.
+ * <p>
+ * Any mappings given on the annotated method itself are added to those mappings inherited from the inverse method. In
+ * case of a conflict local mappings take precedence over inherited mappings.
+ * <p>
+ * If more than one matching inverse method exists, the name of the method to inherit the configuration from must be
+ * specified via {@link #name()}
+ * <p>
+ * {@link Mapping#expression()}, {@link Mapping#constant()}, {@link Mapping#defaultExpression()} and
+ * {@link Mapping#defaultValue()} are not inverse inherited
+ *
+ * <p>
+ * <strong>Examples</strong>
+ * </p>
+ * <pre><code class='java'>
+ * &#64;Mapper
+ * public interface HumanMapper {
+ *      Human toHuman(HumanDto humanDto);
+ *      &#64;InheritInverseConfiguration
+ *      HumanDto toHumanDto(Human human);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * public class HumanMapperImpl implements HumanMapper {
+ *      &#64;Override
+ *      public Human toHuman(HumanDto humanDto) {
+ *          if ( humanDto == null ) {
+ *              return null;
+ *           }
+ *          Human human = new Human();
+ *          human.setName( humanDto.getName() );
+ *          return human;
+ *      }
+ *      &#64;Override
+ *      public HumanDto toHumanDto(Human human) {
+ *          if ( human == null ) {
+ *              return null;
+ *          }
+ *          HumanDto humanDto = new HumanDto();
+ *          humanDto.setName( human.getName() );
+ *          return humanDto;
+ *      }
+ * }
+ * </code></pre>
+ *
+ * <pre><code class='java'>
+ * &#64;Mapper
+ * public interface CarMapper {
+ *
+ * &#64;Mapping( target = "seatCount", source = "numberOfSeats")
+ * &#64;Mapping( target = "enginePower", source = "engineClass", ignore=true) // NOTE: source specified as well
+ * CarDto carToDto(Car car);
+ *
+ * &#64;InheritInverseConfiguration
+ * &#64;Mapping(target = "numberOfSeats", ignore = true)
+ * // no need to specify a mapping with ignore for "engineClass": specifying source above will assume
+ * Car carDtoToCar(CarDto carDto);
+ * }
+ * </code></pre>
+ * @author Sjaak Derksen
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.CLASS)
+public @interface InheritInverseConfiguration {
+
+    /**
+     * The name of the inverse mapping method to inherit the mappings from. Needs to be specified only in case more than
+     * one inverse method exists with a matching source and target type exists.
+     *
+     * @return The name of the inverse mapping method to inherit the mappings from.
+     */
+    String name() default "";
+}

core/src/main/java/org/mapstruct/InjectionStrategy.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+/**
+ * Strategy for handling injection. This is only used on annotated based component models such as CDI, Spring and
+ * JSR330 / Jakarta.
+ *
+ * @author Kevin Grüneberg
+ * @author Lucas Resch
+ */
+public enum InjectionStrategy {
+
+    /** Annotations are written on the field **/
+    FIELD,
+
+    /** Annotations are written on the constructor **/
+    CONSTRUCTOR,
+
+    /** A dedicated setter method is created */
+    SETTER
+}

core/src/main/java/org/mapstruct/IterableMapping.java

@@ -0,0 +1,159 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.Annotation;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import java.text.DecimalFormat;
+import java.text.SimpleDateFormat;
+import java.util.Date;
+
+import org.mapstruct.control.MappingControl;
+
+/**
+ * Configures the mapping between two iterable like types, e.g. {@code List<String>} and {@code List<Date>}.
+ *
+ *
+ * <p>Note: either  {@link #dateFormat()}, {@link #elementTargetType()} or {@link #qualifiedBy() }
+ * must be specified</p>
+ *
+ * <p>
+ * <strong>Example:</strong> Convert List&lt;Float&gt; to List&lt;String&gt;
+ * </p>
+ * <pre><code class='java'>
+ * &#64;Mapper
+ * public interface FloatToStringMapper {
+ *      &#64;IterableMapping( numberFormat = "##.00" )
+ *      List&lt;String&gt; sourceToTarget(List&lt;Float&gt; source);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * public class FloatToStringMapperImpl implements FloatToStringMapper {
+ *      &#64;Override
+ *      public List&lt;String&gt; sourceToTarget(List&lt;Float&gt; source) {
+ *          List&lt;String&gt; list = new ArrayList&lt;String&gt;( source.size() );
+ *          for ( Float float1 : source ) {
+ *              list.add( new DecimalFormat( "##.00" ).format( float1 ) );
+ *          }
+ *     // ...
+ *      }
+ * }
+ * </code></pre>
+ *
+ * Supported mappings are:
+ * <ul>
+ *     <li>{@code Iterable<A>} to/from {@code Iterable<B>}/{@code Iterable<A>}</li>
+ *     <li>{@code Iterable<A>} to/from {@code B[]}/{@code A[]}</li>
+ *     <li>{@code Iterable<A>} to/from {@code Stream<B>}/{@code Stream<A>}</li>
+ *     <li>{@code A[]} to/from {@code Stream<B>}/{@code Stream<A>}</li>
+ *     <li>{@code A[]} to/from {@code B[]}</li>
+ *     <li>{@code Stream<A>} to/from {@code Stream<B>}</li>
+ * </ul>
+ *
+ * @author Gunnar Morling
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.CLASS)
+public @interface IterableMapping {
+
+    /**
+     * A format string as processable by {@link SimpleDateFormat} if the annotated method maps from an iterable of
+     * {@code String} to an iterable {@link Date} or vice-versa. Will be ignored for all other element types.
+     * <p>
+     * If the {@link #locale()} is also specified, the format will consider the specified locale when processing
+     * the date. Otherwise, the system's default locale will be used.
+     *
+     * @return A date format string as processable by {@link SimpleDateFormat}.
+     * @see #locale()
+     */
+    String dateFormat() default "";
+
+    /**
+     * A format string as processable by {@link DecimalFormat} if the annotated method maps from a
+     *  {@link Number} to a {@link String} or vice-versa. Will be ignored for all other element types.
+     * <p>
+     * If the {@link #locale()} is also specified, the number format will be applied in the context of the given locale.
+     * Otherwise, the system's default locale will be used to process the number format.
+     *
+     * @return A decimal format string as processable by {@link DecimalFormat}.
+     * @see #locale()
+     */
+    String numberFormat() default "";
+
+    /**
+     * Specifies the locale to be used when processing {@link #dateFormat()} or {@link #numberFormat()}.
+     * <p>
+     * The locale should be a plain tag representing the language, such as "en" for English, "de" for German, etc.
+     * <p>
+     * If no locale is specified, the system's default locale will be used.
+     *
+     * @return A string representing the locale to be used when formatting dates or numbers.
+     */
+    String locale() default "";
+
+    /**
+     * A qualifier can be specified to aid the selection process of a suitable mapper. This is useful in case multiple
+     * mappers (hand written of internal) qualify and result in an 'Ambiguous mapping methods found' error.
+     *
+     * A qualifier is a custom annotation and can be placed on either a hand written mapper class or a method.
+     *
+     * @return the qualifiers
+     * @see Qualifier
+     */
+    Class<? extends Annotation>[] qualifiedBy() default { };
+
+    /**
+     * String-based form of qualifiers; When looking for a suitable mapping method to map this iterable mapping method's
+     * element type, MapStruct will only consider those methods carrying directly or indirectly (i.e. on the
+     * class-level) a {@link Named} annotation for each of the specified qualifier names.
+     * <p>
+     * Note that annotation-based qualifiers are generally preferable as they allow more easily to find references and
+     * are safe for refactorings, but name-based qualifiers can be a less verbose alternative when requiring a large
+     * number of qualifiers as no custom annotation types are needed.
+     *
+     * @return One or more qualifier name(s)
+     * @see #qualifiedBy()
+     * @see Named
+     */
+    String[] qualifiedByName() default { };
+
+    /**
+     * Specifies the type of the element to be used in the result of the mapping method in case multiple mapping
+     * methods qualify.
+     *
+     * @return the elementTargetType to select
+     */
+    Class<?> elementTargetType() default void.class;
+
+
+    /**
+     * The strategy to be applied when {@code null} is passed as source value to this iterable mapping. If no
+     * strategy is configured, the strategy given via {@link MapperConfig#nullValueMappingStrategy()} or
+     * {@link Mapper#nullValueMappingStrategy()} will be applied, using {@link NullValueMappingStrategy#RETURN_NULL}
+     * by default.
+     *
+     * @return The strategy to be applied when {@code null} is passed as source value to the methods of this mapping.
+     */
+    NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
+
+    /**
+     * Allows detailed control over the mapping process.
+     *
+     * @return the mapping control
+     *
+     * @since 1.4
+     *
+     * @see org.mapstruct.control.DeepClone
+     * @see org.mapstruct.control.NoComplexMapping
+     * @see org.mapstruct.control.MappingControl
+     */
+    Class<? extends Annotation> elementMappingControl() default MappingControl.class;
+
+}

core/src/main/java/org/mapstruct/Javadoc.java

@@ -0,0 +1,115 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Allows the definition of Javadoc comments in the MapStruct <code>Mapper</code> generated class.
+ *
+ * <p>The annotation provides support for the usual Javadoc comments elements by defining analogous attributes.</p>
+ *
+ *
+ * <p>Please, note that at least one of these attributes must be specified.</p>
+ *
+ * <p>
+ * For instance, the following definition;
+ * </p>
+ * <pre><code class='java'>
+ * &#64;Javadoc(
+ *     value = "This is the description",
+ *     authors = { "author1", "author2" },
+ *     deprecated = "Use {&#64;link OtherMapper} instead",
+ *     since = "0.1"
+ * )
+ * </code></pre>
+ *
+ * <p>
+ * will generate:
+ * </p>
+ *
+ * <pre><code class='java'>
+ * /**
+ * * This is the description
+ * *
+ * * &#64;author author1
+ * * &#64;author author2
+ * *
+ * * &#64;deprecated Use {&#64;link OtherMapper} instead
+ * * &#64;since 0.1
+ * *&#47;
+ * </code></pre>
+ *
+ * <p>
+ * The entire Javadoc comment block can be passed directly:
+ * </p>
+ * <pre><code class='java'>
+ * &#64;Javadoc("This is the description\n"
+ *            + "\n"
+ *            + "&#64;author author1\n"
+ *            + "&#64;author author2\n"
+ *            + "\n"
+ *            + "&#64;deprecated Use {&#64;link OtherMapper} instead\n"
+ *            + "&#64;since 0.1\n"
+ * )
+ * </code></pre>
+ *
+ * <pre><code class='java'>
+ * // or using Text Blocks
+ * &#64;Javadoc(
+ *     """
+ *     This is the description
+ *
+ *     &#64;author author1
+ *     &#64;author author2
+ *
+ *     &#64;deprecated Use {&#64;link OtherMapper} instead
+ *     &#64;since 0.1
+ *     """
+ * )
+ * </code></pre>
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.SOURCE)
+public @interface Javadoc {
+    /**
+     * Main Javadoc comment text block.
+     *
+     * @return Main Javadoc comment text block.
+     */
+    String value() default "";
+
+    /**
+     * List of authors of the code that it is being documented.
+     * <p>
+     * It will generate a list of the Javadoc tool comment element <code>&#64;author</code>
+     * with the different values and in the order provided.
+     *
+     * @return array of javadoc authors.
+     */
+    String[] authors() default { };
+
+    /**
+     * Specifies that the functionality that is being documented is deprecated.
+     * <p>
+     * Corresponds to the <code>&#64;deprecated</code> Javadoc tool comment element.
+     *
+     * @return Deprecation message about the documented functionality
+     */
+    String deprecated() default "";
+
+    /**
+     * Specifies the version since the functionality that is being documented is available.
+     * <p>
+     * Corresponds to the <code>&#64;since</code> Javadoc tool comment element.
+     *
+     * @return Version since the functionality is available
+     */
+    String since() default "";
+}

core/src/main/java/org/mapstruct/MapMapping.java

@@ -0,0 +1,227 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.Annotation;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import java.text.DecimalFormat;
+import java.text.SimpleDateFormat;
+import java.util.Date;
+
+import org.mapstruct.control.MappingControl;
+
+/**
+ * Configures the mapping between two map types, e.g. Map<String, String> and Map<Long, Date>.
+ *
+ * <p>
+ * <strong>Example</strong>:
+ * </p>
+ * <pre><code class='java'>
+ * &#64;Mapper
+ * public interface SimpleMapper {
+ *       &#64;MapMapping(valueDateFormat = "dd.MM.yyyy")
+ *       Map&lt;String, String&gt; longDateMapToStringStringMap(Map&lt;Long, Date&gt; source);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * public class SimpleMapperImpl implements SimpleMapper {
+ *      &#64;Override
+ *      public Map&lt;String, String&gt; longDateMapToStringStringMap(Map&lt;Long, Date&gt; source) } {
+ *          Map&lt;String, String&gt; map = new HashMap&lt;String, String&gt;(); }
+ *          for ( java.util.Map.Entry&lt;Long, Date&gt; entry : source.entrySet() ) } {
+ *              String key = new DecimalFormat( "" ).format( entry.getKey() );
+ *              String value = new SimpleDateFormat( "dd.MM.yyyy" ).format( entry.getValue() );
+ *              map.put( key, value );
+ *          }
+ *          // ...
+ *      }
+ * }
+ * </code></pre>
+ *
+ * <p><strong>NOTE:</strong> at least one element needs to be specified</p>
+ *
+ * @author Gunnar Morling
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.CLASS)
+public @interface MapMapping {
+
+    /**
+     * A format string as processable by {@link SimpleDateFormat} if the annotated method maps from a map with key type
+     * {@code String} to an map with key type {@link Date} or vice-versa. Will be ignored for all other key types.
+     * <p>
+     * If the {@link #locale()} is specified, the format will consider the specified locale when processing the date.
+     * Otherwise, the system's default locale will be used.
+     *
+     * @return A date format string as processable by {@link SimpleDateFormat}.
+     * @see #locale()
+     */
+    String keyDateFormat() default "";
+
+    /**
+     * A format string as processable by {@link SimpleDateFormat} if the annotated method maps from a map with value
+     * type {@code String} to an map with value type {@link Date} or vice-versa. Will be ignored for all other value
+     * types.
+     * <p>
+     * If the {@link #locale()} is specified, the format will consider the specified locale when processing the date.
+     * Otherwise, the system's default locale will be used.
+     *
+     * @return A date format string as processable by {@link SimpleDateFormat}.
+     * @see #locale()
+     */
+    String valueDateFormat() default "";
+
+    /**
+     * A format string as processable by {@link DecimalFormat} if the annotated method maps from a
+     *  {@link Number} to a {@link String} or vice-versa. Will be ignored for all other key types.
+     * <p>
+     * If the {@link #locale()} is specified, the number format will be applied in the context of the given locale.
+     * Otherwise, the system's default locale will be used.
+     *
+     * @return A decimal format string as processable by {@link DecimalFormat}.
+     * @see #locale()
+     */
+    String keyNumberFormat() default "";
+
+    /**
+     * A format string as processable by {@link DecimalFormat} if the annotated method maps from a
+     *  {@link Number} to a {@link String} or vice-versa. Will be ignored for all other value types.
+     * <p>
+     * If the {@link #locale()} is specified, the number format will be applied in the context of the given locale.
+     * Otherwise, the system's default locale will be used.
+     *
+     * @return A decimal format string as processable by {@link DecimalFormat}.
+     * @see #locale()
+     */
+    String valueNumberFormat() default "";
+
+    /**
+     * Specifies the locale to be used when processing {@link SimpleDateFormat} or {@link DecimalFormat} for key or
+     * value mappings in maps. The locale should be a plain tag representing the language, such as "en" for English,
+     * "de" for German, etc.
+     * <p>
+     * If no locale is specified, the system's default locale will be used.
+     *
+     * @return A string representing the locale to be used when formatting dates or numbers in maps.
+     */
+    String locale() default "";
+
+    /**
+     * A key value qualifier can be specified to aid the selection process of a suitable mapper. This is useful in
+     * case multiple mappers (hand written of internal) qualify and result in an 'Ambiguous mapping methods found'
+     * error.
+     *
+     * A qualifier is a custom annotation and can be placed on either a hand written mapper class or a method.
+     *
+     * @return the qualifiers
+     * @see Qualifier
+     */
+    Class<? extends Annotation>[] keyQualifiedBy() default { };
+
+    /**
+     * String-based form of qualifiers; When looking for a suitable mapping method to map this map mapping method's key
+     * type, MapStruct will only consider those methods carrying directly or indirectly (i.e. on the class-level) a
+     * {@link Named} annotation for each of the specified qualifier names.
+     * <p>
+     * Note that annotation-based qualifiers are generally preferable as they allow more easily to find references and
+     * are safe for refactorings, but name-based qualifiers can be a less verbose alternative when requiring a large
+     * number of qualifiers as no custom annotation types are needed.
+     *
+     * @return One or more qualifier name(s)
+     * @see #keyQualifiedBy()
+     * @see Named
+     */
+    String[] keyQualifiedByName() default { };
+
+
+    /**
+     * A value qualifier can be specified to aid the selection process of a suitable mapper for the values in the map.
+     * This is useful in case multiple mappers (hand written of internal) qualify and result in an 'Ambiguous mapping
+     * methods found' error.
+     * <p>
+     * A qualifier is a custom annotation and can be placed on either a hand written mapper class or a method.
+     *
+     * @return the qualifiers
+     * @see Qualifier
+     */
+    Class<? extends Annotation>[] valueQualifiedBy() default { };
+
+    /**
+     * String-based form of qualifiers; When looking for a suitable mapping method to map this map mapping method's
+     * value type, MapStruct will only consider those methods carrying directly or indirectly (i.e. on the class-level)
+     * a {@link Named} annotation for each of the specified qualifier names.
+     * <p>
+     * Note that annotation-based qualifiers are generally preferable as they allow more easily to find references and
+     * are safe for refactorings, but name-based qualifiers can be a less verbose alternative when requiring a large
+     * number of qualifiers as no custom annotation types are needed.
+     *
+     * @return One or more qualifier name(s)
+     * @see #valueQualifiedBy()
+     * @see Named
+     */
+    String[] valueQualifiedByName() default { };
+
+    /**
+     * Specifies the type of the key to be used in the result of the mapping method in case multiple mapping
+     * methods qualify.
+     *
+     *
+     * @return the resultType to select
+     */
+    Class<?> keyTargetType() default void.class;
+
+    /**
+     * Specifies the type of the value to be used in the result of the mapping method in case multiple mapping
+     * methods qualify.
+     *
+     *
+     * @return the resultType to select
+     */
+    Class<?> valueTargetType() default void.class;
+
+
+    /**
+     * The strategy to be applied when {@code null} is passed as source value to this map mapping. If no
+     * strategy is configured, the strategy given via {@link MapperConfig#nullValueMappingStrategy()} or
+     * {@link Mapper#nullValueMappingStrategy()} will be applied, using {@link NullValueMappingStrategy#RETURN_NULL}
+     * by default.
+     *
+     * @return The strategy to be applied when {@code null} is passed as source value to the methods of this mapping.
+     */
+    NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
+
+    /**
+     * Allows detailed control over the key mapping process.
+     *
+     * @return the mapping control
+     *
+     * @since 1.4
+
+     * @see org.mapstruct.control.DeepClone
+     * @see org.mapstruct.control.NoComplexMapping
+     * @see org.mapstruct.control.MappingControl
+     */
+    Class<? extends Annotation> keyMappingControl() default MappingControl.class;
+
+
+    /**
+     * Allows detailed control over the value mapping process.
+     *
+     * @return the mapping control
+     *
+     * @since 1.4
+     *
+     * @see org.mapstruct.control.DeepClone
+     * @see org.mapstruct.control.NoComplexMapping
+     * @see org.mapstruct.control.MappingControl
+     */
+    Class<? extends Annotation> valueMappingControl() default MappingControl.class;
+
+}

core/src/main/java/org/mapstruct/Mapper.java

@@ -0,0 +1,391 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.Annotation;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.mapstruct.control.MappingControl;
+import org.mapstruct.factory.Mappers;
+
+import static org.mapstruct.NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
+import static org.mapstruct.SubclassExhaustiveStrategy.COMPILE_ERROR;
+
+/**
+ * Marks an interface or abstract class as a mapper and activates the generation of a implementation of that type via
+ * MapStruct.
+ *
+ * <p>
+ * <strong>Example 1:</strong> Creating mapper
+ * </p>
+ * <pre><code class='java'>
+ * &#64;Mapper
+ * public interface CarMapper {
+ *     CarDto toCarDto(Car source);
+ * }
+ * </code></pre>
+ * <p>
+ * <strong>Example 2:</strong> Use additional mappers with parameters {@link #uses()}, {@link #componentModel()}
+ * and {@link #injectionStrategy()}
+ * </p>
+ * <pre><code class='java'>
+ * // we have MarkMapper (map field "mark" to field "name" to upper case)
+ * &#64;Mapper(componentModel = MappingConstants.ComponentModel.SPRING)
+ * public class MarkMapper {
+ *     public String mapMark(String mark) {
+ *         return mark.toUpperCase();
+ *     }
+ * }
+ * // we have CarMapper
+ * &#64;Mapper(
+ *      componentModel = MappingConstants.ComponentModel.SPRING,
+ *      uses = MarkMapper.class,
+ *      injectionStrategy = InjectionStrategy.CONSTRUCTOR)
+ * public interface CarMapper {
+ *     &#64;Mapping(target = "name", source = "mark")
+ *     CarDto convertMap(CarEntity carEntity);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * &#64;Component
+ * public class CarMapperImpl implements CarMapper {
+ *     private final MarkMapper markMapper;
+ *     &#64;Autowired
+ *     public CarMapperImpl(MarkMapper markMapper) {
+ *         this.markMapper = markMapper;
+ *     }
+ *     &#64;Override
+ *     public CarDto convertMap(CarEntity carEntity) {
+ *         if ( carEntity == null ) {
+ *             return null;
+ *         }
+ *         CarDto carDto = new CarDto();
+ *         carDto.setName( markMapper.mapMark( carEntity.getMark() ) );
+ *         return carDto;
+ *     }
+ * }
+ * </code></pre>
+ *
+ * @author Gunnar Morling
+ * @see Javadoc
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.CLASS)
+public @interface Mapper {
+
+    /**
+     * Other mapper types used by this mapper. May be hand-written classes or other mappers generated by MapStruct. No
+     * cycle between generated mapper classes must be created.
+     *
+     * @return The mapper types used by this mapper.
+     */
+    Class<?>[] uses() default { };
+
+    /**
+     * Additional types for which an import statement is to be added to the generated mapper implementation class.
+     * This allows to refer to those types from within mapping expressions given via {@link Mapping#expression()},
+     * {@link Mapping#defaultExpression()} or using
+     * their simple name rather than their fully-qualified name.
+     *
+     * @return classes to add in the imports of the generated implementation.
+     */
+    Class<?>[] imports() default { };
+
+    /**
+     * How unmapped properties of the source type of a mapping should be
+     * reported. The method overrides an unmappedSourcePolicy set in a central
+     * configuration set by {@link #config() }
+     *
+     * @return The reporting policy for unmapped source properties.
+     *
+     * @since 1.3
+     */
+    ReportingPolicy unmappedSourcePolicy() default ReportingPolicy.IGNORE;
+
+    /**
+     * How unmapped properties of the target type of a mapping should be
+     * reported. The method overrides an unmappedTargetPolicy set in a central
+     * configuration set by {@link #config() }
+     *
+     * @return The reporting policy for unmapped target properties.
+     */
+    ReportingPolicy unmappedTargetPolicy() default ReportingPolicy.WARN;
+
+    /**
+     * How lossy (narrowing) conversion, for instance long to integer should be
+     * reported. The method overrides an typeConversionPolicy set in a central
+     * configuration set by {@link #config() }
+     *
+     * @since 1.3
+     *
+     * @return The reporting policy for unmapped target properties.
+     */
+    ReportingPolicy typeConversionPolicy() default ReportingPolicy.IGNORE;
+
+    /**
+     * Specifies the component model to which the generated mapper should
+     * adhere. Supported values are
+     * <ul>
+     * <li> {@code default}: the mapper uses no component model, instances are
+     * typically retrieved via {@link Mappers#getMapper(Class)}</li>
+     * <li>
+     * {@code cdi}: the generated mapper is an application-scoped CDI bean and
+     * can be retrieved via {@code @Inject}</li>
+     * <li>
+     * {@code spring}: the generated mapper is a Spring bean and
+     * can be retrieved via {@code @Autowired}</li>
+     * <li>
+     * {@code jsr330}: the generated mapper is annotated with {@code @javax.inject.Named} and
+     * {@code @Singleton}, and can be retrieved via {@code @Inject}.
+     * The annotations will either be from javax.inject or jakarta.inject,
+     * depending on which one is available, with javax.inject having precedence.</li>
+     * <li>
+     * {@code jakarta}: the generated mapper is annotated with {@code @jakarta.inject.Named} and
+     * {@code @Singleton}, and can be retrieved via {@code @Inject}.</li>
+     * </ul>
+     * The method overrides a componentModel set in a central configuration set
+     * by {@link #config() }
+     *
+     * @return The component model for the generated mapper.
+     */
+    String componentModel() default MappingConstants.ComponentModel.DEFAULT;
+
+    /**
+     * Specifies the name of the implementation class. The {@code <CLASS_NAME>} will be replaced by the
+     * interface/abstract class name.
+     * <p>
+     * Defaults to postfixing the name with {@code Impl}: {@code <CLASS_NAME>Impl}
+     *
+     * @return The implementation name.
+     * @see #implementationPackage()
+     */
+    String implementationName() default "<CLASS_NAME>Impl";
+
+    /**
+     * Specifies the target package for the generated implementation. The {@code <PACKAGE_NAME>} will be replaced by the
+     * interface's or abstract class' package.
+     * <p>
+     * Defaults to using the same package as the mapper interface/abstract class
+     *
+     * @return the implementation package.
+     * @see #implementationName()
+     */
+    String implementationPackage() default "<PACKAGE_NAME>";
+
+    /**
+     * A class annotated with {@link MapperConfig} which should be used as configuration template. Any settings given
+     * via {@link Mapper} will take precedence over the settings from the referenced configuration source. The list of
+     * referenced mappers will contain all mappers given via {@link Mapper#uses()} and {@link MapperConfig#uses()}.
+     *
+     * @return A class which should be used as configuration template.
+     */
+    Class<?> config() default void.class;
+
+    /**
+     * The strategy to be applied when propagating the value of collection-typed properties. By default, only JavaBeans
+     * accessor methods (setters or getters) will be used, but it is also possible to invoke a corresponding adder
+     * method for each element of the source collection (e.g. {@code orderDto.addOrderLine()}).
+     * <p>
+     * Any setting given for this attribute will take precedence over {@link MapperConfig#collectionMappingStrategy()},
+     * if present.
+     *
+     * @return The strategy applied when propagating the value of collection-typed properties.
+     */
+    CollectionMappingStrategy collectionMappingStrategy() default CollectionMappingStrategy.ACCESSOR_ONLY;
+
+    /**
+     * The strategy to be applied when {@code null} is passed as source argument value to the methods of this mapper.
+     * If no strategy is configured, the strategy given via {@link MapperConfig#nullValueMappingStrategy()} will be
+     * applied, using {@link NullValueMappingStrategy#RETURN_NULL} by default.
+     *
+     * @return The strategy to be applied when {@code null} is passed as source value to the methods of this mapper.
+     */
+    NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
+
+    /**
+     * The strategy to be applied when {@code null} is passed as source argument value to an {@link IterableMapping} of
+     * this mapper. If unset, the strategy set with {@link #nullValueMappingStrategy()} will be applied. If neither
+     * strategy is configured, the strategy given via {@link MapperConfig#nullValueIterableMappingStrategy()} will be
+     * applied, using {@link NullValueMappingStrategy#RETURN_NULL} by default.
+     *
+     * @since 1.5
+     *
+     * @return The strategy to be applied when {@code null} is passed as source value to an {@link IterableMapping} of
+     * this mapper.
+     */
+    NullValueMappingStrategy nullValueIterableMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
+
+    /**
+     * The strategy to be applied when {@code null} is passed as source argument value to a {@link MapMapping} of this
+     * mapper. If unset, the strategy set with {@link #nullValueMappingStrategy()} will be applied. If neither strategy
+     * is configured, the strategy given via {@link MapperConfig#nullValueMapMappingStrategy()} will be applied, using
+     * {@link NullValueMappingStrategy#RETURN_NULL} by default.
+     *
+     * @since 1.5
+     *
+     * @return The strategy to be applied when {@code null} is passed as source value to a {@link MapMapping} of this
+     * mapper.
+     */
+    NullValueMappingStrategy nullValueMapMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
+
+    /**
+     * The strategy to be applied when a source bean property is {@code null} or not present. If no strategy is
+     * configured, the strategy given via {@link MapperConfig#nullValuePropertyMappingStrategy()} will be applied,
+     * {@link NullValuePropertyMappingStrategy#SET_TO_NULL} will be used by default.
+     *
+     * @since 1.3
+     *
+     * @return The strategy to be applied when {@code null} is passed as source property value or the source property
+     * is not present.
+     */
+    NullValuePropertyMappingStrategy nullValuePropertyMappingStrategy() default
+        NullValuePropertyMappingStrategy.SET_TO_NULL;
+
+    /**
+     * The strategy to use for applying method-level configuration annotations of prototype methods in the interface
+     * specified with {@link #config()}. Annotations that can be inherited are for example {@link Mapping},
+     * {@link IterableMapping}, {@link MapMapping}, or {@link BeanMapping}.
+     * <p>
+     * If no strategy is configured, the strategy given via {@link MapperConfig#mappingInheritanceStrategy()} will be
+     * applied, using {@link MappingInheritanceStrategy#EXPLICIT} as default.
+     *
+     * @return The strategy to use for applying {@code @Mapping} configurations of prototype methods in the interface
+     * specified with {@link #config()}.
+     */
+    MappingInheritanceStrategy mappingInheritanceStrategy() default MappingInheritanceStrategy.EXPLICIT;
+
+    /**
+     * Determines when to include a null check on the source property value of a bean mapping.
+     *
+     * Can be overridden by the one on {@link MapperConfig}, {@link BeanMapping}  or {@link Mapping}.
+     *
+     * @return strategy how to do null checking
+     */
+    NullValueCheckStrategy nullValueCheckStrategy() default ON_IMPLICIT_CONVERSION;
+
+    /**
+     * Determines how to handle missing implementation for super classes when using the {@link SubclassMapping}.
+     *
+     * Can be overridden by the one on {@link BeanMapping}, but overrides {@link MapperConfig}.
+     *
+     * @return strategy to handle missing implementation combined with {@link SubclassMappings}.
+     *
+     * @since 1.5
+     */
+    SubclassExhaustiveStrategy subclassExhaustiveStrategy() default COMPILE_ERROR;
+
+    /**
+     * Specifies the exception type to be thrown when a missing subclass implementation is detected
+     * in combination with {@link SubclassMappings}, based on the {@link #subclassExhaustiveStrategy()}.
+     * <p>
+     * This exception will only be thrown when the {@code subclassExhaustiveStrategy} is set to
+     * {@link SubclassExhaustiveStrategy#RUNTIME_EXCEPTION}.
+     *
+     * @return the exception class to throw when missing implementations are found.
+     *         Defaults to {@link IllegalArgumentException}.
+     */
+    Class<? extends Exception> subclassExhaustiveException() default IllegalArgumentException.class;
+
+    /**
+     * Determines whether to use field or constructor injection. This is only used on annotated based component models
+     * such as CDI, Spring and JSR 330.
+     *
+     * If no strategy is configured, {@link InjectionStrategy#FIELD} will be used as default.
+     *
+     * @return strategy how to inject
+     */
+    InjectionStrategy injectionStrategy() default InjectionStrategy.FIELD;
+
+    /**
+     * If MapStruct could not find another mapping method or apply an automatic conversion it will try to generate a
+     * sub-mapping method between the two beans. If this property is set to {@code true} MapStruct will not try to
+     * automatically generate sub-mapping methods.
+     * <p>
+     * Can be configured by the {@link MapperConfig#disableSubMappingMethodsGeneration()} as well.
+     * <p>
+     * Note: If you need to use {@code disableSubMappingMethodsGeneration} please contact the MapStruct team at
+     * <a href="https://mapstruct.org">mapstruct.org</a> or
+     * <a href="https://github.com/mapstruct/mapstruct">github.com/mapstruct/mapstruct</a> to share what problem you
+     * are facing with the automatic sub-mapping generation.
+     *
+     * @return whether the automatic generation of sub-mapping methods is disabled
+     *
+     * @since 1.2
+     */
+    boolean disableSubMappingMethodsGeneration() default false;
+
+    /**
+     * The information that should be used for the builder mappings. This can be used to define custom build methods
+     * for the builder strategy that one uses.
+     *
+     * If no builder is defined the builder given via {@link MapperConfig#builder()} will be applied.
+     *
+     * <p>
+     * NOTE: In case no builder is defined here, in {@link BeanMapping} or {@link MapperConfig} and there is a single
+     * build method, then that method would be used.
+     * <p>
+     * If the builder is defined and there is a single method that does not match the name of the build method then
+     * a compile error will occur
+     *
+     * @return the builder information
+     *
+     * @since 1.3
+     */
+    Builder builder() default @Builder;
+
+    /**
+     * Allows detailed control over the mapping process.
+     *
+     * @return the mapping control
+     *
+     * @since 1.4
+     *
+     * @see org.mapstruct.control.DeepClone
+     * @see org.mapstruct.control.NoComplexMapping
+     * @see org.mapstruct.control.MappingControl
+     */
+    Class<? extends Annotation> mappingControl() default MappingControl.class;
+
+    /**
+     * Exception that should be thrown by the generated code if no mapping matches for enums.
+     * If no exception is configured, the exception given via {@link MapperConfig#unexpectedValueMappingException()}
+     * will be used, using {@link IllegalArgumentException} by default.
+     *
+     * <p>
+     * Note:
+     * <ul>
+     *     <li>
+     *      The defined exception should at least have a constructor with a {@link String} parameter.
+     *     </li>
+     *     <li>
+     *      If the defined exception is a checked exception then the enum mapping methods should have that exception
+     *      in the throws clause.
+     *     </li>
+     * </ul>
+     *
+     * @return the exception that should be used in the generated code
+     *
+     * @since 1.4
+     */
+    Class<? extends Exception> unexpectedValueMappingException() default IllegalArgumentException.class;
+
+    /**
+     * Flag indicating whether the addition of a time stamp in the {@code @Generated} annotation should be suppressed.
+     * i.e. not be added.
+     *
+     * The method overrides the flag set in a central configuration set by {@link #config()}
+     * or through an annotation processor option.
+     *
+     * @return whether the addition of a timestamp should be suppressed
+     *
+     * @since 1.5
+     */
+    boolean suppressTimestampInGenerated() default false;
+}

core/src/main/java/org/mapstruct/MapperConfig.java

@@ -0,0 +1,361 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.Annotation;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.mapstruct.control.MappingControl;
+import org.mapstruct.factory.Mappers;
+
+import static org.mapstruct.NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
+import static org.mapstruct.SubclassExhaustiveStrategy.COMPILE_ERROR;
+
+/**
+ * Marks a class or interface as configuration source for generated mappers. This allows to share common configurations
+ * between several mapper classes.
+ * <p>
+ * Generally, any settings given via {@link Mapper} take precedence over the settings given via the referenced
+ * {@code MapperConfig}. The lists of referenced mappers given via {@link Mapper#uses()} and
+ * {@link MapperConfig#uses()} will be merged.
+ * <p>
+ * Additionally, mapper configuration classes may declare one more <em>prototype mapping methods</em>. These methods are
+ * not meant to be invoked themselves (no implementation will generated for mapper config classes), but serve as
+ * configuration template for mapping methods declared by actual mapper classes. Depending on the configured
+ * {@link #mappingInheritanceStrategy()}, the configuration can be inherited either explicitly using
+ * {@link InheritConfiguration} or {@link InheritInverseConfiguration}, or automatically in case all source and target
+ * types are assignable.
+ * </p>
+ *
+ * <p>
+ * <strong>Example:</strong>
+ * </p>
+ * <pre><code class='java'>
+ * // create config
+ * &#64;MapperConfig(
+ *     uses = CustomMapperViaMapperConfig.class,
+ *     unmappedTargetPolicy = ReportingPolicy.ERROR
+ * )
+ * public interface CentralConfig {
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // use config
+ * &#64;Mapper(config = CentralConfig.class, uses = { CustomMapperViaMapper.class } )
+ * public interface SourceTargetMapper {
+ *   // ...
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // result after applying CentralConfig
+ * &#64;Mapper(
+ *     uses = { CustomMapperViaMapper.class, CustomMapperViaMapperConfig.class },
+ *     unmappedTargetPolicy = ReportingPolicy.ERROR
+ * )
+ * public interface SourceTargetMapper {
+ *    // ...
+ * }
+ * </code></pre>
+ *
+ * @author Sjaak Derksen
+ * @see Mapper#config()
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.CLASS)
+public @interface MapperConfig {
+
+    /**
+     * The mapper types used by this mapper.
+     *
+     * @return The mapper types used by this mapper.
+     */
+    Class<?>[] uses() default { };
+
+    /**
+     * Additional types for which an import statement is to be added to the generated mapper implementation class.
+     * This allows to refer to those types from within mapping expressions given via {@link Mapping#expression()},
+     * {@link Mapping#defaultExpression()} or using
+     * their simple name rather than their fully-qualified name.
+     *
+     * @return classes to add in the imports of the generated implementation.
+     *
+     * @since 1.4
+     */
+    Class<?>[] imports() default { };
+
+    /**
+     * How unmapped properties of the source type of a mapping should be
+     * reported.
+     *
+     * @return The reporting policy for unmapped source properties.
+     *
+     * @since 1.3
+     */
+    ReportingPolicy unmappedSourcePolicy() default ReportingPolicy.IGNORE;
+
+    /**
+     * How unmapped properties of the target type of a mapping should be
+     * reported.
+     *
+     * @return The reporting policy for unmapped target properties.
+     */
+    ReportingPolicy unmappedTargetPolicy() default ReportingPolicy.WARN;
+
+    /**
+     * How lossy (narrowing) conversion, for instance: long to integer should be
+     * reported.
+     *
+     * @since 1.3
+     *
+     * @return The reporting policy for type conversion.
+     */
+    ReportingPolicy typeConversionPolicy() default ReportingPolicy.IGNORE;
+
+    /**
+     * Specifies the component model to which the generated mapper should
+     * adhere. Supported values are
+     * <ul>
+     * <li> {@code default}: the mapper uses no component model, instances are
+     * typically retrieved via {@link Mappers#getMapper(Class)}</li>
+     * <li>
+     * {@code cdi}: the generated mapper is an application-scoped CDI bean and
+     * can be retrieved via {@code @Inject}</li>
+     * <li>
+     * {@code spring}: the generated mapper is a Spring bean and
+     * can be retrieved via {@code @Autowired}</li>
+     * <li>
+     * {@code jsr330}: the generated mapper is annotated with {@code @javax.inject.Named} and
+     * {@code @Singleton}, and can be retrieved via {@code @Inject}.
+     * The annotations will either be from javax.inject or jakarta.inject,
+     * depending on which one is available, with javax.inject having precedence.</li>
+     * <li>
+     * {@code jakarta}: the generated mapper is annotated with {@code @jakarta.inject.Named} and
+     * {@code @Singleton}, and can be retrieved via {@code @Inject}.</li>
+     * </ul>
+     *
+     * @return The component model for the generated mapper.
+     */
+    String componentModel() default MappingConstants.ComponentModel.DEFAULT;
+
+    /**
+     * Specifies the name of the implementation class. The {@code <CLASS_NAME>} will be replaced by the
+     * interface/abstract class name.
+     * <p>
+     * Defaults to postfixing the name with {@code Impl}: {@code <CLASS_NAME>Impl}
+     *
+     * @return The implementation name.
+     * @see #implementationPackage()
+     */
+    String implementationName() default "<CLASS_NAME>Impl";
+
+    /**
+     * Specifies the target package for the generated implementation. The {@code <PACKAGE_NAME>} will be replaced by the
+     * interface's or abstract class' package.
+     * <p>
+     * Defaults to using the same package as the mapper interface/abstract class
+     *
+     * @return the implementation package.
+     * @see #implementationName()
+     */
+    String implementationPackage() default "<PACKAGE_NAME>";
+
+    /**
+     * The strategy to be applied when propagating the value of collection-typed properties. By default, only JavaBeans
+     * accessor methods (setters or getters) will be used, but it is also possible to invoke a corresponding adder
+     * method for each element of the source collection (e.g. {@code orderDto.addOrderLine()}).
+     *
+     * @return The strategy applied when propagating the value of collection-typed properties.
+     */
+    CollectionMappingStrategy collectionMappingStrategy() default CollectionMappingStrategy.ACCESSOR_ONLY;
+
+    /**
+     * The strategy to be applied when {@code null} is passed as source argument value to mapping methods. If no
+     * strategy is configured, {@link NullValueMappingStrategy#RETURN_NULL} will be used by default.
+     *
+     * @return The strategy to be applied when {@code null} is passed as source value to mapping methods.
+     */
+    NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
+
+    /**
+     * The strategy to be applied when {@code null} is passed as source argument value to an {@link IterableMapping}.
+     * If no strategy is configured, the strategy given via {@link #nullValueMappingStrategy()} will be applied, using
+     * {@link NullValueMappingStrategy#RETURN_NULL} by default.
+     *
+     * @since 1.5
+     *
+     * @return The strategy to be applied when {@code null} is passed as source value to an {@link IterableMapping}.
+     */
+    NullValueMappingStrategy nullValueIterableMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
+
+    /**
+     * The strategy to be applied when {@code null} is passed as source argument value to a {@link MapMapping}.
+     * If no strategy is configured, the strategy given via {@link #nullValueMappingStrategy()} will be applied, using
+     * {@link NullValueMappingStrategy#RETURN_NULL} by default.
+     *
+     * @since 1.5
+     *
+     * @return The strategy to be applied when {@code null} is passed as source value to a {@link MapMapping}.
+     */
+    NullValueMappingStrategy nullValueMapMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
+
+    /**
+     * The strategy to be applied when a source bean property is {@code null} or not present. If no strategy is
+     * configured, {@link NullValuePropertyMappingStrategy#SET_TO_NULL} will be used by default.
+     *
+     * @since 1.3
+     *
+     * @return The strategy to be applied when {@code null} is passed as source property value or the source property
+     * is not present.
+     */
+    NullValuePropertyMappingStrategy nullValuePropertyMappingStrategy() default
+        NullValuePropertyMappingStrategy.SET_TO_NULL;
+
+    /**
+     * The strategy to use for applying method-level configuration annotations of prototype methods in the interface
+     * annotated with this annotation. Annotations that can be inherited are for example {@link Mapping},
+     * {@link IterableMapping}, {@link MapMapping}, or {@link BeanMapping}.
+     * <p>
+     * If no strategy is configured, {@link MappingInheritanceStrategy#EXPLICIT} will be used as default.
+     *
+     * @return The strategy to use for applying {@code @Mapping} configurations of prototype methods in the interface
+     * annotated with this annotation.
+     */
+    MappingInheritanceStrategy mappingInheritanceStrategy()
+        default MappingInheritanceStrategy.EXPLICIT;
+
+    /**
+     * Determines when to include a null check on the source property value of a bean mapping.
+     *
+     * Can be overridden by the one on {@link Mapper}, {@link BeanMapping} or {@link Mapping}.
+     *
+     * @return strategy how to do null checking
+     */
+    NullValueCheckStrategy nullValueCheckStrategy() default ON_IMPLICIT_CONVERSION;
+
+    /**
+     * Determines how to handle missing implementation for super classes when using the {@link SubclassMapping}.
+     *
+     * Can be overridden by the one on {@link BeanMapping} or {@link Mapper}.
+     *
+     * @return strategy to handle missing implementation combined with {@link SubclassMappings}.
+     *
+     * @since 1.5
+     */
+    SubclassExhaustiveStrategy subclassExhaustiveStrategy() default COMPILE_ERROR;
+
+    /**
+     * Specifies the exception type to be thrown when a missing subclass implementation is detected
+     * in combination with {@link SubclassMappings}, based on the {@link #subclassExhaustiveStrategy()}.
+     * <p>
+     * This exception will only be thrown when the {@code subclassExhaustiveStrategy} is set to
+     * {@link SubclassExhaustiveStrategy#RUNTIME_EXCEPTION}.
+     *
+     * @return the exception class to throw when missing implementations are found.
+     *         Defaults to {@link IllegalArgumentException}.
+     */
+    Class<? extends Exception> subclassExhaustiveException() default IllegalArgumentException.class;
+
+    /**
+     * Determines whether to use field or constructor injection. This is only used on annotated based component models
+     * such as CDI, Spring and JSR 330.
+     *
+     * Can be overridden by the one on {@link Mapper}.
+     *
+     * If no strategy is configured, {@link InjectionStrategy#FIELD} will be used as default.
+     *
+     * @return strategy how to inject
+     */
+    InjectionStrategy injectionStrategy() default InjectionStrategy.FIELD;
+
+    /**
+     * If MapStruct could not find another mapping method or apply an automatic conversion it will try to generate a
+     * sub-mapping method between the two beans. If this property is set to {@code true} MapStruct will not try to
+     * automatically generate sub-mapping methods.
+     * <p>
+     * Can be overridden by {@link Mapper#disableSubMappingMethodsGeneration()}
+     * <p>
+     * Note: If you need to use {@code disableSubMappingMethodsGeneration} please contact the MapStruct team at
+     * <a href="https://mapstruct.org">mapstruct.org</a> or
+     * <a href="https://github.com/mapstruct/mapstruct">github.com/mapstruct/mapstruct</a> to share what problem you
+     * are facing with the automatic sub-mapping generation.
+     *
+     * @return whether the automatic generation of sub-mapping methods is disabled
+     *
+     * @since 1.2
+     */
+    boolean disableSubMappingMethodsGeneration() default false;
+
+    /**
+     * The information that should be used for the builder mappings. This can be used to define custom build methods
+     * for the builder strategy that one uses.
+     *
+     * <p>
+     * Can be overridden by {@link MapperConfig#builder()}.
+     *
+     * <p>
+     * NOTE: In case no builder is defined here, in {@link BeanMapping} or {@link Mapper} and there is a single
+     * build method, then that method would be used.
+     * <p>
+     * If the builder is defined and there is a single method that does not match the name of the build method then
+     * a compile error will occur
+     *
+     * @return the builder information
+     *
+     * @since 1.3
+     */
+    Builder builder() default @Builder;
+
+    /**
+     * Allows detailed control over the mapping process.
+     *
+     * @return the mapping control
+     *
+     * @since 1.4
+     *
+     * @see org.mapstruct.control.DeepClone
+     * @see org.mapstruct.control.NoComplexMapping
+     * @see org.mapstruct.control.MappingControl
+     */
+    Class<? extends Annotation> mappingControl() default MappingControl.class;
+
+    /**
+     * Exception that should be thrown by the generated code if no mapping matches for enums.
+     * If no exception is configured, {@link IllegalArgumentException} will be used by default.
+     *
+     * <p>
+     * Note:
+     * <ul>
+     *     <li>
+     *      The defined exception should at least have a constructor with a {@link String} parameter.
+     *     </li>
+     *     <li>
+     *      If the defined exception is a checked exception then the enum mapping methods should have that exception
+     *      in the throws clause.
+     *     </li>
+     * </ul>
+     *
+     * @return the exception that should be used in the generated code
+     *
+     * @since 1.4
+     */
+    Class<? extends Exception> unexpectedValueMappingException() default IllegalArgumentException.class;
+
+    /**
+     * Flag indicating whether the addition of a time stamp in the {@code @Generated} annotation should be suppressed.
+     * i.e. not be added.
+     *
+     * The method overrides the flag set through an annotation processor option.
+     *
+     * @return whether the addition of a timestamp should be suppressed
+     *
+     * @since 1.5
+     */
+    boolean suppressTimestampInGenerated() default false;
+}
+

core/src/main/java/org/mapstruct/Mapping.java

@@ -1,45 +1,147 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
+/*
+ * Copyright MapStruct Authors.
  *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
  */
 package org.mapstruct;
 
 import java.lang.annotation.Annotation;
 import java.lang.annotation.ElementType;
+import java.lang.annotation.Repeatable;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
+import java.text.DecimalFormat;
 import java.text.SimpleDateFormat;
 import java.util.Date;
 
+import org.mapstruct.control.MappingControl;
+
+import static org.mapstruct.NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
+
 /**
- * Configures the mapping of one bean attribute or enum constant.
+ * Configures the mapping of one bean attribute.
  * <p>
  * The name of the mapped attribute or constant is to be specified via {@link #target()}. For mapped bean attributes it
  * is assumed by default that the attribute has the same name in the source bean. Alternatively, one of
  * {@link #source()}, {@link #expression()} or {@link #constant()} can be specified to define the property source.
+ * </p>
  * <p>
  * In addition, the attributes {@link #dateFormat()} and {@link #qualifiedBy()} may be used to further define the
  * mapping.
+ * </p>
+ *
+ * <p>
+ * <strong>Example 1:</strong> Implicitly mapping fields with the same name:
+ * </p>
+ * <pre><code class='java'>
+ * // Both classes HumanDto and Human have property with name "fullName"
+ * // properties with the same name will be mapped implicitly
+ * &#64;Mapper
+ * public interface HumanMapper {
+ *    HumanDto toHumanDto(Human human)
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates:
+ * &#64;Override
+ * public HumanDto toHumanDto(Human human) {
+ *    humanDto.setFullName( human.getFullName() );
+ *    // ...
+ * }
+ * </code></pre>
+ *
+ * <p><strong>Example 2:</strong> Mapping properties with different names</p>
+ * <pre><code class='java'>
+ * // We need map Human.companyName to HumanDto.company
+ * // we can use &#64;Mapping with parameters {@link #source()} and {@link #target()}
+ * &#64;Mapper
+ * public interface HumanMapper {
+ *    &#64;Mapping(source="companyName", target="company")
+ *    HumanDto toHumanDto(Human human)
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates:
+ * &#64;Override
+ * public HumanDto toHumanDto(Human human) {
+ *     humanDto.setCompany( human.getCompanyName() );
+ *      // ...
+ * }
+ * </code></pre>
+ * <p>
+ * <strong>Example 3:</strong> Mapping with expression
+ * <b>IMPORTANT NOTE:</b> Now it works only for Java
+ * </p>
+ * <pre><code class='java'>
+ * // We need map Human.name to HumanDto.countNameSymbols.
+ * // we can use {@link #expression()} for it
+ * &#64;Mapper
+ * public interface HumanMapper {
+ *    &#64;Mapping(target="countNameSymbols", expression="java(human.getName().length())")
+ *    HumanDto toHumanDto(Human human)
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates:
+ *&#64;Override
+ * public HumanDto toHumanDto(Human human) {
+ *    humanDto.setCountNameSymbols( human.getName().length() );
+ *    //...
+ * }
+ * </code></pre>
+ * <p>
+ * <strong>Example 4:</strong> Mapping to constant
+ * </p>
+ * <pre><code class='java'>
+ * // We need map HumanDto.name to string constant "Unknown"
+ * // we can use {@link #constant()} for it
+ * &#64;Mapper
+ * public interface HumanMapper {
+ *    &#64;Mapping(target="name", constant="Unknown")
+ *    HumanDto toHumanDto(Human human)
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * &#64;Override
+ * public HumanDto toHumanDto(Human human) {
+ *   humanDto.setName( "Unknown" );
+ *   // ...
+ * }
+ * </code></pre>
+ * <p>
+ * <strong>Example 5:</strong> Mapping with default value
+ * </p>
+ * <pre><code class='java'>
+ * // We need map Human.name to HumanDto.fullName, but if Human.name == null, then set value "Somebody"
+ * // we can use {@link #defaultValue()} or {@link #defaultExpression()} for it
+ * &#64;Mapper
+ * public interface HumanMapper {
+ *    &#64;Mapping(source="name", target="name", defaultValue="Somebody")
+ *    HumanDto toHumanDto(Human human)
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * &#64;Override
+ * public HumanDto toHumanDto(Human human) {
+ *    if ( human.getName() != null ) {
+ *       humanDto.setFullName( human.getName() );
+ *    }
+ *    else {
+ *       humanDto.setFullName( "Somebody" );
+ *    }
+ *   // ...
+ * }
+ * </code></pre>
  *
  * @author Gunnar Morling
  */
-@Retention(RetentionPolicy.SOURCE)
-@Target(ElementType.METHOD)
+
+@Repeatable(Mappings.class)
+@Retention(RetentionPolicy.CLASS)
+@Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
 public @interface Mapping {
 
     /**
@@ -64,7 +166,7 @@ public @interface Mapping {
      * <li>When no matching property is found, MapStruct looks for a matching parameter name instead.</li>
      * <li>When used to map an enum constant, the name of the constant member is to be given.</li>
      * </ol>
-     * Either this attribute or {@link #constant()} or {@link #expression()} may be specified for a given mapping.
+     * This attribute can not be used together with {@link #constant()} or {@link #expression()}.
      *
      * @return The source name of the configured property or enum constant.
      */
@@ -73,39 +175,140 @@ public @interface Mapping {
     /**
      * A format string as processable by {@link SimpleDateFormat} if the attribute is mapped from {@code String} to
      * {@link Date} or vice-versa. Will be ignored for all other attribute types and when mapping enum constants.
+     * <p>
+     * If the {@link #locale()} is also specified, the format will consider the specified locale when processing
+     * the date. Otherwise, the system's default locale will be used.
      *
      * @return A date format string as processable by {@link SimpleDateFormat}.
+     * @see #locale()
      */
     String dateFormat() default "";
 
     /**
-     * A constant {@link String} based on which the specified target property is to be set. If the designated target
-     * property is not of type {@code String}, the value will be converted by applying a matching conversion method or
-     * built-in conversion.
+     * A format string as processable by {@link DecimalFormat} if the annotated method maps from a
+     *  {@link Number} to a {@link String} or vice-versa. Will be ignored for all other element types.
      * <p>
-     * Either this attribute or {@link #source()} or {@link #expression()} may be specified for a given mapping.
+     * If the {@link #locale()} is also specified, the number format will be applied in the context of the given locale.
+     * Otherwise, the system's default locale will be used to process the number format.
+     *
+     * @return A decimal format string as processable by {@link DecimalFormat}.
+     * @see #locale()
+     */
+    String numberFormat() default "";
+
+    /**
+     * Specifies the locale to be used when processing {@link #dateFormat()} or {@link #numberFormat()}.
+     * <p>
+     * The locale should be a plain tag representing the language, such as "en" for English, "de" for German, etc.
+     * <p>
+     * If no locale is specified, the system's default locale will be used.
+     *
+     * @return A string representing the locale to be used when formatting dates or numbers.
+     */
+    String locale() default "";
+
+    /**
+     * A constant {@link String} based on which the specified target property is to be set.
+     * <p>
+     * When the designated target property is of type:
+     * </p>
+     * <ol>
+     * <li>primitive or boxed (e.g. {@code java.lang.Long}).
+     * <p>
+     * MapStruct checks whether the primitive can be assigned as valid literal to the primitive or boxed type.
+     * </p>
+     * <ul>
+     * <li>
+     * If possible, MapStruct assigns as literal.
+     * </li>
+     * <li>
+     * If not possible, MapStruct will try to apply a user defined mapping method.
+     * </li>
+     * </ul>
+     * </li>
+     * <li>other
+     * <p>
+     * MapStruct handles the constant as {@code String}. The value will be converted by applying a matching method,
+     * type conversion method or built-in conversion.
+     * <p>
+     * </li>
+     * </ol>
+     * <p>
+     * You can use {@link #qualifiedBy()} or {@link #qualifiedByName()} to force the use of a conversion method
+     * even when one would not apply. (e.g. {@code String} to {@code String})
+     * </p>
+     * <p>
+     * This attribute can not be used together with {@link #source()}, {@link #defaultValue()},
+     * {@link #defaultExpression()} or {@link #expression()}.
      *
      * @return A constant {@code String} constant specifying the value for the designated target property
      */
     String constant() default "";
 
     /**
-     * An expression {@link String} based on which the specified target property is to be set. The format is determined
-     * by a type of expression. For instance:
-     * {@code expression = "java(new org.example.TimeAndFormat( s.getTime(), s.getFormat() ))")} will insert the java
-     * expression in the designated {@link #target()} property.
+     * An expression {@link String} based on which the specified target property is to be set.
      * <p>
-     * Either this attribute or {@link #source()} or {@link #constant()} may be specified for a given mapping.
+     * Currently, Java is the only supported "expression language" and expressions must be given in form of Java
+     * expressions using the following format: {@code java(<EXPRESSION>)}. For instance the mapping:
+     * <pre><code>
+     * &#64;Mapping(
+     *     target = "someProp",
+     *     expression = "java(new TimeAndFormat( s.getTime(), s.getFormat() ))"
+     * )
+     * </code></pre>
+     * <p>
+     * will cause the following target property assignment to be generated:
+     * <p>
+     * {@code targetBean.setSomeProp( new TimeAndFormat( s.getTime(), s.getFormat() ) )}.
+     * <p>
+     * Any types referenced in expressions must be given via their fully-qualified name. Alternatively, types can be
+     * imported via {@link Mapper#imports()}.
+     * <p>
+     * This attribute can not be used together with {@link #source()}, {@link #defaultValue()},
+     * {@link #defaultExpression()}, {@link #qualifiedBy()}, {@link #qualifiedByName()} or {@link #constant()}.
      *
-     * @return A constant {@code String} constant specifying the value for the designated target property
+     * @return An expression specifying the value for the designated target property
      */
     String expression() default "";
 
+    /**
+     * A defaultExpression {@link String} based on which the specified target property is to be set
+     * if and only if the specified source property is null.
+     * <p>
+     * Currently, Java is the only supported "expression language" and expressions must be given in form of Java
+     * expressions using the following format: {@code java(<EXPRESSION>)}. For instance the mapping:
+     * <pre><code>
+     * &#64;Mapping(
+     *     target = "someProp",
+     *     defaultExpression = "java(new TimeAndFormat( s.getTime(), s.getFormat() ))"
+     * )
+     * </code></pre>
+     * <p>
+     * will cause the following target property assignment to be generated:
+     * <p>
+     * {@code targetBean.setSomeProp( new TimeAndFormat( s.getTime(), s.getFormat() ) )}.
+     * <p>
+     * Any types referenced in expressions must be given via their fully-qualified name. Alternatively, types can be
+     * imported via {@link Mapper#imports()}.
+     * <p>
+     * This attribute can not be used together with {@link #expression()}, {@link #defaultValue()}
+     * or {@link #constant()}.
+     *
+     * @return An expression specifying a defaultValue for the designated target property if the designated source
+     * property is null
+     *
+     * @since 1.3
+     */
+    String defaultExpression() default "";
+
     /**
      * Whether the property specified via {@link #target()} should be ignored by the generated mapping method or not.
-     * This can be useful when certain attributes should not be propagated from source or target or when properties in
+     * This can be useful when certain attributes should not be propagated from source to target or when properties in
      * the target object are populated using a decorator and thus would be reported as unmapped target property by
      * default.
+     * <p>
+     * If you have multiple properties to ignore,
+     * you can use the {@link Ignored} annotation instead and group them all at once.
      *
      * @return {@code true} if the given property should be ignored, {@code false} otherwise
      */
@@ -115,8 +318,189 @@ public @interface Mapping {
      * A qualifier can be specified to aid the selection process of a suitable mapper. This is useful in case multiple
      * mapping methods (hand written or generated) qualify and thus would result in an 'Ambiguous mapping methods found'
      * error. A qualifier is a custom annotation and can be placed on a hand written mapper class or a method.
+     * <p>
+     * Note that {@link #defaultValue()} usage will also be converted using this qualifier.
      *
      * @return the qualifiers
+     * @see Qualifier
      */
     Class<? extends Annotation>[] qualifiedBy() default { };
+
+    /**
+     * String-based form of qualifiers; When looking for a suitable mapping method for a given property, MapStruct will
+     * only consider those methods carrying directly or indirectly (i.e. on the class-level) a {@link Named} annotation
+     * for each of the specified qualifier names.
+     * <p>
+     * Note that annotation-based qualifiers are generally preferable as they allow more easily to find references and
+     * are safe for refactorings, but name-based qualifiers can be a less verbose alternative when requiring a large
+     * number of qualifiers as no custom annotation types are needed.
+     * <p>
+     * Note that {@link #defaultValue()} usage will also be converted using this qualifier.
+     *
+     * @return One or more qualifier name(s)
+     * @see #qualifiedBy()
+     * @see Named
+     */
+    String[] qualifiedByName() default { };
+
+    /**
+     * A qualifier can be specified to aid the selection process of a suitable presence check method.
+     * This is useful in case multiple presence check methods qualify and thus would result in an
+     * 'Ambiguous presence check methods found' error.
+     * A qualifier is a custom annotation and can be placed on a hand written mapper class or a method.
+     * This is similar to the {@link #qualifiedBy()}, but it is only applied for {@link Condition} methods.
+     *
+     * @return the qualifiers
+     * @see Qualifier
+     * @see #qualifiedBy()
+     * @since 1.5
+     */
+    Class<? extends Annotation>[] conditionQualifiedBy() default { };
+
+    /**
+     * String-based form of qualifiers for condition / presence check methods;
+     * When looking for a suitable presence check method for a given property, MapStruct will
+     * only consider those methods carrying directly or indirectly (i.e. on the class-level) a {@link Named} annotation
+     * for each of the specified qualifier names.
+     *
+     * This is similar like {@link #qualifiedByName()} but it is only applied for {@link Condition} methods.
+     * <p>
+     *   Note that annotation-based qualifiers are generally preferable as they allow more easily to find references and
+     *   are safe for refactorings, but name-based qualifiers can be a less verbose alternative when requiring a large
+     *   number of qualifiers as no custom annotation types are needed.
+     * </p>
+     *
+     *
+     * @return One or more qualifier name(s)
+     * @see #conditionQualifiedBy()
+     * @see #qualifiedByName()
+     * @see Named
+     * @since 1.5
+     */
+    String[] conditionQualifiedByName() default { };
+
+    /**
+     * A conditionExpression {@link String} based on which the specified property is to be checked
+     * whether it is present or not.
+     * <p>
+     * Currently, Java is the only supported "expression language" and expressions must be given in form of Java
+     * expressions using the following format: {@code java(<EXPRESSION>)}. For instance the mapping:
+     * <pre><code>
+     * &#64;Mapping(
+     *     target = "someProp",
+     *     conditionExpression = "java(s.getAge() &#60; 18)"
+     * )
+     * </code></pre>
+     * <p>
+     * will cause the following target property assignment to be generated:
+     * <pre><code>
+     *     if (s.getAge() &#60; 18) {
+     *         targetBean.setSomeProp( s.getSomeProp() );
+     *     }
+     * </code></pre>
+     * <p>
+     * Any types referenced in expressions must be given via their fully-qualified name. Alternatively, types can be
+     * imported via {@link Mapper#imports()}.
+     * <p>
+     * This attribute can not be used together with {@link #expression()} or {@link #constant()}.
+     *
+     * @return An expression specifying a condition check for the designated property
+     *
+     * @since 1.5
+     */
+    String conditionExpression() default "";
+
+    /**
+     * Specifies the result type of the mapping method to be used in case multiple mapping methods qualify.
+     *
+     * @return the resultType to select
+     */
+    Class<?> resultType() default void.class;
+
+    /**
+     * One or more properties of the result type on which the mapped property depends. The generated method
+     * implementation will invoke the setters of the result type ordered so that the given dependency relationship(s)
+     * are satisfied. Useful in case one property setter depends on the state of another property of the result type.
+     * <p>
+     * An error will be raised in case a cycle in the dependency relationships is detected.
+     *
+     * @return the dependencies of the mapped property
+     */
+    String[] dependsOn() default { };
+
+    /**
+     * In case the source property is {@code null}, the provided default {@link String} value is set.
+     * <p>
+     * When the designated target property is of type:
+     * </p>
+     * <ol>
+     * <li>primitive or boxed (e.g. {@code java.lang.Long}).
+     * <p>
+     * MapStruct checks whether the primitive can be assigned as valid literal to the primitive or boxed type.
+     * </p>
+     * <ul>
+     * <li>
+     * If possible, MapStruct assigns as literal.
+     * </li>
+     * <li>
+     * If not possible, MapStruct will try to apply a user defined mapping method.
+     * </li>
+     * </ul>
+     * <p>
+     * </li>
+     * <li>other
+     * <p>
+     * MapStruct handles the constant as {@code String}. The value will be converted by applying a matching method,
+     * type conversion method or built-in conversion.
+     * <p>
+     * </li>
+     * </ol>
+     * <p>
+     * This attribute can not be used together with {@link #constant()}, {@link #expression()}
+     * or {@link #defaultExpression()}.
+     *
+     * @return Default value to set in case the source property is {@code null}.
+     */
+    String defaultValue() default "";
+
+    /**
+     * Determines when to include a null check on the source property value of a bean mapping.
+     *
+     * Can be overridden by the one on {@link MapperConfig}, {@link Mapper} or {@link BeanMapping}.
+     *
+     * @since 1.3
+     *
+     * @return strategy how to do null checking
+     */
+    NullValueCheckStrategy nullValueCheckStrategy() default ON_IMPLICIT_CONVERSION;
+
+    /**
+     * The strategy to be applied when the source property is {@code null} or not present. If no strategy is configured,
+     * the strategy given via {@link MapperConfig#nullValuePropertyMappingStrategy()},
+     * {@link BeanMapping#nullValuePropertyMappingStrategy()} or
+     * {@link Mapper#nullValuePropertyMappingStrategy()} will be applied.
+     *
+     * {@link NullValuePropertyMappingStrategy#SET_TO_NULL} will be used by default.
+     *
+     * @since 1.3
+     *
+     * @return The strategy to be applied when {@code null} is passed as source property value or the source property
+     * is not present.
+     */
+    NullValuePropertyMappingStrategy nullValuePropertyMappingStrategy()
+        default NullValuePropertyMappingStrategy.SET_TO_NULL;
+
+    /**
+     * Allows detailed control over the mapping process.
+     *
+     * @return the mapping control
+     *
+     * @since 1.4
+     *
+     * @see org.mapstruct.control.DeepClone
+     * @see org.mapstruct.control.NoComplexMapping
+     * @see org.mapstruct.control.MappingControl
+     */
+    Class<? extends Annotation> mappingControl() default MappingControl.class;
+
 }

core/src/main/java/org/mapstruct/MappingConstants.java

@@ -0,0 +1,154 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+/**
+ * Contains all constants defined in the mapping process.
+ *
+ * @author Sjaak Derksen
+ */
+public final class MappingConstants {
+
+    private MappingConstants() {
+    }
+
+    /**
+     * In an {@link ValueMapping} this represents a {@code null} source or target.
+     */
+    public static final String NULL = "<NULL>";
+
+    /**
+     * In an {@link ValueMapping} this represents any source that is not already mapped by either a defined mapping or
+     * by means of name based mapping.
+     *
+     * NOTE: The value is only applicable to {@link ValueMapping#source()} and not to {@link ValueMapping#target()}.
+     */
+    public static final String ANY_REMAINING = "<ANY_REMAINING>";
+
+    /**
+     * In an {@link ValueMapping} this represents any source that is not already mapped by a defined mapping.
+     *
+     * NOTE: The value is only applicable to {@link ValueMapping#source()} and not to {@link ValueMapping#target()}.
+     *
+     */
+    public static final String ANY_UNMAPPED = "<ANY_UNMAPPED>";
+
+    /**
+     * In an {@link ValueMapping} this represents any target that will be mapped to an
+     * {@link java.lang.IllegalArgumentException} which will be thrown at runtime.
+     * <p>
+     * NOTE: The value is only applicable to {@link ValueMapping#target()} and not to {@link ValueMapping#source()}.
+     */
+    public static final String THROW_EXCEPTION = "<THROW_EXCEPTION>";
+
+    /**
+     * In an {@link EnumMapping} this represent the enum transformation strategy that adds a suffix to the source enum.
+     *
+     * @since 1.4
+     */
+    public static final String SUFFIX_TRANSFORMATION = "suffix";
+
+    /**
+     * In an {@link EnumMapping} this represent the enum transformation strategy that strips a suffix from the source
+     * enum.
+     *
+     * @since 1.4
+     */
+    public static final String STRIP_SUFFIX_TRANSFORMATION = "stripSuffix";
+
+    /**
+     * In an {@link EnumMapping} this represent the enum transformation strategy that adds a prefix to the source enum.
+     *
+     * @since 1.4
+     */
+    public static final String PREFIX_TRANSFORMATION = "prefix";
+
+    /**
+     * In an {@link EnumMapping} this represent the enum transformation strategy that strips a prefix from the source
+     * enum.
+     *
+     * @since 1.4
+     */
+    public static final String STRIP_PREFIX_TRANSFORMATION = "stripPrefix";
+
+    /**
+     * In an {@link EnumMapping} this represent the enum transformation strategy that applies case transformation
+     * at the source.
+     *
+     * @since 1.5
+     */
+    public static final String CASE_TRANSFORMATION = "case";
+
+    /**
+    * Specifies the component model constants to which the generated mapper should adhere.
+    * It can be used with the annotation {@link Mapper#componentModel()} or {@link MapperConfig#componentModel()}
+    *
+    * <p>
+    * <strong>Example:</strong>
+    * </p>
+    * <pre><code class='java'>
+    * // Spring component model
+    * &#64;Mapper(componentModel = MappingConstants.ComponentModel.SPRING)
+    * </code></pre>
+    *
+    * @since 1.5.0
+    */
+    public static final class ComponentModel {
+
+        private ComponentModel() {
+        }
+
+        /**
+         * The mapper uses no component model, instances are typically retrieved
+         * via {@link org.mapstruct.factory.Mappers#getMapper(java.lang.Class)}
+         *
+         */
+        public static final String DEFAULT = "default";
+
+        /**
+         * The generated mapper is an application-scoped CDI bean and can be retrieved via @Inject.
+         * The annotations are either from {@code javax} or {@code jakarta}.
+         * Priority have the {@code javax} annotations.
+         * In case you want to only use Jakarta then use {@link #JAKARTA_CDI}.
+         *
+         * @see #JAKARTA_CDI
+         */
+        public static final String CDI = "cdi";
+
+        /**
+         * The generated mapper is a Spring bean and can be retrieved via @Autowired
+         *
+         */
+        public static final String SPRING = "spring";
+
+        /**
+         * The generated mapper is annotated with @Named and @Singleton, and can be retrieved via @Inject.
+         * The annotations are either from {@code javax.inject} or {@code jakarta.inject}.
+         * Priority have the {@code javax.inject} annotations.
+         * In case you want to only use Jakarta then use {@link #JAKARTA}.
+         *
+         * @see #JAKARTA
+         */
+        public static final String JSR330 = "jsr330";
+
+        /**
+         * The generated mapper is annotated with @Named and @Singleton, and can be retrieved via @Inject.
+         * The annotations are from {@code jakarta.inject}.
+         * In case you want to use {@code javax.inject} then use {@link #JSR330}.
+         *
+         * @see #JSR330
+         */
+        public static final String JAKARTA = "jakarta";
+
+        /**
+         * The generated mapper is an application-scoped Jakarta CDI bean and can be retrieved via @Inject.
+         * @see #CDI
+         */
+        public static final String JAKARTA_CDI = "jakarta-cdi";
+
+    }
+
+}

core/src/main/java/org/mapstruct/MappingInheritanceStrategy.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+/**
+ * Strategy for inheriting configurations given for methods of prototype mapping methods (declared on mapper config
+ * classes) to actual mapping methods declared on mappers referring to such config class via {@link Mapper#config()}.
+ *
+ * @author Andreas Gudian
+ */
+public enum MappingInheritanceStrategy {
+    /**
+     * Apply the method-level configuration annotations only if the prototype method is explicitly referenced using
+     * {@link InheritConfiguration}.
+     */
+    EXPLICIT,
+
+    /**
+     * Inherit the method-level forward configuration annotations automatically if source and target types of the
+     * prototype method are assignable from the types of a given mapping method.
+     */
+    AUTO_INHERIT_FROM_CONFIG,
+
+    /**
+     * Inherit the method-level reverse configuration annotations automatically if source and target types of the
+     * prototype method are assignable from the target and source types of a given mapping method.
+     */
+    AUTO_INHERIT_REVERSE_FROM_CONFIG,
+
+    /**
+     * Inherit the method-level forward and reverse configuration annotations automatically if source and target types
+     * of the prototype method are assignable from the types of a given mapping method.
+     */
+    AUTO_INHERIT_ALL_FROM_CONFIG;
+}

core/src/main/java/org/mapstruct/MappingTarget.java

@@ -0,0 +1,62 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Declares a parameter of a mapping method to be the target of the mapping.
+ * <p>
+ * Not more than one parameter can be declared as {@code MappingTarget}.
+ * <p>
+ * <b>NOTE:</b> The parameter passed as a mapping target <b>must</b> not be {@code null}.
+ *
+ * <p>
+ * <strong>Example 1:</strong> Update exist bean without return value
+ * </p>
+ * <pre><code class='java'>
+ * &#64;Mapper
+ * public interface HumanMapper {
+ *     void updateHuman(HumanDto humanDto, @MappingTarget Human human);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * &#64;Override
+ * public void updateHuman(HumanDto humanDto, Human human) {
+ *     human.setName( humanDto.getName() );
+ *     // ...
+ * }
+ * </code></pre>
+ * <p>
+ * <strong>Example 2:</strong> Update exist bean and return it
+ * </p>
+ * <pre><code class='java'>
+ * &#64;Mapper
+ * public interface HumanMapper {
+ *     Human updateHuman(HumanDto humanDto, @MappingTarget Human human);
+ * }
+ * </code></pre>
+ * // generates:
+ * <pre><code class='java'>
+ * &#64;Override
+ * public Human updateHuman(HumanDto humanDto, Human human) {
+ *     // ...
+ *     human.setName( humanDto.getName() );
+ *     return human;
+ * }
+ *</code></pre>
+ *
+ *
+ * @author Andreas Gudian
+ */
+@Target(ElementType.PARAMETER)
+@Retention(RetentionPolicy.CLASS)
+public @interface MappingTarget {
+}

core/src/main/java/org/mapstruct/Mappings.java

@@ -1,20 +1,7 @@
-/**
- *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
- *  and/or other contributors as indicated by the @authors tag. See the
- *  copyright.txt file in the distribution for a full listing of all
- *  contributors.
+/*
+ * Copyright MapStruct Authors.
  *
- *  Licensed under the Apache License, Version 2.0 (the "License");
- *  you may not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
  */
 package org.mapstruct;
 
@@ -25,11 +12,37 @@ import java.lang.annotation.Target;
 
 /**
  * Configures the mappings of several bean attributes.
+ * <p>
+ * <strong>TIP: When using Java 8 or later, you can omit the @Mappings
+ * wrapper annotation and directly specify several @Mapping annotations on one method.</strong>
+ *
+ * <p>These two examples are equal.
+ * </p>
+ * <pre><code class='java'>
+ * // before Java 8
+ * &#64;Mapper
+ * public interface MyMapper {
+ *     &#64;Mappings({
+ *         &#64;Mapping(target = "firstProperty", source = "first"),
+ *         &#64;Mapping(target = "secondProperty", source = "second")
+ *     })
+ *     HumanDto toHumanDto(Human human);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // Java 8 and later
+ * &#64;Mapper
+ * public interface MyMapper {
+ *     &#64;Mapping(target = "firstProperty", source = "first"),
+ *     &#64;Mapping(target = "secondProperty", source = "second")
+ *     HumanDto toHumanDto(Human human);
+ * }
+ * </code></pre>
  *
  * @author Gunnar Morling
  */
-@Retention(RetentionPolicy.SOURCE)
-@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.CLASS)
+@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE })
 public @interface Mappings {
 
     /**

core/src/main/java/org/mapstruct/Named.java

@@ -0,0 +1,90 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks mapping methods with the given qualifier name. Can be used to qualify a single method or all methods of a given
+ * type by specifying this annotation on the type level.
+ * <p>
+ * Will be used to select the correct mapping methods when mapping a bean property type, element of an iterable type
+ * or the key/value of a map type.
+ * <p>
+ * Example (both methods of {@code Titles} are capable to convert a string, but the ambiguity is resolved by applying
+ * the qualifiers in {@code @Mapping}:
+ *
+ * <pre>
+ * <code>
+ * &#64;Named("TitleTranslator")
+ * public class Titles {
+ *
+ *   &#64;Named("EnglishToGerman")
+ *   public String translateTitleEG(String title) {
+ *       // some mapping logic
+ *   }
+ *
+ *   &#64;Named("GermanToEnglish")
+ *   public String translateTitleGE(String title) {
+ *       // some mapping logic
+ *   }
+ * }
+ *
+ * &#64;Mapper( uses = Titles.class )
+ * public interface MovieMapper {
+ *
+ *    &#64;Mapping( target = "title", qualifiedByName = { "TitleTranslator", "EnglishToGerman" } )
+ *    GermanRelease toGerman( OriginalRelease movies );
+ *
+ * }
+ * </code>
+ * </pre>
+ *
+ * The following implementation of {@code MovieMapper} will be generated:
+ *
+ * <pre>
+ * <code>
+ *
+ * public class MovieMapperImpl implements MovieMapper {
+ *     private final Titles titles = new Titles();
+ *
+ *     &#64;Override
+ *     public GermanRelease toGerman(OriginalRelease movies) {
+ *         if ( movies == null ) {
+ *             return null;
+ *         }
+ *
+ *         GermanRelease germanRelease = new GermanRelease();
+ *
+ *         germanRelease.setTitle( titles.translateTitleEG( movies.getTitle() ) );
+ *
+ *         return germanRelease;
+ *     }
+ * }
+ * </code>
+ * </pre>
+ *
+ * @author Sjaak Derksen
+ * @see org.mapstruct.Mapping#qualifiedByName()
+ * @see IterableMapping#qualifiedByName()
+ * @see MapMapping#keyQualifiedByName()
+ * @see MapMapping#valueQualifiedByName()
+ */
+@Target( { ElementType.TYPE, ElementType.METHOD } )
+@Retention( RetentionPolicy.CLASS )
+@Qualifier
+public @interface Named {
+
+    /**
+     * A name qualifying the annotated element
+     *
+     * @return the name.
+     */
+    String value();
+}

core/src/main/java/org/mapstruct/NullEnum.java

@@ -0,0 +1,15 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+/**
+ * To be used as a default value for enum class annotation elements.
+ *
+ * @author Ben Zegveld
+ * @since 1.6
+ */
+enum NullEnum {
+}

core/src/main/java/org/mapstruct/NullValueCheckStrategy.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+/**
+ * Strategy for dealing with null source values.
+ *
+ * <b>Note:</b> This strategy is not in effect when a specific source presence check method is defined
+ * in the service provider interface (SPI).
+ *  <p>
+ *  <b>Note</b>: some types of mappings (collections, maps), in which MapStruct is instructed to use a getter or adder
+ *  as target accessor see {@link CollectionMappingStrategy}, MapStruct will always generate a source property null
+ *  check, regardless the value of the {@link NullValueCheckStrategy} to avoid addition of {@code null} to the target
+ *  collection or map.
+ *
+ * @author Sean Huang
+ */
+public enum NullValueCheckStrategy {
+
+    /**
+     * This option includes a null check. When:
+     * <br>
+     * <br>
+     * <ol>
+     *   <li>a source value is directly assigned to a target</li>
+     *   <li>a source value assigned to a target by calling a type conversion on the target first</li>
+     * </ol>
+     * <br>
+     * <b>NOTE:</b> mapping methods (generated or hand written) are excluded from this null check. They are intended to
+     * handle a null source value as 'valid' input.
+     *
+     */
+    ON_IMPLICIT_CONVERSION,
+
+    /**
+     * This option always includes a null check.
+     */
+    ALWAYS;
+
+}

core/src/main/java/org/mapstruct/NullValueMappingStrategy.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+/**
+ * Strategy for dealing with {@code null} values passed to mapping methods.
+ *
+ * @author Sjaak Derksen
+ */
+public enum NullValueMappingStrategy {
+
+    /**
+     * If {@code null} is passed to a mapping method, {@code null} will be returned. That's the default behavior if no
+     * alternative strategy is configured globally, for given mapper or method.
+     */
+    RETURN_NULL,
+
+    /**
+     * If {@code null} is passed to a mapping method, a default value will be returned. The value depends on the kind of
+     * the annotated method:
+     * <ul>
+     * <li>For bean mapping methods the target type will be instantiated and returned. Any properties of the target type
+     * which are mapped via {@link Mapping#expression()} or {@link Mapping#constant()} will be populated based on the
+     * given expression or constant. Note that expressions must be prepared to deal with {@code null} values in this
+     * case.</li>
+     * <li>For iterable mapping methods an empty collection will be returned.</li>
+     * <li>For map mapping methods an empty map will be returned.</li>
+     * </ul>
+     */
+    RETURN_DEFAULT;
+}

core/src/main/java/org/mapstruct/NullValuePropertyMappingStrategy.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;
+
+/**
+ * Strategy for dealing with {@code null} or not present properties in the source bean. The
+ * {@link NullValuePropertyMappingStrategy} can be defined on {@link MapperConfig}, {@link Mapper}, {@link BeanMapping}
+ * and {@link Mapping}.
+ * Precedence is arranged  in the reverse order. So {@link Mapping} will override {@link BeanMapping}, will
+ * override {@link Mapper}
+ *
+ * The enum <b>only applies to update methods</b>: methods that update a pre-existing target (annotated with
+ * {@code @}{@link MappingTarget}).
+ *
+ *  <p>
+ *  <b>Note</b>: some types of mappings (collections, maps), in which MapStruct is instructed to use a getter or adder
+ *  as target accessor see {@link CollectionMappingStrategy}, MapStruct will always generate a source property
+ *  null check, regardless the value of the {@link NullValuePropertyMappingStrategy} to avoid addition of {@code null}
+ *  to the target collection or map. Since the target is assumed to be initialised this strategy will not be applied.
+ *
+ * @author Sjaak Derksen
+ * @since 1.3
+ */
+public enum NullValuePropertyMappingStrategy {
+
+    /**
+     * If a source bean property equals {@code null} the target bean property will be set explicitly to {@code null}.
+     */
+    SET_TO_NULL,
+
+    /**
+     * If a source bean property equals {@code null} the target bean property will be set to its default value.
+     * <p>
+     * This means:
+     * <ol>
+     * <li>For {@code List} MapStruct generates an {@code ArrayList}</li>
+     * <li>For {@code Map} a {@code HashMap}</li>
+     * <li>For arrays an empty array</li>
+     * <li>For {@code String} {@code ""}</li>
+     * <li>for primitive / boxed types a representation of {@code 0} or {@code false}</li>
+     * <li>For all other objects an new instance is created, requiring an empty constructor.</li>
+     * </ol>
+     * <p>
+     * Make sure that a {@link Mapping#defaultValue()} is defined if no empty constructor is available on
+     * the default value.
+     */
+    SET_TO_DEFAULT,
+
+    /**
+     * If a source bean property equals {@code null} the target bean property will be ignored and retain its
+     * existing value.
+     */
+    IGNORE;
+}

core/src/main/java/org/mapstruct/ObjectFactory.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This annotation marks a method as a <em>factory method</em> to create beans.
+ * <p>
+ * By default beans are created during the mapping process with the default constructor. If a factory method with a
+ * return type that is assignable to the required object type is present, then the factory method is used instead.
+ * <p>
+ * Factory methods can be defined without parameters, with an {@code @}{@link TargetType} parameter, a
+ * {@code @}{@link Context} parameter, or with the mapping source parameter. If any of those parameters are defined,
+ * then the mapping method that is supposed to use the factory method needs to be declared with an assignable result
+ * type, assignable context parameter, and/or assignable source types.
+ * <p>
+ * <strong>Note:</strong> the usage of this annotation is <em>optional</em> when used in the {@link Mapper#uses()}
+ * if no source parameters are part of the signature, i.e. it is declared without parameters or only with
+ * {@code @}{@link TargetType} and/or {@code @}{@link Context}. It is however <em>mandatory</em> when used inside
+ * an {@code @}{@link Context} annotated class.
+ * <p>
+ * <strong>Example:</strong> Using a factory method for entities to check whether the entity already exists in the
+ * EntityManager and then returns the managed instance:
+ *
+ * <pre>
+ * <code>
+ * &#64;ApplicationScoped // CDI component model
+ * public class ReferenceMapper {
+ *
+ *     &#64;PersistenceContext
+ *     private EntityManager em;
+ *
+ *     &#64;ObjectFactory
+ *     public &lt;T extends AbstractEntity&gt; T resolve(AbstractDto sourceDto, &#64;TargetType Class&lt;T&gt; type) {
+ *         T entity = em.find( type, sourceDto.getId() );
+ *         return entity != null ? entity : type.newInstance();
+ *     }
+ * }
+ * </code>
+ * </pre>
+ * <p>
+ * If there are two factory methods, both serving the same type, one with no parameters and one taking sources as input,
+ * then the one with the source parameters is favored. If there are multiple such factories, an ambiguity error is
+ * shown.
+ *
+ * @author Remo Meier
+ * @since 1.2
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.METHOD)
+public @interface ObjectFactory {
+
+}

core/src/main/java/org/mapstruct/Qualifier.java

@@ -0,0 +1,90 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Declares an annotation type to be a qualifier. Qualifier annotations allow unambiguously identify a suitable mapping
+ * method in case several methods qualify to map a bean property, iterable element etc.
+ * <p>
+ * Can be used in:
+ * <ul>
+ * <li>{@link Mapping#qualifiedBy() }</li>
+ * <li>{@link BeanMapping#qualifiedBy() }</li>
+ * <li>{@link IterableMapping#qualifiedBy() }</li>
+ * <li>{@link MapMapping#keyQualifiedBy() }</li>
+ * <li>{@link MapMapping#valueQualifiedBy() }</li>
+ * <li>{@link SubclassMapping#qualifiedBy() }</li>
+ * </ul>
+ * <p><strong>Example:</strong></p>
+ * <pre><code class='java'>
+ * // create qualifiers
+ * &#64;Qualifier
+ * &#64;Target(ElementType.TYPE)
+ * &#64;Retention(RetentionPolicy.CLASS)
+ * public &#64;interface TitleTranslator {}
+ *
+ * &#64;Qualifier
+ * &#64;Target(ElementType.METHOD)
+ * &#64;Retention(RetentionPolicy.CLASS)
+ * public @interface EnglishToGerman {}
+ *
+ * &#64;Qualifier
+ * &#64;Target(ElementType.METHOD)
+ * &#64;Retention(RetentionPolicy.CLASS)
+ * public @interface GermanToEnglish {}
+ * </code></pre>
+ * <pre><code class='java'>
+ * // we can create class with map methods
+ * &#64;TitleTranslator
+ * public class Titles {
+ *     &#64;EnglishToGerman
+ *     public String translateTitleEnglishToGerman(String title) {
+ *         // some mapping logic
+ *     }
+ *     &#64;GermanToEnglish
+ *     public String translateTitleGermanToEnglish(String title) {
+ *         // some mapping logic
+ *     }
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // usage
+ * &#64;Mapper( uses = Titles.class )
+ * public interface MovieMapper {
+ *      &#64;Mapping( target = "title", qualifiedBy = { TitleTranslator.class, EnglishToGerman.class } )
+ *      GermanRelease toGerman( OriginalRelease movies );
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * public class MovieMapperImpl implements MovieMapper {
+ *      private final Titles titles = new Titles();
+ *      &#64;Override
+ *      public GermanRelease toGerman(OriginalRelease movies) {
+ *          if ( movies == null ) {
+ *              return null;
+ *          }
+ *          GermanRelease germanRelease = new GermanRelease();
+ *          germanRelease.setTitle( titles.translateTitleEnglishToGerman( movies.getTitle() ) );
+ *          return germanRelease;
+ *     }
+ * }
+ * </code></pre>
+ *
+ * <b>NOTE:</b> Qualifiers should have {@link RetentionPolicy#CLASS}.
+ *
+ * @author Sjaak Derksen
+ * @see Named
+ */
+@Target(ElementType.ANNOTATION_TYPE)
+@Retention(RetentionPolicy.CLASS)
+public @interface Qualifier {
+}

core/src/main/java/org/mapstruct/ReportingPolicy.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import javax.tools.Diagnostic.Kind;
+
+/**
+ * Policy for reporting issues occurring during the generation of a mapper
+ * implementation.
+ *
+ * @author Gunnar Morling
+ */
+public enum ReportingPolicy {
+
+    /**
+     * No report will be created for the given issue.
+     */
+    IGNORE,
+
+    /**
+     * A report with {@link Kind#WARNING} will be created for the given issue.
+     */
+    WARN,
+
+    /**
+     * A report with {@link Kind#ERROR} will be created for the given issue,
+     * causing the compilation to fail.
+     */
+    ERROR;
+}

core/src/main/java/org/mapstruct/SourceParameterCondition.java

@@ -0,0 +1,74 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This annotation marks a method as a <em>check method</em> to check if a source parameter needs to be mapped.
+ * <p>
+ * By default, source parameters are checked against {@code null}, unless they are primitives.
+ * <p>
+ * Check methods have to return {@code boolean}.
+ * The following parameters are accepted for the presence check methods:
+ *     <ul>
+ *         <li>The mapping source parameter</li>
+ *         <li>{@code @}{@link Context} parameter</li>
+ *     </ul>
+ *
+ * <strong>Note:</strong> The usage of this annotation is <em>mandatory</em>
+ * for a method to be considered as a source check method.
+ *
+ * <pre><code class='java'>
+ * public class PresenceCheckUtils {
+ *
+ *   &#64;SourceParameterCondition
+ *   public static boolean isDefined(Car car) {
+ *      return car != null &#38;&#38; car.getId() != null;
+ *   }
+ * }
+ *
+ * &#64;Mapper(uses = PresenceCheckUtils.class)
+ * public interface CarMapper {
+ *
+ *     CarDto map(Car car);
+ * }
+ * </code></pre>
+ *
+ * The following implementation of {@code CarMapper} will be generated:
+ *
+ * <pre><code class='java'>
+ * public class CarMapperImpl implements CarMapper {
+ *
+ *     &#64;Override
+ *     public CarDto map(Car car) {
+ *         if ( !PresenceCheckUtils.isDefined( car ) ) {
+ *             return null;
+ *         }
+ *
+ *         CarDto carDto = new CarDto();
+ *
+ *         carDto.setId( car.getId() );
+ *         // ...
+ *
+ *         return carDto;
+ *     }
+ * }
+ * </code></pre>
+ *
+ * @author Filip Hrisafov
+ * @since 1.6
+ * @see Condition @Condition
+ */
+@Target({ ElementType.METHOD })
+@Retention(RetentionPolicy.CLASS)
+@Condition(appliesTo = ConditionStrategy.SOURCE_PARAMETERS)
+public @interface SourceParameterCondition {
+
+}

core/src/main/java/org/mapstruct/SourcePropertyName.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This annotation marks a <em>presence check method</em> parameter as a source property name parameter.
+ * <p>
+ * This parameter enables conditional filtering based on source property name at run-time.
+ * Parameter must be of type {@link String} and can be present only in {@link Condition} method.
+ * </p>
+ *
+ * @author Oliver Erhart
+ * @since 1.6
+ */
+@Target(ElementType.PARAMETER)
+@Retention(RetentionPolicy.CLASS)
+public @interface SourcePropertyName {
+}

core/src/main/java/org/mapstruct/SubclassExhaustiveStrategy.java

@@ -0,0 +1,28 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+/**
+ * Strategy for dealing with subclassMapping annotated methods.
+ *
+ * @since 1.5
+ * @author Ben Zegveld
+ */
+public enum SubclassExhaustiveStrategy {
+
+    /**
+     * If there is no valid constructor or known method to create the return value of a with `@SubclassMapping`
+     * annotated mapping then a compilation error will be thrown.
+     */
+    COMPILE_ERROR,
+
+    /**
+     * If there is no valid constructor or known method to create the return value of a with `@SubclassMapping`
+     * annotated mapping then an {@link IllegalArgumentException} will be thrown if a call is made with a type for which
+     * there is no {@link SubclassMapping} available.
+     */
+    RUNTIME_EXCEPTION;
+}

core/src/main/java/org/mapstruct/SubclassMapping.java

@@ -0,0 +1,110 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.Annotation;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.mapstruct.util.Experimental;
+
+/**
+ * Configures the mapping to handle hierarchy of the source type.
+ * <p>
+ * The subclass to be mapped is to be specified via {@link #source()}.
+ * The subclass to map to is to be specified via {@link #target()}.
+ * </p>
+ * <p>
+ * This annotation can be combined with &#64;Mapping annotations.
+ * </p>
+ *
+ * <pre><code class='java'>
+ * &#64;Mapper
+ * public interface MyMapper {
+ *    &#64;SubclassMapping (target = TargetSubclass.class, source = SourceSubclass.class)
+ *    TargetParent mapParent(SourceParent parent);
+ *
+ *    TargetSubclass mapSubclass(SourceSubclass subInstant);
+ * }
+ * </code></pre>
+ * Below follow examples of the implementation for the mapParent method.
+ * <strong>Example 1:</strong> For parents that cannot be created. (e.g. abstract classes or interfaces)
+ * <pre><code class='java'>
+ * // generates
+ * &#64;Override
+ * public TargetParent mapParent(SourceParent parent) {
+ *     if (parent instanceof SourceSubclass) {
+ *         return mapSubclass( (SourceSubclass) parent );
+ *     }
+ *     else {
+ *         throw new IllegalArgumentException("Not all subclasses are supported for this mapping. Missing for "
+ *                    + parent.getClass());
+ *     }
+ * }
+ * </code></pre>
+ * <strong>Example 2:</strong> For parents that can be created. (e.g. normal classes or interfaces with
+ * &#64;Mapper( uses = ObjectFactory.class ) )
+ * <pre><code class='java'>
+ * // generates
+ * &#64;Override
+ * public TargetParent mapParent(SourceParent parent) {
+ *     TargetParent targetParent1;
+ *     if (parent instanceof SourceSubclass) {
+ *         targetParent1 = mapSubclass( (SourceSubclass) parent );
+ *     }
+ *     else {
+ *         targetParent1 = new TargetParent();
+ *         // ...
+ *     }
+ * }
+ * </code></pre>
+ *
+ * @author Ben Zegveld
+ * @since 1.5
+ */
+@Repeatable(value = SubclassMappings.class)
+@Retention(RetentionPolicy.CLASS)
+@Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
+@Experimental
+public @interface SubclassMapping {
+    /**
+     * @return the source subclass to check for before using the default mapping as fallback.
+     */
+    Class<?> source();
+
+    /**
+     * @return the target subclass to map the source to.
+     */
+    Class<?> target();
+
+    /**
+     * A qualifier can be specified to aid the selection process of a suitable mapper. This is useful in case multiple
+     * mapping methods (hand written or generated) qualify and thus would result in an 'Ambiguous mapping methods found'
+     * error. A qualifier is a custom annotation and can be placed on a hand written mapper class or a method.
+     *
+     * @return the qualifiers
+     * @see Qualifier
+     */
+    Class<? extends Annotation>[] qualifiedBy() default {};
+
+    /**
+     * String-based form of qualifiers; When looking for a suitable mapping method for a given property, MapStruct will
+     * only consider those methods carrying directly or indirectly (i.e. on the class-level) a {@link Named} annotation
+     * for each of the specified qualifier names.
+     * <p>
+     * Note that annotation-based qualifiers are generally preferable as they allow more easily to find references and
+     * are safe for refactorings, but name-based qualifiers can be a less verbose alternative when requiring a large
+     * number of qualifiers as no custom annotation types are needed.
+     *
+     * @return One or more qualifier name(s)
+     * @see #qualifiedBy()
+     * @see Named
+     */
+    String[] qualifiedByName() default {};
+}

core/src/main/java/org/mapstruct/SubclassMappings.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.mapstruct.util.Experimental;
+
+/**
+ * Configures the SubclassMappings of several subclasses.
+ * <p>
+ * <strong>TIP: When using java 8 or later, you can omit the @SubclassMappings
+ * Wrapper annotation and directly specify several @SubclassMapping annotations
+ * on one method.</strong>
+ * </p>
+ * <p>These two examples are equal.
+ * </p>
+ * <pre><code class='java'>
+ * // before java 8
+ * &#64;Mapper
+ * public interface MyMapper {
+ *     &#64;SubclassMappings({
+ *         &#64;SubclassMapping(source = FirstSub.class, target = FirstTargetSub.class),
+ *         &#64;SubclassMapping(source = SecondSub.class, target = SecondTargetSub.class)
+ *     })
+ *     ParentTarget toParentTarget(Parent parent);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // java 8 and later
+ * &#64;Mapper
+ * public interface MyMapper {
+ *     &#64;SubclassMapping(source = First.class, target = FirstTargetSub.class),
+ *     &#64;SubclassMapping(source = SecondSub.class, target = SecondTargetSub.class)
+ *     ParentTarget toParentTarget(Parent parent);
+ * }
+ * </code></pre>
+ *
+ * @author Ben Zegveld
+ * @since 1.5
+ */
+@Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
+@Retention(RetentionPolicy.CLASS)
+@Experimental
+public @interface SubclassMappings {
+
+    /**
+     * @return the subclassMappings to apply.
+     */
+    SubclassMapping[] value();
+
+}

core/src/main/java/org/mapstruct/TargetPropertyName.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This annotation marks a <em>presence check method</em> parameter as a target property name parameter.
+ * <p>
+ * This parameter enables conditional filtering based on target property name at run-time.
+ * Parameter must be of type {@link String} and can be present only in {@link Condition} method.
+ * </p>
+ * @author Nikola Ivačič
+ * @since 1.6
+ */
+@Target(ElementType.PARAMETER)
+@Retention(RetentionPolicy.CLASS)
+public @interface TargetPropertyName {
+}

core/src/main/java/org/mapstruct/TargetType.java

@@ -0,0 +1,53 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Declares a parameter of a custom mapping method to be populated with the target type of the mapping.
+ * <p>
+ * Not more than one parameter can be declared as {@code TargetType} and that parameter needs to be of type
+ * {@link Class} (may be parameterized), or a super-type of it.
+ *
+ * <p>
+ * <strong>Example:</strong>
+ * </p>
+ * <pre><code class='java'>
+ * public class EntityFactory {
+ *    public &lt;T extends BaseEntity&gt; T createEntity(@TargetType Class&lt;T&gt; entityClass) {
+ *         return // ... custom factory logic
+ *    }
+ * }
+ * &#64;Mapper(uses = EntityFactory.class)
+ * public interface CarMapper {
+ *     CarEntity carDtoToCar(CarDto dto);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * public class CarMapperImpl implements CarMapper {
+ *     private final EntityFactory entityFactory = new EntityFactory();
+ *     &#64;Override
+ *     public CarEntity carDtoToCar(CarDto dto) {
+ *         if ( dto == null ) {
+ *             return null;
+ *         }
+ *         CarEntity carEntity = entityFactory.createEntity( CarEntity.class );
+ *         return carEntity;
+ *     }
+ * }
+ * </code></pre>
+ *
+ * @author Andreas Gudian
+ */
+@Target(ElementType.PARAMETER)
+@Retention(RetentionPolicy.CLASS)
+public @interface TargetType {
+}

core/src/main/java/org/mapstruct/ValueMapping.java

@@ -0,0 +1,124 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Configures the mapping of source constant value to target constant value.
+ * <p>
+ * Supported mappings are
+ * <ol>
+ * <li>Enumeration to Enumeration</li>
+ * </ol>
+ * <b>Example 1:</b>
+ *
+ * <pre><code>
+ * public enum OrderType { RETAIL, B2B, C2C, EXTRA, STANDARD, NORMAL }
+ *
+ * public enum ExternalOrderType { RETAIL, B2B, SPECIAL, DEFAULT }
+ *
+ * &#64;ValueMapping(target = "SPECIAL", source = "EXTRA"),
+ * &#64;ValueMapping(target = "DEFAULT", source = "STANDARD"),
+ * &#64;ValueMapping(target = "DEFAULT", source = "NORMAL")
+ * ExternalOrderType orderTypeToExternalOrderType(OrderType orderType);
+ * </code>
+ * Mapping result:
+ * +---------------------+----------------------------+
+ * | OrderType           | ExternalOrderType          |
+ * +---------------------+----------------------------+
+ * | null                | null                       |
+ * | OrderType.EXTRA     | ExternalOrderType.SPECIAL  |
+ * | OrderType.STANDARD  | ExternalOrderType.DEFAULT  |
+ * | OrderType.NORMAL    | ExternalOrderType.DEFAULT  |
+ * | OrderType.RETAIL    | ExternalOrderType.RETAIL   |
+ * | OrderType.B2B       | ExternalOrderType.B2B      |
+ * +---------------------+----------------------------+
+ * </pre>
+ *
+ * <b>Example 2:</b>
+ *
+ * <pre><code>
+ * &#64;ValueMapping( source = MappingConstants.NULL, target = "DEFAULT" ),
+ * &#64;ValueMapping( source = "STANDARD", target = MappingConstants.NULL ),
+ * &#64;ValueMapping( source = MappingConstants.ANY_REMAINING, target = "SPECIAL" )
+ * ExternalOrderType orderTypeToExternalOrderType(OrderType orderType);
+ * </code>
+ * Mapping result:
+ * +---------------------+----------------------------+
+ * | OrderType           | ExternalOrderType          |
+ * +---------------------+----------------------------+
+ * | null                | ExternalOrderType.DEFAULT  |
+ * | OrderType.STANDARD  | null                       |
+ * | OrderType.RETAIL    | ExternalOrderType.RETAIL   |
+ * | OrderType.B2B       | ExternalOrderType.B2B      |
+ * | OrderType.NORMAL    | ExternalOrderType.SPECIAL  |
+ * | OrderType.EXTRA     | ExternalOrderType.SPECIAL  |
+ * +---------------------+----------------------------+
+ * </pre>
+ *
+ * <b>Example 3:</b>
+ *
+ * MapStruct will <B>WARN</B> on incomplete mappings. However, if for some reason no match is found, an
+ * {@link java.lang.IllegalStateException} will be thrown. This compile-time error can be avoided by
+ * using {@link MappingConstants#THROW_EXCEPTION} for {@link ValueMapping#target()}. It will result an
+ * {@link java.lang.IllegalArgumentException} at runtime.
+ * <pre><code>
+ * &#64;ValueMapping( source = "STANDARD", target = "DEFAULT" ),
+ * &#64;ValueMapping( source = "C2C", target = MappingConstants.THROW_EXCEPTION )
+ * ExternalOrderType orderTypeToExternalOrderType(OrderType orderType);
+ * </code>
+ * Mapping result:
+ * {@link java.lang.IllegalArgumentException} with the error message:
+ * Unexpected enum constant: C2C
+ * </pre>
+ *
+ * @author Sjaak Derksen
+ */
+@Repeatable(ValueMappings.class)
+@Retention(RetentionPolicy.CLASS)
+@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
+public @interface ValueMapping {
+    /**
+     * The source value constant to use for this mapping.
+     *
+     * <p>
+     * <b>Valid values:</b>
+     * <ol>
+     * <li>enum constant name</li>
+     * <li>{@link MappingConstants#NULL}</li>
+     * <li>{@link MappingConstants#ANY_REMAINING}</li>
+     * <li>{@link MappingConstants#ANY_UNMAPPED}</li>
+     * </ol>
+     * <p>
+     * <b>NOTE:</b>When using &lt;ANY_REMAINING&gt;, MapStruct will perform the normal name based mapping, in which
+     * source is mapped to target based on enum identifier equality. Using &lt;ANY_UNMAPPED&gt; will not apply name
+     * based mapping.
+     *
+     * @return The source value.
+     */
+    String source();
+
+    /**
+     * The target value constant to use for this mapping.
+     *
+     * <p>
+     * <b>Valid values:</b>
+     * <ol>
+     * <li>enum constant name</li>
+     * <li>{@link MappingConstants#NULL}</li>
+     * <li>{@link MappingConstants#THROW_EXCEPTION}</li>
+     * </ol>
+     *
+     * @return The target value.
+     */
+    String target();
+
+}

core/src/main/java/org/mapstruct/ValueMappings.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Constructs a set of value (constant) mappings.
+ * <p>
+ * <strong>TIP: When using Java 8 or later, you can omit the @ValueMappings
+ * wrapper annotation and directly specify several @ValueMapping annotations on one method.</strong>
+ *
+ * <p>These two examples are equal</p>
+ * <pre><code class='java'>
+ * // before Java 8
+ * &#64;Mapper
+ * public interface GenderMapper {
+ *     &#64;ValueMappings({
+ *         &#64;ValueMapping(target = "M", source = "MALE"),
+ *         &#64;ValueMapping(target = "F", source = "FEMALE")
+ *     })
+ *     GenderDto mapToDto(Gender gender);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * //Java 8 and later
+ * &#64;Mapper
+ * public interface GenderMapper {
+ *     &#64;ValueMapping(target = "M", source = "MALE"),
+ *     &#64;ValueMapping(target = "F", source = "FEMALE")
+ *     GenderDto mapToDto(Gender gender);
+ * }
+ * </code></pre>
+ *
+ * @author Sjaak Derksen
+ */
+@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
+@Retention(RetentionPolicy.CLASS)
+public @interface ValueMappings {
+
+    ValueMapping[] value();
+
+}

core/src/main/java/org/mapstruct/control/DeepClone.java

@@ -0,0 +1,24 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.control;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+import org.mapstruct.util.Experimental;
+
+/**
+ * Clones a source type to a target type (assuming source and target are of the same type).
+ *
+ * @author Sjaak Derksen
+ *
+ * @since 1.4
+ */
+@Retention(RetentionPolicy.CLASS)
+@Experimental
+@MappingControl( MappingControl.Use.MAPPING_METHOD )
+public @interface DeepClone {
+}

core/src/main/java/org/mapstruct/control/MappingControl.java

@@ -0,0 +1,152 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.control;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+
+/**
+ * Controls which means of mapping are considered between the source and the target in mappings.
+ *
+ * <p>
+ * There are several applications of <code>MappingControl</code> conceivable. One application, "deep cloning" is
+ * explained below in the example.
+ * </p>
+ *
+ * <p>
+ * Another application is controlling so called "complex mappings", which are not always desirable and sometimes lead to
+ * unexpected behaviour and prolonged compilation time.
+ * </p>
+ *
+ * <p><strong>Example:</strong>Cloning of an object</p>
+ * <p>
+ * When all methods are allowed, MapStruct would make a shallow copy. It would take the <code>ShelveDTO</code> in
+ * the <code>FridgeDTO</code> and directly enter that as target on the target <code>FridgeDTO</code>. By disabling all
+ * other kinds of mappings apart from {@link MappingControl.Use#MAPPING_METHOD}, see {@link DeepClone} MapStruct is
+ * forced to generate mapping methods all through the object graph `FridgeDTO` and hence create a deep clone.
+ * </p>
+ * <pre><code class='java'>
+ * public class FridgeDTO {
+ *
+ *     private ShelveDTO shelve;
+ *
+ *     public ShelveDTO getShelve() {
+ *         return shelve;
+ *     }
+ *
+ *     public void setShelve(ShelveDTO shelve) {
+ *         this.shelve = shelve;
+ *     }
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * public class ShelveDTO {
+ *
+ *     private CoolBeerDTO coolBeer;
+ *
+ *     public CoolBeerDTO getCoolBeer() {
+ *         return coolBeer;
+ *     }
+ *
+ *     public void setCoolBeer(CoolBeerDTO coolBeer) {
+ *         this.coolBeer = coolBeer;
+ *     }
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * public class CoolBeerDTO {
+ *
+ *     private String beerCount;
+ *
+ *     public String getBeerCount() {
+ *         return beerCount;
+ *     }
+ *
+ *     public void setBeerCount(String beerCount) {
+ *         this.beerCount = beerCount;
+ *     }
+ * }
+ * </code></pre>
+ *
+ * <pre><code class='java'>
+ * &#64;Mapper(mappingControl = DeepClone.class)
+ * public interface CloningMapper {
+ *
+ *     CloningMapper INSTANCE = Mappers.getMapper( CloningMapper.class );
+ *
+ *     FridgeDTO clone(FridgeDTO in);
+ *
+ * }
+ * </code></pre>
+ *
+ * @author Sjaak Derksen
+ *
+ * @since 1.4
+ */
+@Retention(RetentionPolicy.CLASS)
+@Repeatable(MappingControls.class)
+@Target( ElementType.ANNOTATION_TYPE )
+@MappingControl( MappingControl.Use.DIRECT )
+@MappingControl( MappingControl.Use.BUILT_IN_CONVERSION )
+@MappingControl( MappingControl.Use.MAPPING_METHOD )
+@MappingControl( MappingControl.Use.COMPLEX_MAPPING )
+public @interface MappingControl {
+
+    Use value();
+
+    enum Use {
+
+        /**
+         * Controls the mapping, allows for type conversion from source type to target type
+         * <p>
+         * Type conversions are typically supported directly in Java. The "toString()" is such an example,
+         * which allows for mapping for instance a  {@link java.lang.Number} type to a {@link java.lang.String}.
+         * <p>
+         * Please refer to the MapStruct guide for more info.
+         *
+         * @since 1.4
+         */
+        BUILT_IN_CONVERSION,
+
+        /**
+         * Controls the mapping from source to target type, allows mapping by calling:
+         * <ol>
+         * <li>A type conversion, passed into a mapping method</li>
+         * <li>A mapping method, passed into a type conversion</li>
+         * <li>A mapping method passed into another mapping method</li>
+         * </ol>
+         *
+         * @since 1.4
+         */
+        COMPLEX_MAPPING,
+        /**
+         * Controls the mapping, allows for a direct mapping from source type to target type.
+         * <p>
+         * This means if source type and target type are of the same type, MapStruct will not perform
+         * any mappings anymore and assign the target to the source direct.
+         * <p>
+         * An exception are types from the package {@code java}, which will be mapped always directly.
+         *
+         * @since 1.4
+         */
+        DIRECT,
+
+        /**
+         * Controls the mapping, allows for Direct Mapping from source type to target type.
+         * <p>
+         * The mapping method can be either a custom referred mapping method, or a MapStruct built in
+         * mapping method.
+         *
+         * @since 1.4
+         */
+        MAPPING_METHOD
+    }
+
+}

core/src/main/java/org/mapstruct/control/MappingControls.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.control;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Allows multiple {@link MappingControl} on a class declaration.
+ *
+ * @author Sjaak Derksen
+ *
+ * @since 1.4
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.ANNOTATION_TYPE)
+public @interface MappingControls {
+
+    MappingControl[] value();
+}

core/src/main/java/org/mapstruct/control/NoComplexMapping.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.control;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+import org.mapstruct.util.Experimental;
+
+/**
+ * Disables complex mappings, mappings that require 2 mapping means (method, built-in conversion) to constitute
+ * a mapping from source to target.
+ *
+ * @see MappingControl.Use#COMPLEX_MAPPING
+ *
+ * @author Sjaak Derksen
+ *
+ * @since 1.4
+ */
+@Retention(RetentionPolicy.CLASS)
+@Experimental
+@MappingControl( MappingControl.Use.DIRECT )
+@MappingControl( MappingControl.Use.BUILT_IN_CONVERSION )
+@MappingControl( MappingControl.Use.MAPPING_METHOD )
+public @interface NoComplexMapping {
+}

core/src/main/java/org/mapstruct/factory/Mappers.java

@@ -0,0 +1,168 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.factory;
+
+import java.lang.reflect.Constructor;
+import java.lang.reflect.InvocationTargetException;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.ServiceLoader;
+
+import org.mapstruct.Mapper;
+
+/**
+ * Factory for obtaining mapper instances if no explicit component model such as CDI is configured via
+ * {@link Mapper#componentModel()}.
+ * <p>
+ * Mapper implementation types are expected to have the same fully qualified name as their interface type, with the
+ * suffix {@code Impl} appended. When using this factory, mapper types - and any mappers they use - are instantiated by
+ * invoking their public no-args constructor.
+ * <p>
+ * By convention, a single instance of each mapper is retrieved from the factory and exposed on the mapper interface
+ * type by declaring a member named {@code INSTANCE} like this:
+ *
+ * <pre>
+ * &#064;Mapper
+ * public interface CustomerMapper {
+ *
+ *     CustomerMapper INSTANCE = Mappers.getMapper( CustomerMapper.class );
+ *
+ *     // mapping methods...
+ * }
+ * </pre>
+ *
+ * @author Gunnar Morling
+ */
+public class Mappers {
+
+    private static final String IMPLEMENTATION_SUFFIX = "Impl";
+
+    private Mappers() {
+    }
+
+    /**
+     * Returns an instance of the given mapper type.
+     *
+     * @param clazz The type of the mapper to return.
+     * @param <T> The type of the mapper to create.
+     *
+     * @return An instance of the given mapper type.
+     */
+    public static <T> T getMapper(Class<T> clazz) {
+        try {
+            List<ClassLoader> classLoaders = collectClassLoaders( clazz.getClassLoader() );
+
+            return getMapper( clazz, classLoaders );
+        }
+        catch ( ClassNotFoundException | NoSuchMethodException e ) {
+            throw new RuntimeException( e );
+        }
+    }
+
+    private static <T> T getMapper(Class<T> mapperType, Iterable<ClassLoader> classLoaders)
+            throws ClassNotFoundException, NoSuchMethodException {
+
+        for ( ClassLoader classLoader : classLoaders ) {
+            T mapper = doGetMapper( mapperType, classLoader );
+            if ( mapper != null ) {
+                return mapper;
+            }
+        }
+
+        throw new ClassNotFoundException("Cannot find implementation for " + mapperType.getName() );
+    }
+
+    private static <T> T doGetMapper(Class<T> clazz, ClassLoader classLoader) throws NoSuchMethodException {
+        try {
+            @SuppressWarnings( "unchecked" )
+            Class<T> implementation = (Class<T>) classLoader.loadClass( clazz.getName() + IMPLEMENTATION_SUFFIX );
+            Constructor<T> constructor = implementation.getDeclaredConstructor();
+            constructor.setAccessible( true );
+
+            return constructor.newInstance();
+        }
+        catch (ClassNotFoundException e) {
+            return getMapperFromServiceLoader( clazz, classLoader );
+        }
+        catch ( InstantiationException | InvocationTargetException | IllegalAccessException e) {
+            throw new RuntimeException( e );
+        }
+    }
+
+    /**
+     * Returns the class of the implementation for the given mapper type.
+     *
+     * @param clazz The type of the mapper to return.
+     * @param <T> The type of the mapper to create.
+     *
+     * @return A class of the implementation for the given mapper type.
+     *
+     * @since 1.3
+     */
+    public static <T> Class<? extends T> getMapperClass(Class<T> clazz) {
+        try {
+            List<ClassLoader> classLoaders = collectClassLoaders( clazz.getClassLoader() );
+
+            return getMapperClass( clazz, classLoaders );
+        }
+        catch ( ClassNotFoundException e ) {
+            throw new RuntimeException( e );
+        }
+    }
+
+    private static <T> Class<? extends T> getMapperClass(Class<T> mapperType, Iterable<ClassLoader> classLoaders)
+        throws ClassNotFoundException {
+
+        for ( ClassLoader classLoader : classLoaders ) {
+            Class<? extends T> mapperClass = doGetMapperClass( mapperType, classLoader );
+            if ( mapperClass != null ) {
+                return mapperClass;
+            }
+        }
+
+        throw new ClassNotFoundException( "Cannot find implementation for " + mapperType.getName() );
+    }
+
+    @SuppressWarnings("unchecked")
+    private static <T> Class<? extends T> doGetMapperClass(Class<T> clazz, ClassLoader classLoader) {
+        try {
+            return (Class<? extends T>) classLoader.loadClass( clazz.getName() + IMPLEMENTATION_SUFFIX );
+        }
+        catch ( ClassNotFoundException e ) {
+            T mapper = getMapperFromServiceLoader( clazz, classLoader );
+            if ( mapper != null ) {
+                return (Class<? extends T>) mapper.getClass();
+            }
+
+            return null;
+        }
+    }
+
+    private static <T> T getMapperFromServiceLoader(Class<T> clazz, ClassLoader classLoader) {
+        ServiceLoader<T> loader = ServiceLoader.load( clazz, classLoader );
+
+        for ( T mapper : loader ) {
+            if ( mapper != null ) {
+                return mapper;
+            }
+        }
+
+        return null;
+    }
+
+    private static List<ClassLoader> collectClassLoaders(ClassLoader classLoader) {
+        List<ClassLoader> classLoaders = new ArrayList<>( 3 );
+        classLoaders.add( classLoader );
+
+        if ( Thread.currentThread().getContextClassLoader() != null ) {
+            classLoaders.add( Thread.currentThread().getContextClassLoader() );
+        }
+
+        classLoaders.add( Mappers.class.getClassLoader() );
+
+        return classLoaders;
+    }
+}

core/src/main/java/org/mapstruct/factory/package-info.java

@@ -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
+ */
+/**
+ * <p>
+ * Provides the {@link org.mapstruct.factory.Mappers} factory class for the retrieval of mapper instances if no
+ * explicit component model such as CDI is configured via {@link org.mapstruct.Mapper#componentModel()}.
+ * </p>
+ *
+ */
+package org.mapstruct.factory;

core/src/main/java/org/mapstruct/package-info.java

@@ -0,0 +1,18 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * <p>
+ * MapStruct is a code generator which simplifies the implementation of mappings between Java bean types by generating
+ * mapping code at compile time, following a convention-over-configuration approach. The generated code uses plain
+ * method invocations and thus is fast and type-safe.
+ * </p>
+ * <p>
+ * This package contains several annotations which allow to configure how mapper interfaces are generated.
+ * </p>
+ *
+ * @see <a href="https://mapstruct.org/">MapStruct reference documentation</a>
+ */
+package org.mapstruct;

core/src/main/java/org/mapstruct/util/Experimental.java

@@ -0,0 +1,21 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.util;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+/**
+ * Features that are marked with this annotation are considered <em>experimental</em>.
+ *
+ * @author Andreas Gudian
+ */
+@Documented
+@Retention(RetentionPolicy.SOURCE)
+public @interface Experimental {
+    String value() default "";
+}

core/src/test/java/org/mapstruct/factory/MappersTest.java

@@ -0,0 +1,61 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.factory;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.junit.jupiter.api.Test;
+import org.mapstruct.test.model.Foo;
+import org.mapstruct.test.model.SomeClass;
+
+/**
+ * Unit test for {@link Mappers}.
+ *
+ * @author Gunnar Morling
+ */
+public class MappersTest {
+
+    @Test
+    public void shouldReturnImplementationInstance() {
+
+        Foo mapper = Mappers.getMapper( Foo.class );
+        assertThat( mapper ).isNotNull();
+    }
+
+    @Test
+    public void shouldReturnImplementationClass() {
+
+        Class<? extends Foo> mapperClass = Mappers.getMapperClass( Foo.class );
+        assertThat( mapperClass ).isNotNull();
+        assertThat( mapperClass ).isNotExactlyInstanceOf( Foo.class );
+    }
+
+    /**
+     * Checks if an implementation of a nested mapper can be found. This is a special case since
+     * it is named
+     */
+    @Test
+    public void findsNestedMapperImpl() {
+        assertThat( Mappers.getMapper( SomeClass.Foo.class ) ).isNotNull();
+        assertThat( Mappers.getMapper( SomeClass.NestedClass.Foo.class ) ).isNotNull();
+    }
+
+    @Test
+    public void findsNestedMapperImplClass() {
+        assertThat( Mappers.getMapperClass( SomeClass.Foo.class ) ).isNotNull();
+        assertThat( Mappers.getMapperClass( SomeClass.NestedClass.Foo.class ) ).isNotNull();
+    }
+
+    @Test
+    public void shouldReturnPackagePrivateImplementationInstance() {
+        assertThat( Mappers.getMapper( PackagePrivateMapper.class ) ).isNotNull();
+    }
+
+    @Test
+    public void shouldReturnPackagePrivateImplementationClass() {
+        assertThat( Mappers.getMapperClass( PackagePrivateMapper.class ) ).isNotNull();
+    }
+}

core/src/test/java/org/mapstruct/factory/PackagePrivateMapper.java

@@ -0,0 +1,10 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.factory;
+
+interface PackagePrivateMapper {
+
+}

core/src/test/java/org/mapstruct/factory/PackagePrivateMapperImpl.java

@@ -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
+ */
+package org.mapstruct.factory;
+
+class PackagePrivateMapperImpl implements PackagePrivateMapper {
+}

core/src/test/java/org/mapstruct/test/model/Foo.java

@@ -0,0 +1,10 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.test.model;
+
+public interface Foo {
+
+}