Support CollectionMappingStrategy on @Mapping

znight1020 · znight1020 · commit b6cb85b2d248 · 2025-09-21T20:33:27.000+09:00
Signed-off-by: Hyeonsoo Lee &lt;znight1020@naver.com&gt;
diff --git a/core/src/main/java/org/mapstruct/Mapping.java b/core/src/main/java/org/mapstruct/Mapping.java
@@ -490,6 +490,21 @@
     NullValuePropertyMappingStrategy nullValuePropertyMappingStrategy()
         default NullValuePropertyMappingStrategy.SET_TO_NULL;
 
+    /**
+     * The strategy to be applied when mapping a target {@code Collection} property.
+     *
+     * Can be overridden by the one on {@link MapperConfig}, {@link Mapper} or {@link BeanMapping}.
+     *
+     * If no strategy is configured, the strategy given via {@link MapperConfig#collectionMappingStrategy()},
+     * {@link BeanMapping#collectionMappingStrategy()} or {@link Mapper#collectionMappingStrategy()} will be applied.
+     *
+     * {@link CollectionMappingStrategy#ACCESSOR_ONLY} will be used by default.
+     *
+     * @since 1.7
+     * @return The collection mapping strategy to be applied for the designated target property
+     */
+    CollectionMappingStrategy collectionMappingStrategy() default CollectionMappingStrategy.ACCESSOR_ONLY;
+
     /**
      * Allows detailed control over the mapping process.
      *
diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/CollectionAssignmentBuilder.java b/processor/src/main/java/org/mapstruct/ap/internal/model/CollectionAssignmentBuilder.java
@@ -137,7 +137,7 @@ public CollectionAssignmentBuilder nullValuePropertyMappingStrategy( NullValuePr
     public Assignment build() {
         Assignment result = assignment;
 
-        CollectionMappingStrategyGem cms = method.getOptions().getBeanMapping().getCollectionMappingStrategy();
+        CollectionMappingStrategyGem cms = method.getOptions().getCollectionMappingStrategyFor( targetPropertyName );
         boolean targetImmutable = cms == CollectionMappingStrategyGem.TARGET_IMMUTABLE || targetReadAccessor == null;
 
         if ( targetAccessorType == AccessorType.SETTER || targetAccessorType.isFieldAssignment() ) {
diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/source/MappingMethodOptions.java b/processor/src/main/java/org/mapstruct/ap/internal/model/source/MappingMethodOptions.java
@@ -380,6 +380,17 @@ private String getFirstTargetPropertyName(MappingOptions mapping) {
         return getPropertyEntries( mapping )[0];
     }
 
+    public CollectionMappingStrategyGem getCollectionMappingStrategyFor(String targetProperty) {
+        if ( targetProperty != null && mappings != null ) {
+            for ( MappingOptions m : mappings ) {
+                if ( targetProperty.equals( m.getTargetName() ) && m.getCollectionMappingStrategy() != null ) {
+                    return CollectionMappingStrategyGem.valueOf( m.getCollectionMappingStrategy().name() );
+                }
+            }
+        }
+        return getBeanMapping().getCollectionMappingStrategy();
+    }
+
     /**
      * SubclassMappingOptions are not inherited to forged methods. They would result in an infinite loop if they were.
      *
diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/source/MappingOptions.java b/processor/src/main/java/org/mapstruct/ap/internal/model/source/MappingOptions.java
@@ -19,6 +19,7 @@
 import javax.lang.model.element.Element;
 import javax.lang.model.element.ExecutableElement;
 
+import org.mapstruct.ap.internal.gem.CollectionMappingStrategyGem;
 import org.mapstruct.ap.internal.gem.MappingGem;
 import org.mapstruct.ap.internal.gem.MappingsGem;
 import org.mapstruct.ap.internal.gem.NullValueCheckStrategyGem;
@@ -472,6 +473,16 @@ public NullValuePropertyMappingStrategyGem getNullValuePropertyMappingStrategy()
             .orElse( next().getNullValuePropertyMappingStrategy() );
     }
 
+    @Override
+    public CollectionMappingStrategyGem getCollectionMappingStrategy() {
+        return Optional.ofNullable( mapping )
+            .map( MappingGem::collectionMappingStrategy )
+            .filter( GemValue::hasValue )
+            .map( GemValue::getValue )
+            .map( CollectionMappingStrategyGem::valueOf )
+            .orElse( next().getCollectionMappingStrategy() );
+    }
+
     @Override
     public MappingControl getMappingControl(ElementUtils elementUtils) {
         return Optional.ofNullable( mapping ).map( MappingGem::mappingControl )
diff --git a/processor/src/test/java/org/mapstruct/ap/test/bugs/_3708/Issue3708TargetImmutableMapper.java b/processor/src/test/java/org/mapstruct/ap/test/bugs/_3708/Issue3708TargetImmutableMapper.java
@@ -16,12 +16,18 @@
 import org.mapstruct.factory.Mappers;
 
 /**
- * BeanMapping TARGET_IMMUTABLE
+ * Mapping, BeanMapping TARGET_IMMUTABLE
  */
 @Mapper
 public interface Issue3708TargetImmutableMapper {
     Issue3708TargetImmutableMapper INSTANCE = Mappers.getMapper( Issue3708TargetImmutableMapper.class );
 
+    @Mapping(target = "types",
+        nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE,
+        collectionMappingStrategy = CollectionMappingStrategy.TARGET_IMMUTABLE
+    )
+    void partialUpdateMapping(@MappingTarget Partner entity, PartnerDto dto);
+
     @BeanMapping(
         nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE,
         collectionMappingStrategy = CollectionMappingStrategy.TARGET_IMMUTABLE
diff --git a/processor/src/test/java/org/mapstruct/ap/test/bugs/_3708/Issue3708Test.java b/processor/src/test/java/org/mapstruct/ap/test/bugs/_3708/Issue3708Test.java
@@ -54,6 +54,18 @@ void beanMappingTargetImmutableShouldReplaceWhenUpdatesImmutableTarget() {
         assertThat( entity.getTypes() ).containsExactlyInAnyOrder( "B", "C" );
     }
 
+    @ProcessorTest
+    void mappingTargetImmutableShouldReplaceWhenUpdatesImmutableTarget() {
+        Partner entity = new Partner();
+        entity.setTypes( Set.of( "A" ) );
+        PartnerDto dto = new PartnerDto();
+        dto.setTypes( new LinkedHashSet<>( Set.of( "B", "C" ) ) );
+
+        Issue3708TargetImmutableMapper.INSTANCE.partialUpdateMapping( entity, dto );
+
+        assertThat( entity.getTypes() ).containsExactlyInAnyOrder( "B", "C" );
+    }
+
     @ProcessorTest
     void clearAndAddAllShouldNotGenerateWhenTargetImmutable() {
         generated.forMapper( Issue3708TargetImmutableMapper.class )
