Issue Description

After reviewing some issues, I've noticed significant confusion regarding the scope and applicability of NullValueMappingStrategy and NullValuePropertyMappingStrategy. Those issues can be roughly divided into three categories:

1. Some user use NullValueMappingStrategy expecting it to handle null properties within a source bean, when it actually only handles cases where the entire source object is null. issues: 2843

2. Others use NullValuePropertyMappingStrategy with regular mapping methods, not realizing it only applies to update methods (those annotated with @MappingTarget). issues: 3390

3. NullValuePropertyMappingStrategy#SET_TO_DEFAULT, there is indeed a bug, I have make a PR. issues: 2531

Actual Effect Of The Code

Based on the documentation, code comments and test:

NullValueMappingStrategy

• Purpose: Controls behavior when the entire source object passed to a mapping method is null (support Bean、Iterables / Arrays、Maps)
• Options:
  • RETURN_NULL: Returns null (default)
  • RETURN_DEFAULT: Returns a "empty" instance of the target type
• Scope: Applies to all mapping methods (no actual effect in the update method)
• Does NOT: Handle null properties within a non-null source object

NullValuePropertyMappingStrategy

• Purpose: Controls behavior when a property within the source bean is null
• Options:
  • SET_TO_NULL: Sets the target property to null (default)
  • SET_TO_DEFAULT: Sets the target property to its default value (empty collection, empty string, 0, etc.). But have a bug now.
  • IGNORE: Preserves the existing value in the target
• Scope: Only applies to update methods (annotated with @MappingTarget)
• Does NOT: Apply to regular mapping methods

Somethings to discuss

1. Is my understanding correct?
   I think there is a big deviation between the actual implementation of the code and user expectations.
   The community also seems to consider it a bug (but maybe it's by design?)
2. How to do?
   Change the design of NullValueMappingStrategy to support bean properties？
   Add special instructions to the document？
   or other

@filiphr How do you think? Some background information #1273 (comment)