Merge pull request #502 from AuthMe/479-move-return-null-constant

#479 Move RETURN_NULL constant from MapperImpl to LeafValueHandler

Author: ljacqu

src/main/java/ch/jalu/configme/beanmapper/MapperImpl.java

@@ -66,9 +66,6 @@
  */
 public class MapperImpl implements Mapper {
 
-    /** Marker object to signal that null is meant to be used as value. */
-    public static final Object RETURN_NULL = new Object();
-
     // ---------
     // Fields and general configurable methods
     // ---------
@@ -125,13 +122,13 @@ public MapperImpl(@NotNull BeanDefinitionService beanDefinitionService,
         // Step 1: attempt simple value transformation
         Object exportValue = leafValueHandler.toExportValue(value, exportContext);
         if (exportValue != null || value == null) {
-            return unwrapReturnNull(exportValue);
+            return LeafValueHandler.unwrapReturnNull(exportValue);
         }
 
         // Step 2: handle special cases like Collection
         exportValue = createExportValueForSpecialTypes(value, exportContext);
         if (exportValue != null) {
-            return unwrapReturnNull(exportValue);
+            return LeafValueHandler.unwrapReturnNull(exportValue);
         }
 
         // Step 3: treat as bean
@@ -159,12 +156,12 @@ public MapperImpl(@NotNull BeanDefinitionService beanDefinitionService,
 
     /**
      * Handles values of types which need special handling (such as Optional). Null means the value is not
-     * a special type and that the export value should be built differently. Use {@link #RETURN_NULL} to
+     * a special type and that the export value should be built differently. Use {@link LeafValueHandler#RETURN_NULL} to
      * signal that null should be used as the export value of the provided value.
      *
      * @param value the value to convert
      * @param exportContext export context
-     * @return the export value to use or {@link #RETURN_NULL}, or null if not applicable
+     * @return the export value to use or {@link LeafValueHandler#RETURN_NULL}, or null if not applicable
      */
     protected @Nullable Object createExportValueForSpecialTypes(@Nullable Object value,
                                                                 @NotNull ExportContext exportContext) {
@@ -192,16 +189,12 @@ public MapperImpl(@NotNull BeanDefinitionService beanDefinitionService,
             Optional<?> optional = (Optional<?>) value;
             return optional
                 .map(v -> toExportValue(v, exportContext.createChildContext(OPTIONAL_SPECIFIER)))
-                .orElse(RETURN_NULL);
+                .orElse(LeafValueHandler.RETURN_NULL);
         }
 
         return null;
     }
 
-    protected static @Nullable Object unwrapReturnNull(@Nullable Object o) {
-        return o == RETURN_NULL ? null : o;
-    }
-
     // ---------
     // Bean mapping
     // ---------

src/main/java/ch/jalu/configme/beanmapper/leafvaluehandler/LeafValueHandler.java

@@ -20,6 +20,9 @@
  */
 public interface LeafValueHandler {
 
+    /** Marker object to signal that null is meant to be used as value. */
+    Object RETURN_NULL = new Object();
+
     /**
      * Converts the given value to the target type (as defined by the mapping context), if supported. Otherwise,
      * null is returned. If a value is returned, its type is guaranteed to match the target type.
@@ -33,11 +36,25 @@ public interface LeafValueHandler {
     /**
      * Converts the value of a property to a value suitable for exporting. This method converts the opposite
      * way of {@link #convert}. Null is returned if this leaf value handler does not support the object's type.
+     * If the leaf value handler determines that {@code null} should be used as export value, then {@link #RETURN_NULL}
+     * is returned, which the caller needs to unwrap to {@code null}.
      *
      * @param value the value to convert
      * @param exportContext the export context (usually not needed)
      * @return the value suitable for exporting, or null if not applicable
      */
     @Nullable Object toExportValue(@Nullable Object value, @NotNull ExportContext exportContext);
 
+    /**
+     * Returns null if the object is {@link #RETURN_NULL}, otherwise the given object. Used to process return values
+     * from methods like {@link #toExportValue}, where {@code null} means the instance doesn't support the value,
+     * while {@link #RETURN_NULL} means null should be used as export value.
+     *
+     * @param object the object to potentially unwrap
+     * @param <T> the object type
+     * @return null, or the provided object
+     */
+    static <T> @Nullable T unwrapReturnNull(@Nullable T object) {
+        return object == RETURN_NULL ? null : object;
+    }
 }

src/main/java/ch/jalu/configme/beanmapper/leafvaluehandler/MapperLeafType.java

@@ -30,7 +30,7 @@ public interface MapperLeafType {
      * when {@link ch.jalu.configme.beanmapper.MapperImpl#toExportValue(Object)} is called.
      * Returns null if the leaf value handler cannot handle the value.
      * <p>
-     * Return {@link ch.jalu.configme.beanmapper.MapperImpl#RETURN_NULL} to signal that null should be used
+     * Return {@link LeafValueHandler#RETURN_NULL} to signal that null should be used
      * as the export value (returning {@code null} itself means this leaf value handler cannot handle it).
      *
      * @param value the value to convert to an export value, if possible

src/test/java/ch/jalu/configme/beanmapper/leafvaluehandler/LeafValueHandlerTest.java

@@ -0,0 +1,26 @@
+package ch.jalu.configme.beanmapper.leafvaluehandler;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.concurrent.TimeUnit;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.equalTo;
+import static org.hamcrest.Matchers.nullValue;
+
+/**
+ * Test for {@link LeafValueHandler}.
+ */
+class LeafValueHandlerTest {
+
+    @Test
+    void shouldUnwrapReturnNull() {
+        // given / when / then
+        assertThat(LeafValueHandler.unwrapReturnNull(null), nullValue());
+        assertThat(LeafValueHandler.unwrapReturnNull(LeafValueHandler.RETURN_NULL), nullValue());
+
+        assertThat(LeafValueHandler.unwrapReturnNull("null"), equalTo("null"));
+        assertThat(LeafValueHandler.unwrapReturnNull(TimeUnit.SECONDS), equalTo(TimeUnit.SECONDS));
+        assertThat(LeafValueHandler.unwrapReturnNull(12), equalTo(12));
+    }
+}