Fix #1980 (JsonPointer.withObject()/withArray())

Author: cowtowncoder

release-notes/VERSION-2.x

@@ -6,6 +6,8 @@ Project: jackson-databind
 
 2.14.0 (not yet released)
 
+#1980: Add method(s) in `JsonNode` that works like combination of `at()`
+  and `with()`: `withObject(...)` and `withArray(...)`
 #2541: Cannot merge polymorphic objects
  (reported by Matthew A)
  (fix contributed by James W)

src/main/java/com/fasterxml/jackson/databind/JsonNode.java

@@ -6,6 +6,7 @@
 import java.util.*;
 
 import com.fasterxml.jackson.core.*;
+import com.fasterxml.jackson.databind.node.ArrayNode;
 import com.fasterxml.jackson.databind.node.JsonNodeType;
 import com.fasterxml.jackson.databind.node.MissingNode;
 import com.fasterxml.jackson.databind.node.ObjectNode;
@@ -1124,10 +1125,16 @@ public final List<JsonNode> findParents(String fieldName)
      * If the node method is called on is not Object node,
      * or if property exists and has value that is not Object node,
      * {@link UnsupportedOperationException} is thrown
+     *
+     * @param propertyName Name of property for the {@link ObjectNode}
+     *
+     * @return {@link ObjectNode} found or created
+     *
+     * @since 2.14
      */
