Fix #4991: add/update JsonNode.xxxValue() for non-number scalars (#5007)

Author: cowtowncoder

release-notes/VERSION

@@ -100,6 +100,8 @@ Versions: 3.x (for earlier see VERSION-2.x)
 #4956: Rename `JsonNode.isContainerNode()` as `isContainerNode()`
 #4958: Extend, improve set of number value accessors for `JsonNode`
   (`JsonNode.intValue()` etc) [JSTEP-3]
+#4991: Extend, improve set of non-number scalar value accessors for `JsonNode`
+  (`JsonNode.booleanValue()` etc) [JSTEP-3]
 #4992: Rename `JsonNodeFactory.textNode()` as `JsonNodeFactory.stringNode()` [JSTEP-3]
 #5004: Add `JsonMapper.builderWithJackson2Defaults()`
  (fixed by @pjfanning)

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

@@ -541,18 +541,47 @@ public Optional<JsonNode> asOptional() {
     // // Scalar access: Strings
 
     /**
-     * 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 #isString} returns
-     * false) null will be returned.
-     * For String values, null is never returned (but empty Strings may be)
+     * Method that will try to access value of this node as a Java {@code String}
+     * which works if (and only if) node contains JSON String value:
+     * if not, a {@link JsonNodeException} will be thrown.
+     *<p>
+     * NOTE: for more lenient conversions, use {@link #asString()}
      *<p>
      * NOTE: in Jackson 2.x, was {@code textValue()}.
      *
-     * @return String value this node contains, iff node is created from
-     *   a String value.
+     * @return {@code String} value this node represents (if JSON String)
+     *
+     * @throws JsonNodeException if node value is not a JSON String value
      */
-    public String stringValue() { return null; }
+    public abstract String stringValue();
+
+    /**
+     * Method similar to {@link #stringValue()}, but that will return specified
+     * {@code defaultValue} if this node does not contain a JSON String.
+     *
+     * @param defaultValue Value to return if this node does not contain a JSON String.
+     *
+     * @return Java {@code String} value this node represents (if JSON String);
+     *   {@code defaultValue} otherwise
+     */
+    public abstract String stringValue(String defaultValue);
+
+    /**
+     * Method similar to {@link #stringValue()}, but that will return
+     * {@code Optional.empty()} if this node does not contain a JSON String.
+     *
+     * @return {@code Optional<String>} value (if node represents JSON String);
+     *   {@code Optional.empty()} otherwise
+     */
+    public abstract Optional<String> stringValueOpt();
+
+    /**
+     * @deprecated Use {@link #asString()} instead.
+     */
+    @Deprecated // since 3.0
+    public final String textValue() {
+        return stringValue();
+    }
 
     /**
      * Method that will return a valid String representation of
@@ -595,29 +624,53 @@ public String asText(String defaultValue) {
     // // Scalar access: Binary
 
     /**
-     * Method to use for accessing binary content of binary nodes (nodes
-     * 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.
+     * Method that will try to access value of this node as binary value (Java {@code byte[]})
+     * which works if (and only if) node contains binary value (for JSON, Base64-encoded
+     * String, for other formats native binary value): if not,
+     * a {@link JsonNodeException} will be thrown.
+     * To check if this method can be used, you may call {@link #isBinary()}.
+     *<p>
+     * @return Binary value this node represents (if node contains binary value)
      *
-     * @return Binary data this node contains, iff it is a binary
-     *   node; null otherwise
+     * @throws JsonNodeException if node does not contain a Binary value (a
      */
     public abstract byte[] binaryValue();
 
     // // Scalar access: Boolean
 
     /**
-     * Method to use for accessing JSON boolean values (value
-     * literals 'true' and 'false').
-     * For other types, always returns false.
+     * Method that will try to access value of this node as a Java {@code boolean}
+     * which works if (and only if) node contains JSON boolean value: if not,
+     * a {@link JsonNodeException} will be thrown.
+     *<p>
+     * NOTE: for more lenient conversions, use {@link #asBoolean()}
+     *
+     * @return {@code boolean} value this node represents (if JSON boolean)
      *
-     * @return Boolean value this node contains, if any; false for
-     *   non-boolean nodes.
+     * @throws JsonNodeException if node does not represent a JSON boolean value
      */
     public abstract boolean booleanValue();
 
+    /**
+     * Method similar to {@link #booleanValue()}, but that will return specified
+     * {@code defaultValue} if this node does not contain a JSON boolean.
+     *
+     * @param defaultValue Value to return if this node does not contain a JSON boolean.
+     *
+     * @return Java {@code boolean} value this node represents (if JSON boolean);
+     *   {@code defaultValue} otherwise
+     */
+    public abstract boolean booleanValue(boolean defaultValue);
+
+    /**
+     * Method similar to {@link #booleanValue()}, but that will return
+     * {@code Optional.empty()} if this node does not contain a JSON boolean.
+     *
+     * @return {@code Optional<Boolean>} value (if node represents JSON boolean);
+     *   {@code Optional.empty()} otherwise
+     */
+    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

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

@@ -193,12 +193,25 @@ public BigDecimal asDecimal(BigDecimal defaultValue) {
 
     @Override
     public byte[] binaryValue() {
-        return null;
+        return _reportCoercionFail("binaryValue()", Boolean.TYPE,
+                "value type not binary (or convertible to binary via Base64-decoding)");
     }
 
     @Override
     public boolean booleanValue() {
-        return false;
+        return _reportCoercionFail("booleanValue()", Boolean.TYPE, "value type not boolean");
+    }
+
+    @Override
+    public boolean booleanValue(boolean defaultValue) {
+        // Overridden by BooleanNode, for other types return default
+        return defaultValue;
+    }
+
+    @Override
+    public Optional<Boolean> booleanValueOpt() {
+        // Overridden by BooleanNode, for other types return default
+        return Optional.empty();
     }
 
     @Override
@@ -211,6 +224,23 @@ public boolean asBoolean(boolean defaultValue) {
         return defaultValue;
     }
 
+    @Override
+    public String stringValue() {
+        return _reportCoercionFail("stringValue()", String.class, "value type not String");
+    }
+
+    @Override
+    public String stringValue(String defaultValue) {
+        // Overridden by StringNode, for other types return default
+        return defaultValue;
+    }
+
+    @Override
+    public Optional<String> stringValueOpt() {
+        // Overridden by StringNode, for other types return default
+        return Optional.empty();
+    }
+
     @Override
     public String asString(String defaultValue) {
         String str = asString();

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

@@ -87,7 +87,13 @@ public JsonToken asToken() {
     protected String _valueDesc() {
         return "[...(" + _data.length + " bytes)]";
     }
-    
+
+    /*
+    /**********************************************************************
+    /* Overridden JsonNode methods, scalar access
+    /**********************************************************************
+     */
+
     /**
      *<p>
      * Note: caller is not to modify returned array in any way, since
@@ -105,6 +111,12 @@ public String asString() {
         return Base64Variants.getDefaultVariant().encode(_data, false);
     }
 
+    /*
+    /**********************************************************************
+    /* Overridden JsonNode methods, other
+    /**********************************************************************
+     */
+
     @Override
     public final void serialize(JsonGenerator g, SerializationContext provider)
         throws JacksonException

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

@@ -1,5 +1,7 @@
 package tools.jackson.databind.node;
 
+import java.util.Optional;
+
 import tools.jackson.core.*;
 import tools.jackson.databind.SerializationContext;
 
@@ -18,6 +20,9 @@ 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;
 
     /*
@@ -61,14 +66,25 @@ protected String _valueDesc() {
     @Override
     public BooleanNode deepCopy() { return this; }
 
+    /*
+    /**********************************************************************
+    /* Overridden JsonNode methods, scalar access
+    /**********************************************************************
+     */
+
     @Override
     public boolean booleanValue() {
         return _value;
     }
 
     @Override
-    public String asString() {
-        return _value ? "true" : "false";
+    public boolean booleanValue(boolean defaultValue) {
+        return _value;
+    }
+
+    @Override
+    public Optional<Boolean> booleanValueOpt() {
+        return _value ? OPT_TRUE : OPT_FALSE;
     }
 
     @Override
@@ -94,6 +110,17 @@ public double asDouble(double defaultValue) {
         return _value ? 1.0 : 0.0;
     }
 
+    @Override
+    public String asString() {
+        return _value ? "true" : "false";
+    }
+
+    /*
+    /**********************************************************************
+    /* Overridden JsonNode methods, other
+    /**********************************************************************
+     */
+
     @Override
     public final void serialize(JsonGenerator g, SerializationContext provider)
             throws JacksonException {

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

@@ -150,6 +150,12 @@ public boolean asBoolean(boolean defaultValue) {
         return _value != 0;
     }
 
+    /*
+    /**********************************************************************
+    /* Overridden JsonNode methods, other
+    /**********************************************************************
+     */
+    
     @Override
     public final void serialize(JsonGenerator g, SerializationContext provider)
         throws JacksonException

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

@@ -1,12 +1,12 @@
 package tools.jackson.databind.node;
 
 import java.util.Objects;
+import java.util.Optional;
 
 import tools.jackson.core.*;
 import tools.jackson.core.io.NumberInput;
 import tools.jackson.core.util.ByteArrayBuilder;
 import tools.jackson.databind.SerializationContext;
-import tools.jackson.databind.exc.InvalidFormatException;
 
 /**
  * Value node that contains a String value.
@@ -64,11 +64,27 @@ protected String _valueDesc() {
     @Override
     public StringNode deepCopy() { return this; }
 
+    /*
+    /**********************************************************************
+    /* Overridden JsonNode methods, scalar access
+    /**********************************************************************
+     */
+
     @Override
     public String stringValue() {
         return _value;
     }
 
+    @Override
+    public String stringValue(String defaultValue) {
+        return _value;
+    }
+
+    @Override
+    public Optional<String> stringValueOpt() {
+        return Optional.of(_value);
+    }
+
     /**
      * Method for accessing content String assuming they were
      * base64 encoded; if so, content is decoded and resulting binary
@@ -90,12 +106,8 @@ public byte[] getBinaryValue(Base64Variant b64variant) throws JacksonException
         try {
             b64variant.decode(str, builder);
         } catch (IllegalArgumentException e) {
-            throw InvalidFormatException.from(
-                    null, /* Alas, no processor to pass */
-                    String.format(
-"Cannot access contents of `StringNode` as binary due to broken Base64 encoding: %s",
-e.getMessage()),
-                    str, byte[].class);
+            return _reportCoercionFail("binaryValue()", byte[].class,
+                    "value type not binary and Base64-decoding failed with: "+e.getMessage());
         }
         return builder.toByteArray();
     }
@@ -105,34 +117,26 @@ public byte[] binaryValue() throws JacksonException {
         return getBinaryValue(Base64Variants.getDefaultVariant());
     }
 
-    /*
-    /**********************************************************************
-    /* General type coercions
-    /**********************************************************************
-     */
-
     @Override
     public String asString() {
         return _value;
     }
 
     @Override
     public String asString(String defaultValue) {
-        return (_value == null) ? defaultValue : _value;
+        return _value;
     }
 
     // note: neither fast nor elegant, but these work for now:
 
     @Override
     public boolean asBoolean(boolean defaultValue) {
-        if (_value != null) {
-            String v = _value.trim();
-            if ("true".equals(v)) {
-                return true;
-            }
-            if ("false".equals(v)) {
-                return false;
-            }
+        String v = _value.trim();
+        if ("true".equals(v)) {
+            return true;
+        }
+        if ("false".equals(v)) {
+            return false;
         }
         return defaultValue;
     }