From 4ca2b6ecf18acef40c373cf76d87904055581d9a Mon Sep 17 00:00:00 2001 From: Gunnar Morling Date: Mon, 24 Nov 2014 22:27:20 +0100 Subject: [PATCH] #295 Improving wording in JavaDocs, making @NullValueMapping#value() mandatory --- .../src/main/java/org/mapstruct/Mapper.java | 6 +++-- .../main/java/org/mapstruct/MapperConfig.java | 5 ++-- .../java/org/mapstruct/NullValueMapping.java | 20 +++++++------- .../mapstruct/NullValueMappingStrategy.java | 27 ++++++++++--------- .../ap/test/mapnulltodefault/CarMapper.java | 13 ++++----- .../test/mapnulltodefault/CarMapperTest.java | 1 + 6 files changed, 38 insertions(+), 34 deletions(-) diff --git a/core-common/src/main/java/org/mapstruct/Mapper.java b/core-common/src/main/java/org/mapstruct/Mapper.java index cd3e7eab4..4c1434bde 100644 --- a/core-common/src/main/java/org/mapstruct/Mapper.java +++ b/core-common/src/main/java/org/mapstruct/Mapper.java @@ -105,9 +105,11 @@ public @interface Mapper { CollectionMappingStrategy collectionMappingStrategy() default CollectionMappingStrategy.DEFAULT; /** - * The strategy to be applied when for returning a target when the source equals null. + * The strategy to be applied when {@code null} is passed as source value to the methods of this mapper. If no + * strategy is configured, the strategy given via {@link MapperConfig#nullValueMappingStrategy()} will be applied, + * using {@link NullValueMappingStrategy#RETURN_NULL} by default. * - * @return The strategy applied when determining whether to return null or an empty object, list or map. + * @return The strategy to be applied when {@code null} is passed as source value to the methods of this mapper. */ NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.DEFAULT; } diff --git a/core-common/src/main/java/org/mapstruct/MapperConfig.java b/core-common/src/main/java/org/mapstruct/MapperConfig.java index f120ad546..3341bb3fb 100644 --- a/core-common/src/main/java/org/mapstruct/MapperConfig.java +++ b/core-common/src/main/java/org/mapstruct/MapperConfig.java @@ -83,9 +83,10 @@ public @interface MapperConfig { CollectionMappingStrategy collectionMappingStrategy() default CollectionMappingStrategy.DEFAULT; /** - * The strategy to be applied when for returning a target when the source equals null. + * The strategy to be applied when {@code null} is passed as source value to mapping methods. If no strategy is + * configured, {@link NullValueMappingStrategy#RETURN_NULL} will be used by default. * - * @return The strategy applied when determining whether to return null or an empty object, list or map. + * @return The strategy to be applied when {@code null} is passed as source value to mapping methods. */ NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.DEFAULT; } diff --git a/core-common/src/main/java/org/mapstruct/NullValueMapping.java b/core-common/src/main/java/org/mapstruct/NullValueMapping.java index ad1e26db4..ad7d88b69 100644 --- a/core-common/src/main/java/org/mapstruct/NullValueMapping.java +++ b/core-common/src/main/java/org/mapstruct/NullValueMapping.java @@ -24,17 +24,10 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Determines what kind to return in case of a null source argument. + * Specifies how the annotated method should deal with {@code null} values. *

- * For: - *

    - *
  1. Bean Mapping: an 'empty' target bean, except for expressions and constants
    2. - *
  2. Iterable Mapping: an 'empty' list
    3. - *
  3. Map Mapping: an 'empty' map
    4. - *
