Class ReadJSON.XL

  • Enclosing class:
    ReadJSON
    public static class ReadJSON.XL
extends java.lang.Object
    JSON Binding Helper-Class:
    JSON-Binding is the art of converting data that has been stored, saved or transmitted using Java-Script Object Notation into a Primitive-Type or Object-Type of any Programming Language, for instance Java. JSON often arrives into Java-Program Memory from an external Internet Connection, and may have traveled hundreds or even thousands of miles from a Host-Server.

    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 is never completely assured.

    Being able to handle changes that might be made to an API (possibly from great distances away, and without the Software-Manager's consent) is the type of feature that robust JSON-Code simply has to offer.

    Binding-Helper Features:
    • Provides for All-Manner of Exception-Handling & Error-Decision Configurations using the (Simple) JFlag Class.
    • Provides Fine-Grained JSON Exception-Classes, all of which have Pre-written & Consistent Error-Messages,
    • Handles the Transfer & Conversion of All Json-Type's into Java-Type's in just One Line of Code
    • Is a Core Handler-Class for the (Experimental) Google-Chrome Headless Browser Package
    • Utilizes the Java-Standard javax.json.* Package-Library
    More utilities for parsing and converting JSON Data into Java Data Types.

    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 tool included in the J2EE is available on GitHub, and that is the one used by the Java HTML JAR Library. (See: javax.json.* )

    Primary Classes Used: JsonArray and JsonObject
    This provides an additional set of methods for handling properties that should contain numbers, but could possibly contain those numbers represented as String's. This class also handles creating POJO's.

    This class facilitates handling any type of Json Data when converting Json Types to Java Types, and essentially builds on the methods available in class ReadJSON.

    POJO De-Serialization:
    The methods that appear to de-serialize a JSON Object into a standard Java-Object require a constructor that accepts a JsonObject. Automatic type-creation (as exists in libraries such as 'Lombok') is not an feature offered by this class. There is not a lot of "magic", however these methods can reduce a lot of the work needed to convert Json into Java through field initializations that have been reduced to nothing more than a single line of code.

    Te primary value of the FLAGS configuration-parameters and other assorted boolean-parameters are just to ensure that if / when erroneous JSON is received from a REST Web-Service, that it is instantly and automatically handled appropriately. Dealing with such erroneous input can be accomplished through default-values, exception-throws or null-values.

    The exception messages provided by this package are extremely readable, and contain al the information needed when debugging REST-API interfaces.
    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
    • 19 Method(s), 19 declared static
    • 0 Field(s)


    • Method Summary

       
      Retrieve a JsonObject, and transform it to a Java Object
      Returns Modifier and Type Method
      Object static <T> T getObject​(JsonArray ja, int index, Class<T> c, boolean throwOnNull)
      Object static <T> T getObject​(JsonObject jo, Class<T> c)
      Object static <T> T getObject​(JsonObject jo, String propertyName, Class<T> c, boolean isOptional, boolean throwOnNull)
       
      Retrieve either a JsonNumber or JsonString from a JsonArray, and transform to number
      Returns Modifier and Type Method
      Boxed-Primitive static Byte getBYTE​(JsonArray ja, int i, int FLAGS, byte defaultValue, Function<String,​Byte> optionalParser)
      Boxed-Primitive static Double getDOUBLE​(JsonArray ja, int i, int FLAGS, double defaultValue, Function<String,​Double> optionalParser)
      Boxed-Primitive static Float getFLOAT​(JsonArray ja, int i, int FLAGS, float defaultValue, Function<String,​Float> optionalParser)
      Boxed-Primitive static Integer getINTEGER​(JsonArray ja, int i, int FLAGS, int defaultValue, Function<String,​Integer> optionalParser)
      Boxed-Primitive static Long getLONG​(JsonArray ja, int i, int FLAGS, long defaultValue, Function<String,​Long> optionalParser)
      Boxed-Primitive static Number getNUMBER​(JsonArray ja, int i, int FLAGS, Number defaultValue, Function<String,​Number> optionalParser)
      Boxed-Primitive static Short getSHORT​(JsonArray ja, int i, int FLAGS, short defaultValue, Function<String,​Short> optionalParser)
       
      Retrieve either a JsonNumber or JsonString from a JsonObject, and transform to number
      Returns Modifier and Type Method
      Boxed-Primitive static Byte getBYTE​(JsonObject jo, String propertyName, int FLAGS, byte defaultValue, Function<String,​Byte> optionalParser)
      Boxed-Primitive static Double getDOUBLE​(JsonObject jo, String propertyName, int FLAGS, double defaultValue, Function<String,​Double> optionalParser)
      Boxed-Primitive static Float getFLOAT​(JsonObject jo, String propertyName, int FLAGS, float defaultValue, Function<String,​Float> optionalParser)
      Boxed-Primitive static Integer getINTEGER​(JsonObject jo, String propertyName, int FLAGS, int defaultValue, Function<String,​Integer> optionalParser)
      Boxed-Primitive static Long getLONG​(JsonObject jo, String propertyName, int FLAGS, long defaultValue, Function<String,​Long> optionalParser)
      Boxed-Primitive static Number getNUMBER​(JsonObject jo, String propertyName, int FLAGS, Number defaultValue, Function<String,​Number> optionalParser)
      Boxed-Primitive static Short getSHORT​(JsonObject jo, String propertyName, int FLAGS, short defaultValue, Function<String,​Short> optionalParser)
       
      Retrieve JsonValue.TRUE, FALSE, or a JsonString, and transform to boolean
      Returns Modifier and Type Method
      Boxed-Primitive static Boolean getBOOLEAN​(JsonArray ja, int i, int FLAGS, boolean defaultValue, Function<String,​Boolean> optionalParser)
      Boxed-Primitive static Boolean getBOOLEAN​(JsonObject jo, String propertyName, int FLAGS, boolean defaultValue, Function<String,​Boolean> optionalParser)

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • getINTEGER

        🡇  ⇈  ⮫ 
        public static java.lang.Integer getINTEGER​
            (JsonArray ja,
             int i,
             int FLAGS,
             int defaultValue,
             java.util.function.Function<java.lang.String,​java.lang.Integer> optionalParser)
        Used to convert a JsonArray element which can handle either a String, or a Number, and transform that element into a Java Integer.

        This method simply dispatches to one of the ReadJSON methods, depending upon whether a string or a number is found at the array index location.
        Parameters:
        ja - Any JsonArray
        i - Any index into the JsonArray
        FLAGS - The return-value / exception-throw flag 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

        AGAIN: 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 Integer. 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.

        NOTE: null may be passed to parameter 'optionalParser'. If null is received, and if it turns out that a String to Integer parser-function is required to generate the result for this method, then Integer.parseInt(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 Integer, then it is returned.

        If the array-index was a String, and that String was transformed into a Integer using either 'parser' - or the default parser, then that Integer 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 Integer, using either the user-provided 'parser' (if provided), or otherwise, the default-parser (Integer.parseInt(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:
        ReadJSON.getINTEGER(JsonArray, int, int, int), ReadJSON.parseINTEGER(JsonArray, int, int, int, Function)
        Code:
        Exact Method Body:
         JsonValue.ValueType t;

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

      • getLONG

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.Long getLONG​
            (JsonArray ja,
             int i,
             int FLAGS,
             long defaultValue,
             java.util.function.Function<java.lang.String,​java.lang.Long> optionalParser)
        Used to convert a JsonArray element which can handle either a String, or a Number, and transform that element into a Java Long.

        This method simply dispatches to one of the ReadJSON methods, depending upon whether a string or a number is found at the array index location.
        Parameters:
        ja - Any JsonArray
        i - Any index into the JsonArray
        FLAGS - The return-value / exception-throw flag 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

        AGAIN: 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 Long. 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.

        NOTE: null may be passed to parameter 'optionalParser'. If null is received, and if it turns out that a String to Long parser-function is required to generate the result for this method, then Long.parseLong(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 Long, then it is returned.

        If the array-index was a String, and that String was transformed into a Long using either 'parser' - or the default parser, then that Long 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 Long, using either the user-provided 'parser' (if provided), or otherwise, the default-parser (Long.parseLong(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:
        ReadJSON.getLONG(JsonArray, int, int, long), ReadJSON.parseLONG(JsonArray, int, int, long, Function)
        Code:
        Exact Method Body:
         JsonValue.ValueType t;

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

      • getSHORT

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.Short getSHORT​
            (JsonArray ja,
             int i,
             int FLAGS,
             short defaultValue,
             java.util.function.Function<java.lang.String,​java.lang.Short> optionalParser)
        Used to convert a JsonArray element which can handle either a String, or a Number, and transform that element into a Java Short.

        This method simply dispatches to one of the ReadJSON methods, depending upon whether a string or a number is found at the array index location.
        Parameters:
        ja - Any JsonArray
        i - Any index into the JsonArray
        FLAGS - The return-value / exception-throw flag 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

        AGAIN: 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 Short. 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.

        NOTE: null may be passed to parameter 'optionalParser'. If null is received, and if it turns out that a String to Short parser-function is required to generate the result for this method, then Short.parseShort(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 Short, then it is returned.

        If the array-index was a String, and that String was transformed into a Short using either 'parser' - or the default parser, then that Short 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 Short, using either the user-provided 'parser' (if provided), or otherwise, the default-parser (Short.parseShort(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:
        ReadJSON.getSHORT(JsonArray, int, int, short), ReadJSON.parseSHORT(JsonArray, int, int, short, Function)
        Code:
        Exact Method Body:
         JsonValue.ValueType t;
    
 return ((i >= ja.size()) || ((t=ja.get(i).getValueType()) == NUMBER) || (t != STRING))
     ? ReadJSON.getSHORT(ja, i, FLAGS, defaultValue)
     : ReadJSON.parseSHORT(ja, i, FLAGS, defaultValue, optionalParser);

      • getBYTE

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.Byte getBYTE​
            (JsonArray ja,
             int i,
             int FLAGS,
             byte defaultValue,
             java.util.function.Function<java.lang.String,​java.lang.Byte> optionalParser)
        Used to convert a JsonArray element which can handle either a String, or a Number, and transform that element into a Java Byte.

        This method simply dispatches to one of the ReadJSON methods, depending upon whether a string or a number is found at the array index location.
        Parameters:
        ja - Any JsonArray
        i - Any index into the JsonArray
        FLAGS - The return-value / exception-throw flag 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

        AGAIN: 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 Byte. 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.

        NOTE: null may be passed to parameter 'optionalParser'. If null is received, and if it turns out that a String to Byte parser-function is required to generate the result for this method, then Byte.parseByte(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 Byte, then it is returned.

        If the array-index was a String, and that String was transformed into a Byte using either 'parser' - or the default parser, then that Byte 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 Byte, using either the user-provided 'parser' (if provided), or otherwise, the default-parser (Byte.parseByte(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:
        ReadJSON.getBYTE(JsonArray, int, int, byte), ReadJSON.parseBYTE(JsonArray, int, int, byte, Function)
        Code:
        Exact Method Body:
         JsonValue.ValueType t;
    
 return ((i >= ja.size()) || ((t=ja.get(i).getValueType()) == NUMBER) || (t != STRING))
     ? ReadJSON.getBYTE(ja, i, FLAGS, defaultValue)
     : ReadJSON.parseBYTE(ja, i, FLAGS, defaultValue, optionalParser);

      • getDOUBLE

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.Double getDOUBLE​
            (JsonArray ja,
             int i,
             int FLAGS,
             double defaultValue,
             java.util.function.Function<java.lang.String,​java.lang.Double> optionalParser)
        Used to convert a JsonArray element which can handle either a String, or a Number, and transform that element into a Java Double.

        This method simply dispatches to one of the ReadJSON methods, depending upon whether a string or a number is found at the array index location.
        Parameters:
        ja - Any JsonArray
        i - Any index into the JsonArray
        FLAGS - The return-value / exception-throw flag 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

        AGAIN: 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 Double. 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.

        NOTE: null may be passed to parameter 'optionalParser'. If null is received, and if it turns out that a String to Double parser-function is required to generate the result for this method, then Double.parseDouble(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 Double, then it is returned.

        If the array-index was a String, and that String was transformed into a Double using either 'parser' - or the default parser, then that Double 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 Double, using either the user-provided 'parser' (if provided), or otherwise, the default-parser (Double.parseDouble(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:
        ReadJSON.getDOUBLE(JsonArray, int, int, double), ReadJSON.parseDOUBLE(JsonArray, int, int, double, Function)
        Code:
        Exact Method Body:
         JsonValue.ValueType t;
    
 return ((i >= ja.size()) || ((t=ja.get(i).getValueType()) == NUMBER) || (t != STRING))
     ? ReadJSON.getDOUBLE(ja, i, FLAGS, defaultValue)
     : ReadJSON.parseDOUBLE(ja, i, FLAGS, defaultValue, optionalParser);

      • getFLOAT

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.Float getFLOAT​
            (JsonArray ja,
             int i,
             int FLAGS,
             float defaultValue,
             java.util.function.Function<java.lang.String,​java.lang.Float> optionalParser)
        Used to convert a JsonArray element which can handle either a String, or a Number, and transform that element into a Java Float.

        This method simply dispatches to one of the ReadJSON methods, depending upon whether a string or a number is found at the array index location.
        Parameters:
        ja - Any JsonArray
        i - Any index into the JsonArray
        FLAGS - The return-value / exception-throw flag 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

        AGAIN: 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 Float. 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.

        NOTE: null may be passed to parameter 'optionalParser'. If null is received, and if it turns out that a String to Float parser-function is required to generate the result for this method, then Float.parseFloat(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 Float, then it is returned.

        If the array-index was a String, and that String was transformed into a Float using either 'parser' - or the default parser, then that Float 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 Float, using either the user-provided 'parser' (if provided), or otherwise, the default-parser (Float.parseFloat(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:
        ReadJSON.getFLOAT(JsonArray, int, int, float), ReadJSON.parseFLOAT(JsonArray, int, int, float, Function)
        Code:
        Exact Method Body:
         JsonValue.ValueType t;
    
 return ((i >= ja.size()) || ((t=ja.get(i).getValueType()) == NUMBER) || (t != STRING))
     ? ReadJSON.getFLOAT(ja, i, FLAGS, defaultValue)
     : ReadJSON.parseFLOAT(ja, i, FLAGS, defaultValue, optionalParser);

      • getNUMBER

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.Number getNUMBER​
            (JsonArray ja,
             int i,
             int FLAGS,
             java.lang.Number defaultValue,
             java.util.function.Function<java.lang.String,​java.lang.Number> optionalParser)
        Used to convert a JsonArray element which can handle either a String, or a Number, and transform that element into a Java Number.

        This method simply dispatches to one of the ReadJSON methods, depending upon whether a string or a number is found at the array index location.
        Parameters:
        ja - Any JsonArray
        i - Any index into the JsonArray
        FLAGS - The return-value / exception-throw flag 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

        AGAIN: 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.

        NOTE: 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:
        ReadJSON.getNUMBER(JsonArray, int, int, Number), ReadJSON.parseNUMBER(JsonArray, int, int, Number, Function)
        Code:
        Exact Method Body:
         JsonValue.ValueType t;

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

      • getBOOLEAN

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.Boolean getBOOLEAN​
            (JsonArray ja,
             int i,
             int FLAGS,
             boolean defaultValue,
             java.util.function.Function<java.lang.String,​java.lang.Boolean> optionalParser)
        Used to convert a JsonArray element which can handle either a String, or a Number, and transform that element into a Java Boolean.

        This method simply dispatches to one of the ReadJSON methods, depending upon whether a string or a number is found at the array index location.
        Parameters:
        ja - Any JsonArray
        i - Any index into the JsonArray
        FLAGS - The return-value / exception-throw flag 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

        AGAIN: 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 Boolean. 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.

        NOTE: null may be passed to parameter 'optionalParser'. If null is received, and if it turns out that a String to Boolean parser-function is required to generate the result for this method, then Boolean.parseBoolean(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 Boolean, then it is returned.

        If the array-index was a String, and that String was transformed into a Boolean using either 'parser' - or the default parser, then that Boolean 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 Boolean, using either the user-provided 'parser' (if provided), or otherwise, the default-parser (Boolean.parseBoolean(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:
        ReadJSON.getBOOLEAN(JsonArray, int, int, boolean), ReadJSON.parseBOOLEAN(JsonArray, int, int, boolean, Function)
        Code:
        Exact Method Body:
         JsonValue.ValueType t;

 return (    (i >= ja.size())
         ||  ((t=ja.get(i).getValueType()) == TRUE)
         || (t == FALSE)
         || (t != STRING)
     )
     ? ReadJSON.getBOOLEAN(ja, i, FLAGS, defaultValue)
     : ReadJSON.parseBOOLEAN(ja, i, FLAGS, defaultValue, optionalParser);

      • getINTEGER

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.Integer getINTEGER​
            (JsonObject jo,
             java.lang.String propertyName,
             int FLAGS,
             int defaultValue,
             java.util.function.Function<java.lang.String,​java.lang.Integer> optionalParser)
        Used to convert a JsonObject property which can handle either a String, or a Number, and transform that element into a Java Integer.

        This method simply dispatches to one of the ReadJSON methods, depending upon whether the specified object property contains a string or a number.
        Parameters:
        jo - Any JsonObject
        propertyName - Any of the properties defined in the JsonObject
        FLAGS - The return-value / exception-throw flag 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

        AGAIN: 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 Integer. 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.

        NOTE: null may be passed to parameter 'optionalParser'. If null is received, and if it turns out that a String to Integer parser-function is required to generate the result for this method, then Integer.parseInt(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 Integer, then it is returned.

        If the object-property was a String, and that String was transformed into a Integer using either 'parser' - or the default parser, then that Integer 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 Integer, using either the user-provided 'parser' (if provided), or otherwise, the default-parser (Integer.parseInt(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:
        ReadJSON.getINTEGER(JsonObject, String, int, int), ReadJSON.parseINTEGER(JsonObject, String, int, int, Function)
        Code:
        Exact Method Body:
         JsonValue.ValueType t;
    
 return (    (! jo.containsKey(propertyName))
         ||  ((t = jo.get(propertyName).getValueType()) == NUMBER)
         ||  (t != STRING)
     )
     ? ReadJSON.getINTEGER(jo, propertyName, FLAGS, defaultValue)
     : ReadJSON.parseINTEGER(jo, propertyName, FLAGS, defaultValue, optionalParser);

      • getLONG

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.Long getLONG​
            (JsonObject jo,
             java.lang.String propertyName,
             int FLAGS,
             long defaultValue,
             java.util.function.Function<java.lang.String,​java.lang.Long> optionalParser)
        Used to convert a JsonObject property which can handle either a String, or a Number, and transform that element into a Java Long.

        This method simply dispatches to one of the ReadJSON methods, depending upon whether the specified object property contains a string or a number.
        Parameters:
        jo - Any JsonObject
        propertyName - Any of the properties defined in the JsonObject
        FLAGS - The return-value / exception-throw flag 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

        AGAIN: 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 Long. 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.

        NOTE: null may be passed to parameter 'optionalParser'. If null is received, and if it turns out that a String to Long parser-function is required to generate the result for this method, then Long.parseLong(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 Long, then it is returned.

        If the object-property was a String, and that String was transformed into a Long using either 'parser' - or the default parser, then that Long 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 Long, using either the user-provided 'parser' (if provided), or otherwise, the default-parser (Long.parseLong(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:
        ReadJSON.getLONG(JsonObject, String, int, long), ReadJSON.parseLONG(JsonObject, String, int, long, Function)
        Code:
        Exact Method Body:
         JsonValue.ValueType t;
    
 return (    (! jo.containsKey(propertyName))
         ||  ((t = jo.get(propertyName).getValueType()) == NUMBER)
         ||  (t != STRING)
     )
     ? ReadJSON.getLONG(jo, propertyName, FLAGS, defaultValue)
     : ReadJSON.parseLONG(jo, propertyName, FLAGS, defaultValue, optionalParser);

      • getSHORT

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.Short getSHORT​
            (JsonObject jo,
             java.lang.String propertyName,
             int FLAGS,
             short defaultValue,
             java.util.function.Function<java.lang.String,​java.lang.Short> optionalParser)
        Used to convert a JsonObject property which can handle either a String, or a Number, and transform that element into a Java Short.

        This method simply dispatches to one of the ReadJSON methods, depending upon whether the specified object property contains a string or a number.
        Parameters:
        jo - Any JsonObject
        propertyName - Any of the properties defined in the JsonObject
        FLAGS - The return-value / exception-throw flag 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

        AGAIN: 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 Short. 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.

        NOTE: null may be passed to parameter 'optionalParser'. If null is received, and if it turns out that a String to Short parser-function is required to generate the result for this method, then Short.parseShort(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 Short, then it is returned.

        If the object-property was a String, and that String was transformed into a Short using either 'parser' - or the default parser, then that Short 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 Short, using either the user-provided 'parser' (if provided), or otherwise, the default-parser (Short.parseShort(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:
        ReadJSON.getSHORT(JsonObject, String, int, short), ReadJSON.parseSHORT(JsonObject, String, int, short, Function)
        Code:
        Exact Method Body:
         JsonValue.ValueType t;
    
 return (    (! jo.containsKey(propertyName))
         ||  ((t = jo.get(propertyName).getValueType()) == NUMBER)
         ||  (t != STRING)
     )
     ? ReadJSON.getSHORT(jo, propertyName, FLAGS, defaultValue)
     : ReadJSON.parseSHORT(jo, propertyName, FLAGS, defaultValue, optionalParser);

      • getBYTE

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.Byte getBYTE​
            (JsonObject jo,
             java.lang.String propertyName,
             int FLAGS,
             byte defaultValue,
             java.util.function.Function<java.lang.String,​java.lang.Byte> optionalParser)
        Used to convert a JsonObject property which can handle either a String, or a Number, and transform that element into a Java Byte.

        This method simply dispatches to one of the ReadJSON methods, depending upon whether the specified object property contains a string or a number.
        Parameters:
        jo - Any JsonObject
        propertyName - Any of the properties defined in the JsonObject
        FLAGS - The return-value / exception-throw flag 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

        AGAIN: 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 Byte. 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.

        NOTE: null may be passed to parameter 'optionalParser'. If null is received, and if it turns out that a String to Byte parser-function is required to generate the result for this method, then Byte.parseByte(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 Byte, then it is returned.

        If the object-property was a String, and that String was transformed into a Byte using either 'parser' - or the default parser, then that Byte 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 Byte, using either the user-provided 'parser' (if provided), or otherwise, the default-parser (Byte.parseByte(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:
        ReadJSON.getBYTE(JsonObject, String, int, byte), ReadJSON.parseBYTE(JsonObject, String, int, byte, Function)
        Code:
        Exact Method Body:
         JsonValue.ValueType t;
    
 return (    (! jo.containsKey(propertyName))
         ||  ((t = jo.get(propertyName).getValueType()) == NUMBER)
         ||  (t != STRING)
     )
     ? ReadJSON.getBYTE(jo, propertyName, FLAGS, defaultValue)
     : ReadJSON.parseBYTE(jo, propertyName, FLAGS, defaultValue, optionalParser);

      • getDOUBLE

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.Double getDOUBLE​
            (JsonObject jo,
             java.lang.String propertyName,
             int FLAGS,
             double defaultValue,
             java.util.function.Function<java.lang.String,​java.lang.Double> optionalParser)
        Used to convert a JsonObject property which can handle either a String, or a Number, and transform that element into a Java Double.

        This method simply dispatches to one of the ReadJSON methods, depending upon whether the specified object property contains a string or a number.
        Parameters:
        jo - Any JsonObject
        propertyName - Any of the properties defined in the JsonObject
        FLAGS - The return-value / exception-throw flag 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

        AGAIN: 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 Double. 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.

        NOTE: null may be passed to parameter 'optionalParser'. If null is received, and if it turns out that a String to Double parser-function is required to generate the result for this method, then Double.parseDouble(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 Double, then it is returned.

        If the object-property was a String, and that String was transformed into a Double using either 'parser' - or the default parser, then that Double 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 Double, using either the user-provided 'parser' (if provided), or otherwise, the default-parser (Double.parseDouble(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:
        ReadJSON.getDOUBLE(JsonObject, String, int, double), ReadJSON.parseDOUBLE(JsonObject, String, int, double, Function)
        Code:
        Exact Method Body:
         JsonValue.ValueType t;
    
 return (    (! jo.containsKey(propertyName))
         ||  ((t = jo.get(propertyName).getValueType()) == NUMBER)
         ||  (t != STRING)
     )
     ? ReadJSON.getDOUBLE(jo, propertyName, FLAGS, defaultValue)
     : ReadJSON.parseDOUBLE(jo, propertyName, FLAGS, defaultValue, optionalParser);

      • getFLOAT

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.Float getFLOAT​
            (JsonObject jo,
             java.lang.String propertyName,
             int FLAGS,
             float defaultValue,
             java.util.function.Function<java.lang.String,​java.lang.Float> optionalParser)
        Used to convert a JsonObject property which can handle either a String, or a Number, and transform that element into a Java Float.

        This method simply dispatches to one of the ReadJSON methods, depending upon whether the specified object property contains a string or a number.
        Parameters:
        jo - Any JsonObject
        propertyName - Any of the properties defined in the JsonObject
        FLAGS - The return-value / exception-throw flag 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

        AGAIN: 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 Float. 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.

        NOTE: null may be passed to parameter 'optionalParser'. If null is received, and if it turns out that a String to Float parser-function is required to generate the result for this method, then Float.parseFloat(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 Float, then it is returned.

        If the object-property was a String, and that String was transformed into a Float using either 'parser' - or the default parser, then that Float 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 Float, using either the user-provided 'parser' (if provided), or otherwise, the default-parser (Float.parseFloat(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:
        ReadJSON.getFLOAT(JsonObject, String, int, float), ReadJSON.parseFLOAT(JsonObject, String, int, float, Function)
        Code:
        Exact Method Body:
         JsonValue.ValueType t;
    
 return (    (! jo.containsKey(propertyName))
         ||  ((t = jo.get(propertyName).getValueType()) == NUMBER)
         ||  (t != STRING)
     )
     ? ReadJSON.getFLOAT(jo, propertyName, FLAGS, defaultValue)
     : ReadJSON.parseFLOAT(jo, propertyName, FLAGS, defaultValue, optionalParser);

      • getNUMBER

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.Number getNUMBER​
            (JsonObject jo,
             java.lang.String propertyName,
             int FLAGS,
             java.lang.Number defaultValue,
             java.util.function.Function<java.lang.String,​java.lang.Number> optionalParser)
        Used to convert a JsonObject property which can handle either a String, or a Number, and transform that element into a Java Number.

        This method simply dispatches to one of the ReadJSON methods, depending upon whether the specified object property contains a string or a number.
        Parameters:
        jo - Any JsonObject
        propertyName - Any of the properties defined in the JsonObject
        FLAGS - The return-value / exception-throw flag 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

        AGAIN: 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.

        NOTE: 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:
        ReadJSON.getNUMBER(JsonObject, String, int, Number), ReadJSON.parseNUMBER(JsonObject, String, int, Number, Function)
        Code:
        Exact Method Body:
         JsonValue.ValueType t;

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

      • getBOOLEAN

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.Boolean getBOOLEAN​
            (JsonObject jo,
             java.lang.String propertyName,
             int FLAGS,
             boolean defaultValue,
             java.util.function.Function<java.lang.String,​java.lang.Boolean> optionalParser)
        Used to convert a JsonObject property which can handle either a String, or a Number, and transform that element into a Java Boolean.

        This method simply dispatches to one of the ReadJSON methods, depending upon whether the specified object property contains a string or a number.
        Parameters:
        jo - Any JsonObject
        propertyName - Any of the properties defined in the JsonObject
        FLAGS - The return-value / exception-throw flag 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

        AGAIN: 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 Boolean. 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.

        NOTE: null may be passed to parameter 'optionalParser'. If null is received, and if it turns out that a String to Boolean parser-function is required to generate the result for this method, then Boolean.parseBoolean(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 Boolean, then it is returned.

        If the object-property was a String, and that String was transformed into a Boolean using either 'parser' - or the default parser, then that Boolean 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 Boolean, using either the user-provided 'parser' (if provided), or otherwise, the default-parser (Boolean.parseBoolean(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:
        ReadJSON.getBOOLEAN(JsonObject, String, int, boolean), ReadJSON.parseBOOLEAN(JsonObject, String, int, boolean, Function)
        Code:
        Exact Method Body:
         JsonValue.ValueType t;

 return (    (! jo.containsKey(propertyName))
         ||  ((t = jo.get(propertyName).getValueType()) == TRUE)
         || (t == FALSE)
         || (t != STRING)
     )
     ? ReadJSON.getBOOLEAN(jo, propertyName, FLAGS, defaultValue)
     : ReadJSON.parseBOOLEAN(jo, propertyName, FLAGS, defaultValue, optionalParser);

      • getObject

        🡅  🡇  ⇈  ⮫ 
        public static <T> T getObject​(JsonArray ja,
                              int index,
                              java.lang.Class<T> c,
                              boolean throwOnNull)
        Retrieve a JsonArray element, and transform it to a Java Object (POJO).
        Type Parameters:
        T - This is the Java-Type to which the JsonObject is going to be bound / transformed.

        It is important to note that this method is not as smart as you might think. The Java-Type instance that is being created / instantiated must contain a consructor that accepts a JsonObject as a parameter in order to do the actual bindng. specifically, whatever class is passed to type parameter 'T', that class must have a single-parameter constructor whose parameter-type is JsonObject
        Parameters:
        ja - Any instance of JsonArray
        index - A valid index into array parameter 'ja'. In Json (and unlike Java), array element types are not actually checked for consistency - meaning an array may hold many different types! This array-index must contain a JsonObject
        c - This is the class that will bind to the JsonObject parameter 'jo'.

        IMPORTANT: The class 'c' must have a a constructor that accepts a JsonObject. If this class doesn't have such a constructor, then a JsonBindingException throws.
        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 Type Parameter T, if the 'ja' array element located at 'index' uses the appropriate Json-Type - JsonObject.

        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 bounds of 'ja'
        JsonTypeArrException - If the array-element (specified by 'index') does not actually contain a JsonObject (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'
        JsonException - If any of the Java reflection-operations throw exceptions, those exceptions are wrapped into a JsonException instance, and then re-thrown with the original exception assigned to the Throwable.cause. Class JsonException is an unchecked / Runtime exception, while many of the cause exceptions are not. The possible cause exceptions are listed below.

        Description copied from: java.lang.Constructor.newInstance(Object... args), JDK 1.8
        ExceptionJDK Explanation
        IllegalAccessException if this Constructor object is enforcing Java language access control and the underlying constructor is inaccessible.
        IllegalArgumentException if the number of actual and formal parameters differ; if an unwrapping conversion for primitive arguments fails; or if, after possible unwrapping, a parameter value cannot be converted to the corresponding formal parameter type by a method invocation conversion; if this constructor pertains to an enum type.
        InstantiationException if the class that declares the underlying constructor represents an abstract class.
        InvocationTargetException if the underlying constructor throws an exception.
        ExceptionInInitializerError if the initialization provoked by this method fails.
        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, OBJECT, c);
         else return getObject(null, c);

     case OBJECT: return getObject((JsonObject) jv, c);

     // The JsonValue at the specified array-index does not contain a JsonObject.
     default: throw new JsonTypeArrException(ja, index, OBJECT, jv, c);
 }

      • getObject

        🡅  🡇  ⇈  ⮫ 
        public static <T> T getObject​(JsonObject jo,
                              java.lang.String propertyName,
                              java.lang.Class<T> c,
                              boolean isOptional,
                              boolean throwOnNull)
        Extract a JsonObject property, and transform it to a Java Object (POJO).
        Type Parameters:
        T - This is the Java-Type to which the JsonObject is going to be bound / transformed.

        It is important to note that this method is not as smart as you might think. The Java-Type instance that is being created / instantiated must contain a consructor that accepts a JsonObject as a parameter in order to do the actual bindng. specifically, whatever class is passed to type parameter 'T', that class must have a single-parameter constructor whose parameter-type is JsonObject
        Parameters:
        jo - Any instance of JsonObject.
        propertyName - The name of the JSON property that should be contained within 'jo'. This property will be retrieved and subsequently transformed / converted to Java-Type Type Parameter T.
        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 JsonObject property named 'propertyName' evaluates to Json-Null, then this method will throw a JsonNullObjException. When this parameter is FALSE, if the specified property contains Json-Null, then Java-Null is returned.
        Returns:
        An instance of Java-Type Type Parameter T', if the 'propertyName' is available inside 'jo', and that property uses the appropriate Json-Type - JsonObject.

        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 JsonObject (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'
        JsonException - If any of the Java reflection-operations throw exceptions, those exceptions are wrapped into a JsonException instance, and then re-thrown with the original exception assigned to the Throwable.cause. Class JsonException is an unchecked / Runtime exception, while many of the cause exceptions are not. The possible cause exceptions are listed below.

        Description copied from: java.lang.Constructor.newInstance(Object... args), JDK 1.8
        ExceptionJDK Explanation
        IllegalAccessException if this Constructor object is enforcing Java language access control and the underlying constructor is inaccessible.
        IllegalArgumentException if the number of actual and formal parameters differ; if an unwrapping conversion for primitive arguments fails; or if, after possible unwrapping, a parameter value cannot be converted to the corresponding formal parameter type by a method invocation conversion; if this constructor pertains to an enum type.
        InstantiationException if the class that declares the underlying constructor represents an abstract class.
        InvocationTargetException if the underlying constructor throws an exception.
        ExceptionInInitializerError if the initialization provoked by this method fails.
        Code:
        Exact Method Body:
         if (! jo.containsKey(propertyName))
 {
     if (isOptional) return null;

     throw new JsonPropMissingException(jo, propertyName, OBJECT, c);
 }

 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, OBJECT, c);

         return getObject(null, c);

     case OBJECT: return getObject((JsonObject) jv, c);

         // The JsonObject propertydoes not contain a JsonObject.
     default: throw new JsonTypeObjException(jo, propertyName, OBJECT, jv, c);
 }

      • getObject

        🡅  ⇈  ⮫ 
        public static <T> T getObject​(JsonObject jo,
                              java.lang.Class<T> c)
        This class contains a lot of the reason / impetus for writing 'ReadJSON'. This does converts a JsonObject into a Java-Object. The actual binding must be implemented by the programmer - because the class-type that is passed to this method (parameter 'c') must have a constructor accepting this JsonObject.

        IMPORTANT: This method makes no effort to figure out which JsonObject properties should be bound to the POJO Object fields! Note, however, that all of the other one-line type conversion methods in this class is exactly why writing such a constuctor for your Java-Type's should be much easier.

        That really is the point of this class.
        Type Parameters:
        T - This is the Java-Type to which the JsonObject is going to be bound / transformed.

        It is important to note that this method is not as smart as you might think. The Java-Type instance that is being created / instantiated must contain a consructor that accepts a JsonObject as a parameter in order to do the actual bindng. specifically, whatever class is passed to type parameter 'T', that class must have a single-parameter constructor whose parameter-type is JsonObject
        Parameters:
        jo - This may be any JsonObject which can be bound to 'c'.

        NOTE: This parameter may be null, and if it is, null is passed to the 'c' constructor.
        c - This is the class that will bind to the JsonObject parameter 'jo'.

        IMPORTANT: The class 'c' must have a a constructor that accepts a JsonObject. If this class doesn't have such a constructor, then a JsonBindingException throws.
        Returns:
        An instance of the class 'T', which is specified by 'c'
        Throws:
        JsonException - If any of the Java reflection-operations throw exceptions, those exceptions are wrapped into a JsonException instance, and then re-thrown with the original exception assigned to the Throwable.cause. Class JsonException is an unchecked / Runtime exception, while many of the cause exceptions are not. The possible cause exceptions are listed below.

        Description copied from: java.lang.Constructor.newInstance(Object... args), JDK 1.8
        ExceptionJDK Explanation
        IllegalAccessException if this Constructor object is enforcing Java language access control and the underlying constructor is inaccessible.
        IllegalArgumentException if the number of actual and formal parameters differ; if an unwrapping conversion for primitive arguments fails; or if, after possible unwrapping, a parameter value cannot be converted to the corresponding formal parameter type by a method invocation conversion; if this constructor pertains to an enum type.
        InstantiationException if the class that declares the underlying constructor represents an abstract class.
        InvocationTargetException if the underlying constructor throws an exception.
        ExceptionInInitializerError if the initialization provoked by this method fails.
        Code:
        Exact Method Body:
         Constructor<T> ctor = null;

 try
 {
     // This just gets a "Constructor" using Reflection.  The main point is that the
     // Constructor must have exactly one parameter - and that parameter must have a
     // type "JsonObject"  (basic java.lang.reflect stuff)
     //
     //System.out.println("c.getName:():" + c.getName());

     ctor = c.getDeclaredConstructor(JsonObject.class);
 }
 catch (Exception e)
 {
     if (c.getEnclosingClass() != null)
     {
         int modifiers = c.getModifiers();

         if ((! Modifier.isStatic(modifiers)) ||  (! Modifier.isPublic(modifiers)))

             throw new JsonException(
                 "Unable to retrieve POJO Constructor for class: " +
                 "[" + c.getName() + "]\n" +
                 "Your class appears to be a Nested-Class, however it has not been " +
                 "declared public and static.  There is no way to retrieve a " +
                 "1-Argument JsonObject Constructor for Nested-Type's unless the " +
                 "type has been declared BOTH static AND public.\n" +
                 "See Exception.getCause() for details.",
                 e
             );
     }

     else throw new JsonException(
         "Unable to retrieve POJO Constructor for class: [" + c.getName() + "]\n" +
         "Do you have a one-argument, public, constructor for this class?\n" +
         "Does it accept a JsonObject in its parameter list?\n" +
         "See Exception.getCause() for details.",
         e
     );
 }

 // If the user has requested a class that doesn't have that kind of constructor, then
 // there is no way to build the object.  Throw an exception.

 if (ctor == null) throw new JsonException(
     "The class which was passed to parameter 'c' [" + c.getName() + "] does not " +
     "appear to have a constructor with precisely one parameter of type JsonObject."
 );

 // Call that constructor using the parameter 'jo', and return that instance / object
 try
     { return ctor.newInstance(jo); }

 // NOTE: There are *MANY* possible Exception's that may be thrown by reflective
 //       operations like those above.  Furthermore, they are *ALL* checked exceptions.
 //       The code below wraps those exceptions into an UN-CHECKED / RuntimeException
 //       (JsonException)

 catch (Exception e)
 {
     throw new JsonException(
         "Unable to instantiate class: [" + c.getName() + "] using provided " +
             "Java-Object\n" +
         "See Exception.getCause() for details.",
         e
     );
 }