Fix #5350: add DeserializationFeature.USE_NULL_FOR_MISSING_REFERENCE_VALUES (#5365)

Author: cowtowncoder

release-notes/VERSION

@@ -5,6 +5,11 @@ Versions: 3.x (for earlier see VERSION-2.x)
 === Releases ===
 ------------------------------------------------------------------------
 
+3.1.0 (not yet released)
+
+#5350: Add `DeserializationFeature.USE_NULL_FOR_MISSING_REFERENCE_VALUES` for
+  selecting `null` vs "empty/absent" value when deserializing missing `Optional` value
+
 3.0.1 (21-Oct-2025)
 
 #5335: JsonMapper to deserialize `Optional.empty()` instead of `null`

src/main/java/tools/jackson/databind/DeserializationFeature.java

@@ -98,6 +98,24 @@ public enum DeserializationFeature implements ConfigFeature
      */
     USE_JAVA_ARRAY_FOR_JSON_ARRAY(false),
 
+    /**
+     * Feature that determines whether deserialization of "Reference Types"
+     * (such as {@link java.util.Optional}, {@link java.util.concurrent.atomic.AtomicReference},
+     * and Kotlin/Scala equivalents) should return Java {@code null} in case
+     * of value missing from incoming JSON. If disabled, reference type's
+     * "absent" value is returned (for example, {@link java.util.Optional#empty()}.
+     *<p>
+     * NOTE: this feature only affects handling of missing values; not explicit
+     * JSON {@code null}s.
+     * Also note that this feature only affects deserialization when reference value
+     * is passed via Creator (constructor or factory method) parameter; when
+     * Setter methods or fields are used, the reference type is left un-assigned
+     * (this is not specifically related to reference types, but general behavior).
+     *
+     * @since 3.1
+     */
+    USE_NULL_FOR_MISSING_REFERENCE_VALUES(false),
+
     /*
     /**********************************************************************
     /* Error handling features

src/main/java/tools/jackson/databind/deser/jdk/AtomicReferenceDeserializer.java

@@ -34,14 +34,9 @@ public AtomicReference<Object> getNullValue(DeserializationContext ctxt) {
         return new AtomicReference<>(_valueDeserializer.getNullValue(ctxt));
     }
 
-    @Override
-    public Object getAbsentValue(DeserializationContext ctxt) {
-        // 15-Oct-2025, tatu: For [databind#5335] (and earlier [databind#3601])
-        //   base impl changed to return "null value" (which here means "empty" ref).
-        //   But for AtomicReference we will instead return actual null to maintain
-        //   2.x compatibility. (3.1 may add configurability for this)
-        return null;
-    }
+    // 25-Oct-2025, tatu: As per [databind#5335], no need to override any more
+    //@Override
+    // public Object getAbsentValue(DeserializationContext ctxt) { }
 
     @Override
     public AtomicReference<Object> referenceValue(Object contents) {

src/main/java/tools/jackson/databind/deser/std/ReferenceTypeDeserializer.java

@@ -120,10 +120,14 @@ public Object getEmptyValue(DeserializationContext ctxt) {
     public Object getAbsentValue(DeserializationContext ctxt) {
         // 21-Sep-2022, tatu: [databind#3601] Let's make absent become `null`,
         //   NOT "null value" (Empty)
-        //return null;
+        // return null;
         // 15-Oct-2025, tatu: [databind#5335] Revert above change for 3.0.1 to
         //  keep compatibility with 2.x series; 3.1 will add configurability
-        return getNullValue(ctxt);
+        //return getNullValue(ctxt);
+
+        // 25-Oct-2025, tatu: [databind#5350] Now configurable
+        return ctxt.isEnabled(DeserializationFeature.USE_NULL_FOR_MISSING_REFERENCE_VALUES)
+                ? null : getNullValue(ctxt);
     }
 
     public abstract T referenceValue(Object contents);

src/test/java/tools/jackson/databind/deser/jdk/JDKAtomicTypesDeserTest.java

@@ -400,19 +400,30 @@ public void testAbsentAtomicRefViaCreator() throws Exception
     {
         AtomicRefBean bean;
 
+        ObjectReader r = MAPPER.readerFor(AtomicRefBean.class);
+        
         // First: null should become empty, non-null reference
-        bean = MAPPER.readValue(a2q("{'atomic':null}"), AtomicRefBean.class);
+        bean = r.readValue(a2q("{'atomic':null}"));
         assertNotNull(bean._atomic);
         assertNull(bean._atomic.get());
 
         // And then absent (missing), via Creator method, should become actual null
-        bean = MAPPER.readValue("{}", AtomicRefBean.class);
+        // 25-Oct-2025, tatu: [databind#53530] Actually, by default should become
+        //   empty ref
+        bean = r.readValue("{}");
+        assertNotNull(bean._atomic);
+        assertNull(bean._atomic.get());
+
+        // 25-Oct-2025, tatu: but can reconfigure to get `null` instead
+        bean = r.with(DeserializationFeature.USE_NULL_FOR_MISSING_REFERENCE_VALUES)
+                .readValue("{}");
         assertNull(bean._atomic);
 
-        // Except that we can override handling to produce empty
+        // Plus can override handling to produce empty
         AtomicRefBeanWithEmpty bean2 = MAPPER.readValue("{}", AtomicRefBeanWithEmpty.class);
         assertNotNull(bean2._atomic);
         assertNull(bean2._atomic.get());
+
     }
 
     // @since 2.14
@@ -429,7 +440,16 @@ public void testAtomicRefWithNodeViaCreator() throws Exception
         assertTrue(n.isNull());
 
         // And then absent (missing), via Creator method, should become actual null
+        // 25-Oct-2025, tatu: [databind#5350] Not any longer... (by default)
         bean = MAPPER.readValue("{}", AtomicRefWithNodeBean.class);
+        assertNotNull(bean._atomicNode);
+        n = bean._atomicNode.get();
+        assertTrue(n.isNull());
+
+        // but can reconfigure to get `null` instead
+        bean = MAPPER.readerFor(AtomicRefWithNodeBean.class)
+                .with(DeserializationFeature.USE_NULL_FOR_MISSING_REFERENCE_VALUES)
+                .readValue("{}");
         assertNull(bean._atomicNode);
     }
 }

src/test/java/tools/jackson/databind/ext/jdk8/CreatorForOptionalTest.java

@@ -43,8 +43,10 @@ public CreatorWithOptionalStrings(@JsonProperty("a") Optional<String> a,
     @Test
     public void testCreatorWithOptional() throws Exception
     {
-        CreatorWithOptionalStrings bean = MAPPER.readValue(
-                a2q("{'a':'foo'}"), CreatorWithOptionalStrings.class);
+        final String JSON = a2q("{'a':'foo'}");
+        ObjectReader r = MAPPER.readerFor(CreatorWithOptionalStrings.class);
+
+        CreatorWithOptionalStrings bean = r.readValue(JSON);
         assertNotNull(bean);
         assertNotNull(bean.a);
         assertTrue(bean.a.isPresent());
@@ -55,5 +57,15 @@ public void testCreatorWithOptional() throws Exception
 
         //assertNull(bean.b);
         assertEquals(Optional.empty(), bean.b);
+
+        // But can be reconfigured
+
+        bean = r.with(DeserializationFeature.USE_NULL_FOR_MISSING_REFERENCE_VALUES)
+                .readValue(JSON);
+        assertNotNull(bean);
+        assertNotNull(bean.a);
+        assertTrue(bean.a.isPresent());
+
+        assertNull(bean.b);
     }
 }