org.mapstruct:mapstruct

Features

• Add support for JSpecify nullness annotations (#1243) - MapStruct now detects @NonNull, @Nullable, @NullMarked and @NullUnmarked from org.jspecify.annotations to control null check generation:
  • Source @NonNull skips null checks; target @NonNull always adds them
  • @NonNull source parameters skip the method-level null guard
  • @NonNull source on collection-typed property mappings skips the wrapping null guard
  • Container mapping methods (Iterable, Map, Stream, arrays) honor JSpecify on their source parameter
  • @NonNull mapping-method return type implies NullValueMappingStrategy.RETURN_DEFAULT semantics across bean, iterable, map and stream mapping methods
  • @NullMarked / @NullUnmarked scope is resolved by walking method → class → outer class → package
  • Compile error when mapping a potentially nullable source to a @NonNull constructor parameter without a defaultValue
  • Can be disabled with the mapstruct.disableJSpecify compiler option
• Add URI to String built-in conversions (#4018)
• Add ClassAccessibility enum to control the declared accessibility of generated mappers (#2513)

Enhancements

• Support SET_TO_NULL for overloaded target methods, requiring a cast (#3949)
• Use switch expressions in generated code when targeting JDK 14 or later (#4062)
• Make URLToStringConversion generate URI.create(String).toURL() instead of the deprecated new URL(String) (#4041)
• Report a compilation error for SET_TO_DEFAULT when the target has no accessible no-args constructor (#4060)
• Use multi-catch in generated code (#4021)
• Use diamond operator for new expressions in generated code (#4045)
• Always use factory methods for LinkedHashMap and LinkedHashSet when targeting SequencedSet and SequencedMap (#3990)
• Improve annotation processing performance by removing regex matching from Type.describe() (#3991)
• Add support for generics in arrays (#4050)

Bugs

• Prevent mapper generation from a type with a generic super bound to a type with a generic extends bound (#3994)
• Fix location for Javadoc when generating the distribution zip
• Fix Optional target not using the static builder factory method (#4046)
• Match generic types of a declared type exactly to prevent incorrect mappings and infinite resolution loops (#3948)
• Fix mapping ZonedDateTime or OffsetDateTime to LocalDateTime or Instant (#4027)

Documentation

• Add SECURITY.md and .github/INCIDENT_RESPONSE.md

Build

• Test on JDK 25 and 26, drop integration test on JDK 11 (#4039)
• Specify OpenJDK 21 for the Jitpack build (#4042)
• Add CodeQL custom workflow and set build mode for java-kotlin to none
• Use diamond operator in test code (#4048)
• Upgrade integration tests to JUnit 5 (#4023)
• Update Maven compiler plugin (#3972)
• Upgrade Freemarker to 2.3.34
• Update license plugin
• Enforce import order via Checkstyle CustomImportOrder (#4024)
• Enforce spaces inside parentheses for control flow statements via Checkstyle
• Simplify fail in assertCheckstyleRules
• Remove deprecated Number API usage from tests
• Use StandardCharsets.UTF_8 in tests
• Remove obsolete override of AssertJ version in integration tests
• Let GitHub determine whether or not the released version is the latest
• Simplify parallel-capable registration in ModifiableURLClassLoader test util (#4052)
• Improve class loading for tests by replacing LauncherDiscoveryListener with CompilerLauncherInterceptor (#4051)
• Enforce ParenPad for ENUM_CONSTANT_DEF via Checkstyle (#4075)
• Upgrade codecov-action to v7 (#4067)
• Improve JavaFileAssert#hasSameMapperContent to include file information in the diff (#4063)

Internal

• Upgrade internal Visitor6 usages to Visitor8
• Refactor TypeFactory.getTypeParameters (#4020)
• Simplify boolean logic in ValueMappingMethod by removing inversion (#4007)
• Remove unnecessary keySet() invocation (#3989)
• Remove unused methods in Fields (#4010)
• Add missing self reference in GeneratedTypeBuilder (#4009)
• Fix self check in equals of Type (#3995)
• Remove reflection from isDefaultMethod (#4053)

Features

• Support for Java 21 Sequenced Collections (#3240)
• Native support for java.util.Optional mapping (#674) - MapStruct now fully supports Optional as both source and target types:
  • Optional to Optional - Both source and target wrapped in Optional
  • Optional to Non-Optional - Unwrapping Optional values
  • Non-Optional to Optional - Wrapping values in Optional
  • Optional properties in beans with automatic presence checks. Note, there is no null check done for Optional properties.
• Improved support for Kotlin. Requires use of org.jetbrains.kotlin:kotlin-metadata-jvm.
  • Data Classes (#2281, #2577, #3031) - MapStruct now properly handles:
    • Single field data classes
    • Proper primary constructor detection
      • Data classes with multiple constructors
      • Data classes with all default parameters
  • Sealed Classes (#3404) - Subclass exhaustiveness is now checked for Kotlin sealed classes
• Add support for ignoring multiple target properties at once (#3838) - Using new annotation @Ignored

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.
• Add support for custom exception for subclass exhaustive strategy for @SubclassMapping mapping (#3821) - Available on @BeanMapping, @Mapper and @MappingConfig.
• Add new NullValuePropertyMappingStrategy#CLEAR for clearing Collection and Map properties when updating a bean (#1830)
• Use deterministic order for supporting fields and methods (#3940)
• Support @AnnotatedWith on decorators (#3659)
• Behaviour change: Add warning/error for redundant ignoreUnmappedSourceProperties entries (#3906)
• Behaviour change: Warning when the target has no target properties (#1140)
• Behaviour change: Initialize Optional with Optional.empty instead of null (#3852)
• Behaviour change: Mark String to Number as lossy conversion (#3848)

Bugs

• Improve error message when mapping non-iterable to array (#3786)
• Fix conditional mapping with @TargetPropertyName failing for nested update mappings (#3809)
• Resolve duplicate invocation of overloaded lifecycle methods with inheritance (#3849) - It is possible to disable this by using the new compiler option mapstruct.disableLifecycleOverloadDeduplicateSelector.
• Support generic @Context (#3711)
• Properly apply NullValuePropertyMappingStrategy.IGNORE for collections / maps without setters (#3806)
• Properly recognize the type of public generic fields (#3807)
• Fix method in Record is treated as a fluent setter (#3886)
• Ensure NullValuePropertyMappingStrategy.SET_TO_DEFAULT initializes empty collection/map when target is null (#3884)
• Fix Compiler error when mapping an object named Override (#3905)

Documentation

• General Improvements
  • Javadoc
  • Typos in comments
  • Small code refactorings

Build

• Move Windows and MacOS builds outside of the main workflow
• Update release to release using the new Maven Central Portal
• Skip codecov coverage on forks
• Improve testing support for Kotlin

Behaviour Change

Warning when the target has no target properties (#1140)

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.

Warning for redundant ignoreUnmappedSourceProperties entries (#3906)

With this change, if the ignoreUnmappedSourceProperties configuration contains properties that are actually mapped, a warning or compiler error will be shown.
The unmappedSourcePolicy is used to determine whether a warning, or an error is shown.

Initialize Optional with Optional.empty instead of null (#3852)

With this change, if the target Optional property is null, it will be initialized with Optional.empty() instead of null.

Mark String to Number as lossy conversion (#3848)

With this change, if the source String property is mapped to a Number property, a warning will be shown.
This is similar to what is happening when mapping long to int, etc.
The typeConversionPolicy ReportingPolicy is used to determine whether a warning, error or ignore is shown.

Bugs

• Redundant if condition in Java record mapping with RETURN_DEFAULT strategy (#3747)
• Stackoverflow with Immutables custom builder (#3370)
• Unused import of java.time.LocalDate when mapping source LocalDateTime to target LocalDate (#3732)

Documentation

• Add section to README.md comparing mapstruct with Java Records (#3751)

Bugs

• Regression from 1.6.1: ClassCastException when using records (#3717)

Enhancements

• Use Java LinkedHashSet and LinkedHashMap new factory method with known capacity when on Java 19 or later (#3113)

Bugs

• Inverse Inheritance Strategy not working for ignored mappings only with target (#3652)
• Inconsistent ambiguous mapping method error when using SubclassMapping: generic vs raw types (#3668)
• Fix regression when using InheritInverseConfiguration with nested target properties and reversing target = "." (#3670)
• Deep mapping with multiple mappings broken in 1.6.0 (#3667)
• Two different constants are ignored in 1.6.0 (#3673)
• Inconsistent ambiguous mapping method error: generic vs raw types in 1.6.0 (#3668)
• Fix cross module records with interfaces not recognizing accessors (#3661)
• @AfterMapping methods are called twice when using target with builder (#3678)
• Compile error when using @AfterMapping method with Builder and TargetObject (#3703)

Behaviour change

Inverse Inheritance Strategy not working for ignored mappings only with target

Prior to this fix @Mapping(target = "myProperty", ignore = true) was being ignored when using @InheritInverseConfiguration.

e.g.

@Mapper
public interface ModelMapper {

    @Mapping(target = "creationDate", ignore = true)
    Entity toEntity(Model model);    

    @InheritInverseConfiguration
    Model toModel(Entity entity);
}

In the example above prior 1.6.1 the Model toModel(Entity entity) was going to map the id property. In order to keep that behavior you'll need to explicitly do the mapping for it.

@Mapper
public interface ModelMappe {
    @Mapping(target = "creationDate", ignore = true) // NOTE: Handled by JPA.
    Entity toEntity(Model model);    

    @InheritInverseConfiguration
    @Mapping(target = "creationDate", source = "creationDate") // Allow reading from Entity
    Model toModel(Entity entity);
}

Previous Release Notes

• 1.6.0.RC1
• 1.6.0.Beta2
• 1.6.0.Beta1

Enhancements

• Breaking change: (#3574) -
  This reverts #2560, because we've decided that @BeanMapping(ignoreByDefault = true) should only be applied to target properties and not to source properties.
  Source properties are ignored anyway, the BeanMapping#unmappedSourcePolicy should be used to control what should happen with unmapped source policy

Bugs

• Breaking change: Presence check method used only once when multiple source parameters are provided (#3601)
• Fix @SubclassMapping not working with @BeanMapping#ignoreUnmappedSourceProperties (#3609)
• Fix duplicate method generation with recursive auto mapping (#3591)

Documentation

• Fix documentation of unmappedSourcePolicy default value (#3635)
• Fix documentation link of before and after mapping when using builders (#3639)
• Fix typo in experimental note (#3634)
• Add example classes for the passing target type documentation (#3504)

Build

• Enforce whitespaces around the for colon with CheckStyle (#3642)

Breaking changes

Presence checks for source parameters

In 1.6, support for presence checks on source parameters has been added.
This means that even if you want to map a source parameter directly to some target property the new @SourceParameterCondition or @Condition(appliesTo = ConditionStrategy.SOURCE_PARAMETERS) should be used.

e.g.

If we had the following in 1.5:

@Mapper
public interface OrderMapper {

    @Mapping(source = "dto", target = "customer", conditionQualifiedByName = "mapCustomerFromOrder")
    Order map(OrderDTO dto);

    @Condition
    @Named("mapCustomerFromOrder")
    default boolean mapCustomerFromOrder(OrderDTO dto) {
        return dto != null && dto.getCustomerName() != null;
    }

}

Then MapStruct would generate

public class OrderMapperImpl implements OrderMapper {

    @Override
    public Order map(OrderDTO dto) {
        if ( dto == null ) {
            return null;
        }

        Order order = new Order();

        if ( mapCustomerFromOrder( dto ) ) {
            order.setCustomer( orderDtoToCustomer( orderDTO ) );
        }

        return order;
    }
}

In order for the same to be generated in 1.6, the mapper needs to look like this:

@Mapper
public interface OrderMapper {

    @Mapping(source = "dto", target = "customer", conditionQualifiedByName = "mapCustomerFromOrder")
    Order map(OrderDTO dto);

    @SourceParameterCondition
    @Named("mapCustomerFromOrder")
    default boolean mapCustomerFromOrder(OrderDTO dto) {
        return dto != null && dto.getCustomerName() != null;
    }

}

Features

• Support conditional mapping for source parameters (#2610, #3459, #3270)
• Add @SourcePropertyName to handle a property name of the source object (#3323) - Currently only applicable for @Condition methods

Enhancements

• Improve error message for mapping to target = "." using expression (#3485)
• Improve error messages for auto generated mappings (#2788)
• Remove unnecessary casts to long (#3400)

Bugs

• @Condition cannot be used only with @Context parameters (#3561)
• @Condition treated as ambiguous mapping for methods returning Boolean/boolean (#3565)
• Subclass mapping warns about unmapped property that is mapped in referenced mapper (#3360)
• Interface inherited build method is not found (#3463)
• Bean with getter returning Stream is treating the Stream as an alternative setter (#3462)
• Using Mapping#expression and Mapping#conditionalQualifiedBy(Name) should lead to compile error (#3413)
• Defined mappings for subclass mappings with runtime exception subclass exhaustive strategy not working if result type is abstract class (#3331)

Documentation

• Clarify that Mapping#ignoreByDefault is inherited in nested mappings in documentation (#3577)

Build

• Improve tests to show that Lombok @SuperBuilder is supported (#3524)
• Add Java 21 CI matrix build (#3473)

Features

• Access to target property name (#2688) - @TargetPropertyName can be used to access the target property name to conditional and mapping methods
• Support passing annotations to generated code (#1574, #2773, #2895, #2983) - Using @AnnotateWith. If a method is annotated with @Deprecated it is automatically copied into the generated code.
• Support for globally defining nullValueIterableMappingStrategy and nullValueMapMappingStrategy (#2953) - The different strategies can be configured using mapstruct.nullValueIterableMappingStrategy and mapstruct.nullValueMapMappingStrategy respectively
• Support qualifiers for SubclassMapping annotated methods (#3119)
• Support defining custom processor options for custom SPI (#3071) - There is also AdditionalSupportedOptionsProvider that can be used to defined the supported options for a custom SPI. The additional options cannot start with mapstruct.
• Support for defining Javadoc on the generated mapper (#2987) - Using @Javadoc

Enhancements

• Support for converting between Enum and Integer (#2963)
• Support for converting between Locale and String (#3172)
• Support for implicit conversion between java.time.LocalDate and java.time.LocalDateTime (#3199)
• Support custom name in Spring annotations (#1427) - Can be done using @AnnotateWith(value = Service.class, elements = @AnnotateWith.Element(strings = "cakeMapperV2"))
• Support meta annotations for @ValueMapping (#3037)
• Ambiguous mapping method but there is a more specific mapping (#1216)
• Do not treat getter as an alternative write accessor when using CollectionMappingStrategy#TARGET_IMMUTABLE (#2952)
• Improve line location report for invalid qualifier for SubclassMapping (#3202)
• Support @InheritConfiguration for @SubclassMapping in methods with identical signature (#3125)
• Do not require subclassExhaustiveStrategy when source is a sealed class and all subtypes are specified (#3054)
• Add validation of String type for @TargetPropertyName (#2863)
• Support for all lifecycle methods on type being build with builders (#1454)
  • @BeforeMapping with @TargetType the type being build
  • @AfterMapping with @TargetType the type being build
  • @AfterMapping with @MappingTarget the type being build
• Redundant null checks for nested properties (#3245)
• @Default on Java Record's constructor isn't respected (#3231)
• Add InjectionStrategy.SETTER (#3229)
• Add BeanMapping#unmappedSourcePolicy (#3309)
• Improve support for Map attributes for immutables (#3089)
• Support mapping Iterable to Collection (#3376)

Bugs

• Breaking change: Mapping from Map to Bean (#3144)
• Condition with @TargetType on Collection fails to compile (#2901)
• Annotations are automatically passed in forged methods (#3015)
• Mapping Composition does not work for @SubclassMapping (#3174)
• Mapping control disabling conversions does not disable them in 2 step mappings (#3186)
• @BeanMapping(ignoreByDefault = true) does not work for constructor properties (#3158)
• @ValueMapping strips spaces from source (#3153)
• defaultExpression does not work when mapping a collection of custom types (#3159)
• Arrays cannot be mapped to collection / iterable using an adder method (#3165)
• Unmapped source properties error when source is mapped to a nested field of the target object (#2781)
• NullPointerException when ignoring target '.' (#3238) - There is now a compilation error instead of an error in the processor
• NullValuePropertyMappingStrategy.IGNORE does not ignore target collection even when source one is null (only when collectionMappingStrategy = CollectionMappingStrategy.TARGET_IMMUTABLE) (#3104)
• @SubclassMapping not working with @Mapping nested properties and target all (#3126)
• Compile error when using default and static methods in @MapperConfig (#3296)
• Generic class with adder method and CollectionMappingStrategy.ADDER_PREFERRED fails (#3310)
• MapStruct can not map only primitives (#3317)
• 2-step mapping with generics does not work correctly (#2663)
• MapStruct no longer handles generic mapping methods (in conjunction with immutables) after upgrading from 1.4.x to version 1.5.x (#3163)
• Ignored mappings when using @InheritConfiguration (#3361)

Documentation

• Use GitHub new Issue Form Templates (#3008)
• Mapping composition is no longer experimental (#3239)
• Improve Lombok integration documentation (#3374)

Build / Refactoring

• Try to stabilise some date conversion tests (#2806)
• Avoid unnecessary unboxing of Boolean (#3003)
• Update FreeMarker to 2.3.32
• Refactor method selection and use a context to be able to more easily access information (#3280)
• Update tarLongFileMode to use POSIX (#3340)
• Simplified some expressions, redundant expressions removed (#3292)
• Refactor to use presence check for mapping methods (#3347) - Still only internal and custom presence checks methods are not supported for source parameters (see #2610 for that)
• Update github actions (#3397)
  • Add Java 21 to test matrix
  • Add Java EA to test matrix
  • Removing java 13 and 18 from test matrict

Breaking Changes

Map to Bean

In 1.5 we added support for mapping a map to a bean by implicitly mapping all the properties from the target bean by accessing them from the map. However, this lead to some problems in multi mapping methods. Therefore, in this release we tightened up a bit and in multi source mapping methods the Map will not be considered when doing implicit mappings.

e.g.

@Mapper
public interface CarMapper {

    // This method is going to implicitly map all the target properties from the map
    Target map(Map<String, Object> map);
    
    // This method is not going to use the map for implicit mappings.
    //  Only the name will be mapped from the map (since it has been defined like that
    @Mapping(target = "name", source = "map.name")
    Target map(Source source, Map<String, Object> map)

}

@BeanMapping inheritance

All, except resultType and ignoredUnmappedSourceProperties attributes of @BeanMapping have been made to consistently be passed down to the generated nested methods. This means that if you were relying on some buggy behavior it might no longer work.

e.g. BeanMapping#ignoreByDefault was not being passed down properly, i.e. implicit mapping was being done for nested properties. This has been fixed. If you want to implicitly map nested mappings then you'll have to define your own mapper appropriatelly.

@Mapper
interface MyMapper {
  @BeanMapping( ignoreByDefault = true )
  @Mapping( source = "sub", target = "target" )
  Target map( Source source );
}

needs to be replaced with

@Mapper
interface MyMapper {
  @BeanMapping( ignoreByDefault = true )
  @Mapping( source = "sub", target = "target" )
  Target map( Source source );
  
  // this is the mapping `source = "sub"` and `target = "target"` 
  // redefined to get rid of the `ignoreByDefault=true`, because this property is inherited
  SubTarget subSourceToSubTarget( SubSource subSource );
}

Sponsoring

After the request from the community we have enabled sponsoring for the project. See #2340 for how you can sponsor us if you want to.

Contributors

• @anton-erofeev
• @Blackbaud-JasonBodnar
• @Bragolgirith
• @chenzijia12300
• @eroznik
• @EvaristeGalois11
• @ivlcic
• @jccampanero
• @kooixh
• @MengxingYuan
• @MLNW
• @nikolas-charalambidis
• @paparadva
• @prasanth08
• @ro0sterjam
• @rgdoliveira
• @venkatesh2090