package Torello.Java.Additional;

import javax.json.*;
import java.math.*;

import static javax.json.JsonValue.ValueType.*;
import static Torello.Java.Additional.JFlag.*;

import java.util.function.Function;

/**
 * Class which provides a series of helper functions for both {@link ReadJSON} and
 * {@link ReadJSON.XL}.
 * 
 * <BR /><BR />The helpers for class {@link ReadArrJSON} are kept inside that class, and do not
 * appear in this one.
 * 
 * <BR /><BR /><B CLASS=JDDescLabel>IMPORTANT:</B>
 * <BR />100% of the helper-methods that appear here are protected, and cannot be accessed
 * outside of this package.  They are included in the documentation solely for the purposes of
 * (<I>if you happen to be interested</I>) letting you know how the JSON-Tools work.  <I>It is not
 * intended that programmers would ever need to invoke, directly, any of the methods in this
 * class!</I>
 */
@Torello.JavaDoc.StaticFunctional
public class RJInternal
{
    private RJInternal() { }


    // ********************************************************************************************
    // ********************************************************************************************
    // "Helpers for the Helpers for the Helpers"
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Generates a {@code JsonException} with a uniformly-consisten error-message.
     
    protected static void throwJsonBindingException(Class<?> c)
    {
        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."
        );
    }
    */

    /**
     * Helper Method that generates an {@code ArithmeticException} with a uniformly-consistent
     * exception message
     * @param jn A Java {@code javax.json.JsonNumber} whose magnitude is too large.
     * @throws ArithmeticException
     */
    protected static void throwAE_INFINITY
        (JsonNumber jn, String primTypeName, boolean positiveOrNegative)
    {
        throw new ArithmeticException(
            "When attempting to conver the JsonNumber [" + jn.toString() + "] to a " +
            primTypeName + " primitive, the number had a magnitude that was too large: " +
            (positiveOrNegative ? "Positive" : "Negative") + " Infinity was returned."
        );
    }

    /**
     * Helper Method that generates an {@code ArithmeticException} with a uniformly-consistent
     * exception message
     * @param bd A Java {@code java.math.BigDecimal} whose magnitude is too large.
     * @throws ArithmeticException
     */
    protected static void throwAE_INFINITY
        (BigDecimal bd, String primTypeName, boolean positiveOrNegative)
    {
        throw new ArithmeticException(
            "When attempting to conver the JsonNumber [" + bd.toString() + "] to a " +
            primTypeName + " primitive, the number had a magnitude that was too large: " +
            (positiveOrNegative ? "Positive" : "Negative") + " Infinity was returned."
        );
    }

    /**
     * Converts a {@link JsonNumber} into a Java {@code double}
     * @param jn Any {@link JsonNumber}
     * @return java {@code double} primitive
     * @throws JsonArithmeticException If infinity is returned from the call to
     * {@code BigDecimal.doubleValue()}
     * @see JsonNumber#bigDecimalValue()
     */
    protected static double DOUBLE_WITH_CHECK(JsonNumber jn)
    { return DOUBLE_WITH_CHECK(jn.bigDecimalValue()); }

    /**
     * Converts a {@code BigDecimal} into a Java {@code double}
     * @param bd Any {@code BigDecimal}
     * @return Java {@code double} primitive
     * @throws JsonArithmeticException If infinity is returned from the call to
     * {@code code BigDecimal.doubleValue()}
     */
    protected static double DOUBLE_WITH_CHECK(BigDecimal bd)
    {
        double ret = bd.doubleValue();

        if (ret == Double.NEGATIVE_INFINITY) throwAE_INFINITY(bd, "double", false);
        if (ret == Double.POSITIVE_INFINITY) throwAE_INFINITY(bd, "double", true);

        return ret;
    }

    /**
     * Converts a {@link JsonNumber} into a Java {@code float}
     * @param jn Any {@link JsonNumber}
     * @return java {@code float} primitive
     * @throws JsonArithmeticException If infinity is returned from the call to
     * {@code BigDecimal.floatValue()}
     * @see JsonNumber#bigDecimalValue()
     */
    protected static float FLOAT_WITH_CHECK(JsonNumber jn)
    { return FLOAT_WITH_CHECK(jn.bigDecimalValue()); }

    /**
     * Converts a {@code BigDecimal} into a Java {@code float}
     * @param bd Any {@code BigDecimal}
     * @return Java {@code float} primitive
     * @throws JsonArithmeticException If infinity is returned from the call to
     * {@code code BigDecimal.floatValue()}
     */
    protected static float FLOAT_WITH_CHECK(BigDecimal bd)
    {
        float ret = bd.floatValue();

        if (ret == Float.NEGATIVE_INFINITY) throwAE_INFINITY(bd, "float", false);
        if (ret == Float.POSITIVE_INFINITY) throwAE_INFINITY(bd, "float", true);

        return ret;
    }

    /**
     * Converts any {@link JsonNumber} into one of the inheriting subclasses of Java class
     * {@code Number}
     * @param jn Any {@link JsonNumber}
     * @return The most appropriate intance of {@code java.lang.Number}
     * @see ReadJSON#getNUMBER(JsonObject, String, int, Number)
     * @see ReadJSON#getNUMBER(JsonArray, int, int, Number)
     * @see JsonNumber#isIntegral()
     * @see JsonNumber#bigIntegerValue()
     * @see JsonNumber#bigDecimalValue()
     */
    protected static Number convertToNumber(JsonNumber jn)
    {
        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 ((f != Float.NEGATIVE_INFINITY) && (f != Float.POSITIVE_INFINITY)) return f;

            double d = bd.doubleValue();
            if ((f != Double.NEGATIVE_INFINITY) && (f != Double.POSITIVE_INFINITY)) return d;

            return bd;
        }
    }

    /**
     * Converts any {@code java.lang.String} into one of the inheriting subclasses of Java class
     * {@code Number}
     * @param s Any {@code String}
     * @return The most appropriate instance of {@code java.lang.Number}
     * @throws NumberFormatException If the input {@code String} isn't properly formatted as a
     * number.
     * @see ReadJSON#parseNUMBER(JsonObject, String, int, Number, Function)
     * @see ReadJSON#parseNUMBER(JsonArray, int, int, Number, Function)
     */
    protected static Number convertToNumber(String s)
    { return convertToNumber(new BigDecimal(s.trim())); }

    /**
     * Converts any {@code java.math.BigDecimal} into one of the inheriting subclasses of
     * {@code Number}.
     * @param bd Any {@code BigDecimal}
     * @return The most appropriate instance of {@code java.lang.Number}
     */
    protected static Number convertToNumber(BigDecimal bd)
    {
        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 ((f != Float.NEGATIVE_INFINITY) && (f != Float.POSITIVE_INFINITY)) return f;

            double d = bd.doubleValue();
            if ((f != Double.NEGATIVE_INFINITY) && (f != Double.POSITIVE_INFINITY)) return d;

            return bd;
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // PRIMARY FOUR "GET" METHODS FOR NUMBERS
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This is an internal helper method for retrieving an element from a {@link JsonArray},
     * and converting it to one of the standard <B STYLE='color: red;'>Java Types</B>.
     * 
     * @param <T> <EMBED CLASS='external-html' DATA-FILE-ID=JR_GET_T>
     * @param ja Any instance of {@link JsonArray}
     * @param index Any index into the array which holds a {@link JsonNumber}
     * @param primitiveClass <EMBED CLASS='external-html' DATA-FILE-ID=JR_GET_PC>
     * @param jsonTypeToJavaType <EMBED CLASS='external-html' DATA-FILE-ID=JR_GET_JTTJT>
     * 
     * @return The converted number, as an instance Generic-Parameter {@code 'T'}
     * 
     * @throws JsonNullPrimitiveArrException <EMBED CLASS='external-html'
     *  DATA-FILE-ID=JR_GET_JNPAEX>
     * @throws JsonTypeArrException <EMBED CLASS='external-html' DATA-FILE-ID=JR_GET_JTAEX>
     * @throws JsonArithmeticArrException If there any arithmetic problems during the conversion
     * @throws IndexOutOfBoundsException If {@code 'index'} is out of the bounds of {@code 'ja'}
     * 
     * @see ReadJSON#getInt(JsonArray, int)
     * @see ReadJSON#getLong(JsonArray, int)
     * @see ReadJSON#getShort(JsonArray, int)
     * @see ReadJSON#getByte(JsonArray, int)
     * @see ReadJSON#getDouble(JsonArray, int)
     * @see ReadJSON#getFloat(JsonArray, int)
     */
    protected static <T> T GET(
            JsonArray ja, int index, Class<T> primitiveClass,
            Function<JsonNumber, T> jsonTypeToJavaType
        )
    {
        // This will throw an IndexOutOfBoundsException if the index is out of bounds.
        JsonValue jv = ja.get(index);

        switch (jv.getValueType())
        {
            // This method allows for null-returns.  If Json-Null, return Java-Null.
            case NULL: throw new JsonNullPrimitiveArrException
                (ja, index, NUMBER, primitiveClass);

            // This will throw ArithmeticException if it cannot be converted
            case NUMBER:

                // REMEMBER: The primary reason for this class is that MEANINGFUL ERROR MESSAGES
                //           make Json-Binding a lot easer...  "JsonArithmeticException" has just
                //           about everything that you need to know when debugging this stuff

                try
                    { return jsonTypeToJavaType.apply((JsonNumber) jv); }

                catch (ArithmeticException ae)
                {
                    throw new JsonArithmeticArrException
                        (ae, ja, index, NUMBER, jv, primitiveClass);
                }

            // The JsonValue at the specified array-index does not contain an JsonNumber.
            default: throw new JsonTypeArrException
                (ja, index, NUMBER, jv, primitiveClass);
        }
    }

    /**
     * This is an internal helper method for retrieving an element from a {@link JsonArray},
     * and converting it to one of the standard <B STYLE='color: red;'>Java Types</B>.
     * 
     * @param <T> <EMBED CLASS='external-html' DATA-FILE-ID=JR_GET_T>
     * @param ja Any instance of {@link JsonArray}
     * @param index Any index into the array which holds a {@link JsonNumber}
     * @param jsonTypeToJavaType <EMBED CLASS='external-html' DATA-FILE-ID=JR_GET_JTTJT>
     * 
     * @return The converted number, as an instance Generic-Parameter {@code 'T'}
     * 
     * @throws JsonTypeArrException <EMBED CLASS='external-html' DATA-FILE-ID=JR_GET_JTAEX>
     * @throws JsonArithmeticArrException If there any arithmetic problems during the conversion
     * @throws IndexOutOfBoundsException If {@code 'index'} is out of the bounds of {@code 'ja'}
     * 
     * @see ReadJSON#getINTEGER(JsonArray, int)
     * @see ReadJSON#getLONG(JsonArray, int)
     * @see ReadJSON#getSHORT(JsonArray, int)
     * @see ReadJSON#getBYTE(JsonArray, int)
     * @see ReadJSON#getDOUBLE(JsonArray, int)
     * @see ReadJSON#getFLOAT(JsonArray, int)
     */
    protected static <T extends java.lang.Number> T GET
        (JsonArray ja, int index, Function<JsonNumber, T> jsonTypeToJavaType, Class<T> returnClass)
    {
        // This will throw an IndexOutOfBoundsException if the index is out of bounds.
        // Since this *IS NOT* a method with FLAGS, the user has no way to avoid this exception
        // throw if, indeed, the index really is out of bounds!
        //
        // Using one of the 'FLAGS' variants of the 'GET' array-index, a user may request that
        // either null or a default-value be returned.  Not with this version-of 'GET', though.

        JsonValue jv = ja.get(index);

        switch (jv.getValueType())
        {
            // This method allows for null-returns.  If Json-Null, return Java-Null.
            case NULL: return null;

            // This will throw ArithmeticException if it cannot be converted
            case NUMBER:

                // REMEMBER: The primary reason for this class is that MEANINGFUL ERROR MESSAGES
                //           make Json-Binding a lot easer...  "JsonArithmeticException" has just
                //           about everything that you need to know when debugging this stuff

                try
                    { return jsonTypeToJavaType.apply((JsonNumber) jv); }

                catch (ArithmeticException ae)
                {
                    throw new JsonArithmeticArrException
                        (ae, ja, index, NUMBER, jv, returnClass);
                }

            // The JsonValue at the specified array-index does not contain an JsonNumber.
            default: throw new JsonTypeArrException
                (ja, index, NUMBER, jv, returnClass);
        }
    }

    /**
     * This is an internal helper method for retrieving a property from a {@link JsonObject},
     * and converting it to one of the standard <B STYLE='color: red;'>Java Types</B>.
     * 
     * @param <T> <EMBED CLASS='external-html' DATA-FILE-ID=JR_GET_T>
     * @param jo Any instance of {@link JsonObject}
     * @param propertyName Any property name contained by {@code 'jo'}
     * @param jsonTypeToJavaType <EMBED CLASS='external-html' DATA-FILE-ID=JR_GET_JTTJT>
     * 
     * @return The converted number, as an instance Generic-Parameter {@code 'T'}
     * 
     * @throws JsonNullPrimitiveObjException <EMBED CLASS='external-html'
     *  DATA-FILE-ID=JR_GET_JNPOEX>
     * @throws JsonPropMissingException If the property is missing, and {@code 'isOptional'}
     * is {@code FALSE}.
     * @throws JsonTypeObjException <EMBED CLASS='external-html' DATA-FILE-ID=JR_GET_JTAEX>
     * @throws JsonArithmeticObjException If there any arithmetic problems during the conversion
     * 
     * @see ReadJSON#getInt(JsonObject, String)
     * @see ReadJSON#getLong(JsonObject, String)
     * @see ReadJSON#getShort(JsonObject, String)
     * @see ReadJSON#getByte(JsonObject, String)
     * @see ReadJSON#getDouble(JsonObject, String)
     * @see ReadJSON#getFloat(JsonObject, String)
     */
    protected static <T> T GET(
            JsonObject jo, String propertyName, Class<T> primitiveClass,
            Function<JsonNumber, T> jsonTypeToJavaType
        )
    {
        // Here, a 'get' request was made for a property that isn't actually listed among the
        // properties in the provided JsonObject.  Since this internal 'GET' is used by methods
        // that are trying to return a Java Primitive (like 'int' or 'float'), then an exception
        // has to be thrown.  The option of returning 'null' isn't possible here!
    
        if (! jo.containsKey(propertyName)) throw new JsonPropMissingException
            (jo, propertyName, NUMBER, primitiveClass);

        JsonValue jv = jo.get(propertyName);

        switch (jv.getValueType())
        {
            // This method allows for null-returns.  If Json-Null, return Java-Null.
            case NULL: throw new JsonNullPrimitiveObjException
                (jo, propertyName, NUMBER, primitiveClass);

            // This will throw ArithmeticException if this isn't a proper Java int
            case NUMBER:

                // REMEMBER: The primary reason for this class is that MEANINGFUL ERROR MESSAGES
                //           make Json-Binding a lot easer...  "JsonArithmeticException" has just
                //           about everything that you need to know when debugging this stuff

                try
                    { return jsonTypeToJavaType.apply((JsonNumber) jv); }

                catch (ArithmeticException ae)
                {
                    throw new JsonArithmeticObjException
                        (ae, jo, propertyName, NUMBER, jv, primitiveClass);
                }

            // The JsonObject property does not contain a JsonNumber.
            default: throw new JsonTypeObjException
                (jo, propertyName, NUMBER, jv, primitiveClass);
        }
    }

    /**
     * This is an internal helper method for retrieving a property from a {@link JsonObject},
     * and converting it to one of the standard <B STYLE='color: red;'>Java Types</B>.
     * 
     * @param <T> <EMBED CLASS='external-html' DATA-FILE-ID=JR_GET_T>
     * @param jo Any instance of {@link JsonObject}
     * @param propertyName Any property name contained by {@code 'jo'}
     * @param isOptional Indicates whether {@code 'propertyName'} may be missing from {@code 'jo'}
     * @param jsonTypeToJavaType <EMBED CLASS='external-html' DATA-FILE-ID=JR_GET_JTTJT>
     * 
     * @return The converted number, as an instance Generic-Parameter {@code 'T'}
     * 
     * @throws JsonPropMissingException If the property is missing, and {@code 'isOptional'}
     * is {@code FALSE}.
     * @throws JsonTypeObjException <EMBED CLASS='external-html' DATA-FILE-ID=JR_GET_JTAEX>
     * @throws JsonArithmeticObjException If there any arithmetic problems during the conversion
     * 
     * @see ReadJSON#getINTEGER(JsonObject, String, boolean)
     * @see ReadJSON#getLONG(JsonObject, String, boolean)
     * @see ReadJSON#getSHORT(JsonObject, String, boolean)
     * @see ReadJSON#getBYTE(JsonObject, String, boolean)
     * @see ReadJSON#getDOUBLE(JsonObject, String, boolean)
     * @see ReadJSON#getFLOAT(JsonObject, String, boolean)
     */
    protected static <T extends java.lang.Number> T GET(
            JsonObject jo, String propertyName, boolean isOptional,
            Function<JsonNumber, T> jsonTypeToJavaType, Class<T> returnClass
        )
    {
        // Here, a 'get' request was made for a property that isn't actually listed among the
        // properties in the provided JsonObject.  If 'isOptional' return null, otherwise throw

        if (! jo.containsKey(propertyName))
        {
            if (isOptional) return null;

            throw new JsonPropMissingException
                (jo, propertyName, NUMBER, returnClass);
        }

        JsonValue jv = jo.get(propertyName);

        switch (jv.getValueType())
        {
            // This method allows for null-returns.  If Json-Null, return Java-Null.
            case NULL: return null;

            // This will throw ArithmeticException if this isn't a proper Java int
            case NUMBER:

                // REMEMBER: The primary reason for this class is that MEANINGFUL ERROR MESSAGES
                //           make Json-Binding a lot easer...  "JsonArithmeticException" has just
                //           about everything that you need to know when debugging this stuff

                try
                    { return jsonTypeToJavaType.apply((JsonNumber) jv); }

                catch (ArithmeticException ae)
                {
                    throw new JsonArithmeticObjException
                        (ae, jo, propertyName, NUMBER, jv, returnClass);
                }

            // The JsonObject property does not contain a JsonNumber.
            default: throw new JsonTypeObjException
                (jo, propertyName, NUMBER, jv, returnClass);
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // FLAG-CHECKER METHODS another section of "Helpers for the Helpers ..."
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Flag Checker for {@code IndexOutOfBoundsException}.
     * 
     * <BR /><BR />Checks whether the relevant flags were set in the users {@code FLAGS} parameter,
     * and either returns the appropriate value accordingly, or throws
     * {@code IndexOutOfBoundsException}.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=FLAG_PRECEDENCE>
     * 
     * @param <T> If requested, the default-value is returned, and this is its type.
     * 
     * @return Can return either the user-provided default-value, or null depending on whether a
     * match was found in the user's request settings ({@code 'FLAGS'}).
     * 
     * @throws IndexOutOfBoundsException If no flag was set specifying one of the two return-value
     * options.
     * 
     * @see JFlag#RETURN_NULL_ON_IOB
     * @see JFlag#RETURN_DEFVAL_ON_IOB
     * @see JFlag#RETURN_NULL_ON_ANY_ALL
     * @see JFlag#RETURN_DEFVAL_ON_ANY_ALL
     */
    protected static <T> T IOOBEX(JsonArray ja, int index, T defaultValue, int FLAGS)
    {
        if ((FLAGS & RETURN_NULL_ON_IOB) != 0)          return null;
        if ((FLAGS & RETURN_DEFVAL_ON_IOB) != 0)        return defaultValue;
        if ((FLAGS & RETURN_NULL_ON_ANY_ALL) != 0)      return null;
        if ((FLAGS & RETURN_DEFVAL_ON_ANY_ALL) != 0)    return defaultValue;

        ja.get(index); // Throws an IndexOutOfBoundsException

        // If you have reached this statment, this method was not applied properly
        throw new Torello.Java.UnreachableError();
    }

    /**
     * Flag Checker for {@link JsonPropMissingException}
     * 
     * <BR /><BR />Checks whether the relevant flags were set in the users {@code FLAGS} parameter,
     * and either returns the appropriate value accordingly, or throws
     * {@code JsonPropMissingException}.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=FLAG_PRECEDENCE>
     * 
     * @param <T> If requested, the default-value is returned, and this is its type.
     * 
     * @return Can return either the user-provided default-value, or null depending on whether a
     * match was found in the user's request settings ({@code 'FLAGS'}).
     * 
     * @throws JsonPropMissingException If no flag was set specifying one of the two return-value
     * options.
     * 
     * @see JFlag#RETURN_NULL_ON_MISSING
     * @see JFlag#RETURN_DEFVAL_ON_MISSING
     * @see JFlag#RETURN_NULL_ON_ANY_ALL
     * @see JFlag#RETURN_DEFVAL_ON_ANY_ALL
     */
    protected static <T> T JPMEX(
            JsonObject jo, String propertyName, T defaultValue, int FLAGS,
            JsonValue.ValueType expectedType, Class<T> returnClass
        )
    {
        if ((FLAGS & RETURN_NULL_ON_MISSING) != 0)      return null;
        if ((FLAGS & RETURN_DEFVAL_ON_MISSING) != 0)    return defaultValue;
        if ((FLAGS & RETURN_NULL_ON_ANY_ALL) != 0)      return null;
        if ((FLAGS & RETURN_DEFVAL_ON_ANY_ALL) != 0)    return defaultValue;

        throw new JsonPropMissingException(jo, propertyName, expectedType, returnClass);
    }

    /**
     * Flag Checker for {@link JsonNullArrException}
     * 
     * <BR /><BR />Checks whether the relevant flags were set in the users {@code FLAGS} parameter,
     * and either returns the appropriate value accordingly, or throws
     * {@code JsonNullArrException}.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=FLAG_PRECEDENCE>
     * 
     * @param <T> If requested, the default-value is returned, and this is its type.
     * 
     * @return Can return either the user-provided default-value, or null depending on whether a
     * match was found in the user's request settings ({@code 'FLAGS'}).
     * 
     * @throws JsonNullArrException If no flag was set specifying one of the two return-value
     * options.
     * 
     * @see JFlag#RETURN_NULL_ON_NULL
     * @see JFlag#RETURN_DEFVAL_ON_NULL
     * @see JFlag#RETURN_NULL_ON_ANY_ALL
     * @see JFlag#RETURN_DEFVAL_ON_ANY_ALL
     */
    protected static <T> T JNAEX(
            JsonArray ja, int index, T defaultValue, int FLAGS, JsonValue.ValueType expectedType,
            Class<T> returnClass
        )
    {
        if ((FLAGS & RETURN_NULL_ON_NULL) != 0)         return null;
        if ((FLAGS & RETURN_DEFVAL_ON_NULL) != 0)       return defaultValue;
        if ((FLAGS & RETURN_NULL_ON_ANY_ALL) != 0)      return null;
        if ((FLAGS & RETURN_DEFVAL_ON_ANY_ALL) != 0)    return defaultValue;

        throw new JsonNullArrException(ja, index, expectedType, returnClass);
    }

    /**
     * Flag Checker for {@link JsonNullObjException}
     * 
     * <BR /><BR />Checks whether the relevant flags were set in the users {@code FLAGS} parameter,
     * and either returns the appropriate value accordingly, or throws
     * {@code JsonNullObjException}.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=FLAG_PRECEDENCE>
     * 
     * @param <T> If requested, the default-value is returned, and this is its type.
     * 
     * @return Can return either the user-provided default-value, or null depending on whether a
     * match was found in the user's request settings ({@code 'FLAGS'}).
     * 
     * @throws JsonNullObjException If no flag was set specifying one of the two return-value
     * options.
     * 
     * @see JFlag#RETURN_NULL_ON_NULL
     * @see JFlag#RETURN_DEFVAL_ON_NULL
     * @see JFlag#RETURN_NULL_ON_ANY_ALL
     * @see JFlag#RETURN_DEFVAL_ON_ANY_ALL
     */
    protected static <T> T JNOEX(
            JsonObject jo, String propertyName, T defaultValue, int FLAGS,
            JsonValue.ValueType expectedType, Class<T> returnClass
        )
    {
        if ((FLAGS & RETURN_NULL_ON_NULL) != 0)         return null;
        if ((FLAGS & RETURN_DEFVAL_ON_NULL) != 0)       return defaultValue;
        if ((FLAGS & RETURN_NULL_ON_ANY_ALL) != 0)      return null;
        if ((FLAGS & RETURN_DEFVAL_ON_ANY_ALL) != 0)    return defaultValue;

        throw new JsonNullObjException(jo, propertyName, expectedType, returnClass);
    }

    /**
     * Flag Checker for {@link JsonTypeArrException}
     * 
     * <BR /><BR />Checks whether the relevant flags were set in the users {@code FLAGS} parameter,
     * and either returns the appropriate value accordingly, or throws
     * {@code JsonTypeArrException}.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=FLAG_PRECEDENCE>
     * 
     * @param <T> If requested, the default-value is returned, and this is its type.
     * 
     * @return Can return either the user-provided default-value, or null depending on whether a
     * match was found in the user's request settings ({@code 'FLAGS'}).
     * 
     * @throws JsonTypeArrException If no flag was set specifying one of the two return-value
     * options.
     * 
     * @see JFlag#RETURN_NULL_ON_WRONG_JSONTYPE
     * @see JFlag#RETURN_DEFVAL_ON_WRONG_JSONTYPE
     * @see JFlag#RETURN_NULL_ON_ANY_ALL
     * @see JFlag#RETURN_DEFVAL_ON_ANY_ALL
     */
    protected static <T> T JTAEX(
            JsonArray ja, int index, T defaultValue, int FLAGS, JsonValue.ValueType expectedType,
            JsonValue retrievedValue, Class<T> returnClass
        )
    {
        if ((FLAGS & RETURN_NULL_ON_WRONG_JSONTYPE) != 0)   return null;
        if ((FLAGS & RETURN_DEFVAL_ON_WRONG_JSONTYPE) != 0) return defaultValue;
        if ((FLAGS & RETURN_NULL_ON_ANY_ALL) != 0)          return null;
        if ((FLAGS & RETURN_DEFVAL_ON_ANY_ALL) != 0)        return defaultValue;

        throw new JsonTypeArrException(ja, index, expectedType, retrievedValue, returnClass);
    }

    /**
     * Flag Checker for {@link JsonTypeObjException}
     * 
     * <BR /><BR />Checks whether the relevant flags were set in the users {@code FLAGS} parameter,
     * and either returns the appropriate value accordingly, or throws
     * {@code JsonNullObjException}.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=FLAG_PRECEDENCE>
     * 
     * @param <T> If requested, the default-value is returned, and this is its type.
     * 
     * @return Can return either the user-provided default-value, or null depending on whether a
     * match was found in the user's request settings ({@code 'FLAGS'}).
     * 
     * @throws JsonNullObjException If no flag was set specifying one of the two return-value
     * options.
     * 
     * @see JFlag#RETURN_NULL_ON_WRONG_JSONTYPE
     * @see JFlag#RETURN_DEFVAL_ON_WRONG_JSONTYPE
     * @see JFlag#RETURN_NULL_ON_ANY_ALL
     * @see JFlag#RETURN_DEFVAL_ON_ANY_ALL
     */
    protected static <T> T JTOEX(
            JsonObject jo, String propertyName, T defaultValue, int FLAGS,
            JsonValue.ValueType expectedType, JsonValue retrievedValue, Class<T> returnClass
        )
    {
        if ((FLAGS & RETURN_NULL_ON_WRONG_JSONTYPE) != 0)   return null;
        if ((FLAGS & RETURN_DEFVAL_ON_WRONG_JSONTYPE) != 0) return defaultValue;
        if ((FLAGS & RETURN_NULL_ON_ANY_ALL) != 0)          return null;
        if ((FLAGS & RETURN_DEFVAL_ON_ANY_ALL) != 0)        return defaultValue;

        throw new JsonTypeObjException
            (jo, propertyName, expectedType, retrievedValue, returnClass);
    }

    /**
     * Flag Checker for {@link JsonStrParseArrException}
     * 
     * <BR /><BR />Checks whether the relevant flags were set in the users {@code FLAGS} parameter,
     * and either returns the appropriate value accordingly, or throws
     * {@code JsonStrParseArrException}.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=FLAG_PRECEDENCE>
     * 
     * @param <T> If requested, the default-value is returned, and this is its type.
     * 
     * @return Can return either the user-provided default-value, or null depending on whether a
     * match was found in the user's request settings ({@code 'FLAGS'}).
     * 
     * @throws JsonStrParseArrException If no flag was set specifying one of the two return-value
     * options.
     * 
     * @see JFlag#RETURN_NULL_ON_SPEX
     * @see JFlag#RETURN_DEFVAL_ON_SPEX
     * @see JFlag#RETURN_NULL_ON_ANY_ALL
     * @see JFlag#RETURN_DEFVAL_ON_ANY_ALL
     */
    protected static <T> T JSPAEX(
            Exception e, JsonArray ja, int index, T defaultValue, int FLAGS,
            JsonValue retrievedValue, Class<T> returnClass
        )
    {
        if ((FLAGS & RETURN_NULL_ON_SPEX) != 0)         return null;
        if ((FLAGS & RETURN_DEFVAL_ON_SPEX) != 0)       return defaultValue;
        if ((FLAGS & RETURN_NULL_ON_ANY_ALL) != 0)      return null;
        if ((FLAGS & RETURN_DEFVAL_ON_ANY_ALL) != 0)    return defaultValue;

        throw new JsonStrParseArrException(e, ja, index, retrievedValue, returnClass);
    }

    /**
     * Flag Checker for {@link JsonStrParseObjException}
     * 
     * <BR /><BR />Checks whether the relevant flags were set in the users {@code FLAGS} parameter,
     * and either returns the appropriate value accordingly, or throws
     * {@code JsonStrParseObjException}.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=FLAG_PRECEDENCE>
     * 
     * @param <T> If requested, the default-value is returned, and this is its type.
     * 
     * @return Can return either the user-provided default-value, or null depending on whether a
     * match was found in the user's request settings ({@code 'FLAGS'}).
     * 
     * @throws JsonStrParseObjException If no flag was set specifying one of the two return-value
     * options.
     * 
     * @see JFlag#RETURN_NULL_ON_SPEX
     * @see JFlag#RETURN_DEFVAL_ON_SPEX
     * @see JFlag#RETURN_NULL_ON_ANY_ALL
     * @see JFlag#RETURN_DEFVAL_ON_ANY_ALL
     */
    protected static <T> T JSPOEX(
            Exception e, JsonObject jo, String propertyName, T defaultValue, int FLAGS,
            JsonValue retrievedValue, Class<T> returnClass
        )
    {
        if ((FLAGS & RETURN_NULL_ON_SPEX) != 0)         return null;
        if ((FLAGS & RETURN_DEFVAL_ON_SPEX) != 0)       return defaultValue;
        if ((FLAGS & RETURN_NULL_ON_ANY_ALL) != 0)      return null;
        if ((FLAGS & RETURN_DEFVAL_ON_ANY_ALL) != 0)    return defaultValue;

        throw new JsonStrParseObjException(e, jo, propertyName, retrievedValue, returnClass);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // GET: USES-FLAG METHODS
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This is an internal helper method for retrieving an element from a {@link JsonArray},
     * and converting it to a <B STYLE='color: red;'>Java Type</B>.
     * <EMBED CLASS=defs DATA-TYPE=number DATA-JTYPE=JsonNumber>
     * @param ja Any instance of {@link JsonArray}
     * @param index The array index containing the element to retrieve.
     * @param FLAGS The return-value / exception-throw flag constants defined in {@link JFlag}
     * @param defaultValue This is the 'Default Value' returned by this method, if there are any
     * problems converting or extracting the specified number, and the appropriate flags are set.
     * 
     * @return On success, this method returns the converted number.
     * 
     * @throws IndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=JRF_IOOBEX>
     * @throws JsonArithmeticArrException <EMBED CLASS='external-html' DATA-FILE-ID=JRF_JAEX>
     * @throws JsonNullArrException <EMBED CLASS='external-html' DATA-FILE-ID=JRF_JNAEX>
     * @throws JsonTypeArrException <EMBED CLASS='external-html' DATA-FILE-ID=JRF_JTAEX>
     * 
     * @see ReadJSON#getINTEGER(JsonArray, int, int, int)
     * @see ReadJSON#getLONG(JsonArray, int, int, long)
     * @see ReadJSON#getSHORT(JsonArray, int, int, short)
     * @see ReadJSON#getBYTE(JsonArray, int, int, byte)
     * @see ReadJSON#getDOUBLE(JsonArray, int, int, double)
     * @see ReadJSON#getFLOAT(JsonArray, int, int, float)
     * @see ReadJSON#getNUMBER(JsonArray, int, int, Number)
     */
    protected static <T extends java.lang.Number> T GET(
            JsonArray ja, int index,
            int FLAGS, T defaultValue,
            Class<T> returnClass,
            Function<JsonNumber, T> jsonTypeToJavaType,
            Function<JsonNumber, T> typeToType2
        )
    {
        // When TRUE, the index provided turned out to be outside of the bounds of the array.  The
        // IndexOutOfBounds "handler" (the method called here) will check the FLAGS, and:
        //
        //  1) return the defaultValue (if Requested by 'FLAGS' for IOOBEX)
        //  2) return null (if Requested by 'FLAGS' for IOOBEX)
        //  3) throw IndexOutOfBoundsException
        //
        // NOTE: It is probably a "little less efficient" to turn this into a method call,
        //       since there are all these parameters that have to be passed, but this is
        //       trading "readability" (less head-aches) in exchange for efficiency.
        //
        // This point applies to all of the "Exception Flag Handlers" used here

        if (index >= ja.size()) return IOOBEX(ja, index, defaultValue, FLAGS);

        JsonValue jv = ja.get(index);

        switch (jv.getValueType())
        {
            // When a 'NULL' (Json-Null) JsonValue is present, the JsonNullArrException 'handler'
            // will do one of the following:
            //
            //  1) return the defaultValue (if Requested by 'FLAGS' for JNAEX)
            //  2) return null (if Requested by 'FLAGS' for JNAEX)
            //  3) throw JsonNullArrException

            case NULL: return JNAEX(ja, index, defaultValue, FLAGS, NUMBER, returnClass);

            case NUMBER:

                // Temp Variable, Used Twice (Just a Cast)
                JsonNumber n = (JsonNumber) jv;

                try
                    { return jsonTypeToJavaType.apply(n); }

                // Because
                //
                // 1) A method for this code would only be invoked here, and...
                // 2) And because there would be 9 parameters to pass, 
                // 3) the 'inline' version of "Flag Handler" is left here!
                //
                // NOTE: All four "JsonArithmetic Arr/Obj Exception" exception throws
                //       are different for each of the 4 methods where they are used.

                catch (ArithmeticException ae)
                {
                    if ((FLAGS & RETURN_NULL_ON_AEX) != 0)          return null;
                    if ((FLAGS & RETURN_DEFVAL_ON_AEX) != 0)        return defaultValue;
                    if ((FLAGS & RETURN_JAPPROX_ON_AEX) != 0)       return typeToType2.apply(n);
                    if ((FLAGS & RETURN_NULL_ON_ANY_ALL) != 0)      return null;
                    if ((FLAGS & RETURN_DEFVAL_ON_ANY_ALL) != 0)    return defaultValue;
            
                    throw new JsonArithmeticArrException
                        (ae, ja, index, NUMBER, jv, returnClass);
                }

            // The JsonValue at the specified array-index does not contain an JsonNumber.
            // The "JsonTypeArrException Handler" will do one of these:
            //
            //  1) return the defaultValue (if Requested by 'FLAGS' for JTAEX)
            //  2) return null (if Requested by 'FLAGS' for JTAEX)
            //  3) throw JsonTypeArrException

            default: return JTAEX(ja, index, defaultValue, FLAGS, NUMBER, jv, returnClass);
        }
    }

    /**
     * This is an internal helper method for retrieving a property from a {@link JsonObject},
     * and converting it to a <B STYLE='color: red;'>Java Type</B>.
     * <EMBED CLASS=defs DATA-TYPE=number DATA-JTYPE=JsonNumber>
     * 
     * @param jo Any instance of {@link JsonObject}
     * @param propertyName The name of the property in {@code 'jo'} to retrieve.
     * @param FLAGS The return-value / exception-throw flag constants defined in {@link JFlag}
     * @param defaultValue This is the 'Default Value' returned by this method, if there are any
     * problems converting or extracting the specified number, and the appropriate flags are set
     * 
     * @return On success, this method returns the converted number
     * 
     * @throws JsonPropMissingException <EMBED CLASS='external-html' DATA-FILE-ID=JRF_JPMEX>
     * @throws JsonArithmeticObjException <EMBED CLASS='external-html' DATA-FILE-ID=JRF_JAEX>
     * @throws JsonNullObjException <EMBED CLASS='external-html' DATA-FILE-ID=JRF_JNOEX>
     * @throws JsonTypeObjException <EMBED CLASS='external-html' DATA-FILE-ID=JRF_JTOEX>
     * 
     * @see ReadJSON#getINTEGER(JsonObject, String, int, int)
     * @see ReadJSON#getLONG(JsonObject, String, int, long)
     * @see ReadJSON#getSHORT(JsonObject, String, int, short)
     * @see ReadJSON#getBYTE(JsonObject, String, int, byte)
     * @see ReadJSON#getDOUBLE(JsonObject, String, int, double)
     * @see ReadJSON#getFLOAT(JsonObject, String, int, float)
     * @see ReadJSON#getNUMBER(JsonObject, String, int, Number)
     */
    protected static <T extends java.lang.Number> T GET(
            JsonObject jo, String propertyName,
            int FLAGS, T defaultValue,
            Class<T> returnClass,
            Function<JsonNumber, T> jsonTypeToJavaType,
            Function<JsonNumber, T> typeToType2
        )
    {
        JsonValue jv = jo.get(propertyName);

        // When TRUE, the user-specified 'property' (named by 'propertyName') isn't actually one
        // of the listed properties inside the JsonObject.  The JsonPropMissingException "handler"
        // (the method called here) will check the FLAGS, and:
        //
        //  1) return the defaultValue (if Requested by 'FLAGS' for JPMEX)
        //  2) return null (if Requested by 'FLAGS' for JPMEX)
        //  3) throw JsonPropMissingException
        //
        // NOTE: It is probably a "little less efficient" to turn this into a method call,
        //       since there are all these parameters that have to be passed, but this is
        //       trading "readability" (less head-aches) in exchange for efficiency.
        //
        // This point applies to all of the "Exception Flag Handlers" used here

        if (jv == null) return JPMEX(jo, propertyName, defaultValue, FLAGS, NUMBER, returnClass);

        switch (jv.getValueType())
        {
            // When a 'NULL' (Json-Null) JsonValue is present, the JsonNullObjException 'handler'
            // will do one of the following:
            //
            //  1) return the defaultValue (if Requested by 'FLAGS' for JNOEX)
            //  2) return null (if Requested by 'FLAGS' for JNOEX)
            //  3) throw JsonNullArrException

            case NULL: return JNOEX(jo, propertyName, defaultValue, FLAGS, NUMBER, returnClass);

            case NUMBER:

                // Temp Variable, Used Twice (Just a Cast)
                JsonNumber n = (JsonNumber) jv;

                try
                    { return jsonTypeToJavaType.apply(n); }

                // Because
                //
                // 1) A method for this code would only be invoked here, and...
                // 2) And because there would be 9 parameters to pass, 
                // 3) the 'inline' version of "Flag Handler" is left here!
                //
                // NOTE: All four "JsonArithmetic Arr/Obj Exception" exception throws
                //       are different for each of the 4 methods where they are used.

                catch (ArithmeticException ae)
                {
                    if ((FLAGS & RETURN_NULL_ON_AEX) != 0)          return null;
                    if ((FLAGS & RETURN_DEFVAL_ON_AEX) != 0)        return defaultValue;
                    if ((FLAGS & RETURN_JAPPROX_ON_AEX) != 0)       return typeToType2.apply(n);
                    if ((FLAGS & RETURN_NULL_ON_ANY_ALL) != 0)      return null;
                    if ((FLAGS & RETURN_DEFVAL_ON_ANY_ALL) != 0)    return defaultValue;

                    throw new JsonArithmeticObjException
                        (ae, jo, propertyName, NUMBER, jv, returnClass);
                }

            // The JsonValue of 'propertyName' does not contain an JsonNumber.
            // The "JsonTypeObjException Handler" will do one of these:
            //
            //  1) return the defaultValue (if Requested by 'FLAGS' for JTOEX)
            //  2) return null (if Requested by 'FLAGS' for JTOEX)
            //  3) throw JsonTypeObjException

            default: return JTOEX(jo, propertyName, defaultValue, FLAGS, NUMBER, jv, returnClass);
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // HELPER PARSE - JsonString Inputs (also uses flags)
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Retrieve a {@link JsonArray} element containing a {@link JsonString}, and transform it to
     * a <B STYLE='color: red'>Java Type</B>, with either a user-provided parser, or the standard
     * java parser for that class (passed as a parameter).
     * 
     * @param <T> The type of the returned value
     * @param ja Any instance of {@link JsonArray}
     * @param index array-index containing the {@link JsonString} to retrieve.
     * @param FLAGS The return-value / exception-throw flag constants defined in {@link JFlag}
     * @param defaultValue User-provided default-value, only returned if flags are set.
     * @param parser A valid {@code String -> 'T'} parser.  This parameter may be null.
     * @param defaultParser1 Default {@code String -> 'T'} parser.
     * @param defaultParser2 {@code String -> 'T'} parser, that will round on Arithmetic Exceptions
     * 
     * @return On success, this method returns the converted type.
     * 
     * @throws JsonPropMissingException {@code 'jo'} doesn't have {@code 'propertyName'}, unless
     * flags are set.
     * @throws JsonArithmeticArrException after parse, conversion fails, and flags aren't set
     * @throws JsonStrParseArrException parser-failure unless flags are set
     * @throws JsonNullArrException property contains null, unless flags are set
     * @throws JsonTypeArrException property doesn't contain {@code JsonString}, unless flags are
     * set.
     * 
     * @see ReadJSON#parseINTEGER(JsonArray, int, int, int, Function)
     * @see ReadJSON#parseLONG(JsonArray, int, int, long, Function)
     * @see ReadJSON#parseSHORT(JsonArray, int, int, short, Function)
     * @see ReadJSON#parseBYTE(JsonArray, int, int, byte, Function)
     * @see ReadJSON#parseDOUBLE(JsonArray, int, int, double, Function)
     * @see ReadJSON#parseFLOAT(JsonArray, int, int, float, Function)
     * @see ReadJSON#parseNUMBER(JsonArray, int, int, Number, Function)
     */
    protected static <T extends Number> T PARSE(
            JsonArray ja, int index, int FLAGS, T defaultValue, Class<T> returnClass,
            Function<String, T> parser,
            Function<BigDecimal, T> defaultParser1,
            Function<BigDecimal, T> defaultParser2
        )
    {
        // When TRUE, the index provided turned out to be outside of the bounds of the array.  The
        // IndexOutOfBounds "handler" (the method called here) will check the FLAGS, and:
        //
        //  1) return the defaultValue (if Requested by 'FLAGS' for IOOBEX)
        //  2) return null (if Requested by 'FLAGS' for IOOBEX)
        //  3) throw IndexOutOfBoundsException
        //
        // NOTE: It is probably a "little less efficient" to turn this into a method call,
        //       since there are all these parameters that have to be passed, but this is
        //       trading "readability" (less head-aches) in exchange for efficiency.
        //
        // This point applies to all of the "Exception Flag Handlers" used here

        if (index >= ja.size()) return IOOBEX(ja, index, defaultValue, FLAGS);

        JsonValue jv = ja.get(index);

        switch (jv.getValueType())
        {
            // When a 'NULL' (Json-Null) JsonValue is present, the JsonNullArrException 'handler'
            // will do one of the following:
            //
            //  1) return the defaultValue (if Requested by 'FLAGS' for JNAEX)
            //  2) return null (if Requested by 'FLAGS' for JNAEX)
            //  3) throw JsonNullArrException

            case NULL: return JNAEX(ja, index, defaultValue, FLAGS, STRING, returnClass);

            case STRING:

                String s = ((JsonString) jv).getString();

                // NOTE: This isn't actually an "Exception Case", and if the user hasn't made
                //       a request, the empty-string is passed to whatever parser is configured

                if (s.length() == 0)
                {
                    if ((FLAGS & RETURN_NULL_ON_0LEN_STR) != 0)     return null;
                    if ((FLAGS & RETURN_DEFVAL_ON_0LEN_STR) != 0)   return defaultValue;
                    if ((FLAGS & RETURN_NULL_ON_ANY_ALL) != 0)      return null;
                    if ((FLAGS & RETURN_DEFVAL_ON_ANY_ALL) != 0)    return defaultValue;
                }

                // Temp Variable, used in order not to invoke the BigDecimal contructor twice
                BigDecimal bd = null;

                try
                {
                    return (parser != null)
                        ? parser.apply(s)
                        : defaultParser1.apply(bd = new BigDecimal(s.trim()));

                        // NOTE: 'bd' will not be null if "ArithmeticException" is thrown...
                        // new BigDecimal throws "NumberFormatException" is thrown
                        // parser.applly can throw ArithmeticException
                }

                // Because
                //
                // 1) A method for this code would only be invoked here, and...
                // 2) And because there would be 9 parameters to pass, 
                // 3) the 'inline' version of "Flag Handler" is left here!
                //
                // NOTE: All four "JsonArithmetic Arr/Obj Exception" exception throws
                //       are different for each of the 4 methods where they are used.

                catch (ArithmeticException ae)
                {
                    if ((FLAGS & RETURN_NULL_ON_AEX) != 0)          return null;
                    if ((FLAGS & RETURN_DEFVAL_ON_AEX) != 0)        return defaultValue;
                    if ((FLAGS & RETURN_JAPPROX_ON_AEX) != 0)       return defaultParser2.apply(bd);
                    if ((FLAGS & RETURN_NULL_ON_ANY_ALL) != 0)      return null;
                    if ((FLAGS & RETURN_DEFVAL_ON_ANY_ALL) != 0)    return defaultValue;

                    throw new JsonArithmeticArrException(ae, ja, index, STRING, jv, returnClass);
                }

                // HANDLER STRIKES AGAIN! - but this time for "JsonStrParseArrException"
                // RETURNS: null, or defaultValue, (otherwise throws JsonStrParseArrException)

                catch (Exception e)
                    { return JSPAEX(e, ja, index, defaultValue, FLAGS, jv, returnClass); }

            // The JsonValue at the specified array-index does not contain an JsonString.
            // The "JsonTypeArrException Handler" will do one of these:
            //
            //  1) return the defaultValue (if Requested by 'FLAGS' for JTAEX)
            //  2) return null (if Requested by 'FLAGS' for JTAEX)
            //  3) throw JsonTypeArrException

            default: return JTAEX(ja, index, defaultValue, FLAGS, STRING, jv, returnClass);
        }
    }

    /**
     * Retrieve a {@link JsonObject} property containing a {@link JsonString}, and transform it to
     * a <B STYLE='color: red'>Java Type</B>, with either a user-provided parser, or the standard
     * java parser for that class (passed as a parameter).
     * 
     * @param <T> The type of the returned value.
     * @param jo Any instance of {@link JsonObject}
     * @param propertyName propertyName containing the {@link JsonString} to retrieve.
     * @param FLAGS The return-value / exception-throw flag constants defined in {@link JFlag}
     * @param defaultValue User-provided default-value, only returned if flags are set.
     * @param parser A valid {@code String -> 'T'} parser.  This parameter may be null.
     * @param defaultParser1 Default {@code String -> 'T'} parser.
     * @param defaultParser2 {@code String -> 'T'} parser, that will round on Arithmetic Exceptions
     * 
     * @return On success, this method returns the converted type instance.
     * 
     * @throws JsonPropMissingException {@code 'jo'} doesn't have {@code 'propertyName'}, unless
     * flags are set.
     * @throws JsonArithmeticObjException after parse, conversion fails, and flags aren't set
     * @throws JsonStrParseObjException parser-failure unless flags are set
     * @throws JsonNullObjException property contains null, unless flags are set
     * @throws JsonTypeObjException property doesn't contain {@code JsonString}, unless flags are
     * set.
     * 
     * @see ReadJSON#parseINTEGER(JsonObject, String, int, int, Function)
     * @see ReadJSON#parseLONG(JsonObject, String, int, long, Function)
     * @see ReadJSON#parseSHORT(JsonObject, String, int, short, Function)
     * @see ReadJSON#parseBYTE(JsonObject, String, int, byte, Function)
     * @see ReadJSON#parseDOUBLE(JsonObject, String, int, double, Function)
     * @see ReadJSON#parseFLOAT(JsonObject, String, int, float, Function)
     * @see ReadJSON#parseNUMBER(JsonObject, String, int, Number, Function)
     */
    protected static <T extends Number> T PARSE(
            JsonObject jo, String propertyName, int FLAGS, T defaultValue, Class<T> returnClass,
            Function<String, T> parser,
            Function<BigDecimal, T> defaultParser1,
            Function<BigDecimal, T> defaultParser2
        )
    {
        JsonValue jv = jo.get(propertyName);

        // When TRUE, the user-specified 'property' (named by 'propertyName') isn't actually one
        // of the listed properties inside the JsonObject.  The JsonPropMissingException "handler"
        // (the method called here) will check the FLAGS, and:
        //
        //  1) return the defaultValue (if Requested by 'FLAGS' for JPMEX)
        //  2) return null (if Requested by 'FLAGS' for JPMEX)
        //  3) throw JsonPropMissingException
        //
        // NOTE: It is probably a "little less efficient" to turn this into a method call,
        //       since there are all these parameters that have to be passed, but this is
        //       trading "readability" (less head-aches) in exchange for efficiency.
        //
        // This point applies to all of the "Exception Flag Handlers" used here

        if (jv == null) return JPMEX(jo, propertyName, defaultValue, FLAGS, STRING, returnClass);

        switch (jv.getValueType())
        {
            // When a 'NULL' (Json-Null) JsonValue is present, the JsonNullObjException 'handler'
            // will do one of the following:
            //
            //  1) return the defaultValue (if Requested by 'FLAGS' for JNOEX)
            //  2) return null (if Requested by 'FLAGS' for JNOEX)
            //  3) throw JsonNullArrException

            case NULL: return JNOEX(jo, propertyName, defaultValue, FLAGS, STRING, returnClass);

            case STRING:

                String s = ((JsonString) jv).getString();

                // NOTE: This isn't actually an "Exception Case", and if the user hasn't made
                //       a request, the empty-string is passed to whatever parser is configured

                if (s.length() == 0)
                {
                    if ((FLAGS & RETURN_NULL_ON_0LEN_STR) != 0)     return null;
                    if ((FLAGS & RETURN_DEFVAL_ON_0LEN_STR) != 0)   return defaultValue;
                    if ((FLAGS & RETURN_NULL_ON_ANY_ALL) != 0)      return null;
                    if ((FLAGS & RETURN_DEFVAL_ON_ANY_ALL) != 0)    return defaultValue;
                }

                // Temp Variable, used in order not to invoke the BigDecimal contructor twice
                BigDecimal bd = null;

                try
                {
                    return (parser != null)
                        ? parser.apply(s)
                        : defaultParser1.apply(bd = new BigDecimal(s.trim()));

                        // NOTE: 'bd' will not be null if "ArithmeticException" is thrown...
                        // new BigDecimal throws "NumberFormatException" is thrown
                        // parser.applly can throw ArithmeticException
                }

                // Because
                //
                // 1) A method for this code would only be invoked here, and...
                // 2) And because there would be 9 parameters to pass, 
                // 3) the 'inline' version of "Flag Handler" is left here!
                //
                // NOTE: All four "JsonArithmetic Arr/Obj Exception" exception throws
                //       are different for each of the 4 methods where they are used.

                catch (ArithmeticException ae)
                {
                    if ((FLAGS & RETURN_NULL_ON_AEX) != 0)          return null;
                    if ((FLAGS & RETURN_DEFVAL_ON_AEX) != 0)        return defaultValue;
                    if ((FLAGS & RETURN_JAPPROX_ON_AEX) != 0)      return defaultParser2.apply(bd);
                    if ((FLAGS & RETURN_NULL_ON_ANY_ALL) != 0)      return null;
                    if ((FLAGS & RETURN_DEFVAL_ON_ANY_ALL) != 0)    return defaultValue;

                    throw new JsonArithmeticObjException
                        (ae, jo, propertyName, STRING, jv, returnClass);
                }

                // HANDLER STRIKES AGAIN! - but this time for "JsonStrParseObjException"
                // RETURNS: null, or defaultValue, (otherwise throws JsonStrParseObjException)

                catch (Exception e)
                    { return JSPOEX(e, jo, propertyName, defaultValue, FLAGS, jv, returnClass); }

            // The JsonValue of 'propertyName' does not contain an JsonString.
            // The "JsonTypeObjException Handler" will do one of these:
            //
            //  1) return the defaultValue (if Requested by 'FLAGS' for JTOEX)
            //  2) return null (if Requested by 'FLAGS' for JTOEX)
            //  3) throw JsonTypeObjException

            default: return JTOEX(jo, propertyName, defaultValue, FLAGS, STRING, jv, returnClass);
        }
    }
}