Package Torello.JSON

Class ReadNumberJSON

  • public class ReadNumberJSON
extends java.lang.Object
    Builds on the J2EE Standard Release JSON Parsing Tools by providing additional help with converting JSON Data into the Best-Fit java.lang.Number

    This class builds on the J2EE Standard 'Glass-Fish' JSON Processor


    There are several JSON Parsers available, and even more implementations for serializing and de-serializing data to/from JSON. The Glass Fish Tool is included in the J2EE, and is available on GitHub. That is the one used by the Java HTML JAR Library (See: javax.json.* )

    Primary Classes Used: JsonArray and JsonObject

    This comment-note is intentionally repeated, verbatim, at the top of all Json Reader Classes in this package.


    JSON to Java Binding:
    JSON-Binding is the art of converting data that has been stored, saved or transmitted using Java-Script Object Notation into a Java Primitive or Object-Type. JSON can arrive into Java-Program Memory from almost any source. If you are wondering why such a massive amount of "work" is necessary just to convert a Json Integer into Java Integer, the value added is the extraordinary amount of attention paid to user configuration, error checking, & exception messaging. Methods here don't require more than 1 or 2 lines of code, and guarantee that a thorough type checking is performed.

    Unlike Java-Types which are checked by the Java-Compiler each-and-every time a programmer compiles his project, any guarantee that JSON-Type Data is pristine, uncorrupted, and in any kind of pre-agreed format may or may not be assured. The methods here are able to handle changes that might be made to an API (possibly from great distances away, and without the Software-Manager's consent). If an error could occur, configuration flags can be used to determine default error-recovery behaviors. If an exception does throw, the exception messages printed will contain multiple lines of detailed information.

    • Utilizes the Java-Standard javax.json.* Package-Library, & its Glass-Fish Implementation
    • Handles the Transfer & Conversion of All Json-Type's into Java-Type's with just One Line of Code
    • Provides all manner of User-Configurable Exception-Handling & Error-Decision Management via Class JFlag
    • Provides a Fine-Grained Suite of Exception-Classes, all with Consistent & Meaningful Error-Messages. Json Files can occasionally grow extremely large, and error messaging details make debugging easier
    • Primary Helper-Classes for the (Experimental) Google-Chrome Browser Automation Package

    The goal of Torello.JSON is to provide small, static helper methods in the same spirit as java.util.Objects and java.util.Arrays: simple calls that keep JSON handling out of your application logic. Instead of repeating loops, type checks, null checks, and exception wiring at every call site, these methods centralize that work behind a consistent set of straight-forward “read value” operations.


    Reads a Json NUMBER or numeric STRING and returns the best-fit java.lang.Number

    This class reads a single Json value and returns a "best fit" instance of java.lang.Number. JSON data may represent numbers either as true JSON numbers (JsonNumber) or as numeric strings (JsonString), and this class supports both forms.
    When the source is a true JSON number, the value is converted to the smallest standard Java numeric type that can represent it exactly. Integral values are returned as either Integer, Long, or BigInteger depending on magnitude. Non-integral values are returned as either Float, Double, or BigDecimal depending on whether the value round-trips without precision loss.

    When the source is a JSON string, the text is parsed using BigDecimal (by default) and then the same "best fit" conversion is applied. This means that values such as 3 and "3" can be handled uniformly, without forcing callers to duplicate type checks and parsing logic across large JSON traversals.

    The primary goal is correctness and clarity. If a value is missing, is null, is not a NUMBER or STRING in the required context, or cannot be converted as requested, this package throws highly-informative exceptions so that errors are detected immediately while binding complex or evolving JSON structures.
    See Also:
    Json, JsonObject, JsonArray



    Stateless Class:
    This class neither contains any program-state, nor can it be instantiated. The @StaticFunctional Annotation may also be called 'The Spaghetti Report'. Static-Functional classes are, essentially, C-Styled Files, without any constructors or non-static member fields. It is a concept very similar to the Java-Bean's @Stateless Annotation.

    • 1 Constructor(s), 1 declared private, zero-argument constructor
    • 11 Method(s), 11 declared static
    • 0 Field(s)


    • Method Summary

       
      Best-Fit: Guess appropriate Java Number-Type out of a JsonArray
      Modifier and Type Method
      static Number get​(JsonArray ja, int index, boolean throwOnNull)
      static Number get​(JsonArray ja, int index, int FLAGS, Number defaultValue)
      static Number parse​(JsonArray ja, int index, int FLAGS, Number defaultValue, Function<String,​Number> optionalParser)
       
      Best-Fit: Guess appropriate Java Number-Type out of a JsonObject
      Modifier and Type Method
      static Number get​(JsonObject jo, String propertyName, boolean isOptional, boolean throwOnNull)
      static Number get​(JsonObject jo, String propertyName, int FLAGS, Number defaultValue)
      static Number parse​(JsonObject jo, String propertyName, int FLAGS, Number defaultValue, Function<String,​Number> optionalParser)
       
      Handle either a JsonNumber or a JsonString and Guess Number-Type
      Modifier and Type Method
      static Number get​(JsonArray ja, int i, int FLAGS, Number defaultValue, Function<String,​Number> optionalParser)
      static Number get​(JsonObject jo, String propertyName, int FLAGS, Number defaultValue, Function<String,​Number> optionalParser)
       
      Internal Use Only: (Protected Methods) Convert To Number
      Modifier and Type Method
      protected static Number convertToNumber​(String s)
      protected static Number convertToNumber​(BigDecimal bd)
      protected static Number convertToNumber​(JsonNumber jn)

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • get

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.lang.Number get​(JsonArray ja,
                                   int index,
                                   boolean throwOnNull)
        Retrieve a JsonArray element, and transform it to a java.lang.Number. There are several possible Boxed-Type subclasses of java.lang.Number which may be returned from this method. This method makes an effort to return the most appropriate subclass based on the value of the JsonNumber. Note that if the number is too large to fit into the standard boxed-types, an instance of java.lang.BigInteger or BigDecimal is returned, instead.

        If a call to JsonNumber.isIntegral() evaluates to TRUE, then one of the following types listed below is returned. The method BigInteger.bitLength() is used to determine which of these is used.

        • java.lang.Integer (The number uses 32 bits or less)
        • java.lang.Long (The number uses 64 bits or less)
        • java.math.BigInteger


        If the call to isIntegral() returns FALSE, then one of these types is returned:

        • java.lang.Float
        • java.lang.Double
        • java.math.BigDecimal
        Parameters:
        ja - Any instance of JsonArray
        index - A valid index into 'ja'
        throwOnNull - Asks that an exception throw if Json-Null is encountered
        Returns:
        An instance of Java-Type java.lang.Number, if the 'ja' array element located at 'index' uses the appropriate Json-Type - JsonNumber.

        If the specified array element contains Json-Null, and 'throwOnNull' has been passed FALSE, then Java-Null is returned. If the element is null, and 'throwOnNull' is TRUE, then a JsonNullArrException throws.
        Throws:
        java.lang.IndexOutOfBoundsException - If 'index' is out of the bounds of 'ja'
        JsonTypeArrException - If the array-element (specified by 'index') does not actually contain a JsonNumber (but rather, some other non-null Json-Type), then this exception throws.
        JsonNullArrException - If the JsonArray element specified by 'index' contains a Json-Null, and TRUE has been passed to 'throwOnNull'
        See Also:
        JsonValue.getValueType(), convertToNumber(JsonNumber)
        Code:
        Exact Method Body:
         // This will throw an IndexOutOfBoundsException if the index is out of bounds.
 JsonValue jv = ja.get(index);

 switch (jv.getValueType())
 {
     case NULL:

         // This is simple-stuff (not rocket-science).  "Type Mapping" Code has to worry
         // about what the meaning of "null" should be.

         if (throwOnNull) throw new JsonNullArrException(ja, index, NUMBER, Number.class);
         else return null;

     case NUMBER: return convertToNumber((JsonNumber) jv);

     // The JsonValue at the specified array-index does not contain a JsonString.
     default: throw new JsonTypeArrException(ja, index, NUMBER, jv, Number.class);
 }

      • get

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.lang.Number get​(JsonArray ja,
                                   int index,
                                   int FLAGS,
                                   java.lang.Number defaultValue)
        Retrieve a JsonArray element, and transform it to a java.lang.Number. There are several possible Boxed-Type subclasses of java.lang.Number which may be returned from this method. This method makes an effort to return the most appropriate subclass based on the value of the JsonNumber. Note that if the number is too large to fit into the standard boxed-types, an instance of java.lang.BigInteger or BigDecimal is returned, instead.

        If a call to JsonNumber.isIntegral() evaluates to TRUE, then one of the following types listed below is returned. The method BigInteger.bitLength() is used to determine which of these is used.

        • java.lang.Integer (The number uses 32 bits or less)
        • java.lang.Long (The number uses 64 bits or less)
        • java.math.BigInteger


        If the call to isIntegral() returns FALSE, then one of these types is returned:

        • java.lang.Float
        • java.lang.Double
        • java.math.BigDecimal
        Parameters:
        ja - Any instance of JsonArray
        index - The array index containing the element to retrieve.
        FLAGS - Return-value / exception-throw constants defined in JFlag
        defaultValue - This is the 'Default Value' returned by this method, if there are any exception or problems converting or extracting the specified number.

        The default value is only returned by this method if the appropriate JSON Exception Flag has been passed to the 'FLAGS' parameter! Specifically, if 'FLAGS' were passed '0', then this parameter is fully-irrelevant and ignored. The exception flags are listed in inner-class JFlags

        If an exception-case is encountered, but the exception-flag for that exception has not been set, then this default-value won't be returned, and that exception will throw instead.
        Returns:
        Best fit boxed number, or null.
        Throws:
        java.lang.IndexOutOfBoundsException - If 'index' is out of the bounds of input array 'ja' and none of these Exception-Flags are set:
        JsonNullArrException - If the JsonArray element located at 'index' contains Json-Null, rather than a JsonNumber, and none of these Exception-Flags are set:
        JsonTypeArrException - If the JsonArray element located at 'index' contains a some other Json-Type rather than JsonNumber, and none of these Exception-Flags are set:
        See Also:
        ReadBoxedJSON.GET(JsonArray, int, int, Number, Class, Function, Function), convertToNumber(JsonNumber)
        Code:
        Exact Method Body:
         return ReadBoxedJSON.GET
     (ja, index, FLAGS, defaultValue, Number.class, ReadNumberJSON::convertToNumber, null);

      • parse

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.lang.Number parse​
            (JsonArray ja,
             int index,
             int FLAGS,
             java.lang.Number defaultValue,
             java.util.function.Function<java.lang.String,​java.lang.Number> optionalParser)
        Retrieve a JsonArray element containing a JsonString, and transform it to a java.lang.Number, with either a user-provided parser, or the standard java parser

        If 'parser' is passed null, the default parser is used, which is just the java.math.BigDecimal constructor which accepts a String. What is done with the parsed BigDecimal instance is explained below.

        There are several possible Boxed-Type subclasses of java.lang.Number which may be returned from this method. This method makes an effort to return the most appropriate subclass based on the value of the JsonNumber. Note that if the number is too large to fit into the standard boxed-types, an instance of java.lang.BigInteger or BigDecimal is returned, instead.

        If a call to BigDecimal.scale() returns '0' then one of the following types listed below is returned. The method BigInteger.bitLength() is used to determine which of these is used.

        • java.lang.Integer (The number uses 32 bits or less)
        • java.lang.Long (The number uses 64 bits or less)
        • java.math.BigInteger


        Otherwise, one of these types is returned:

        • java.lang.Float
        • java.lang.Double
        • java.math.BigDecimal
        Parameters:
        ja - Any instance of JsonArray
        index - The array index containing the JsonString element to retrieve.
        FLAGS - Return-value / exception-throw constants defined in JFlag
        defaultValue - This is the 'Default Value' returned by this method, if there are any exception or problems converting or extracting the specified number.

        The default value is only returned by this method if the appropriate JSON Exception Flag has been passed to the 'FLAGS' parameter! Specifically, if 'FLAGS' were passed '0', then this parameter is fully-irrelevant and ignored. The exception flags are listed in inner-class JFlags

        If an exception-case is encountered, but the exception-flag for that exception has not been set, then this default-value won't be returned, and that exception will throw instead.
        optionalParser - Any function-pointer to a function that will transform / convert a java.lang.String into the specified type.

        This parameter may be null, and if it is, the standard Java parser is used.
        Returns:
        If the JsonArray index contained a JsonString, and that string was successfully parsed to a java.lang.Number, then it is returned.
        If there were errors attempting to transform the String array-element, and the user-provided flags specified that defaultValue be returned, then that is returned. Null is returned if the flags specified it on error.

        If flags has been passed a '0', and an error-case has arisen, then the relevant exception will throw, instead.
        Throws:
        java.lang.IndexOutOfBoundsException - If 'index' is out of the bounds of input array 'ja' and none of these Exception-Flags are set:
        JsonStrParseArrException - If the JsonArray element located at 'index' throws an exception while attempting to parse the java.lang.String into a java.lang.Number, and none of these Exception-Flags are set:
        JsonNullArrException - If the JsonArray element located at 'index' contains Json-Null, rather than a JsonString, and none of these Exception-Flags are set:
        JsonTypeArrException - If the JsonArray element located at 'index' contains a some other Json-Type rather than JsonString, and none of these Exception-Flags are set:
        See Also:
        ParseBoxedJSON.PARSE(JsonObject, String, int, Number, Class, Function, Function, Function), convertToNumber(String)
        Code:
        Exact Method Body:
         return ParseBoxedJSON.PARSE(
     ja, index, FLAGS, defaultValue, Number.class, optionalParser,
     ReadNumberJSON::convertToNumber, null  /* Not Needed, convertToNumber won't throw */
 );

      • get

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.lang.Number get​(JsonObject jo,
                                   java.lang.String propertyName,
                                   boolean isOptional,
                                   boolean throwOnNull)
        Extract a JsonObject property, and transform it to a java.lang.Number. There are several possible Boxed-Type subclasses of java.lang.Number which may be returned from this method. This method makes an effort to return the most appropriate subclass based on the value of the JsonNumber. Note that if the number is too large to fit into the standard boxed-types, an instance of java.lang.BigInteger or BigDecimal is returned, instead.

        If a call to JsonNumber.isIntegral() evaluates to TRUE, then one of the following types listed below is returned. The method BigInteger.bitLength() is used to determine which of these is used.

        • java.lang.Integer (The number uses 32 bits or less)
        • java.lang.Long (The number uses 64 bits or less)
        • java.math.BigInteger


        If the call to isIntegral() returns FALSE, then one of these types is returned:

        • java.lang.Float
        • java.lang.Double
        • java.math.BigDecimal
        Parameters:
        jo - Any instance of JsonObject.
        propertyName - Any property name contained by 'jo'
        isOptional - When TRUE is passed, if 'propertyName' is not actually listed in 'jo' this method shall return Java-Null gracefully. When FALSE is passed, if 'jo' does not have the specified property, a JsonPropMissingException will throw.

        If 'jo' actually has a property named 'propertyName', then the value passed to this parameter is fully irrelevant.
        throwOnNull - When TRUE is passed to this parameter, if the JsonArray element located at 'index' contains Json-Null, then this method will throw a JsonNullArrException. When this parameter is FALSE, if the specified array element contains Json-Null, then Java-Null is returned.
        Returns:
        An instance of Java-Type java.lang.Number', if the 'propertyName' is available inside 'jo', and that property uses the appropriate Json-Type - JsonNumber.

        If the specified property contains Json-Null, and 'throwOnNull' has been passed FALSE, then Java-Null is returned. If the property is null, and 'throwOnNull' is TRUE, then a JsonNullObjException throws.

        If the specified property is simply missing, Java-Null is returned, unless 'isOptional' has been passed FALSE - in which case a JsonPropMissingException shall be thrown.
        Throws:
        JsonPropMissingException - This exception shall throw if the specified property is missing from the 'JsonObject' (parameter 'jo'). This exception throw can be avoided if 'TRUE' is passed to parameter 'isOptional'.
        JsonTypeObjException - If the property (specified by 'propertyName') is extracted, but that property does not actually contain a JsonNumber (but rather, some other non-null Json-Type), then this exception throws.
        JsonNullObjException - If the JsonObject property specified by 'propertyName' contains a Json-Null, and TRUE has been passed to 'throwOnNull'
        See Also:
        JsonValue.getValueType(), convertToNumber(JsonNumber)
        Code:
        Exact Method Body:
         if (! jo.containsKey(propertyName))
 {
     if (isOptional) return null;
     else throw new JsonPropMissingException(jo, propertyName, NUMBER, Number.class);
 }

 JsonValue jv = jo.get(propertyName);

 switch (jv.getValueType())
 {
     case NULL:
         // This is simple-stuff (not rocket-science).  "Type Mapping" Code has to worry
         // about what the meaning of "null" should be.

         if (throwOnNull) throw new JsonNullObjException
             (jo, propertyName, NUMBER, Number.class);

         else return null;

     case NUMBER: return convertToNumber((JsonNumber) jv);

     // The JsonObject propertydoes not contain a JsonNumber.
     default: throw new JsonTypeObjException
         (jo, propertyName, NUMBER, jv, Number.class);
 }

      • parse

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.lang.Number parse​
            (JsonObject jo,
             java.lang.String propertyName,
             int FLAGS,
             java.lang.Number defaultValue,
             java.util.function.Function<java.lang.String,​java.lang.Number> optionalParser)
        Retrieve a JsonObject property containing a JsonString, and transform it to a java.lang.Number, with either a user-provided parser, or the standard java parser

        If 'parser' is passed null, the default parser is used, which is just the java.math.BigDecimal constructor which accepts a String. What is done with the parsed BigDecimal instance is explained below.

        There are several possible Boxed-Type subclasses of java.lang.Number which may be returned from this method. This method makes an effort to return the most appropriate subclass based on the value of the JsonNumber. Note that if the number is too large to fit into the standard boxed-types, an instance of java.lang.BigInteger or BigDecimal is returned, instead.

        If a call to BigDecimal.scale() returns '0' then one of the following types listed below is returned. The method BigInteger.bitLength() is used to determine which of these is used.

        • java.lang.Integer (The number uses 32 bits or less)
        • java.lang.Long (The number uses 64 bits or less)
        • java.math.BigInteger


        Otherwise, one of these types is returned:

        • java.lang.Float
        • java.lang.Double
        • java.math.BigDecimal
        Parameters:
        jo - Any instance of JsonObject
        propertyName - Any property name contained by 'jo'
        FLAGS - Return-value / exception-throw constants defined in JFlag
        defaultValue - This is the 'Default Value' returned by this method, if there are any exception or problems converting or extracting the specified number.

        The default value is only returned by this method if the appropriate JSON Exception Flag has been passed to the 'FLAGS' parameter! Specifically, if 'FLAGS' were passed '0', then this parameter is fully-irrelevant and ignored. The exception flags are listed in inner-class JFlags

        If an exception-case is encountered, but the exception-flag for that exception has not been set, then this default-value won't be returned, and that exception will throw instead.
        optionalParser - Any function-pointer to a function that will transform / convert a java.lang.String into the specified type.

        This parameter may be null, and if it is, the standard Java parser is used.
        Returns:
        If the JsonObject property contained a JsonString, and that string was successfully parsed to a java.lang.Number, then it is returned.
        If there were errors attempting to transform the String object-property, and the user-provided flags specified that defaultValue be returned, then that is returned. Null is returned if the flags specified it on error.

        If flags has been passed a '0', and an error-case has arisen, then the relevant exception will throw, instead.
        Throws:
        JsonPropMissingException - If 'jo' does not have a property with the name 'propertyName' and none of these Exception-Flags are set:
        JsonStrParseObjException - If the JsonObject property specified by 'propertyName' throws an exception while attempting to parse the java.lang.String into a java.lang.Number, and none of these Exception-Flags are set:
        JsonNullObjException - If the JsonObject property specified by 'propertyName' contains Json-Null, rather than a JsonString, and none of these Exception-Flags are set:
        JsonTypeObjException - If the JsonObject property specified by 'propertyName' contains a some other Json-Type rather than JsonString, and none of these Exception-Flags are set:
        See Also:
        ParseBoxedJSON.PARSE(JsonObject, String, int, Number, Class, Function, Function, Function), convertToNumber(String)
        Code:
        Exact Method Body:
         return ParseBoxedJSON.PARSE(
     jo, propertyName, FLAGS, defaultValue, Number.class, optionalParser,
     ReadNumberJSON::convertToNumber,
     null /* Not Needed, convertToNumber won't throw */
 );

      • get

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.lang.Number get​
            (JsonArray ja,
             int i,
             int FLAGS,
             java.lang.Number defaultValue,
             java.util.function.Function<java.lang.String,​java.lang.Number> optionalParser)

        Checks: Json Type of the specified JsonArray index contents, and dispatches based on type.
        Flags: Accepts all Error-Handler Flags; Suppresses exceptions when requested by the flag mask
        Returns: A Java Boxed Number
        Parameters:
        ja - Any JsonArray
        i - Any index into the JsonArray
        FLAGS - Return-value / exception-throw constants defined in JFlag
        defaultValue - This is the 'Default Value' returned by this method, if there are any exception or problems converting or extracting the specified number.

        The default value is only returned by this method if the appropriate JSON Exception Flag has been passed to the 'FLAGS' parameter! Specifically, if 'flags' were passed '0', then this parameter is fully-irrelevant and ignored. The exception flags are listed in class JFlags

        If an exception-case is encountered, but the exception-flag for that exception has not been set, then this default-value won't be returned, and that exception will throw instead.
        optionalParser - A function wich can map a java.lang.String into a Java Number. This 'optionalParser' is only used if the specified element contains a JsonString rather than a JsonNumber. If a JsonNumber is found, or some other unrelated type, then this parameter is wholly ignored.

        null may be passed to parameter 'optionalParser'. If null is received, and if it turns out that a String to Number parser-function is required to generate the result for this method, then new BigDecimal(String.trim()) will be used as the default-parser, instead.
        Returns:
        If the JsonArray index contained a number, and that number was successfully transformed to a Number, then it is returned.

        If the array-index was a String, and that String was transformed into a Number using either 'parser' - or the default parser, then that Number is returned.

        In all exception or error cases, parameter 'FLAGS' may indicate that either the default-value be returned, or that null be returned. If the exception-handling flags were not sufficiently set, and an error-case has occured, one of the exceptions listed below is thrown.
        Throws:
        java.lang.IndexOutOfBoundsException - If 'index' is out of the bounds of input array 'ja' and none of these Exception-Flags are set:
        JsonStrParseArrException - If the JsonArray element located at 'index' contains a JsonString, this method will attempt to parse that String into a Java Number, using either the user-provided 'parser' (if provided), or otherwise, the default-parser (new BigDecimal(String.trim())). This exception will throw if parsing the String generates an exception throw AND none of these Exception-Flags are set:
        JsonNullArrException - If the JsonArray element located at 'index' contains Json-Null, rather than a JsonNumber or a JsonString, and none of these Exception-Flags are set:
        JsonTypeArrException - If the JsonArray element located at 'index' neither contains a JsonNumber, nor a JsonString, AND none of these Exception-Flags are set:
        See Also:
        get(JsonArray, int, int, Number), parse(JsonArray, int, int, Number, Function)
        Code:
        Exact Method Body:
         JsonValue.ValueType t;

 return ((i >= ja.size()) || ((t=ja.get(i).getValueType()) == NUMBER) || (t != STRING))
     ? get(ja, i, FLAGS, defaultValue)
     : parse(ja, i, FLAGS, defaultValue, optionalParser);

      • get

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.lang.Number get​
            (JsonObject jo,
             java.lang.String propertyName,
             int FLAGS,
             java.lang.Number defaultValue,
             java.util.function.Function<java.lang.String,​java.lang.Number> optionalParser)

        Checks: Json Type of the specified JsonObject property, and dispatches based on type.
        Flags: Accepts all Error-Handler Flags; Suppresses exceptions when requested by the flag mask
        Returns: A Java Boxed Number
        Parameters:
        jo - Any JsonObject
        propertyName - Any of the properties defined in the JsonObject
        FLAGS - Return-value / exception-throw constants defined in JFlag
        defaultValue - This is the 'Default Value' returned by this method, if there are any exception or problems converting or extracting the specified number.

        The default value is only returned by this method if the appropriate JSON Exception Flag has been passed to the 'FLAGS' parameter! Specifically, if 'flags' were passed '0', then this parameter is fully-irrelevant and ignored. The exception flags are listed in class JFlags

        If an exception-case is encountered, but the exception-flag for that exception has not been set, then this default-value won't be returned, and that exception will throw instead.
        optionalParser - A function wich can map a java.lang.String into a Java Number. This 'optionalParser' is only used if the specified element contains a JsonString rather than a JsonNumber. If a JsonNumber is found, or some other unrelated type, then this parameter is wholly ignored.

        null may be passed to parameter 'optionalParser'. If null is received, and if it turns out that a String to Number parser-function is required to generate the result for this method, then new BigDecimal(String.trim()) will be used as the default-parser, instead.
        Returns:
        If the JsonObject property contained a number, and that number was successfully transformed to a Number, then it is returned.

        If the object-property was a String, and that String was transformed into a Number using either 'parser' - or the default parser, then that Number is returned.

        In all exception or error cases, parameter 'FLAGS' may indicate that either the default-value be returned, or that null be returned. If the exception-handling flags were not sufficiently set, and an error-case has occured, one of the exceptions listed below is thrown.
        Throws:
        JsonPropMissingException - If 'jo' does not have a property with the name 'propertyName' and none of these Exception-Flags are set:
        JsonStrParseObjException - If the JsonObject property specified by 'propertyName' contains a JsonString, this method will attempt to parse that String into a Java Number, using either the user-provided 'parser' (if provided), or otherwise, the default-parser (new BigDecimal(String.trim())). This exception will throw if parsing the String generates an exception throw AND none of these Exception-Flags are set:
        JsonNullObjException - If the JsonObject property specified by 'propertyName' contains Json-Null, rather than a JsonNumber or a JsonString, and none of these Exception-Flags are set:
        JsonTypeObjException - If the JsonObject property specified by 'propertyName' neither contains a JsonNumber, nor a JsonString, AND none of these Exception-Flags are set:
        See Also:
        get(JsonObject, String, int, Number), parse(JsonObject, String, int, Number, Function)
        Code:
        Exact Method Body:
         JsonValue.ValueType t;

 return (    (! jo.containsKey(propertyName))
         ||  ((t = jo.get(propertyName).getValueType()) == NUMBER)
         ||  (t != STRING)
     )
     ? get(jo, propertyName, FLAGS, defaultValue)
     : parse(jo, propertyName, FLAGS, defaultValue, optionalParser);

      • convertToNumber

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected static java.lang.Number convertToNumber​(JsonNumber jn)
        Converts any JsonNumber into one of the inheriting subclasses of Java class Number
        Parameters:
        jn - Any JsonNumber
        Returns:
        The most appropriate intance of java.lang.Number
        See Also:
        get(JsonObject, String, int, Number), JsonNumber.isIntegral(), JsonNumber.bigIntegerValue(), JsonNumber.bigDecimalValue()
        Code:
        Exact Method Body:
         if (jn.isIntegral())
 {
     BigInteger bi = jn.bigIntegerValue();
     int        l  = bi.bitLength();

     if (l <= 32) return Integer.valueOf(bi.intValue());
     if (l <= 64) return Long.valueOf(bi.longValue());

     return bi;
 }

 else
 {
     BigDecimal bd = jn.bigDecimalValue();

     // This probably isn't the most efficient thing I've ever written, but I do not
     // have the energy to stare at java.math.BigDecimal at the moment.  The JavaDoc for
     // this JSON => Java-Type Conversion is quite intricate.  I will figure this out at
     // at later date.

     float f = bd.floatValue();

     if (    (! Float.isInfinite(f))
         &&  (BigDecimal.valueOf(f).compareTo(bd) == 0)
     )
         return (Float) f;

     double d = bd.doubleValue();

     if (    (! Double.isInfinite(d))
         &&  (BigDecimal.valueOf(d).compareTo(bd) == 0)
     )
         return (Double) d;

     return bd;
 }

      • convertToNumber

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        protected static java.lang.Number convertToNumber​(java.math.BigDecimal bd)
        Converts any java.math.BigDecimal into one of the inheriting subclasses of Number.
        Parameters:
        bd - Any BigDecimal
        Returns:
        The most appropriate instance of java.lang.Number
        Code:
        Exact Method Body:
         if (bd.scale() == 0)
 {
     BigInteger bi = bd.toBigInteger();
     int        l  = bi.bitLength();

     if (l <= 32) return Integer.valueOf(bi.intValue());
     if (l <= 64) return Long.valueOf(bi.longValue());
     return bi;
 }

 else
 {
     // This probably isn't the most efficient thing I've ever written, but I do not
     // have the energy to stare at java.math.BigDecimal at the moment.  The JavaDoc for
     // this JSON => Java-Type Conversion is quite intricate.  I will figure this out at
     // at later date.

     float f = bd.floatValue();

     if (    (! Float.isInfinite(f))
         &&  (BigDecimal.valueOf(f).compareTo(bd) == 0)
     )
         return (Float) f;

     double d = bd.doubleValue();

     if (    (! Double.isInfinite(d))
         &&  (BigDecimal.valueOf(d).compareTo(bd) == 0)
     )
         return (Double) d;

     return bd;
 }