Migration notes

Toni Fadjukoff edited this page Jan 10, 2017 · 16 revisions
Clone this wiki locally

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


  • 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