Extend, improve set of scalar value accessors for JsonNode (JsonNode.asInt() etc) for 3.0 [JSTEP-3]

[cowtowncoder]

As explained on https://github.com/FasterXML/jackson-future-ideas/wiki/JSTEP-3 we want to improve and extend the set of Scalar value accessors like asInt() for Jackson 3.0.

As of 2.x, there are a few accessors for type like, say, int:

• intValue(): return int if (and only if!) we got numeric integer node (JsonToken.VALUE_NUMBER_INT) -- but won't throw exception, returns default value (0) otherwise
• asInt(): same as asInt(0)
• asInt(int defaultValue): return int value from JsonToken.VALUE_NUMBER_INT (if within value range) OR if coercible (from double or String); otherwise return defaultValue

But none actually throws exception: partly due to historical reasons (was not done initially), and also since methods do not expose JacksonException (or IOException). So this limitation is due to backwards compatibility (for 2.x)

So there are a few things to improve for 3.0:

1. Should allow throwing exceptions, for case where no default is specified. We can now do this more easily as we throw unchecked exception -- meaning accessors are still safe with Java 8 streaming
   • Jackson 3.0 now has JsonNodeException to use
2. Should allow use of Java 8 Optional, as that is useful for stream() operations

This would lead to bigger set of methods, once again for int:

1. intValue() as before, return value if JsonToken.VALUE_NUMBER_INT, within Java int range AND has no fraction (if floating point value) -- but if not, throw exception
2. intValue(int defaultValue) as intValue() except returns defaultValue instead of exception
3. intValueOpt() similar to intValue() but returns OptionalInt, either present (as per intValue()) or absent (instead of exception)
4. asInt() (or asIntValue()?) similar to intValue() but allows coercion from double and String, as well as null (and even Boolean?). But if not, throw exception
5. asIntOpt() like asInt() but returns OptionalInt, either present (as per asInt()) or absent (instead of exception)

We will add/change similar methods for:

1. "long": longValue(), longValue(long defaultValue), OptionalLong longValueOpt(), asLong()
2. "double": doubleValue(), doubleValue(double defaultValue), OptionalDouble doubleValueOpt(), asDouble()
3. "boolean": booleanValue(), booleanValue(boolean defaultValue), Optional<Boolean> booleanValueOpt(), asBoolean()
   • Conversions allowed just from StringNode (if matching name), NullNode, MissingNode
4. "String": stringValue(), stringValue(String defaultValue), Optional<String> stringValueOpt(), asString()
   • Conversions allowed from all Scalar nodes but NOT from ContainerNode (Array, Object) or from true BinaryNode

And we can consider additional accessors as well, but let's start with above.