1.4.2.Final

Enhancement

• Relax strictness for Mapping#qualifiedByName and Mapping#qualifier for collection mappings (#2324, #2346)
• Mark mapstruct-processor jar as Spring-Boot-Jar-Type: annotation-processor (#2244)

Bugs

• Nested target properties uses same method for different mappings after upgrade from 1.3.1.Final to 1.4.1.Final (#2236)
• MapStruct 1.3.0.Final version is generating wrong code for optional collection getter fields (#2233)
• Problems with Optional<T> mapping (#2295)
• Nested source null check calls method twice instead of using intermediate variable (#2245)
• Mapper create invalid implementation - variable is already defined in method (#2251)
• Stack Trace instead of Message on Missing Mapping (#2263)
• Wrong reporting for unmapped source properties when source source is implicitly mapped (#2253)
• Getting either "Unknown property" or "Unmapped target property" (#2301)
• @InheritInverseConfiguration and @Mapping(target:"bean.childProperty", ignore=true) do not play together (#2278)
• Mappings are ignored when @InheritConfiguration defines a mapping for a sub-field (#2318)

Documentation

• Vague documentation and code samples of @Default annotation as of 1.4.X (#2258)
• Example uses wrong maven plugin configuration (#2307)
• Typo in @MapperConfig annotation in documentation (#2293)

1.4.1.Final

Bugs

• @InheritConfiguration is broken when using multiple source parameters of the same type (#2221)
• @Mapping with defaultValue and method argument where is missing source does nothing (#2220)
• NPE when running MapStruct from IntelliJ 2020.3 EAP (#2215) - 1.4.1.Final is the first MapStruct version that supports the new improved IntelliJ experience for annotation processor compiling. In order to avoid the NPE in older MapStruct releases you'll have to build your project with -Djps.track.ap.dependencies=false. More info about this is in IDEA-250718
• @Mapping needs to define source parameter with defaultValue if you have two arguments in 1.4.0.Final (#2214)
• Mapping with qualifying and only target defined should implicitly look for a matching property in one of the parameters (#2206)
• Deep cloning creates intermediate methods for primitive arrays (#2213)

1.4.0.Final

For full upgrade instructions please read the release notes for the previous 1.4 releases:

• 1.4.0.Beta1
• 1.4.0.Beta2
• 1.4.0.Beta3
• 1.4.0.CR1

Bugs

• Possible regression: Wrong mapper code generation when using Builder (#2195)
• Qualifier is ignored in case of name based mapping when there are multiple source parameters (#2125)
• Invalid code generated for enum mapping when field name starts with underscore '_' and continues with digits (#2197)

1.4.0.CR1

Features

• Support custom unexpected enum constant exception for Value (Enum) Mapping (#2169)

Enhancements

• Use short names instead of FQN's in error messages (PR #2166)
• Redundant exception wrapping in nested generated method (#2174)
• StackOverflow caused by recursive uses declaration (#2185) - There is now a compile warning instead of a stack overflow error

Bug fixes

• Missing import in generated mapping class when using generic mapper interface (#2170)
• Mapping to generic class via constructor does not work (#2177)
• Parameter no longer recognised in 1.4 when not explicitly mentioned (#2164)

Documentation

• Add @since 1.4 to new interfaces (#2167)
• Fix typos

1.4.0.Beta3

Enhancements

• Improve the error message when using @Qualifier in 2 step mapping methods (#2135)
• Strip leading underscore when in local variable names (#2142)
• Allow @Default to overrule potentially existing parameterless default constructor. (#2150) - With this we actually changed the rules for selection a constructor. Now the following is done:
  • Constructor annotated with @Default (from any package) has highest precedence
  • If there is a single public constructor then it would be used to construct the object
  • If a parameterless constructor exists then it would be used to construct the object, and the other constructors will be ignored
• Improve ambiguous method error description (#2156)

Bug fixes

• NullPointerException when using only Mapping#target in mapping inheritance (#2139)
• Selection JAXB object factory has been compromised between 1.3.1.Final and 1.4.0Beta2 (#2145)
• Internal error in the mapping processor: java.lang.ArrayIndexOutOfBoundsException: 0 (#2149) - This was caused by using @BeanMapping(ignoreByDefault = true) in combination with @Mapping(target = "."). This is now not allowed

1.4.0.Beta2

Enhancements

• Improve the error message when using @Qualifier in 2 step mapping methods (#2135)
• Improve performance for 2 step mappings (#2136)

Bug fixes

• Can't override @MappingConfig inherited reverse mapping (#1844)
• Nested constants do not work when the same type is concerned (#2101)
• Mapping a value wrapped in a list generates invalid code (stringToXmlGregorianCalender will be added) (#2122)
• Regression: @BeanMapping#resultType does not work with nested mappings (#2133)
• Error: java: variable name might not have been initialized when nullValueCheckStrategy set to ALWAYS and using constructor for instantiating mapping target (#2131)
• Cannot map enum argument to target enum property with same type (#2117)
• Enum to String mapping generated code cause build failure (#2121)
• Variable not initialized in generated mapper in case of constructor mapping and mapper function (#2124)
• Assignment for array field is not generated properly (#2109)

1.4.0.Beta1

Features

• Make use of constructor arguments when instantiating mapping targets (#73) - Also supports Java 14 records and Kotlin Data classes
• Support using "." for targeting current target object (#1406)
• Support value mapping between String and Enum (#1557)
• Support @Mapping in meta annotation (#807)
• Support Gradle incremental annotation processing feature (#1420)
• User control over mapping features (direct, method, conversion, 2step) (#695)
• Support mapping from/to Java 14 records (preview feature) (#2014)
• Add EnumTransformationStrategy and EnumNamingStrategy SPIs (#796, #1220, #1789, #1667 and PRs: #2089, #2100)

See release announcement for more information.

Enhancements

• Add "verbose" processor option to print out details if required (#37) - Can be activated by using the compiler argument mapstruct.verbose=true
• Qualifiers work dubiously in 2 step mappings (#1714) - See Behaviour changes
• Skip java.lang.Object as intermediate result in 2 step mappings (#1698)
• Add imports to @MapperConfig (#1435)
• Annotation processor option for default injection strategy (#1792)
• Inconsistency in support of containers (enum vs non enum type) (#1788) - Allow mapping between enum and non enum in the same way as mapping between primitive and objects
• Strange error message when mapping with adder update method (#1719)
• Support for conversion between java.time.LocalDateTime and javax.xml.datatype.XMLGregorianCalendar (#1791)
• Do not allow using qualifiedBy and qualifiedByName with expression in Mapping (#1851) - This never worked, with this change we are adding a compile error if you try to use it.

Bug fixes

• @BeanMapping(ignoreByDefault=true) in @MapperConfig not passed to mapping method (#1933)
• unmappedSourcePolicy set to ERROR leads to a nested Bean issue (#1881)
• <ANY_REMAING> and <ANY_UNMAPPED> not ignored when inverting Value mapping (#1936)
• defaultExpression not being applied when source property not specified explicitly (#1966)
• Error mapping processor from Set to Array of Object (#2001)
• Wrong decorator class name used when Decorator class is nested inside mapper interface (#2021)
• MapStruct should work properly on the module path (#2060)
• "uses" entries ignored when used class is generated during annotation processing (#2056)
• Problems with compiling in Eclipse with the Lombok javaagent (#1159)
• NullPointer when accidentally using String source (#2077)

Documentation

• Split reference guide source into an adoc file per chapter (#991)
• Documentation Update: jsr330/@DecoratedWith (#1773)
• Add code-examples to Javadoc of org.mapstruct.* annotations (#166)
• @InheritInverseConfiguration doesn't pickup ignore mapping (#1983)
• Various typo fixes

Build

• Replace hickory:prism with the new MapStruct Tools Gem (#2011)
• NullPointerException when building on OpenJDK 11 (#1675)
• Move CI from Travis to GitHub Actions (#2019)
• Update Checkstyle to 8.29 (#2016)
• Switch to JUnit Jupiter and do not use Toolchains for the integration tests (#1308 and PR #2013)
• Update tycho-compiler-jdt to 1.6.0 version (#1553)
• Remove plexus-container-default dependency (#1857)

Codebase Enhancements

• Refactor SourceReference (#1745)
• Refactor: make sure that init of Mapping happens inside bean mapping scope (#1845)
• Refactor the creation of ForgedMethod into a builder or static method creation (#1088)
• model.source should reflect source only and not (intermediate) creation state (#1867)
• Refactoring of BeanMapping and Source/TargetReferences (common base class) (PR #1903)
• Simplify usage of inheritance of annotation fields in @MapperConfig, @Mapper, @BeanMapping, @Mapping, @IterableMapping and @MapMapping (#1998)
• Various codebase changes by using more Java 8 features
• Various codebase warning fixes (PRs: #1858, #1859, #1860, #1861, #1863, #1865, #1866, #1869, #1870, #1871, #1872)
• Remove JaxbMapper from integration tests (#724) - Not needed anymore, since MapStruct can work without it. No changes for users
• Remove not used method "asCollectionOrMap" from TypeFactory (#1883)
• Remove unused methods from class SourceMethod (#1897)
• Refactor class org.mapstruct.ap.internal.util.Filters (#1895)
• Remove unused parameters from classes TargetTypeSelector, ValueMapping, MethodRetrievalProcessor (#1889)
• Refactoring class Type (#1914)
• Change return type MapperConfiguration.getBuilderPrism from Optional<BuilderPrism> to BuilderPrism (#1911)
• Remove unused constants in JavaStreamConstants (#1944)
• Fix minor warnings with collection in package model and util (#1948)
• Simplify conditions in some classes (#1946)
• Use Map.computeIfAbsent in NestedTargetPropertyMappingHolder (#1951)
• Fix TODO items in integration tests (#1953)
• Add test case with properties with underscore verifying that it is working as expected (#2018)
• TargetReference refactorings (#2069)

Behavior

Qualifiers should not qualify when no qualifier is found

Before when doing 2 step mappings MapStruct was forgetting the qualifiers and could select methods with other qualifiers. This is unexpected and has been changed so that qualifiers are always used.

See Issue #1714 and PR #1739 for more information.

Removed Deprecated Enum mapping

Before this release it was possible to use @Mapping for mapping enums. This is no longer possible and @ValueMapping should be used before. There was a warning before, so if you don't have that in your build then you don't need to do anything.

Contributors

We'd like to thank all the contributors who worked on this release!

• @Zomzog
• @xcorail
• @juliojgd
• @power721
• @mattdrees
• @jakraska
• @dekelpilli
• @ttzn
• @fml2
• @marceloverdijk
• @vegemite4me
• @timjb
• @sullis
• @pradzins
• @seime

1.3.1.Final

Enhancements

• @AfterMapping methods with non unique parameters (#1457) - Stricter matching for lifecycle methods / non-unique parameters
  In case a lifecycle method has multiple matching parameters (e. g. same type)
  all parameter names must match exactly with the ones from the mapping method,
  otherwise the lifecycle method will not be used and a warning will be shown.
• Ability to disable builders on method level via Builder#disableBuilder (#1661)
• Vague message when handling nested property mapping (#1756)

Bug fixes

• MapStruct producing uncompilable code when using bounded wildcard (#1738)
• Bug with Nested Properties and ReportingPolicy.ERROR on Unmapped Source Properties (#1772)
• Make MapStruct generate compilable mapping code for attributes of type EnumSet (#1797)
• StackOverflowError in DefaultBuilderProvider` when a type has a public static generic method that returns the type (#1751)
• Null pointer exception in nested property mapping method with presence check (#1826)
• 1.3.0.Final Regression in nullValuePropertyMappingStrategy when inherited (#1790)
• Some Mappers using @Context not yielding Impl classes in Java11 (#1904)
• Fluent setters on fields with names starting with set are not working #1799
• MapStruct 1.3.0.Final produces uncompilable code when using Java 11 + Lombok 1.18.6 (#1742)
• Using constructor as builderCreationMethod in custom builder provider causes NullPointerException (#1801)
• MapStruct 1.3.0.Final generates invalid implementation when nested property of target is populated with multiple nested properties of source (#1828)
• Nullptr in 1.3.0.Final due to result type definition (#1821)

Documentation

• Clarify use of clearing collections in case of update methods (#1142)
• Fix typo in documentation (PR #1760)
• Fix typo and code error in documentation (PR #1779)
• Wrong documentation in relation to NullValueMappingStrategy.RETURN_DEFAULT (#1784)
• Documentation clarification on obtaining Mapper (#1819)
• Improve terms in qualifier docs (PR #1814)
• Update @MappingTarget documentation to take builders (#1862)

1.3.0.Final

This contains only changes between 1.3.0.Beta2 and 1.3.0.Final. To read the changes from the betas go to 1.3.0.Beta1 and 1.3.0.Beta2

Enhancements

• Improvement: builder for Mapper/Decorator/GeneratedType (PR #1649)
• Builtin mapping of String <-> Duration/Period/Instant (#1656)
• Add Mappers.getMapperClass for getting the class of a Mapper (#1657)
• Defaults for `NullValuePropertyMapping#SET_TO_DEFAULT (boxed types, Strings and primitives) (#1699)
• Optimising code (local variables) for CollectionMappingStrategy#ADDER_PREFERRED
• NullValuePropertyMapping strategy not implemented fully (#1685)
• Consider sensible defaults for NullValuePropertyMappingStrategy.SET_TO_DEFAULT (#1699)
• Optimise AdderWrapper / StreamAdderWrapper to use local variable (#1700)

Bug fixes

• unmappedSourcePolicy may lead to false positives (#1648)
• Static factory method incorrectly recognised as a fluent setter (#1660) - With the fix for this a method is only considered a candidate if it is public not static
• Adder with primitive type not being used (#1665)
• Nested mapping & MappingTarget - "cannot find symbol" (#1650)
• NullValuePropertyMappingStrategy was not implemented completely (#1685)
• Non-void update methods try calling build() on the @MappingTarget when a Builder is available (#1681)
• Uncompilable code is generated when mapping Stream to List and using @AfterMapping on result (#1707)

Documentation

• Use Repeatable Mapping annotation in the reference documentation (#1645)
• Update gradle installation guide (#1695)

Build

1.3.0.Beta2

IMPORTANT: Starting from this version MapStruct uses Java 8 as a baseline (#1301)

Features

• Apply source presence tracking recursively (#1456)

Enhancements

• Avoid using java.beans.Introspector (#1524)
• Cache javax.xml.datatype.DatatypeFactory (#1532)
• Rename isBuilderSetter in isFluentSetter in the DefaultAccessorNamingStrategy (#1578) - NB: The isBuilderSetter was added in 1.3.0.Beta1
• Add support for "adders" in combination with java.util.stream.Stream (#1561)
• Allow nullValueCheckStrategy on @BeanMapping (#1571)
• Support for conversion between java.time.Instant and java.util.Date (#1595)
• Use javax.annotation.processing.Generated if available (#1551)
• Map java.sql.Date to a java.time.LocalDate (#1591)
• When source is null target should NOT be set to null (#1306) - Added new NullValuePropertyMappingStrategy . See PR #1618 and Behavior for more information
• Adder wrapper should use singular from the source for the Iterable element (#1478)
• Emit warnings for precision loss (#5)
• Introduce mechanism to report error from MappingResolver (#1458)
• Access to Types and Elements in AccessorNamingStrategy (#1253) - The AccessorNamingStrategy has been extended with a default init method that allows for initialising it with the Elements and Types utils through the MapStructProcessingEnvironment
• Use MapStructProcessingEnvironment for initialising the BuilderProvider (#1640) - The BuilderProvider has been extended with the same init functionality as the AccessorNamingStrategy
• Property error logging on @Mapping annotation (#1504)
• FQN of LocalDateTime is used when a simple name is possible (#1576) - With this issue we have also optimised the way we store the required imports (see PR #1642 for more information)

Bug fixes

• NPE when using varargs in mapping method (#1541)
• ZoneOffset not fully qualified (#1569)
• Exception when processing mapping from constants/expressions to inner fields with multi-arg mapping (#1552)
• [Compilation Error] class java.util.ArrayList not found. MappersImpl cannot be compiled. (#1590)
• Generated code fails to build when the source type is a byte array annotated with @NotNull (#1558) - Fixes a generic problem for all usages of annotations with ElementType.TYPE_VAR
• Missing imports for Immutables (#1596)
• Fluent setters starting with is are not correctly handled (#1608)
• Similar with #1148 (Nested target properties uses same method for different mappings) (#1594)
• Setters on a Builder super class are not called (#1566) - As part of this a new custom AccessorNamingStrategy has been added for FreeBuilder (see 104ebf8 for more information)

Documentation

• Adding an issue template. PR #1616

Build

• Add Integration tests with Protobuf (#1499)
• Inherit configuration for sub classes using @InheritConfiguration (#1593) - Add tests to show it is working
• Fix wrong line number in JDK for @Repeatable Mappings (#1633) - There is a bug in the javac compiler that does not report the diagnostics on the correct place. See JDK-8042710 and #1628 for tracking it on our side

Behavior

Nested source presence tracking

With #1456 MapStruct now uses nested source presence tracking for nested objects. If the first property has a presence check method then a presence check would be checked recursively. See the issue description for what has changed.

Handling null or missing source properties

With #1306 MapStruct now has a NullValuePropertyMappingStrategy that can be used to control how null or not present source properties are updated within a target. The possibilities are:

• SET_TO_NULL - If the source property is null or not present the target property is set to null. This is also the default, which is the same behaviour from before.
• SET_TO_DEFAULT - If the source property is null or not present the target property is set to default (empty list, empty set, new object instantiation etc)
• IGNORE - If the source property is null or not present the target property is not set at all

NB: During this we noticed that we handle differently collections / maps for normal mapping methods (i.e. we were setting those to null if the source property was null or not present). This is now changed and collections / maps won't be set if the source property is null or not present. In such case one needs to use @ObjectFactory or set the default in the constructor of the target object

NB2: In 1.2.0.Final with #1273 we added support for using NullValueMappingStrategy#RETURN_DEFAULT to control how collections / maps default values are set. We realized that this was a mistake on our side and now one should use NullValuePropertyMappingStrategy#SET_TO_DEFAULT.

See this for more information as well

BuilderProvider

The BuilderProvider interface has been changed from 1.3.0.Beta1. Now it has an init method that can be used to get access to the Elements and Types utils and the findBuilderInfo method only gets the TypeMirror