Fix #5034: re-write JsonNode.asBoolean(), .asString(), variants (#5042)

Author: cowtowncoder

release-notes/VERSION

@@ -111,6 +111,8 @@ Versions: 3.x (for earlier see VERSION-2.x)
 #5025: Add support for automatic detection of subtypes (like `@JsonSubTypes`)
   from Java 17 sealed types
  (contributed by Andy B
+#5034: Extend, improve set of `JsonNode.asXxx()` methods for non-number
+  types (Boolean, String)
 - Remove `MappingJsonFactory`
 - Add context parameter for `TypeSerializer` contextualization (`forProperty()`)
 - Default for `JsonNodeFeature.STRIP_TRAILING_BIGDECIMAL_ZEROES` changed to `false` for 3.0

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

@@ -584,27 +584,35 @@ public final String textValue() {
     }
 
     /**
-     * Method that will return a valid String representation of
-     * the contained value, if the node is a value node
-     * (method {@link #isValueNode} returns true),
-     * otherwise empty String.
+     * Method that will try to convert value of this node to a {@code String}.
+     * JSON Strings map naturally; other scalars map to their string representation
+     * (including Binary data as Base64 encoded String);
+     * JSON {@code null}s map to empty String.
+     * Other values (including structured types like Objects and Arrays, and "missing"
+     * value) will result in a {@link JsonNodeException} being thrown.
      *<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
+     * <p>NOT VALID ENCODED JSON</p> for all nodes (although is for some, like
      * {@code NumberNode}s and {@code BooleanNode}s).
+     *
+     * @return String representation of this node, if coercible; exception otherwise
+     *
+     * @throws JsonNodeException if node cannot be coerced to a {@code String}
      */
     public abstract String asString();
 
     /**
-     * Returns the text value of this node or the provided {@code defaultValue} if this node
-     * does not have a text value. Useful for nodes that are {@link MissingNode} or
-     * {@link tools.jackson.databind.node.NullNode}, ensuring a default value is returned instead of null or missing indicators.
-     *
-     * @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.
+     * Similar to {@link #asString()}, but instead of throwing an exception for
+     * non-coercible values, will return specified default value.
      */
     public abstract String asString(String defaultValue);
 
+    /**
+     * Similar to {@link #asString()}, but instead of throwing an exception for
+     * non-coercible values, will return {@code Optional.empty()}.
+     */
+    public abstract Optional<String> asStringOpt();
+
     /**
      * @deprecated Use {@link #asString()} instead.
      */
@@ -672,29 +680,31 @@ public String asText(String defaultValue) {
     public abstract Optional<Boolean> booleanValueOpt();
 
     /**
-     * Method that will try to convert value of this node to a Java <b>boolean</b>.
-     * JSON booleans map naturally; integer numbers other than 0 map to true, and
-     * 0 maps to false
+     * Method that will try to convert value of this node to a Java {@code boolean}.
+     * JSON Booleans map naturally; Integer numbers other than 0 map to true, and
+     * 0 maps to false; {@code null} maps to false
      * and Strings 'true' and 'false' map to corresponding values.
-     *<p>
-     * If representation cannot be converted to a boolean value (including structured types
-     * like Objects and Arrays),
-     * default value of <b>false</b> will be returned; no exceptions are thrown.
+     * Other values (including structured types like Objects and Arrays) will
+     * result in a {@link JsonNodeException} being thrown.
+     *
+     * @return Boolean value this node represents, if coercible; exception otherwise
+     *
+     * @throws JsonNodeException if node cannot be coerced to a Java {@code boolean}
      */
     public abstract boolean asBoolean();
 
     /**
-     * Method that will try to convert value of this node to a Java <b>boolean</b>.
-     * JSON booleans map naturally; integer numbers other than 0 map to true, and
-     * 0 maps to false
-     * and Strings 'true' and 'false' map to corresponding values.
-     *<p>
-     * If representation cannot be converted to a boolean value (including structured types
-     * like Objects and Arrays),
-     * specified <b>defaultValue</b> will be returned; no exceptions are thrown.
+     * Similar to {@link #asBoolean()}, but instead of throwing an exception for
+     * non-coercible values, will return specified default value.
      */
     public abstract boolean asBoolean(boolean defaultValue);
 
+    /**
+     * Similar to {@link #asBoolean()}, but instead of throwing an exception for
+     * non-coercible values, will return {@code Optional.empty()}.
+     */
+    public abstract Optional<Boolean> asBooleanOpt();
+
     // // Scalar access: Numbers, generic
 
     /**

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

@@ -19,10 +19,7 @@ protected ThreadGroupDeserializer() {
 
     @Override
     public ThreadGroup convert(JsonNode root, DeserializationContext ctxt) {
-        String name = root.path("name").asString();
-        if (name == null) {
-            name = "";
-        }
+        String name = root.path("name").asString("");
         return new ThreadGroup(name);
     }
 }

src/main/java/tools/jackson/databind/node/BaseJsonNode.java

@@ -32,6 +32,9 @@ public abstract class BaseJsonNode
 {
     private static final long serialVersionUID = 3L;
 
+    protected final static Optional<Boolean> OPT_FALSE = Optional.of(false);
+    protected final static Optional<Boolean> OPT_TRUE = Optional.of(true);
+
     // Simplest way is by using a helper
     Object writeReplace() {
         return NodeSerialization.from(this);
@@ -199,7 +202,8 @@ public byte[] binaryValue() {
 
     @Override
     public boolean booleanValue() {
-        return _reportCoercionFail("booleanValue()", Boolean.TYPE, "value type not boolean");
+        return _reportCoercionFail("booleanValue()", Boolean.TYPE,
+                "value type not boolean");
     }
 
     @Override
@@ -216,17 +220,36 @@ public Optional<Boolean> booleanValueOpt() {
 
     @Override
     public boolean asBoolean() {
-        return asBoolean(false);
+        Boolean b = _asBoolean();
+        if (b == null) {
+            return _reportCoercionFail("asBoolean()", Boolean.TYPE,
+                    "value type not coercible to `boolean`");
+        }
+        return b;
     }
 
     @Override
     public boolean asBoolean(boolean defaultValue) {
-        return defaultValue;
+        Boolean b = _asBoolean();
+        if (b == null) {
+            return defaultValue;
+        }
+        return b;
+    }
+
+    @Override
+    public Optional<Boolean> asBooleanOpt() {
+        Boolean b = _asBoolean();
+        if (b == null) {
+            return Optional.empty();
+        }
+        return b.booleanValue() ? OPT_TRUE : OPT_FALSE;
     }
 
     @Override
     public String stringValue() {
-        return _reportCoercionFail("stringValue()", String.class, "value type not String");
+        return _reportCoercionFail("stringValue()", String.class,
+                "value type not String");
     }
 
     @Override
@@ -241,10 +264,28 @@ public Optional<String> stringValueOpt() {
         return Optional.empty();
     }
 
+    @Override
+    public String asString() {
+        String str = _asString();
+        if (str == null) {
+            return _reportCoercionFail("asString()", String.class,
+                    "value type not coercible to `String`");
+        }
+        return str;
+    }
+
     @Override
     public String asString(String defaultValue) {
-        String str = asString();
-        return (str == null) ? defaultValue : str;
+        String str = _asString();
+        if (str == null) {
+            return defaultValue;
+        }
+        return str;
+    }
+
+    @Override
+    public Optional<String> asStringOpt() {
+        return Optional.ofNullable(_asString());
     }
 
     /*
@@ -264,7 +305,8 @@ public final JsonNode findPath(String fieldName)
     }
 
     // Also, force (re)definition
-    @Override public abstract int hashCode();
+    @Override
+    public abstract int hashCode();
 
     /*
     /**********************************************************************
@@ -417,6 +459,36 @@ protected ArrayNode _withArray(JsonPointer origPtr,
         return null;
     }
 
+    /*
+    /**********************************************************************
+    /* asXxx() helper methods for sub-classes to implement
+    /**********************************************************************
+     */
+
+    /**
+     * Method sub-classes should override if they can produce {@code boolean}
+     * values via {@link #asBoolean()} -- if not, return {@code null} (in which
+     * case appropriate error will be thrown or default value returned).
+     *
+     * @return Coerced value if possible; otherwise {@code null} to indicate this
+     *     node cannot be coerced.
+     */
+    protected Boolean _asBoolean() {
+        return null;
+    }
+
+    /**
+     * Method sub-classes should override if they can produce {@code String}
+     * values via {@link #asString()} -- if not, return {@code null} (in which
+     * case appropriate error will be thrown or default value returned).
+     *
+     * @return Coerced value if possible; otherwise {@code null} to indicate this
+     *     node cannot be coerced.
+     */
+    protected String _asString() {
+        return null;
+    }
+
     /*
     /**********************************************************************
     /* JacksonSerializable

src/main/java/tools/jackson/databind/node/BigIntegerNode.java

@@ -75,7 +75,17 @@ public BigIntegerNode(BigInteger v) {
     /* Overridden JsonNode methods, scalar access
     /**********************************************************************
      */
-    
+
+    @Override
+    protected Boolean _asBoolean() {
+        return !BigInteger.ZERO.equals(_value);
+    }
+
+    @Override
+    public String _asString() {
+        return _value.toString();
+    }
+
     @Override
     public Number numberValue() {
         return _value;
@@ -185,22 +195,6 @@ public Optional<BigDecimal> decimalValueOpt() {
         return Optional.of(new BigDecimal(_value));
     }
 
-    /*
-    /**********************************************************
-    /* General type coercions
-    /**********************************************************
-     */
-
-    @Override
-    public String asString() {
-        return _value.toString();
-    }
-
-    @Override
-    public boolean asBoolean(boolean defaultValue) {
-        return !BigInteger.ZERO.equals(_value);
-    }
-
     /*
     /**********************************************************
     /* Other overrides

src/main/java/tools/jackson/databind/node/BinaryNode.java

@@ -107,7 +107,7 @@ protected String _valueDesc() {
      * but will work correctly.
      */
     @Override
-    public String asString() {
+    protected String _asString() {
         return Base64Variants.getDefaultVariant().encode(_data, false);
     }
 

src/main/java/tools/jackson/databind/node/BooleanNode.java

@@ -19,9 +19,6 @@ public class BooleanNode
 
     public final static BooleanNode TRUE = new BooleanNode(true);
     public final static BooleanNode FALSE = new BooleanNode(false);
-
-    private final static Optional<Boolean> OPT_FALSE = Optional.of(false);
-    private final static Optional<Boolean> OPT_TRUE = Optional.of(true);
 
     private final boolean _value;
 
@@ -72,31 +69,48 @@ protected String _valueDesc() {
     /**********************************************************************
      */
 
+    // // // Override "asBoolean()" methods as minor optimization
+    
     @Override
-    public boolean booleanValue() {
+    public final boolean asBoolean() {
         return _value;
     }
 
     @Override
-    public boolean booleanValue(boolean defaultValue) {
+    public final boolean asBoolean(boolean defaultValue) {
         return _value;
     }
 
     @Override
-    public Optional<Boolean> booleanValueOpt() {
+    public Optional<Boolean> asBooleanOpt() {
         return _value ? OPT_TRUE : OPT_FALSE;
     }
+    
+    @Override
+    protected Boolean _asBoolean() {
+        return _value;
+    }
 
     @Override
-    public boolean asBoolean() {
+    public boolean booleanValue() {
         return _value;
     }
 
     @Override
-    public boolean asBoolean(boolean defaultValue) {
+    public boolean booleanValue(boolean defaultValue) {
         return _value;
     }
 
+    @Override
+    public Optional<Boolean> booleanValueOpt() {
+        return _value ? OPT_TRUE : OPT_FALSE;
+    }
+
+    @Override
+    protected String _asString() {
+        return _value ? "true" : "false";
+    }
+    
     @Override
     public int asInt(int defaultValue) {
         return _value ? 1 : 0;
@@ -110,11 +124,6 @@ public double asDouble(double defaultValue) {
         return _value ? 1.0 : 0.0;
     }
 
-    @Override
-    public String asString() {
-        return _value ? "true" : "false";
-    }
-
     /*
     /**********************************************************************
     /* Overridden JsonNode methods, other

src/main/java/tools/jackson/databind/node/ContainerNode.java

@@ -43,9 +43,6 @@ public boolean isContainer() {
     @Override
     public abstract JsonToken asToken();
 
-    @Override
-    public String asString() { return ""; }
-
     /*
     /**********************************************************************
     /* Methods reset as abstract to force real implementation