-    public <T extends JsonNode> T withObject(String propertyName) {
-        throw new UnsupportedOperationException("JsonNode not of type ObjectNode (but "
-                +getClass().getName()+"), cannot call withObject() on it");
+    public ObjectNode withObject(String propertyName) {
+        throw new UnsupportedOperationException("`JsonNode` not of type `ObjectNode` (but "
+                +getClass().getName()+"), cannot call `withObject()` on it");
     }
 
     /**
@@ -1137,10 +1144,10 @@ public <T extends JsonNode> T withObject(String propertyName) {
      * consider {@link JsonPointer} segments index if at all possible
      * and only secondarily as property name
      *
-     * @param ptr Pointer that indicates path to use for Object value to return
+     * @param ptr {@link JsonPointer} that indicates path to use for Object value to return
      *   (potentially creating as necessary)
      *
-     * @return ObjectNode found or created
+     * @return {@link ObjectNode} found or created
      *
      * @since 2.14
      */
@@ -1149,18 +1156,70 @@ public final ObjectNode withObject(JsonPointer ptr) {
     }
 
     /**
-     * Method that can be called on Object nodes, to access a Object-valued
+     * Method that can be called on Object or Array nodes, to access a Object-valued
      * node pointed to by given {@link JsonPointer}, if such a node exists:
-     * if not, an attempt is made to create it.
-     * If the node method is called on is not Object node,
-     * or if property exists and has value that is not Object node,
-     * {@link UnsupportedOperationException} is thrown
+     * or if not, an attempt is made to create one and return it.
+     * For example, on document
+     *<pre>
+     *  { "a" : {
+     *       "b" : {
+     *          "c" : 13
+     *       }
+     *    }
+     *  }
+     *</pre>
+     * calling method with {@link JsonPointer} of {@code /a/b} would return
+     * {@link ObjectNode}
+     *<pre>
+     *  { "c" : 13 }
+     *</pre>
+     *<p>
+     * In cases where path leads to "missing" nodes, a path is created.
+     * So, for example, on above document, and
+     * {@link JsonPointer} of {@code /a/x} an empty {@link ObjectNode} would
+     * be returned and the document would look like:
+     *<pre>
+     *  { "a" : {
+     *       "b" : {
+     *          "c" : 13
+     *       },
+     *       "x" : { }
+     *    }
+     *  }
+     *</pre>
+     * Finally, if the path is incompatible with the document -- there is an existing
+     * {@code JsonNode} through which expression cannot go -- a replacement is
+     * attempted if (and only if) conversion is allowed as per {@code overwriteMode}
+     * passed in. For example, with above document and expression of {@code /a/b/c},
+     * conversion is allowed if passing {@code OverwriteMode.SCALARS} or
+     * {@code OvewriteMode.ALL}, and resulting document would look like:
+     *<pre>
+     *  { "a" : {
+     *       "b" : {
+     *          "c" : { }
+     *       },
+     *       "x" : { }
+     *    }
+     *  }
+     *</pre>
+     * but if different modes ({@code NONE} or {@code NULLS}) is passed, an exception
+     * is thrown instead.
      *
-     * @param ptr Pointer that indicates path to use for Object value to return
-     *   (potentially creating as necessary)
-     * @param overwriteMode Defines w
+     * @param ptr Pointer that indicates path to use for {@link ObjectNode} value to return
+     *   (potentially creating one as necessary)
+     * @param overwriteMode Defines which node types may be converted in case of
+     *    incompatible {@code JsonPointer} expression: if conversion not allowed,
+     *    {@link UnsupportedOperationException} is thrown.
+     * @param preferIndex When creating a path (for empty or replacement), and path
+     *    contains segment that may be an array index (simple integer number like
+     *    {@code 3}), whether to construct an {@link ArrayNode} ({@code true}) or
+     *    {@link ObjectNode} ({@code false}). In latter case matching property with
+     *    quoted number (like {@code "3"}) is used within Object.
      *
-     * @return ObjectNode found or created
+     * @return {@link ObjectNode} found or created
+     *
+     * @throws UnsupportedOperationException if a conversion would be needed for given
+     *    {@code JsonPointer}, document, but was not allowed for the type encountered
      *
      * @since 2.14
      */
@@ -1172,26 +1231,116 @@ public ObjectNode withObject(JsonPointer ptr,
     }
 
     /**
-     * @deprecated Since 2.14 use {@code withObject} instead
+     * @deprecated Since 2.14 use {@code withObject(String)} instead
      */
+    @SuppressWarnings("unchecked")
     @Deprecated // since 2.14
     public final <T extends JsonNode> T with(String propertyName) {
-        return withObject(propertyName);
+        return (T) withObject(propertyName);
     }
 
     /**
-     * Method that can be called on Object nodes, to access a property
+     * Method that can be called on {@link ObjectNode} nodes, to access a property
      * that has <code>Array</code> value; or if no such property exists, to create,
      * add and return such Array node.
      * If the node method is called on is not Object node,
      * or if property exists and has value that is not Array node,
      * {@link UnsupportedOperationException} is thrown
+     *
+     * @param propertyName Name of property for the {@link ArrayNode}
+     *
+     * @return {@link ArrayNode} found or created
      */
     public <T extends JsonNode> T withArray(String propertyName) {
         throw new UnsupportedOperationException("JsonNode not of type ObjectNode (but "
                 +getClass().getName()+"), cannot call withArray() on it");
     }
 
+    /**
+     * Same as {@link #withArray(JsonPointer, OverwriteMode, boolean)} but
+     * with defaults of {@code OvewriteMode#NULLS} (overwrite mode)
+     * and {@code true} for {@code preferIndex}.
+     *
+     * @param ptr Pointer that indicates path to use for {@link ArrayNode} to return
+     *   (potentially creating as necessary)
+     *
+     * @return {@link ArrayNode} found or created
+     *
+     * @since 2.14
+     */
+    public final ArrayNode withArray(JsonPointer ptr) {
+        return withArray(ptr, OverwriteMode.NULLS, true);
+    }
+
+    /**
+     * Method that can be called on Object or Array nodes, to access a Array-valued
+     * node pointed to by given {@link JsonPointer}, if such a node exists:
+     * or if not, an attempt is made to create one and return it.
+     * For example, on document
+     *<pre>
+     *  { "a" : {
+     *       "b" : [ 1, 2 ]
+     *    }
+     *  }
+     *</pre>
+     * calling method with {@link JsonPointer} of {@code /a/b} would return
+     * {@code Array}
+     *<pre>
+     *  [ 1, 2 ]
+     *</pre>
+     *<p>
+     * In cases where path leads to "missing" nodes, a path is created.
+     * So, for example, on above document, and
+     * {@link JsonPointer} of {@code /a/x} an empty {@code ArrayNode} would
+     * be returned and the document would look like:
+     *<pre>
+     *  { "a" : {
+     *       "b" : [ 1, 2 ],
+     *       "x" : [ ]
+     *    }
+     *  }
+     *</pre>
+     * Finally, if the path is incompatible with the document -- there is an existing
+     * {@code JsonNode} through which expression cannot go -- a replacement is
+     * attempted if (and only if) conversion is allowed as per {@code overwriteMode}
+     * passed in. For example, with above document and expression of {@code /a/b/0},
+     * conversion is allowed if passing {@code OverwriteMode.SCALARS} or
+     * {@code OvewriteMode.ALL}, and resulting document would look like:
+     *<pre>
+     *  { "a" : {
+     *       "b" : [ [ ], 2 ],
+     *       "x" : [ ]
+     *    }
+     *  }
+     *</pre>
+     * but if different modes ({@code NONE} or {@code NULLS}) is passed, an exception
+     * is thrown instead.
+     *
+     * @param ptr Pointer that indicates path to use for {@link ArrayNode} value to return
+     *   (potentially creating it as necessary)
+     * @param overwriteMode Defines which node types may be converted in case of
+     *    incompatible {@code JsonPointer} expression: if conversion not allowed,
+     *    an exception is thrown.
+     * @param preferIndex When creating a path (for empty or replacement), and path
+     *    contains segment that may be an array index (simple integer number like
+     *    {@code 3}), whether to construct an {@link ArrayNode} ({@code true}) or
+     *    {@link ObjectNode} ({@code false}). In latter case matching property with
+     *    quoted number (like {@code "3"}) is used within Object.
+     *
+     * @return {@link ArrayNode} found or created
+     *
+     * @throws UnsupportedOperationException if a conversion would be needed for given
+     *    {@code JsonPointer}, document, but was not allowed for the type encountered
+     *
+     * @since 2.14
+     */
+    public ArrayNode withArray(JsonPointer ptr,
+            OverwriteMode overwriteMode, boolean preferIndex) {
+        // To avoid abstract method, base implementation just fails
+        throw new UnsupportedOperationException("`withArray(JsonPointer)` not implemented by "
+                +getClass().getName());
+    }
+
     /*
     /**********************************************************
     /* Public API, comparison

src/main/java/com/fasterxml/jackson/databind/node/ArrayNode.java

@@ -65,6 +65,12 @@ public ArrayNode deepCopy()
         return ret;
     }
 
+    /*
+    /**********************************************************
+    /* Support for withArray()/withObject()
+    /**********************************************************
+     */
+
     @Override
     protected ObjectNode _withObject(JsonPointer origPtr,
             JsonPointer currentPtr,
@@ -83,14 +89,35 @@ protected ObjectNode _withObject(JsonPointer origPtr,
                 return found;
             }
             // Ok no; must replace if allowed to
-            if (!_withObjectMayReplace(n, overwriteMode)) {
-                _withObjectVerifyReplace(origPtr, currentPtr, overwriteMode, preferIndex, n);
-            }
+            _withXxxVerifyReplace(origPtr, currentPtr, overwriteMode, preferIndex, n);
         }
         // Either way; must replace or add a new property
         return _withObjectAddTailElement(currentPtr, preferIndex);
     }
 