- * - * 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 + * If no strategy is configured explicitly for a given method, the configuration from the enclosing mapper will be + * applied, using {@link NullValueMappingStrategy#RETURN_NULL} by default. * * @author Sjaak Derksen */ @@ -42,5 +35,10 @@ import java.lang.annotation.Target; @Retention( RetentionPolicy.SOURCE ) public @interface NullValueMapping { - NullValueMappingStrategy value() default NullValueMappingStrategy.RETURN_DEFAULT; + /** + * The strategy for mapping null values. + * + * @return The strategy for mapping null values + */ + NullValueMappingStrategy value(); } diff --git a/core-common/src/main/java/org/mapstruct/NullValueMappingStrategy.java b/core-common/src/main/java/org/mapstruct/NullValueMappingStrategy.java index 826653a71..1aa7ca5c4 100644 --- a/core-common/src/main/java/org/mapstruct/NullValueMappingStrategy.java +++ b/core-common/src/main/java/org/mapstruct/NullValueMappingStrategy.java @@ -19,34 +19,35 @@ package org.mapstruct; /** - * Strategy for propagating the value of collection-typed properties from source to target. + * Strategy for dealing with {@code null} values passed to mapping methods. * * @author Sjaak Derksen */ public enum NullValueMappingStrategy { /** - * A null source argument of a mapping method will be mapped to a null target result + * If {@code null} is passed to a mapping method, {@code null} will be returned. That's the default behavior if no + * alternative strategy is configured globally, for given mapper or method. */ RETURN_NULL, /** - * A null source argument of a mapping method will be mapped to a default target result - *

- *

    - *
  1. 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> - *
  2. For an iterable mapping this means a {@link java.util.Collections#emptyList() } will be returned<\li> - *
  3. For an map mapping this means a {@link java.util.Collections#emptyMap() } will be returned<\li> - *
+ * If {@code null} is passed to a mapping method, a default value will be returned. The value depends on the kind of + * the annotated method: + * */ RETURN_DEFAULT, /** - * When given via {@link Mapper#nullValueMappingStrategy() ()}, causes the setting specified via - * {@link MapperConfig#nullValueMappingStrategy() ()} to be applied, if present. + * When given via {@link Mapper#nullValueMappingStrategy()}, causes the setting specified via + * {@link MapperConfig#nullValueMappingStrategy()} to be applied, if present. *

- * When given via {@link NullValueMapping#value() ()}, causes the setting specified via + * When given via {@link NullValueMapping#value()}, causes the setting specified via * {@link Mapper#nullValueMappingStrategy() ()} to be applied, if present. *

* Otherwise causes {@link #RETURN_NULL} to be applied. diff --git a/processor/src/test/java/org/mapstruct/ap/test/mapnulltodefault/CarMapper.java b/processor/src/test/java/org/mapstruct/ap/test/mapnulltodefault/CarMapper.java index 897fd76c7..1d7a0dc75 100644 --- a/processor/src/test/java/org/mapstruct/ap/test/mapnulltodefault/CarMapper.java +++ b/processor/src/test/java/org/mapstruct/ap/test/mapnulltodefault/CarMapper.java @@ -18,14 +18,16 @@ */ package org.mapstruct.ap.test.mapnulltodefault; +import static org.mapstruct.NullValueMappingStrategy.RETURN_DEFAULT; + import java.util.List; import java.util.Map; import java.util.UUID; import org.mapstruct.Mapper; -import org.mapstruct.NullValueMapping; import org.mapstruct.Mapping; import org.mapstruct.Mappings; +import org.mapstruct.NullValueMapping; import org.mapstruct.ap.test.mapnulltodefault.source.Car; import org.mapstruct.ap.test.mapnulltodefault.target.CarDto; import org.mapstruct.factory.Mappers; @@ -35,7 +37,7 @@ public interface CarMapper { CarMapper INSTANCE = Mappers.getMapper( CarMapper.class ); - @NullValueMapping + @NullValueMapping(RETURN_DEFAULT) @Mappings({ @Mapping(target = "seatCount", source = "numberOfSeats"), @Mapping(target = "model", constant = "ModelT"), @@ -43,7 +45,7 @@ public interface CarMapper { }) CarDto carToCarDto(Car car); - @NullValueMapping + @NullValueMapping(RETURN_DEFAULT) @Mappings({ @Mapping(target = "seatCount", source = "car.numberOfSeats"), @Mapping(target = "model", source = "model"), // TODO, should not be needed, must be made based on name only @@ -52,10 +54,9 @@ public interface CarMapper { CarDto carToCarDto(Car car, String model); - @NullValueMapping + @NullValueMapping(RETURN_DEFAULT) List carsToCarDtos(List cars); - - @NullValueMapping + @NullValueMapping(RETURN_DEFAULT) Map carsToCarDtoMap(Map cars); } diff --git a/processor/src/test/java/org/mapstruct/ap/test/mapnulltodefault/CarMapperTest.java b/processor/src/test/java/org/mapstruct/ap/test/mapnulltodefault/CarMapperTest.java index 09cbd184f..a6c1c3fa7 100644 --- a/processor/src/test/java/org/mapstruct/ap/test/mapnulltodefault/CarMapperTest.java +++ b/processor/src/test/java/org/mapstruct/ap/test/mapnulltodefault/CarMapperTest.java @@ -122,6 +122,7 @@ public class CarMapperTest { } @Test + @SuppressWarnings( { "rawtypes", "unchecked" } ) public void shouldMapMapWithNullArg() { //given