Fix #4879 (#4880)

FasterXML · Jan 1, 2025 · 38b1f77 · 38b1f77
1 parent 1ba52b8
commit 38b1f77
Show file tree

Hide file tree

Showing 49 changed files with 306 additions and 281 deletions.
diff --git a/release-notes/VERSION b/release-notes/VERSION
@@ -87,6 +87,8 @@ Versions: 3.x (for earlier see VERSION-2.x)
 #4865: Add spliterator support in `JsonNode`
  (contributed by @pjfanning)
 #4875: Remove `JsonNode.fields()` from 3.0
+#4879: Rename `TextNode` as `StringNode`; `JsonNode.xxxTextYyy()` (mostly) as
+  `JsonNode.xxxStringYyy()` [JSTEP-3]
 - Remove `MappingJsonFactory`
 - Add context parameter for `TypeSerializer` contextualization (`forProperty()`)
 - Default for `JsonNodeFeature.STRIP_TRAILING_BIGDECIMAL_ZEROES` changed to `false` for 3.0
diff --git a/src/main/java/tools/jackson/databind/JsonNode.java b/src/main/java/tools/jackson/databind/JsonNode.java
@@ -200,7 +200,7 @@ public boolean isObject() {
      *   field. Null otherwise.
      */
     @Override
-    public JsonNode get(String fieldName) { return null; }
+    public JsonNode get(String propertyName) { return null; }
 
     /**
      * Method for accessing value of the specified element of
@@ -259,7 +259,7 @@ public boolean isObject() {
      */
 
     @Override
-    public abstract JsonNode path(String fieldName);
+    public abstract JsonNode path(String propertyName);
 
     /**
      * This method is similar to {@link #get(int)}, except
@@ -424,13 +424,21 @@ public final boolean isNumber() {
     public boolean isBigInteger() { return false; }
 
     /**
-     * Method that checks whether this node represents basic JSON String
+     * Method that checks whether this node represents JSON String
      * value.
      */
-    public final boolean isTextual() {
+    public final boolean isString() {
         return getNodeType() == JsonNodeType.STRING;
     }
 
+    /**
+     * @deprecated Use {@link #isString} instead.
+     */
+    @Deprecated // since 3.0
+    public boolean isTextual() {
+        return isString();
+    }
+
     /**
      * Method that can be used to check if this node was created from
      * JSON boolean value (literals "true" and "false").
@@ -451,7 +459,7 @@ public final boolean isNull() {
     /**
      * Method that can be used to check if this node represents
      * binary data (Base64 encoded). Although this will be externally
-     * written as JSON String value, {@link #isTextual} will
+     * written as JSON String value, {@link #isString} will
      * return false if this method returns true.
      *
      * @return True if this node represents base64 encoded binary data
@@ -522,19 +530,21 @@ public boolean canConvertToExactIntegral() {
     /**
      * Method to use for accessing String values.
      * Does <b>NOT</b> do any conversions for non-String value nodes;
-     * for non-String values (ones for which {@link #isTextual} returns
+     * for non-String values (ones for which {@link #isString} returns
      * false) null will be returned.
      * For String values, null is never returned (but empty Strings may be)
+     *<p>
+     * NOTE: in Jackson 2.x, was {@code textValue()}.
      *
-     * @return Textual value this node contains, iff it is a textual
-     *   JSON node (comes from JSON String value entry)
+     * @return String value this node contains, iff node is created from
+     *   a String value.
      */
-    public String textValue() { return null; }
+    public String stringValue() { return null; }
 
     /**
      * Method to use for accessing binary content of binary nodes (nodes
-     * for which {@link #isBinary} returns true); or for Text Nodes
-     * (ones for which {@link #textValue} returns non-null value),
+     * for which {@link #isBinary} returns true); or for String Nodes
+     * (ones for which {@link #stringValue} returns non-null value),
      * to read decoded base64 data.
      * For other types of nodes, returns null.
      *
@@ -652,11 +662,15 @@ public byte[] binaryValue() {
 
     /**
      * Method that will return a valid String representation of
-     * the container value, if the node is a value node
+     * the contained value, if the node is a value node
      * (method {@link #isValueNode} returns true),
      * otherwise empty String.
+     *<p>
+     * NOTE: this is NOT same as {@link #toString()} in that result is
+     * <p>NOT VALID ENCODED JSON</p> for all nodes (but is for some, like
+     * {@code NumberNode}s and {@code BooleanNode}s).
      */
-    public abstract String asText();
+    public abstract String asString();
 
     /**
      * Returns the text value of this node or the provided {@code defaultValue} if this node
@@ -666,11 +680,27 @@ public byte[] binaryValue() {
      * @param defaultValue The default value to return if this node's text value is absent.
      * @return The text value of this node, or {@code defaultValue} if the text value is absent.
      */
-    public String asText(String defaultValue) {
-        String str = asText();
+    public String asString(String defaultValue) {
+        String str = asString();
         return (str == null) ? defaultValue : str;
     }
 
+    /**
+     * @deprecated Use {@link #asString()} instead.
+     */
+    @Deprecated // since 3.0
+    public final String asText() {
+        return asString();
+    }
+
+    /**
+     * @deprecated Use {@link #asString(String)} instead.
+     */
+    @Deprecated // since 3.0
+    public String asText(String defaultValue) {
+        return asString(defaultValue);
+    }
+
     /**
      * Method that will try to convert value of this node to a Java <b>int</b>.
      * Numbers are coerced using default Java rules; booleans convert to 0 (false)
@@ -832,10 +862,10 @@ public <T extends JsonNode> T requireNonNull() {
     /**
      * Method is functionally equivalent to
      *{@code
-     *   path(fieldName).required()
+     *   path(propertyName).required()
      *}
      * and can be used to check that this node is an {@code ObjectNode} (that is, represents
-     * JSON Object value) and has value for specified property with key {@code fieldName}
+     * JSON Object value) and has value for specified property with key {@code propertyName}
      * (but note that value may be explicit JSON null value).
      * If this node is Object Node and has value for specified property, matching value
      * is returned; otherwise {@link IllegalArgumentException} is thrown.
@@ -943,20 +973,20 @@ public final JsonNode requiredAt(final JsonPointer path) {
      *<p>
      * This method is equivalent to:
      *<pre>
-     *   node.get(fieldName) != null
+     *   node.get(propertyName) != null
      *</pre>
      * (since return value of get() is node, not value node contains)
      *<p>
      * NOTE: when explicit <code>null</code> values are added, this
      * method will return <code>true</code> for such properties.
      *
-     * @param fieldName Name of element to check
+     * @param propertyName Name of element to check
      *
      * @return True if this node is a JSON Object node, and has a property
      *   entry with specified name (with any value, including null value)
      */
-    public boolean has(String fieldName) {
-        return get(fieldName) != null;
+    public boolean has(String propertyName) {
+        return get(propertyName) != null;
     }
 
     /**
@@ -991,13 +1021,11 @@ public boolean has(int index) {
      *<p>
      * This method is functionally equivalent to:
      *<pre>
-     *   node.get(fieldName) != null &amp;&amp; !node.get(fieldName).isNull()
+     *   node.get(propertyName) != null &amp;&amp; !node.get(propertyName).isNull()
      *</pre>
-     *
-     * @since 2.1
      */
-    public boolean hasNonNull(String fieldName) {
-        JsonNode n = get(fieldName);
+    public boolean hasNonNull(String propertyName) {
+        JsonNode n = get(propertyName);
         return (n != null) && !n.isNull();
     }
 
@@ -1009,8 +1037,6 @@ public boolean hasNonNull(String fieldName) {
      *<pre>
      *   node.get(index) != null &amp;&amp; !node.get(index).isNull()
      *</pre>
-     *
-     * @since 2.1
      */
     public boolean hasNonNull(int index) {
         JsonNode n = get(index);
@@ -1135,11 +1161,11 @@ public void forEachEntry(BiConsumer<? super String, ? super JsonNode> action) {
      * Note that traversal is done in document order (that is, order in which
      * nodes are iterated if using {@link JsonNode#values()})
      *
-     * @param fieldName Name of field to look for
+     * @param propertyName Name of field to look for
      *
      * @return Value of first matching node found, if any; null if none
      */
-    public abstract JsonNode findValue(String fieldName);
+    public abstract JsonNode findValue(String propertyName);
 
     /**
      * Method for finding JSON Object fields with specified name -- both immediate
@@ -1150,11 +1176,11 @@ public void forEachEntry(BiConsumer<? super String, ? super JsonNode> action) {
      * If no matching fields are found in this node or its descendants, returns
      * an empty List.
      *
-     * @param fieldName Name of field to look for
+     * @param propertyName Name of field to look for
      */
-    public final List<JsonNode> findValues(String fieldName)
+    public final List<JsonNode> findValues(String propertyName)
     {
-        List<JsonNode> result = findValues(fieldName, null);
+        List<JsonNode> result = findValues(propertyName, null);
         if (result == null) {
             return Collections.emptyList();
         }
@@ -1165,9 +1191,9 @@ public final List<JsonNode> findValues(String fieldName)
      * Similar to {@link #findValues}, but will additionally convert
      * values into Strings, calling {@link #asText}.
      */
-    public final List<String> findValuesAsText(String fieldName)
+    public final List<String> findValuesAsString(String propertyName)
     {
-        List<String> result = findValuesAsText(fieldName, null);
+        List<String> result = findValuesAsString(propertyName, null);
         if (result == null) {
             return Collections.emptyList();
         }
@@ -1181,45 +1207,45 @@ public final List<String> findValuesAsText(String fieldName)
      * returns true; and all value access methods return empty or
      * missing value.
      *
-     * @param fieldName Name of field to look for
+     * @param propertyName Name of field to look for
      *
      * @return Value of first matching node found; or if not found, a
      *    "missing node" (non-null instance that has no value)
      */
-    public abstract JsonNode findPath(String fieldName);
+    public abstract JsonNode findPath(String propertyName);
 
     /**
      * Method for finding a JSON Object that contains specified field,
      * within this node or its descendants.
      * If no matching field is found in this node or its descendants, returns null.
      *
-     * @param fieldName Name of field to look for
+     * @param propertyName Name of field to look for
      *
      * @return Value of first matching node found, if any; null if none
      */
-    public abstract JsonNode findParent(String fieldName);
+    public abstract JsonNode findParent(String propertyName);
 
     /**
      * Method for finding a JSON Object that contains specified field,
      * within this node or its descendants.
      * If no matching field is found in this node or its descendants, returns null.
      *
-     * @param fieldName Name of field to look for
+     * @param propertyName Name of field to look for
      *
      * @return Value of first matching node found, if any; null if none
      */
-    public final List<JsonNode> findParents(String fieldName)
+    public final List<JsonNode> findParents(String propertyName)
     {
-        List<JsonNode> result = findParents(fieldName, null);
+        List<JsonNode> result = findParents(propertyName, null);
         if (result == null) {
             return Collections.emptyList();
         }
         return result;
     }
 
-    public abstract List<JsonNode> findValues(String fieldName, List<JsonNode> foundSoFar);
-    public abstract List<String> findValuesAsText(String fieldName, List<String> foundSoFar);
-    public abstract List<JsonNode> findParents(String fieldName, List<JsonNode> foundSoFar);
+    public abstract List<JsonNode> findValues(String propertyName, List<JsonNode> foundSoFar);
+    public abstract List<String> findValuesAsString(String propertyName, List<String> foundSoFar);
+    public abstract List<JsonNode> findParents(String propertyName, List<JsonNode> foundSoFar);
 
     /*
     /**********************************************************************

diff --git a/src/main/java/tools/jackson/databind/node/ArrayNode.java b/src/main/java/tools/jackson/databind/node/ArrayNode.java
@@ -361,10 +361,10 @@ public List<JsonNode> findValues(String propertyName, List<JsonNode> foundSoFar)
     }
 
     @Override
-    public List<String> findValuesAsText(String propertyName, List<String> foundSoFar)
+    public List<String> findValuesAsString(String propertyName, List<String> foundSoFar)
     {
         for (JsonNode node : _children) {
-            foundSoFar = node.findValuesAsText(propertyName, foundSoFar);
+            foundSoFar = node.findValuesAsString(propertyName, foundSoFar);
         }
         return foundSoFar;
     }

diff --git a/src/main/java/tools/jackson/databind/node/BigIntegerNode.java b/src/main/java/tools/jackson/databind/node/BigIntegerNode.java
@@ -93,7 +93,7 @@ public Number numberValue() {
      */
 
     @Override
-    public String asText() {
+    public String asString() {
         return _value.toString();
     }
 

diff --git a/src/main/java/tools/jackson/databind/node/BinaryNode.java b/src/main/java/tools/jackson/databind/node/BinaryNode.java
@@ -84,7 +84,7 @@ public JsonToken asToken() {
      * but will work correctly.
      */
     @Override
-    public String asText() {
+    public String asString() {
         return Base64Variants.getDefaultVariant().encode(_data, false);
     }
 

diff --git a/src/main/java/tools/jackson/databind/node/BooleanNode.java b/src/main/java/tools/jackson/databind/node/BooleanNode.java
@@ -62,7 +62,7 @@ public boolean booleanValue() {
     }
 
     @Override
-    public String asText() {
+    public String asString() {
         return _value ? "true" : "false";
     }
 

diff --git a/src/main/java/tools/jackson/databind/node/ContainerNode.java b/src/main/java/tools/jackson/databind/node/ContainerNode.java
@@ -38,7 +38,7 @@ protected ContainerNode(JsonNodeFactory nc) {
     public abstract JsonToken asToken();
 
     @Override
-    public String asText() { return ""; }
+    public String asString() { return ""; }
 
     /*
     /**********************************************************************
@@ -145,7 +145,7 @@ public final NumericNode numberNode(long v) {
     public final ValueNode numberNode(Double v) { return _nodeFactory.numberNode(v); }
 
     @Override
-    public final TextNode textNode(String text) { return _nodeFactory.textNode(text); }
+    public final StringNode textNode(String text) { return _nodeFactory.textNode(text); }
 
     @Override
     public final BinaryNode binaryNode(byte[] data) { return _nodeFactory.binaryNode(data); }

diff --git a/src/main/java/tools/jackson/databind/node/DecimalNode.java b/src/main/java/tools/jackson/databind/node/DecimalNode.java
@@ -103,7 +103,7 @@ public BigInteger bigIntegerValue() {
     public BigDecimal decimalValue() { return _value; }
 
     @Override
-    public String asText() {
+    public String asString() {
         return _value.toString();
     }
 

diff --git a/src/main/java/tools/jackson/databind/node/DoubleNode.java b/src/main/java/tools/jackson/databind/node/DoubleNode.java
@@ -93,7 +93,7 @@ public BigInteger bigIntegerValue() {
     }
 
     @Override
-    public String asText() {
+    public String asString() {
         return String.valueOf(_value);
     }
 

diff --git a/src/main/java/tools/jackson/databind/node/FloatNode.java b/src/main/java/tools/jackson/databind/node/FloatNode.java
@@ -93,7 +93,7 @@ public BigInteger bigIntegerValue() {
     }
 
     @Override
-    public String asText() {
+    public String asString() {
         return String.valueOf(_value);
     }
 

diff --git a/src/main/java/tools/jackson/databind/node/IntNode.java b/src/main/java/tools/jackson/databind/node/IntNode.java
@@ -100,7 +100,7 @@ public Number numberValue() {
     public BigInteger bigIntegerValue() { return BigInteger.valueOf(_value); }
 
     @Override
-    public String asText() {
+    public String asString() {
         return String.valueOf(_value);
     }
 

diff --git a/src/main/java/tools/jackson/databind/node/JsonNodeFactory.java b/src/main/java/tools/jackson/databind/node/JsonNodeFactory.java
@@ -241,7 +241,7 @@ public ValueNode numberNode(BigDecimal v)
      * String value
      */
     @Override
-    public TextNode textNode(String text) { return TextNode.valueOf(text); }
+    public StringNode textNode(String text) { return StringNode.valueOf(text); }
 
     /**
      * Factory method for constructing a node that represents given