+    @Override
+    protected ArrayNode _withArray(JsonPointer origPtr,
+            JsonPointer currentPtr,
+            OverwriteMode overwriteMode, boolean preferIndex)
+    {
+        if (currentPtr.matches()) {
+            return this;
+        }
+        JsonNode n = _at(currentPtr);
+        // If there's a path, follow it
+        if ((n != null) && (n instanceof BaseJsonNode)) {
+            ArrayNode found = ((BaseJsonNode) n)._withArray(origPtr, currentPtr.tail(),
+                    overwriteMode, preferIndex);
+            if (found != null) {
+                return found;
+            }
+            // Ok no; must replace if allowed to
+            _withXxxVerifyReplace(origPtr, currentPtr, overwriteMode, preferIndex, n);
+        }
+        // Either way; must replace or add a new property
+        return _withArrayAddTailElement(currentPtr, preferIndex);
+    }
+
     protected ObjectNode _withObjectAddTailElement(JsonPointer tail, boolean preferIndex)
     {
         final int index = tail.getMatchingIndex();
@@ -99,22 +126,45 @@ protected ObjectNode _withObjectAddTailElement(JsonPointer tail, boolean preferI
         // First: did we complete traversal? If so, easy, we got our result
         if (tail.matches()) {
             ObjectNode result = this.objectNode();
-            _withObjectSetArrayElement(index, result);
+            _withXxxSetArrayElement(index, result);
             return result;
         }
 
         // Otherwise, do we want Array or Object
         if (preferIndex && tail.mayMatchElement()) { // array!
             ArrayNode next = this.arrayNode();
-            _withObjectSetArrayElement(index, next);
+            _withXxxSetArrayElement(index, next);
             return next._withObjectAddTailElement(tail, preferIndex);
         }
         ObjectNode next = this.objectNode();
-        _withObjectSetArrayElement(index, next);
+        _withXxxSetArrayElement(index, next);
         return next._withObjectAddTailProperty(tail, preferIndex);
     }
 
-    protected void _withObjectSetArrayElement(int index, JsonNode value) {
+    protected ArrayNode _withArrayAddTailElement(JsonPointer tail, boolean preferIndex)
+    {
+        final int index = tail.getMatchingIndex();
+        tail = tail.tail();
+
+        // First: did we complete traversal? If so, easy, we got our result
+        if (tail.matches()) {
+            ArrayNode result = this.arrayNode();
+            _withXxxSetArrayElement(index, result);
+            return result;
+        }
+
+        // Otherwise, do we want Array or Object
+        if (preferIndex && tail.mayMatchElement()) { // array!
+            ArrayNode next = this.arrayNode();
+            _withXxxSetArrayElement(index, next);
+            return next._withArrayAddTailElement(tail, preferIndex);
+        }
+        ArrayNode next = this.arrayNode();
+        _withXxxSetArrayElement(index, next);
+        return next._withArrayAddTailElement(tail, preferIndex);
+    }
+
+    protected void _withXxxSetArrayElement(int index, JsonNode value) {
         // 27-Jul-2022, tatu: Let's make it less likely anyone OOMs by
         //    humongous index...
         if (index >= size()) {