#295 NullValueMapping inheritance mechanism from MapperConfig to Mapper to Method

core-common/src/main/java/org/mapstruct/MapNullToDefault.java

@@ -24,16 +24,17 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Advises the code generator to apply all the {@link Mapping}s from an inverse mapping method to the annotated method
- * as well. An inverse mapping method is a method which has the annotated method's source type as target type (return
- * type or indicated through a parameter annotated with {@link MappingTarget}) and the annotated method's target type as
- * source type.
+ * Determines what kind to return in case of a null source argument.
  * <p>
- * Any mappings given on the annotated method itself are added to those mappings inherited from the inverse method. In
- * case of a conflict local mappings take precedence over inherited mappings.
- * <p>
- * If more than one matching inverse method exists, the name of the method to inherit the configuration from must be
- * specified via {@link #name()}
+ * For:
+ * <ol>
+ * <li>Bean Mapping: an 'empty' target bean, except for expressions and constants</li>
+ * <li>Iterable Mapping: an 'empty' list</li>
+ * <li>Map Mapping: an 'empty' map</li>
+ * </ol>
+ *
+ * The user has a choice to use this annotation. When its used, it is used to either override a more global
+ * setting, or in the most common case, to set the specific behavior to map null to default
  *
  * @author Sjaak Derksen
  */
@@ -41,5 +42,5 @@ import java.lang.annotation.Target;
 @Retention( RetentionPolicy.SOURCE )
 public @interface MapNullToDefault {
 
-    boolean value() default true;
+    MapNullToDefaultStrategy value() default MapNullToDefaultStrategy.MAP_NULL_TO_DEFAULT;
 }

core-common/src/main/java/org/mapstruct/MapNullToDefaultStrategy.java

@@ -0,0 +1,56 @@
+/**
+ *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
+ *  and/or other contributors as indicated by the @authors tag. See the
+ *  copyright.txt file in the distribution for a full listing of all
+ *  contributors.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package org.mapstruct;
+
+/**
+ * Strategy for propagating the value of collection-typed properties from source to target.
+ *
+ * @author Sjaak Derksen
+ */
+public enum MapNullToDefaultStrategy {
+
+    /**
+     * A null source argument of a mapping method will be mapped to a null target result
+     */
+    MAP_NULL_TO_NULL,
+
+    /**
+     * A null source argument of a mapping method will be mapped to a default target result
+     * <p>
+     * <ol>
+     * <li>For a bean mapping this means a target object will be returned. {@link Mapping#expression()} and
+     * {@link Mapping#constant()} will be added to the target<\li>
+     * <li>For an iterable mapping this means a {@link java.util.Collections#emptyList() } will be returned<\li>
+     * <li>For an map mapping this means a {@link java.util.Collections#emptyMap() } will be returned<\li>
+     * </ol>
+     */
+    MAP_NULL_TO_DEFAULT,
+
+    /**
+     * When given via {@link Mapper#mapNullToDefaultStrategy()}, causes the setting specified via
+     * {@link MapperConfig#mapNullToDefaultStrategy()} to be applied, if present.
+     * <p>
+     * When given via {@link MapNullToDefault#mapNullToDefaultStrategy()}, causes the setting specified via
+     * {@link Mapper#mapNullToDefaultStrategy()} to be applied, if present.
+     * <p>
+     * Otherwise causes
+     * {@link #MAP_NULL_TO_NULL} to be applied.
+     */
+    DEFAULT;
+}

core-common/src/main/java/org/mapstruct/Mapper.java

@@ -104,4 +104,10 @@ public @interface Mapper {
      */
     CollectionMappingStrategy collectionMappingStrategy() default CollectionMappingStrategy.DEFAULT;
 
+    /**
+     * The strategy to be applied when for returning a target when the source equals null.
+     *
+     * @return The strategy applied when determining whether to return null or an empty object, list or map.
+     */
+    MapNullToDefaultStrategy mapNullToDefaultStrategy() default MapNullToDefaultStrategy.DEFAULT;
 }

core-common/src/main/java/org/mapstruct/MapperConfig.java

@@ -81,4 +81,11 @@ public @interface MapperConfig {
      * @return The strategy applied when propagating the value of collection-typed properties.
      */
     CollectionMappingStrategy collectionMappingStrategy() default CollectionMappingStrategy.DEFAULT;
+
+    /**
+     * The strategy to be applied when for returning a target when the source equals null.
+     *
+     * @return The strategy applied when determining whether to return null or an empty object, list or map.
+     */
+    MapNullToDefaultStrategy mapNullToDefaultStrategy() default MapNullToDefaultStrategy.DEFAULT;
 }

processor/src/main/java/org/mapstruct/ap/model/BeanMappingMethod.java

@@ -101,7 +101,8 @@ public class BeanMappingMethod extends MappingMethod {
 
             // mapNullToDefault
             MapNullToDefaultPrism prism = MapNullToDefaultPrism.getInstanceOn( method.getExecutable() );
-            boolean mapNullToDefault = ( prism != null ) && prism.value();
+            boolean mapNullToDefault =
+                    MapperConfig.getInstanceOn( ctx.getMapperTypeElement() ).isMapToDefault( prism );
 
             MethodReference factoryMethod = AssignmentFactory.createFactoryMethod( method.getReturnType(), ctx );
             return new BeanMappingMethod( method, propertyMappings, factoryMethod, mapNullToDefault );

processor/src/main/java/org/mapstruct/ap/model/IterableMappingMethod.java

@@ -32,6 +32,7 @@ import org.mapstruct.ap.model.common.Type;
 import org.mapstruct.ap.model.common.TypeFactory;
 import org.mapstruct.ap.model.source.Method;
 import org.mapstruct.ap.prism.MapNullToDefaultPrism;
+import org.mapstruct.ap.util.MapperConfig;
 import org.mapstruct.ap.util.Strings;
 
 /**
@@ -109,7 +110,8 @@ public class IterableMappingMethod extends MappingMethod {
 
             // mapNullToDefault
             MapNullToDefaultPrism prism = MapNullToDefaultPrism.getInstanceOn( method.getExecutable() );
-            boolean mapNullToDefault = ( prism != null ) && prism.value();
+            boolean mapNullToDefault
+                    = MapperConfig.getInstanceOn( ctx.getMapperTypeElement() ).isMapToDefault( prism );
 
             MethodReference factoryMethod = AssignmentFactory.createFactoryMethod( method.getReturnType(), ctx );
             return new IterableMappingMethod(

processor/src/main/java/org/mapstruct/ap/model/MapMappingMethod.java

@@ -32,6 +32,7 @@ import org.mapstruct.ap.model.common.Type;
 import org.mapstruct.ap.model.common.TypeFactory;
 import org.mapstruct.ap.model.source.Method;
 import org.mapstruct.ap.prism.MapNullToDefaultPrism;
+import org.mapstruct.ap.util.MapperConfig;
 import org.mapstruct.ap.util.Strings;
 
 /**
@@ -141,7 +142,8 @@ public class MapMappingMethod extends MappingMethod {
 
            // mapNullToDefault
             MapNullToDefaultPrism prism = MapNullToDefaultPrism.getInstanceOn( method.getExecutable() );
-            boolean mapNullToDefault = ( prism != null ) && prism.value();
+            boolean mapNullToDefault =
+                    MapperConfig.getInstanceOn( ctx.getMapperTypeElement() ).isMapToDefault( prism );
 
             MethodReference factoryMethod = AssignmentFactory.createFactoryMethod( method.getReturnType(), ctx );
 

processor/src/main/java/org/mapstruct/ap/prism/MapNullToDefaultStrategyPrism.java

@@ -0,0 +1,31 @@
+/**
+ *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
+ *  and/or other contributors as indicated by the @authors tag. See the
+ *  copyright.txt file in the distribution for a full listing of all
+ *  contributors.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package org.mapstruct.ap.prism;
+
+/**
+ * Prism for the enum {@link org.mapstruct.MapNullToDefaultStrategy}
+ *
+ * @author Sjaak Derksen
+ */
+public enum MapNullToDefaultStrategyPrism {
+
+    MAP_NULL_TO_NULL,
+    MAP_NULL_TO_DEFAULT,
+    DEFAULT;
+}

processor/src/main/java/org/mapstruct/ap/util/MapperConfig.java

@@ -29,6 +29,9 @@ import javax.lang.model.type.DeclaredType;
 import javax.lang.model.type.TypeKind;
 import javax.lang.model.type.TypeMirror;
 
+import org.mapstruct.ap.prism.MapNullToDefaultStrategyPrism;
+import org.mapstruct.ap.prism.MapNullToDefaultPrism;
+
 import org.mapstruct.ap.option.ReportingPolicy;
 import org.mapstruct.ap.prism.CollectionMappingStrategyPrism;
 import org.mapstruct.ap.prism.MapperConfigPrism;
@@ -84,13 +87,12 @@ public class MapperConfig {
     }
 
     public String unmappedTargetPolicy() {
-        if ( !ReportingPolicy.valueOf( mapperPrism.unmappedTargetPolicy() ).equals( ReportingPolicy.DEFAULT ) ) {
+        if ( ReportingPolicy.valueOf( mapperPrism.unmappedTargetPolicy() ) != ReportingPolicy.DEFAULT ) {
             // it is not the default configuration
             return mapperPrism.unmappedTargetPolicy();
         }
         else if ( mapperConfigPrism != null &&
-            !ReportingPolicy.valueOf( mapperConfigPrism.unmappedTargetPolicy() )
-                .equals( ReportingPolicy.DEFAULT ) ) {
+            ReportingPolicy.valueOf( mapperConfigPrism.unmappedTargetPolicy() ) != ReportingPolicy.DEFAULT ) {
             return mapperConfigPrism.unmappedTargetPolicy();
         }
         else {
@@ -117,6 +119,41 @@ public class MapperConfig {
         return CollectionMappingStrategyPrism.ACCESSOR_ONLY;
     }
 
+    public boolean isMapToDefault(MapNullToDefaultPrism mapNullToDefault) {
+
+        // check on method level
+        if ( mapNullToDefault != null ) {
+            MapNullToDefaultStrategyPrism methodPolicy
+                    = MapNullToDefaultStrategyPrism.valueOf( mapNullToDefault.value() );
+            if ( methodPolicy != MapNullToDefaultStrategyPrism.DEFAULT ) {
+                return methodPolicy == MapNullToDefaultStrategyPrism.MAP_NULL_TO_DEFAULT;
+            }
+        }
+
+        // check on mapper level
+        MapNullToDefaultStrategyPrism mapperPolicy =
+                MapNullToDefaultStrategyPrism.valueOf( mapperPrism.mapNullToDefaultStrategy() );
+
+        if ( mapperPolicy != MapNullToDefaultStrategyPrism.DEFAULT ) {
+            // it is not the default mapper configuration, so return the mapper configured value
+            return mapperPolicy == MapNullToDefaultStrategyPrism.MAP_NULL_TO_DEFAULT;
+        }
+
+        // check on mapping config level
+        else if ( mapperConfigPrism != null ) {
+            // try the config mapper configuration
+            MapNullToDefaultStrategyPrism configPolicy =
+                    MapNullToDefaultStrategyPrism.valueOf( mapperConfigPrism.mapNullToDefaultStrategy() );
+            if ( configPolicy != MapNullToDefaultStrategyPrism.DEFAULT )  {
+                // its not the default configuration, so return the mapper config configured value
+                return configPolicy == MapNullToDefaultStrategyPrism.MAP_NULL_TO_DEFAULT;
+            }
+        }
+        // when nothing specified, return MAP_NULL_TO_NULL (default option)
+        return false;
+    }
+
+
     public String componentModel() {
         if ( !mapperPrism.componentModel().equals( "default" ) ) {
             return mapperPrism.componentModel();

processor/src/test/java/org/mapstruct/ap/test/mapnulltodefault/CarMapperSettingOnConfig.java

@@ -0,0 +1,53 @@
+/**
+ *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
+ *  and/or other contributors as indicated by the @authors tag. See the
+ *  copyright.txt file in the distribution for a full listing of all
+ *  contributors.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package org.mapstruct.ap.test.mapnulltodefault;
+
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+
+import org.mapstruct.Mapper;
+import org.mapstruct.MapNullToDefault;
+import org.mapstruct.MapNullToDefaultStrategy;
+import org.mapstruct.Mapping;
+import org.mapstruct.Mappings;
+import org.mapstruct.ap.test.mapnulltodefault.source.Car;
+import org.mapstruct.ap.test.mapnulltodefault.target.CarDto;
+import org.mapstruct.factory.Mappers;
+
+@Mapper(imports = UUID.class, config = CentralConfig.class )
+public interface CarMapperSettingOnConfig {
+
+    CarMapperSettingOnConfig INSTANCE = Mappers.getMapper( CarMapperSettingOnConfig.class );
+
+    @Mappings({
+        @Mapping(target = "seatCount", source = "numberOfSeats"),
+        @Mapping(target = "model", constant = "ModelT"),
+        @Mapping(target = "catalogId", expression = "java( UUID.randomUUID().toString() )")
+    })
+    CarDto carToCarDto(Car car);
+
+
+    @MapNullToDefault(MapNullToDefaultStrategy.DEFAULT)
+    List<CarDto> carsToCarDtos(List<Car> cars);
+
+
+    @MapNullToDefault(MapNullToDefaultStrategy.MAP_NULL_TO_NULL)
+    Map<Integer, CarDto> carsToCarDtoMap(Map<Integer, Car> cars);
+}

processor/src/test/java/org/mapstruct/ap/test/mapnulltodefault/CarMapperSettingOnMapper.java

@@ -0,0 +1,53 @@
+/**
+ *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
+ *  and/or other contributors as indicated by the @authors tag. See the
+ *  copyright.txt file in the distribution for a full listing of all
+ *  contributors.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package org.mapstruct.ap.test.mapnulltodefault;
+
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+
+import org.mapstruct.Mapper;
+import org.mapstruct.MapNullToDefault;
+import org.mapstruct.MapNullToDefaultStrategy;
+import org.mapstruct.Mapping;
+import org.mapstruct.Mappings;
+import org.mapstruct.ap.test.mapnulltodefault.source.Car;
+import org.mapstruct.ap.test.mapnulltodefault.target.CarDto;
+import org.mapstruct.factory.Mappers;
+
+@Mapper(imports = UUID.class, mapNullToDefaultStrategy = MapNullToDefaultStrategy.MAP_NULL_TO_DEFAULT )
+public interface CarMapperSettingOnMapper {
+
+    CarMapperSettingOnMapper INSTANCE = Mappers.getMapper( CarMapperSettingOnMapper.class );
+
+    @Mappings({
+        @Mapping(target = "seatCount", source = "numberOfSeats"),
+        @Mapping(target = "model", constant = "ModelT"),
+        @Mapping(target = "catalogId", expression = "java( UUID.randomUUID().toString() )")
+    })
+    CarDto carToCarDto(Car car);
+
+
+    @MapNullToDefault(MapNullToDefaultStrategy.DEFAULT)
+    List<CarDto> carsToCarDtos(List<Car> cars);
+
+
+    @MapNullToDefault(MapNullToDefaultStrategy.MAP_NULL_TO_NULL)
+    Map<Integer, CarDto> carsToCarDtoMap(Map<Integer, Car> cars);
+}

processor/src/test/java/org/mapstruct/ap/test/mapnulltodefault/CarMapperTest.java

@@ -35,7 +35,10 @@ import org.mapstruct.ap.testutil.runner.AnnotationProcessorTestRunner;
 @WithClasses({
     Car.class,
     CarDto.class,
-    CarMapper.class
+    CarMapper.class,
+    CarMapperSettingOnMapper.class,
+    CentralConfig.class,
+    CarMapperSettingOnConfig.class
 })
 @RunWith(AnnotationProcessorTestRunner.class)
 public class CarMapperTest {
@@ -141,4 +144,79 @@ public class CarMapperTest {
        assertThat( carDtoMap2.isEmpty() ).isTrue();
 
     }
+
+    @Test
+    public void shouldMapExpressionAndConstantRegardlessNullArgOnMapper() {
+
+        //when
+        CarDto carDto = CarMapperSettingOnMapper.INSTANCE.carToCarDto( null );
+
+        //then
+        assertThat( carDto ).isNotNull();
+        assertThat( carDto.getMake() ).isNull();
+        assertThat( carDto.getSeatCount() ).isEqualTo( 0 );
+        assertThat( carDto.getModel() ).isEqualTo( "ModelT" );
+        assertThat( carDto.getCatalogId() ).isNotEmpty();
+    }
+
+    @Test
+    public void shouldMapIterableWithNullArgOnMapper() {
+
+       //when
+       List<CarDto> carDtos = CarMapperSettingOnMapper.INSTANCE.carsToCarDtos( null );
+
+       //then
+       assertThat( carDtos ).isNotNull();
+       assertThat( carDtos.isEmpty() ).isTrue();
+
+    }
+
+    @Test
+    public void shouldMapMapWithNullArgOnMapper() {
+
+       //when
+       Map<Integer, CarDto> carDtoMap = CarMapperSettingOnMapper.INSTANCE.carsToCarDtoMap( null );
+
+       //then
+       assertThat( carDtoMap ).isNull();
+
+    }
+
+    @Test
+    public void shouldMapExpressionAndConstantRegardlessNullArgOnConfig() {
+
+        //when
+        CarDto carDto = CarMapperSettingOnConfig.INSTANCE.carToCarDto( null );
+
+        //then
+        assertThat( carDto ).isNotNull();
+        assertThat( carDto.getMake() ).isNull();
+        assertThat( carDto.getSeatCount() ).isEqualTo( 0 );
+        assertThat( carDto.getModel() ).isEqualTo( "ModelT" );
+        assertThat( carDto.getCatalogId() ).isNotEmpty();
+    }
+
+
+    @Test
+    public void shouldMapIterableWithNullArgOnConfig() {
+
+       //when
+       List<CarDto> carDtos = CarMapperSettingOnConfig.INSTANCE.carsToCarDtos( null );
+
+       //then
+       assertThat( carDtos ).isNotNull();
+       assertThat( carDtos.isEmpty() ).isTrue();
+
+    }
+
+    @Test
+    public void shouldMapMapWithNullArgOnConfig() {
+
+       //when
+       Map<Integer, CarDto> carDtoMap = CarMapperSettingOnConfig.INSTANCE.carsToCarDtoMap( null );
+
+       //then
+       assertThat( carDtoMap ).isNull();
+
+    }
 }

processor/src/test/java/org/mapstruct/ap/test/mapnulltodefault/CentralConfig.java

@@ -0,0 +1,31 @@
+/**
+ *  Copyright 2012-2014 Gunnar Morling (http://www.gunnarmorling.de/)
+ *  and/or other contributors as indicated by the @authors tag. See the
+ *  copyright.txt file in the distribution for a full listing of all
+ *  contributors.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package org.mapstruct.ap.test.mapnulltodefault;
+
+import org.mapstruct.MapNullToDefaultStrategy;
+import org.mapstruct.MapperConfig;
+
+/**
+ *
+ * @author Sjaak Derksen
+ */
+@MapperConfig( mapNullToDefaultStrategy = MapNullToDefaultStrategy.MAP_NULL_TO_DEFAULT )
+public class CentralConfig {
+
+}

processor/src/test/java/org/mapstruct/ap/test/prism/EnumPrismsTest.java

@@ -26,6 +26,8 @@ import org.mapstruct.CollectionMappingStrategy;
 import org.mapstruct.ap.prism.CollectionMappingStrategyPrism;
 
 import static org.fest.assertions.Assertions.assertThat;
+import org.mapstruct.MapNullToDefaultStrategy;
+import org.mapstruct.ap.prism.MapNullToDefaultStrategyPrism;
 
 /**
  * Test for manually created prisms on enumeration types
@@ -39,6 +41,12 @@ public class EnumPrismsTest {
             namesOf( CollectionMappingStrategyPrism.values() ) );
     }
 
+    @Test
+    public void mapNullToDefaultStrategyPrismIsCorrect() {
+        assertThat( namesOf( MapNullToDefaultStrategy.values() ) ).isEqualTo(
+            namesOf( MapNullToDefaultStrategyPrism.values() ) );
+    }
+
     private static List<String> namesOf(Enum<?>[] values) {
         List<String> names = new ArrayList<String>( values.length );