Migration notes

This page lists breaking changes (either API or behavioral changes) in MapStruct releases.

Starting from 1.2.0.Beta3. All the migration notes can be found at releases

1.2.0.Beta3

MapStruct now uses the unmappedTargetPolicy when generating matching methods (see #1104).
MapStruct now inherits @InheritInverseConfiguration from config prototype methods (see #1065).

MapStruct from now on starts to generate methods when property names match between source and target and there is no matching method available. This was already done for Map - and Iterable mapping methods. Prior to this release, one had to define an mapping method or to have a qualifying method in one of the mappers in the 'uses' field in @Mapper. MapStruct will generate an error when its not able to do so.
The generated code for nested target mappings has been altered in relation to issue #1011.

There are two behavioural changes regarding the handling of null values:

Nested mappings that refer to a primitive type source property and map to a target property that inherits from java.lang.Object will be mapped to null if one of the parent beans of the source property is null.

Example: @Mapping( target = "targetObjectProperty", source = "sourceObjectProperty.primitiveProperty" ) sets targetObjectProperty to null if sourceObjectProperty == null.

More info: issue #931.
There were once two null checks on the source property in generated java.lang.Collection to java.lang.Collection mappings. The sequence was as such in pseudo code: null-check-outer-source-property { null-check-target-propety { null-check-inner-source-propety { mapping } } } The null-check-outer-source-property is removed, since it can be controlled with the null-check-inner-source-propety. Please note: null-check-inner-source-propety is either the same as null-check-outer-source-property when mapped direct or the result of a mapping method. In the latter case, the result of the mapping method can be controlled by the user.

The method getCollectionGetterName in the SPI AccessorNamingStrategy has been deprecated and won't be called by MapStruct anymore. See the reference documentation for more information about the SPI.

Usage of @Mapping for enum mappings is deprecated and leads to a warning message. Please switch to the new annotation @ValueMapping in those cases.

The annotation @NullValueMapping was removed. For method-level configuration of the NullValueMappingStrategy, the attribute nullValueMappingStrategy was added to @BeanMapping, @IterableMapping and @MapMapping - this is now in alignment with the class level annotations @Mapper and @MapperConfig.

Reverse mapping methods must explicitly be tagged as such via @InheritInverseConfiguration
The attribute @Mapping#target() is mandatory now; It was possible to specify ignore() and dateFormat() with source() rather than target() (assuming both are the same), for consistency reasons now always the target of a mapping has to be specified
The processor options are prefixed with "mapstruct." now; I.e. mapstruct.suppressGeneratorTimestamp, , mapstruct.defaultComponentModel and mapstruct.unmappedTargetPolicy are to be used now rather than suppressGeneratorTimestamp, unmappedTargetPolicy and defaultComponentModel