Expected behavior

Using NullValueMappingStrategy.RETURN_NULL on an update method (which is also the default) should make the method return null when the update entity is null.

@BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE,
            nullValueMappingStrategy = NullValueMappingStrategy.RETURN_NULL)
    @Mapping(target = "id", ignore = true)
    public abstract Ship updateShipWithShipDto(ShipDto update, @MappingTarget Ship destination);

->

@Override
    public Ship updateShipWithShipDto(ShipDto update, Ship destination) {
        if ( update == null ) {
            return null;
        }
        ...
        ...
    }

Actual behavior

It actually makes the method return the original, non-updated target entity:

@Override
    public Ship updateShipWithShipDto(ShipDto update, Ship destination) {
        if ( update == null ) {
            return destination;
        }
        ...
        ...
    }

This makes it impossible to update this field to null, when updateShipWithShipDto gets called by other Mappers.

Perhaps a third option for NullValueMappingStrategy could be added to apply this current behaviour, but the javadoc on RETURN_NULL states that "If null is passed to a mapping method, null will be returned.".

Steps to reproduce the problem

I have created a Short, Self Contained, Correct Example (SSCCE) at this repository: https://github.com/goldflam-gmbh/mapstruct-return-null-from-update

If you check this out and run a mvn clean compile you will get the result mentioned partially above.

There are also two test cases (which currently fail), to show the behaviour that we expected.

This behaviour has been implemented because of issue #1752 and while we do understand why this is the default option, we also feel like there should be an option to return null. Naming of the NullValueMappingStrategies could be difficult though if a third option was to be added.

MapStruct Version

1.5.3.Final