Extend, improve set of number value accessors for JsonNode (JsonNode.intValue() etc) [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 types like, say, int:

• intValue(): return int if (and only if!) we got numeric node (JsonToken.VALUE_NUMBER_INT or JsonToken.VALUE_NUMBER_FLOAT) -- but won't throw exception, returns default value (0`) otherwise. Also: can lose accuracy for FP numbers with fractions
• intValue(int defaultValue) -- int if coercible, defaultValue if not
• asInt() -- adds coercions from some non-numeric types too

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. "decimal" (for BigDecimal): decimalValue(), decimalValue(BigDecimal defaultValue), Optional<BigDecimal> decimalValueOpt(), asDecimal()

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

NOTE:

• There are following partial sets for number access: need to be changed to throw on non-numbers and have range checks
  • bigIntegerValue() -- same
  • floatValue()
  • shortValue() -- same
  • numberValue() -- same; needs to throw exception for non-numbers

NOTE:

This issue does NOT yet add/change JsonNode.asXxx() but only (numeric) JsonNode.xxxValue() methods (and variants) -- there's #5003 for asInt() and such.