Skip to content

#3387 Add nullValueIterablePropertyMappingStrategy and nullValueMapPropertyMappingStrategy - #4093

Open
Ork2004 wants to merge 4 commits into
mapstruct:mainfrom
Ork2004:issue-3387-nvpms-container-strategies
Open

#3387 Add nullValueIterablePropertyMappingStrategy and nullValueMapPropertyMappingStrategy#4093
Ork2004 wants to merge 4 commits into
mapstruct:mainfrom
Ork2004:issue-3387-nvpms-container-strategies

Conversation

@Ork2004

@Ork2004 Ork2004 commented Jul 13, 2026

Copy link
Copy Markdown

Closes #3387

Right now nullValuePropertyMappingStrategy applies the same way to every property,
no matter what type it is. So if you want SET_TO_DEFAULT for your List/Map
properties (reset to empty instead of null) but still want a nested bean property to
just become null, you can't set it once on the mapper — you have to repeat
nullValuePropertyMappingStrategy on every single @Mapping for every
list/map property. Not great if you have a lot of mappers.

So I added two new attributes, nullValueIterablePropertyMappingStrategy and
nullValueMapPropertyMappingStrategy, on @Mapping, @BeanMapping, @Mapper and
@MapperConfig. Basically the same idea as the existing
nullValueIterableMappingStrategy / nullValueMapMappingStrategy (used for the whole
method argument), just applied at the property level instead.

What I changed:

  • added the two new attributes in core (with fallback to the general
    nullValuePropertyMappingStrategy if you don't set them)
  • wired them up in the processor, in the same option-resolving classes that already
    handle the existing attributes (MappingOptions, BeanMappingOptions,
    MapperOptions, MapperConfigOptions, DefaultOptions)
  • the actual decision of which strategy to use happens in
    PropertyMappingBuilder.options(), based on whether the target property is a Map,
    an Iterable/array, or something else
  • added some tests under nullvaluepropertymapping.containertype
  • added a doc section + changelog entry

I ran all the tests and they pass (3642 tests, no failures). Also ran checkstyle and
the other checks, all good. This is my first PR here, so let me know if I did
something wrong or if you'd prefer a different approach.

Ork2004 added 4 commits July 13, 2026 18:17
…alueMapPropertyMappingStrategy attributes

Add the two new attributes to @mapping, @BeanMapping, @Mapper and @MapperConfig,
mirroring the existing nullValueIterableMappingStrategy / nullValueMapMappingStrategy
attributes used for whole-argument null handling.
…ullValueMapPropertyMappingStrategy

Wire the new attributes through the DelegatingOptions chain (Mapping, BeanMapping,
Mapper, MapperConfig and Default levels), following the same specific-then-general-
then-next-level precedence already used for nullValueIterableMappingStrategy /
nullValueMapMappingStrategy.

PropertyMappingBuilder.options() now picks the strategy based on the target
property's type: Map-typed properties use nullValueMapPropertyMappingStrategy,
Iterable/array-typed properties use nullValueIterablePropertyMappingStrategy,
everything else keeps using the general nullValuePropertyMappingStrategy.
…rategies

Cover the two scenarios that matter most: the general
nullValuePropertyMappingStrategy vs. the Iterable/Map-specific one on
@Mapper, and the more specific @Mapping-level override taking precedence
over the mapper-level container strategy.
…nullValueMapPropertyMappingStrategy

Add a dedicated section to chapter-10-advanced-mapping-options.asciidoc,
mirroring the existing section for nullValueIterableMappingStrategy /
nullValueMapMappingStrategy, and note the new attributes in
NEXT_RELEASE_CHANGELOG.md.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Introduce dedicated nullValueIterablePropertyMappingStrategy and nullValueMapPropertyMappingStrategy

1 participant