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

• See information in the releases for more information.

• 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.

• No migration concerns compared to 1.1.0.CR2.

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.

• No migration concerns

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

• No migration concerns

• No migration concerns

• No migration concerns

• 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