package Torello.Java.JSON;

import Torello.Java.StringParse;
import Torello.Java.UnreachableError;

import Torello.Java.Additional.Ret3;
import Torello.Java.Additional.EffectivelyFinal;
import Torello.Java.Additional.Counter;

import Torello.Java.Function.ToByteFunction;
import Torello.Java.Function.ToFloatFunction;
import Torello.Java.Function.ToShortFunction;

import java.util.*;
import java.util.stream.*;
import java.util.function.*;
import java.math.*;
import javax.json.*;

import java.lang.reflect.Array;

// This is "The Great Sillyness" - it is only used because of the Java-Quirk about constructor's
// not referencing "this" before a call to "super(...)" or "this(...)".  The only way around it I
// have ever found is to use a static-temporary variable, and set its value inside of a static
// helper-method.
//
// This is, essentially, just fine.  However, if the user ever ran this in a multi-threaded program
// it might "get messed up".  TO PREVENT THAT: You have to have a few lines that are synchronized.
// Using the "ReentrantLock" is easier for me to think about than using "synchronized"
//
// NOTE: There is NO MULTI-THREADED CALLS IN THIS CLASS WHATSOEVER.  This is only used as a 
//       "Constructor-Helper"
//
// THIS CLASS IS **VERY** THREAD-SAFE

import java.util.concurrent.locks.ReentrantLock;

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

/**
 * Utilities for parsing Json Array's into Java Array's.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=GLASS_FISH_NOTE>
 * <EMBED CLASS='external-html' DATA-FILE-ID=READ_ARR_JSON>
 *
 * @see Json
 * @see Json
 * @see JsonArray
 */
@Torello.JavaDoc.StaticFunctional
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JSON_JDHBI")
public class ReadArrJSON
{
    private ReadArrJSON() { }

    // ********************************************************************************************
    // ********************************************************************************************
    // TEST-PREDICATE'S
    // ********************************************************************************************
    // ********************************************************************************************


    private static final BigInteger LONG_MAX    = BigInteger.valueOf(Long.MAX_VALUE);
    private static final BigInteger LONG_MIN    = BigInteger.valueOf(Long.MIN_VALUE);
    private static final BigInteger SHORT_MAX   = BigInteger.valueOf(Short.MAX_VALUE);
    private static final BigInteger SHORT_MIN   = BigInteger.valueOf(Short.MIN_VALUE);
    private static final BigInteger BYTE_MAX    = BigInteger.valueOf(Byte.MAX_VALUE);
    private static final BigInteger BYTE_MIN    = BigInteger.valueOf(Byte.MIN_VALUE);

    /** 
     * These are eliminated / removed from any call to a method which returns either an array
     * of Java Primitives or a Java Primitive Stream
     * 
     * @see #intArrayToStream(JsonArray, int, int, ToIntFunction)
     * @see #longArrayToStream(JsonArray, long, int, ToLongFunction)
     * @see #doubleArrayToStream(JsonArray, double, int, ToDoubleFunction)
     * @see #byteArray(JsonArray, byte, int, ToByteFunction)
     * @see #floatArray(JsonArray, float, int, ToFloatFunction)
     * @see #shortArray(JsonArray, short, int, ToShortFunction)
     * @see #booleanArray(JsonArray, boolean, int, Predicate)
     */
    public static final int NOT_ALLOWED_RET_NULL_MASKS = ~(RETURN_NULL_ON_ANY_ALL |
        RETURN_NULL_ON_AEX | RETURN_NULL_ON_NULL | RETURN_NULL_ON_SPEX | RETURN_NULL_ON_STR |
        RETURN_NULL_ON_0LEN_STR | RETURN_NULL_ON_WRONG_JSONTYPE | INSERT_NULL_ON_NON_SUBARRAY_TYPE);


    // For "Integer", the javax.json will always return an instance of "Integer" if the JsonNumber
    // is, indeed, a valid Integer.  This doesn't work for Long - even though java.json will return
    // an instance of boxed-type "Long" when the number is a Long because if the user has requested
    // a LongStream, and an Integer was parsed (because the number was between 0 and MAX_INT), then
    // just checking the Class of the returned value will fail.
    //
    // Converting to a returned "Integer" or "Long" to a "BigInteger" is extremely cheap, and fast,
    // since the class BigInteger will just save the "Integer" internally.


    private static boolean shortTypePred(JsonNumber jn)
    {
        if (! jn.isIntegral()) return false;

        BigInteger bi = jn.bigIntegerValue();
        int signum = bi.signum();

        return  ((signum > 0) && (bi.compareTo(SHORT_MAX) <= 0))
            ||  ((signum < 0) && (bi.compareTo(SHORT_MIN) >= 0))
            ||  (signum == 0);
    }

    private static boolean byteTypePred(JsonNumber jn)
    {
        if (! jn.isIntegral()) return false;

        BigInteger bi = jn.bigIntegerValue();
        int signum = bi.signum();

        return  ((signum > 0) && (bi.compareTo(BYTE_MAX) <= 0))
            ||  ((signum < 0) && (bi.compareTo(BYTE_MIN) >= 0))
            ||  (signum == 0);
    }

    private static boolean doubleTypePred(JsonNumber jn)
    { return true; /* for now!  Only bizzare & egregious cases won't fit into a double... */ }

    private static boolean floatTypePred(JsonNumber jn)
    { return true; }

    private static boolean longTypePred(JsonNumber jn)
    {
        if (! jn.isIntegral()) return false;

        BigInteger bi = jn.bigIntegerValue();
        int signum = bi.signum();

        return  ((signum > 0) && (bi.compareTo(LONG_MAX) <= 0))
            ||  ((signum < 0) && (bi.compareTo(LONG_MIN) >= 0))
            ||  (signum == 0);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // HELPER-RECORD
    // ********************************************************************************************
    // ********************************************************************************************


    // NOTE: It is **A LOT** Smarter to check for the exception instead of using the try-catch
    //       since I have read that generating an exception is one of the most costly-expensive
    //       things the JRE does.  It isn't the Exception-Constructor that costs a lot - it is the
    //       creating of the **STACK-TRACE** that costs well over 100 to 1,000 times the number of
    //       of CPU-Cycles that the cost of a simple constructor.  This is an "Only if abolutely"
    //       necessary things.

    private static <T extends Number> ArithmeticException getAEX
        (JsonNumber jn, Function<BigDecimal, ?> converter)
    {
        try
            { converter.apply(jn.bigDecimalValue()); }
        catch (ArithmeticException aex)
            { return aex; }

        throw new UnreachableError();
    }

    private static Exception getSPEX(String s, Function<String, ?> converter)
    {
        try
            { converter.apply(s); }
        catch (Exception e)
            { return e; }

        throw new UnreachableError();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // RECORD Configuration-Class
    // ********************************************************************************************
    // ********************************************************************************************


    private static class RECORD<T, U>
    {
        // Assigned after construction, cannot be final
        private JsonArray ja;

        private final T defaultValue;

        private final boolean RJA_AEX, RTS_WT, IN_NSAT, S_NSAT;

        private final Runnable handlerNull, handlerAEX, handlerSPEX, handlerZLS, handlerWrongType;
        private final ObjIntConsumer<JsonValue> handlerJsonString;

        private final Class<T>                  CLASS;
        private final Predicate<JsonNumber>     jsonNumWillFit;
        private final Predicate<String>         validStrTester;
        private final Function<String, T>       defaultParser;
        private final Function<Number, T>       numberConverter;
        private final Function<BigDecimal, T>   numberConverterExThrow;
        private final Function<String, T>       userParser;

        // NOTE: This class "RECORD" can handle the standard "Stream<T>", but it can also handle
        //       the three primitive-Stream's: IntStream, LongStream and DoubleStream.
        //
        // Therefore these are kept as separate function-pointers.  If it weren't for those three
        // primitive-streams, this would be completely unnecessary.   YES, this class is a little
        // hard to read.

        private final Runnable      c;  // Stream.builder()
        private final Consumer<T>   a;  // Stream.Builder.accept(T)
        private final Supplier<U>   b;  // Stream.Builder.build()


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // This is only used by the methods in the nested-class "DimN"
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // This is not final, because it is set after the constructor. 
        //
        // Since the user is incapable of accessing any of this, and since great care has been 
        // taken to rigorously test all of this stuff, it is basically unimportant.

        private Function<JsonArray, Object> array1DGenerator = null;


        // ****************************************************************************************
        // ****************************************************************************************
        // PRIMARY RECORD Constructor
        // ****************************************************************************************
        // ****************************************************************************************


        private RECORD(
                T                       defaultValue,
                int                     FLAGS,

                Class<T>                CLASS,
                Predicate<JsonNumber>   jsonNumWillFit,
                Predicate<String>       validStrTester,
                Function<String, T>     defaultParser,
                Function<Number, T>     numberConverter,
                Function<BigDecimal, T> numberConverterExThrow,
                Function<String, T>     userParser,
                boolean                 NULLS,

                Runnable                streamConstructor,
                Consumer<T>             streamAcceptor,
                Supplier<U>             streamBuilder
            )
        {
            this.defaultValue           = defaultValue;     // User-Provided Default-Value
            this.CLASS                  = CLASS;            // Class of the Stream.Builder "accept" Parameter
            this.jsonNumWillFit         = jsonNumWillFit;   // Checks if JsonNumber will fit properly
            this.validStrTester         = validStrTester;   // Used for Verifying a JsonString
            this.defaultParser          = defaultParser;    // Default JsonString Parser to Number
            this.numberConverter        = numberConverter;  // interface java.lang.Number method
            this.numberConverterExThrow = numberConverterExThrow;
            this.userParser             = userParser;       // Optional User Parser

            this.c = streamConstructor;    // Stream.builder()
            this.a = streamAcceptor;       // Stream.Builder.accept()
            this.b = streamBuilder;        // Stream.Builder.build()

            this.RJA_AEX    = (FLAGS & RETURN_JAPPROX_ON_AEX) > 0;
            this.RTS_WT     = (FLAGS & RETURN_TOSTRING_ON_WRONGTYPE) > 0;
            this.IN_NSAT    = (FLAGS & INSERT_NULL_ON_NON_SUBARRAY_TYPE) > 0;
            this.S_NSAT     = (FLAGS & SKIP_ON_NON_SUBARRAY_TYPE) > 0;

            boolean RN_AA   = NULLS && ((FLAGS & RETURN_NULL_ON_ANY_ALL) > 0);
            boolean RD_AA   = (FLAGS & RETURN_DEFVAL_ON_ANY_ALL) > 0;
            boolean S_AA    = (FLAGS & SKIP_ON_ANY_ALL) > 0;

            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Null Handler (JsonNull was in the JsonArray)
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            //
            // NOTE: AN(), AD() and NOOP() are just one-line private methods that:
            //       a.accept(null), a.accept(defaultValue), and {} ==> do nothing (SKIP)

            if (NULLS && ((FLAGS & RETURN_NULL_ON_NULL) > 0))   handlerNull = this::AN;
            else if ((FLAGS & RETURN_DEFVAL_ON_NULL) > 0)       handlerNull = this::AD;
            else if ((FLAGS & SKIP_ON_NULL) > 0)                handlerNull = this::NOOP;
            else if (NULLS && RN_AA)                            handlerNull = this::AN;
            else if (RD_AA)                                     handlerNull = this::AD;
            else if (S_AA)                                      handlerNull = this::NOOP;
            else if (NULLS)                                     handlerNull = this::AN;
            else                                                handlerNull = null;


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // AEX Handler (ArithmeticException)
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            //
            // NOTE: AN(), AD() and NOOP() are just one-line private methods that:
            //       a.accept(null), a.accept(defaultValue), and {} ==> do nothing (SKIP)

            if (NULLS && ((FLAGS & RETURN_NULL_ON_AEX) > 0))    handlerAEX = this::AN;
            else if ((FLAGS & RETURN_DEFVAL_ON_AEX) > 0)        handlerAEX = this::AD;
            else if ((FLAGS & SKIP_ON_AEX) > 0)                 handlerAEX = this::NOOP;
            else if (NULLS && RN_AA)                            handlerAEX = this::AN;
            else if (RD_AA)                                     handlerAEX = this::AD;
            else if (S_AA)                                      handlerAEX = this::NOOP;
            else                                                handlerAEX = null;


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // SPEX Handler (Exception while parsing a String into the Java-Type)
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            //
            // NOTE: AN(), AD() and NOOP() are just one-line private methods that:
            //       a.accept(null), a.accept(defaultValue), and {} ==> do nothing (SKIP)

            if (NULLS && ((FLAGS & RETURN_NULL_ON_SPEX) > 0))   handlerSPEX = this::AN;
            else if ((FLAGS & RETURN_DEFVAL_ON_SPEX) > 0)       handlerSPEX = this::AD;
            else if ((FLAGS & SKIP_ON_SPEX) > 0)                handlerSPEX = this::NOOP;
            else if (NULLS && RN_AA)                            handlerSPEX = this::AN;
            else if (RD_AA)                                     handlerSPEX = this::AD;
            else if (S_AA)                                      handlerSPEX = this::NOOP;
            else                                                handlerSPEX = null;


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // ZLS Handler (A Zero-Length String was in the JsonArray)
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            //
            // NOTE: AN(), AD() and NOOP() are just one-line private methods that:
            //       a.accept(null), a.accept(defaultValue), and {} ==> do nothing (SKIP)

            if (NULLS && ((FLAGS & RETURN_NULL_ON_0LEN_STR) > 0))   handlerZLS = this::AN;
            else if ((FLAGS & RETURN_DEFVAL_ON_0LEN_STR) > 0)       handlerZLS = this::AD;
            else if ((FLAGS & SKIP_ON_0LEN_STR) > 0)                handlerZLS = this::NOOP;
            else if (NULLS && RN_AA)                                handlerZLS = this::AN;
            else if (RD_AA)                                         handlerZLS = this::AD;
            else if (S_AA)                                          handlerZLS = this::NOOP;
            else                                                    handlerZLS = null;


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Wrong-Type Handler (A JsonObject or a nested-JsonArray was in an array position)
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            //
            // NOTE: AN(), AD() and NOOP() are just one-line private methods that:
            //       a.accept(null), a.accept(defaultValue), and {} ==> do nothing (SKIP)
            //
            // ALSO: RN_WT & RD_WT are the abbreviated-flags for "ON_WRONG_JSONTYPE"

            if (NULLS && ((FLAGS & RN_WT) > 0))             handlerWrongType = this::AN;
            else if ((FLAGS & RD_WT) > 0)                   handlerWrongType = this::AD;
            else if ((FLAGS & SKIP_ON_WRONG_JSONTYPE) > 0)  handlerWrongType = this::NOOP;
            else if (NULLS && RN_AA)                        handlerWrongType = this::AN;
            else if (RD_AA)                                 handlerWrongType = this::AD;
            else if (S_AA)                                  handlerWrongType = this::NOOP;
            else                                            handlerWrongType = null;


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // JsonString Handler (This was *ALSO* moved here to get rid of more of the if's)
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            //
            // NOTE: AN(JsonValue, int), AD(JsonValue, int) and NOOP(JsonValue, int) are just
            //       one-line private methods that:
            //       a.accept(null), a.accept(defaultValue), and {} ==> do nothing (SKIP)

            if (userParser != null)         handlerJsonString = this::useUserParser;
            else if ((FLAGS & RP_S) > 0)    handlerJsonString = this::parseString;
            else if (NULLS && ((FLAGS & RETURN_NULL_ON_STR) > 0))   handlerJsonString = this::AN;
            else if ((FLAGS & RETURN_DEFVAL_ON_STR) > 0)            handlerJsonString = this::AD;
            else if ((FLAGS & SKIP_ON_STR) > 0)                     handlerJsonString = this::NOOP;
            else if (NULLS && RN_AA)                                handlerJsonString = this::AN;
            else if (RD_AA)                                         handlerJsonString = this::AD;
            else if (S_AA)                                          handlerJsonString = this::NOOP;
            else handlerJsonString = (JsonValue jv, int i) ->
                { throw new JsonTypeArrException (this.ja, i, NUMBER, jv, this.CLASS); };
        }


        // ****************************************************************************************
        // ****************************************************************************************
        // Boxed-Primitive Stream RECORD Contructor
        // ****************************************************************************************
        // ****************************************************************************************


        @SuppressWarnings({"unchecked"})
        private RECORD(
                T                       defaultValue,
                int                     FLAGS,

                Class<T>                CLASS,
                Predicate<JsonNumber>   jsonNumWillFit,
                Predicate<String>       validStrTester,
                Function<String, T>     defaultParser,
                Function<Number, T>     numberConverter,
                Function<BigDecimal, T> numberConverterExThrow,
                Function<String, T>     userParser
            )
        {
            this(
                defaultValue, FLAGS,

                CLASS, jsonNumWillFit, validStrTester, defaultParser, numberConverter,
                numberConverterExThrow, userParser, true,

                constructorHelper(new EffectivelyFinal<>(null)),//, CLASS, Stream.class),
                (Consumer<T>)   constructorHelper.b,    // Un-Checked Cast
                (Supplier<U>)   constructorHelper.c     // Un-Checked Cast
            );

            // Essentially, the lock is only used for about three instructions that are inside the
            // method "constructorHelper".  It, sort-of, "borrows" a private static-field for just
            // a moment, so that the values can be passed to the call to "this(...)", which is
            // just  "kind-of" faking out the compiler so I can do some processing before calling
            // "this(...)" as above
            //
            // Now that the loan-out is over, unlock the lock, and it can be used in another call

            lock.unlock();

            // THIS CLASS *IS* THREAD SAFE, 
            // THIS Nested-Class "RECORD" IS NOT THREAD-SAFE - EXCEPT THE USER IS NOT ALLOWED ACCESS,
            // AND MAY NOT OBTAIN AN INSTNANCE OF "RECORD", so it all works just fine, even in a
            // multi-threaded program!

            /*
            // OLD CODE - DON'T ERASE THIS, EVEN BEFORE THE LOCK, THIS WAS KIND OF UGLY

            final EffectivelyFinal<Stream.Builder<T>> EFSB = new EffectivelyFinal<>(null);

            this.c = ()     -> EFSB.f = Stream.builder();
            this.a = (T t)  -> EFSB.f.accept(t);
            this.b = ()     -> (U) EFSB.f.build();
            */
        }

        // These are the "Contructor Helpers" that are mentioned at the top of this class (in the
        // "import-statement" section).  These are just here to help by-pass the Java Requirement
        // that calls to "this(...)" and "super(...)" occur on the first line.

        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // This is NOT TO BE UNDERSTOOD BY MORTAL-MEN, SO DON'T ASK
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // The **MAIN-POINT** of all this non-sense is that at **RUNTIME** (as you should know by
        // by now) all Generic-Type Information has been erased.  An instance of class Object is
        // no different than an instance of class String, Integer or anything else.  It is just a
        // pointer to a class.
        //
        // This whole thing is just "Faking Out The Compiler"
        //
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Mostly, I am very used to having all the fields in Class "RECORD" being declared FINAL
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // It is very soothing to know that the constructor is "setting everything up", and the
        // Json-Processor stuff isn't going to do anything with the configurations (because they
        // are all declared FINAL).

        private static final ReentrantLock lock = new ReentrantLock();

        @SuppressWarnings("rawtypes")
        private static Ret3 constructorHelper;

        @SuppressWarnings({"rawtypes", "unchecked"})
        private static Runnable constructorHelper(final EffectivelyFinal<Stream.Builder> EFSB)
        {
            lock.lock();

            // If you don't understand this line, oh well...
            //
            // This was "built" or "developed" in a step-wise fasion.
            // There is a WHOLE-BUNCH of testing code, and it all worked.  All this 'type-magic' is
            // doing is tricking the java compiler, so I can have my way.
            //
            // Every time I play with the types, I go back and run a GIANT-STACK of TEST
            // PROCEDURES.  If they all work, I know this works.  This is **NOT REALLY** a good
            // software-writing  practice, **HOWEVER** Java-Generics are sometimes a real problem.
            //
            // The purpose of having TYPES in a programming language is to help catch programming
            // errors early-on at compile-time.  Java does this pretty well, but when things get
            // advanced (it is always with Function-Pointers - a.k.a. "Functional-Interfaces" and
            // Lambda-Expressions)... when things get "ADVANCED" it is sometimes a little
            // ridiculours.
            //
            // When they say that Java-Script is a "TYPE-LESS" language at that it is easier, well,
            // Java-Script has tons of Run-Time errors that can be impossible to debug/find!
            //
            // There is no real-way that I can think of to "improve" generics, because all the are
            // in the first-place is a little "Help Finding the Errors" at Compile-Time thing...

            constructorHelper = new Ret3<Runnable, Consumer, Supplier>(
                (Runnable)  (()         -> EFSB.f = Stream.builder()),
                (Consumer)  ((Object o) -> EFSB.f.accept(o)),
                (Supplier)  (()         -> /*(B)*/ EFSB.f.build())
            );

            return (Runnable) constructorHelper.a;
        }


        // ****************************************************************************************
        // ****************************************************************************************
        // HELPER'S FOR THE HANDLERS
        // ****************************************************************************************
        // ****************************************************************************************

        private void AN()   { a.accept(null); }
        private void AD()   { a.accept(defaultValue); }
        private void NOOP() { }

        private void AN(JsonValue jv, int i)    { a.accept(null); }
        private void AD(JsonValue jv, int i)    { a.accept(defaultValue); }
        private void NOOP(JsonValue jv, int i)  { }

        private void useUserParser(JsonValue jv, int i)
        {
            try
            {
                this.a.accept
                    (this.userParser.apply(((JsonString) jv).getString()));
            }

            catch (Exception e)
            {
                if (this.handlerSPEX != null) this.handlerSPEX.run();
                else throw new JsonStrParseArrException(e, this.ja, i, jv, this.CLASS);
            }
        };

        private void parseString(JsonValue jv, int i)
        {
            String s = ((JsonString) jv).getString();

            if (s.length() == 0)
            {
                if (this.handlerZLS != null) this.handlerZLS.run();

                else throw new JsonStrParseArrException(
                    new IllegalArgumentException("Zero Length String"),
                    this.ja, i, jv, this.CLASS
                );
            }

            // StringParse.isInteger(s), isLong(String) **AND** s -> true (Double)
            else if (this.validStrTester.test(s))

                // Integer.parseInt(String), Long.parseLong, Double.parseDouble
                this.a.accept(this.defaultParser.apply(s));

            else if (this.handlerSPEX != null) this.handlerSPEX.run();

            else throw new JsonStrParseArrException
                (getSPEX(s, this.defaultParser), this.ja, i, jv, this.CLASS);
        }


        // ****************************************************************************************
        // ****************************************************************************************
        // Static RECORD Factory/Builder Methods  --  Primitive-Streams
        // ****************************************************************************************
        // ****************************************************************************************


        private static RECORD<Integer, IntStream> getIntStreamRec
            (int defaultValue, int FLAGS, ToIntFunction<String> optionalUserParser)
        {
            EffectivelyFinal<IntStream.Builder> EFISB = new EffectivelyFinal<>(null);

            RECORD<Integer, IntStream> rec = new RECORD<>(
                defaultValue, 
                FLAGS,

                // The class of the (only) parameter to the Stream.Builder "accept" method
                int.class,

                // A simple way to test if there will be an "ArithmeticException"
                // Somewhat "counter-intuitive", but it works great...

                (JsonNumber jn) -> Integer.class == jn.numberValue().getClass(),

                StringParse::isInteger,     // number-string-tester
                Integer::parseInt,          // default-parser (string to int)
                Number::intValue,           // numberConverter
                BigDecimal::intValueExact,  // cause AEX (ArithmeticException)

                // Parse Number-Strings (this may be null)
                // IMPORTANT, If the user didn't pass a parser, it is imperative that this is null!

                (optionalUserParser != null)
                    ? (String s) -> optionalUserParser.applyAsInt(s)
                    : null, 

                // Primitive (nulls not allowed)
                false,

                ()          -> EFISB.f = IntStream.builder(),   // Stream.Builder constructor
                (Integer x) -> EFISB.f.accept(x),               // Builder "accept" Function-Ptr
                ()          -> EFISB.f.build()                  // Builder "build" Function-Ptr
            );

            // This is used by the methods in the Nested-Class "DimN" only.  It is a wrapper
            // for the JsonArray -> JavaArray method.  This is *NOT* used in ReadArrJSON

            rec.array1DGenerator =
                (JsonArray ja) -> jsonArrToStream(ja, rec).toArray();

            return rec;
        }

        private static RECORD<Long, LongStream> getLongStreamRec
            (long defaultValue, int FLAGS, ToLongFunction<String> optionalUserParser)
        {
            EffectivelyFinal<LongStream.Builder> EFLSB = new EffectivelyFinal<>(null);
    
            RECORD<Long, LongStream> rec = new RECORD<>(
                defaultValue,
                FLAGS,

                long.class,                 // Class of the Stream.Builder "accept" Parameter
                ReadArrJSON::longTypePred,  // Checks the JsonNumber retrieved
                StringParse::isLong,        // String-tester (for parsing number-strings)
                Long::parseLong,            // default-parser (number-string to long)
                Number::longValue,          // numberConverter
                BigDecimal::longValueExact, // Generates AEX (ArithmeticException)

                // Parse Number-Strings (this may be null)
                // IMPORTANT, If the user didn't pass a parser, it is imperative that this is null!

                (optionalUserParser != null)
                    ? (String s) -> optionalUserParser.applyAsLong(s)
                    : null,

                // Primitive (nulls not allowed)
                false,

                () ->       EFLSB.f = LongStream.builder(), // Stream.Builder constructor
                (Long x) -> EFLSB.f.accept(x),              // Builder "accept" Function-Pointer
                () ->       EFLSB.f.build()                 // Builder "build" Function-Pointer
            );

            // This is used by the methods in the Nested-Class "DimN" only.  It is a wrapper
            // for the JsonArray -> JavaArray method.  This is *NOT* used in ReadArrJSON

            rec.array1DGenerator =
                (JsonArray ja) -> jsonArrToStream(ja, rec).toArray();

            return rec;
        }

        private static RECORD<Double, DoubleStream> getDoubleStreamRec
            (double defaultValue, int FLAGS, ToDoubleFunction<String> optionalUserParser)
        {
            EffectivelyFinal<DoubleStream.Builder> EFDSB = new EffectivelyFinal<>(null);

            RECORD<Double, DoubleStream> rec = new RECORD<>(
                defaultValue,
                FLAGS,

                double.class,                   // Stream.Builder "accept" Parameter-Class
                ReadArrJSON::doubleTypePred,    // Checks the JsonNumber retrieved
                StringParse::isDouble,          // String-tester (for parsing number-strings)
                Double::parseDouble,            // default-parser (number-string to double)
                (Number n) -> n.doubleValue(),  // numberConverter

                // Generate an AEX if the "StringParse.isDouble" failed
                (BigDecimal bd) -> { throw new ArithmeticException("Invalid Input"); },

                // Parse Number-Strings (this may be null)
                // IMPORTANT, If the user didn't pass a parser, it is imperative that this is null!

                (optionalUserParser != null)
                    ? (String s) -> optionalUserParser.applyAsDouble(s)
                    : null,

                // Primitive (nulls not allowed)
                false,

                ()          -> EFDSB.f = DoubleStream.builder(),    // Stream.Builder constructor
                (Double x)  -> EFDSB.f.accept(x),                   // Builder "accept" FunctionPtr
                ()          -> EFDSB.f.build()                      // Builder "build" FunctionPtr
            );

            // This is used by the methods in the Nested-Class "DimN" only.  It is a wrapper
            // for the JsonArray -> JavaArray method.  This is *NOT* used in ReadArrJSON

            rec.array1DGenerator =
                (JsonArray ja) -> jsonArrToStream(ja, rec).toArray();

            return rec;
        }


        // ****************************************************************************************
        // ****************************************************************************************
        // Static RECORD Factory/Builder Methods  --  Boxed-Primitive-Streams
        // ****************************************************************************************
        // ****************************************************************************************


        private static RECORD<Integer, Stream<Integer>> getINTEGERStreamRec
            (int defaultValue, int FLAGS, Function<String, Integer> optionalUserParser)
        {
            RECORD<Integer, Stream<Integer>> rec = new RECORD<>(
                defaultValue,
                FLAGS,
                Integer.class,              // Class of the Stream.Builder "accept" Parameter
                (JsonNumber jn) -> jn.numberValue().getClass() == Integer.class,
                StringParse::isInteger,     // String-tester (for parsing number-strings)
                Integer::parseInt,          // default-parser (number-string to Integer)
                Number::intValue,           // numberConverter (JAPPROX_ON_AEX *AND* usual-ans)
                BigDecimal::intValueExact,  // Generates AEX on fail
                optionalUserParser
            );

            // This is used by the methods in the Nested-Class "DimN" only.  It is a wrapper
            // for the JsonArray -> JavaArray method.  This is *NOT* used in ReadArrJSON.
            // Note that this produces a Boxed-Type Array **ONLY**, if the user wants a 
            // primitive "int[]" array (rather than an "Integer[]"), "IntStream.toArray" is used

            rec.array1DGenerator = (JsonArray ja) ->
                jsonArrToBoxedStream(ja, rec).toArray(Integer[]::new);

            return rec;
        }

        private static RECORD<Short, Stream<Short>> getSHORTStreamRec(
                short defaultValue, int FLAGS, Function<String, Short> optionalUserParser,
                boolean primitiveOrBoxedOutput1DArray
            )
        {
            RECORD<Short, Stream<Short>> rec = new RECORD<>(
                defaultValue,
                FLAGS,
                Short.class,                    // Class of the Stream.Builder "accept" Parameter
                ReadArrJSON::shortTypePred,     // Checks the JsonNumber retrieved
                StringParse::isShort,           // String-tester (for parsing number-strings)
                Short::parseShort,              // default-parser (number-string to short)
                Number::shortValue,             // numberConverter (JAPPROX_ON_AEX *AND* usual-ans)
                BigDecimal::shortValueExact,    // Generates AEX on fail
                optionalUserParser
            );

            // Only used by "DimN" Sub-Class.  It builds the 1D arrays.  Since short's do not have
            // a "BoxedStream" (and ergo, do not have a ShortStream.toArray method), this must be
            // used to dispatch-build *BOTH* a short[] and a Short[]

            rec.array1DGenerator = primitiveOrBoxedOutput1DArray
                ? rec::array1DGeneratorShort
                : (JsonArray ja) -> jsonArrToBoxedStream(ja, rec).toArray(Short[]::new);

            return rec;
        }

        private static RECORD<Byte, Stream<Byte>> getBYTEStreamRec(
                byte defaultValue, int FLAGS, Function<String, Byte> optionalUserParser,
                boolean primitiveOrBoxedOutput1DArray
            )
        {
            RECORD<Byte, Stream<Byte>> rec = new RECORD<>(
                defaultValue,
                FLAGS,
                Byte.class,                 // Class of the Stream.Builder "accept" Parameter
                ReadArrJSON::byteTypePred,  // Checks the JsonNumber retrieved
                StringParse::isByte,        // String-tester (for parsing number-strings)
                Byte::parseByte,            // default-parser (number-string to byte)
                Number::byteValue,          // numberConverter (JAPPROX_ON_AEX *AND* usual-ans)
                BigDecimal::byteValueExact, // Generates AEX on fail
                optionalUserParser
            );

            // Only used by "DimN" Sub-Class.  It builds the 1D arrays.  Since short's do not have
            // a "BoxedStream" (and ergo, do not have a ShortStream.toArray method), this must be
            // used to dispatch-build *BOTH* a short[] and a Short[]

            rec.array1DGenerator = primitiveOrBoxedOutput1DArray
                ? rec::array1DGeneratorByte
                : (JsonArray ja) -> jsonArrToBoxedStream(ja, rec).toArray(Byte[]::new);

            return rec;
        }

        private static RECORD<Long, Stream<Long>> getLONGStreamRec
            (long defaultValue, int FLAGS, Function<String, Long> optionalUserParser)
        {
            RECORD<Long, Stream<Long>> rec = new RECORD<>(
                defaultValue,
                FLAGS,
                Long.class,                 // Class of the Stream.Builder "accept" Parameter
                ReadArrJSON::longTypePred,  // Checks the JsonNumber retrieved
                StringParse::isLong,        // String-tester (for parsing number-strings)
                Long::parseLong,            // default-parser (number-string to long)
                Number::longValue,          // numberConverter (JAPPROX_ON_AEX *AND* usual-ans)
                BigDecimal::longValueExact, // Generates AEX on fail
                optionalUserParser
            );

            // This is used by the methods in the Nested-Class "DimN" only.  It is a wrapper
            // for the JsonArray -> JavaArray method.  This is *NOT* used in ReadArrJSON.
            // Note that this produces a Boxed-Type Array **ONLY**, if the user wants a 
            // primitive "long[]" array (rather than an "Long[]"), "LongStream.toArray" is used

            rec.array1DGenerator = (JsonArray ja) ->
                jsonArrToBoxedStream(ja, rec).toArray(Long[]::new);

            return rec;
        }

        private static RECORD<Double, Stream<Double>> getDOUBLEStreamRec
            (double defaultValue, int FLAGS, Function<String, Double> optionalUserParser)
        {
            RECORD<Double, Stream<Double>> rec = new RECORD<>(
                defaultValue,
                FLAGS,
                Double.class,                   // Class of the Stream.Builder "accept" Parameter
                ReadArrJSON::doubleTypePred,    // Checks the JsonNumber retrieved
                StringParse::isDouble,          // String-tester (for parsing number-strings)
                Double::parseDouble,            // default-parser (number-string to double)
                Number::doubleValue,            // numberConverter (JAPPROX_ON_AEX *AND* usual-ans)
                (BigDecimal bd) -> { throw new ArithmeticException("Invalid Input"); },
                optionalUserParser
            );

            // This is used by the methods in the Nested-Class "DimN" only.  It is a wrapper
            // for the JsonArray -> JavaArray method.  This is *NOT* used in ReadArrJSON.
            // Note that this produces a Boxed-Type Array **ONLY**, if the user wants a 
            // primitive "double[]" array (rather than an "Double[]"), "DoubleStream.toArray" is
            // used

            rec.array1DGenerator = (JsonArray ja) ->
                jsonArrToBoxedStream(ja, rec).toArray(Double[]::new);

            return rec;
        }

        private static RECORD<Float, Stream<Float>> getFLOATStreamRec(
                float defaultValue, int FLAGS, Function<String, Float> optionalUserParser,
                boolean primitiveOrBoxedOutput1DArray
            )
        {
            RECORD<Float, Stream<Float>> rec = new RECORD<>(
                defaultValue,
                FLAGS,
                Float.class,                // Class of the Stream.Builder "accept" Parameter
                ReadArrJSON::floatTypePred, // Checks the JsonNumber retrieved
                StringParse::isDouble,      // String-tester (for parsing number-strings)
                Float::parseFloat,          // default-parser (number-string to float)
                Number::floatValue,         // numberConverter (JAPPROX_ON_AEX *AND* usual-ans)
                (BigDecimal bd) -> { throw new ArithmeticException("Invalid Input"); },
                optionalUserParser
            );

            // Only used by "DimN" Sub-Class.  It builds the 1D arrays.  Since short's do not have
            // a "BoxedStream" (and ergo, do not have a ShortStream.toArray method), this must be
            // used to dispatch-build *BOTH* a short[] and a Short[]

            rec.array1DGenerator = primitiveOrBoxedOutput1DArray
                ? rec::array1DGeneratorFloat
                : (JsonArray ja) -> jsonArrToBoxedStream(ja, rec).toArray(Float[]::new);

            return rec;
        }

        private static RECORD<Boolean, Stream<Boolean>> getBOOLEANStreamRec(
                boolean defaultValue, int FLAGS, Function<String, Boolean> optionalUserParser,
                boolean primitiveOrBoxedOutput1DArray
            )
        {
            RECORD<Boolean, Stream<Boolean>> rec = new RECORD<>(
                defaultValue,
                FLAGS,
                Boolean.class,          // Class of the Stream.Builder "accept" Parameter
                null,                   // Checks the JsonNumber retrieved
                s -> true,              // String-tester (for parsing number-strings)
                Boolean::parseBoolean,  // default-parser (number-string to float)
                null,                   // numberConverter (JAPPROX_ON_AEX *AND* usual-ans)
                null,
                optionalUserParser
            );

            // Only used by "DimN" Sub-Class.  It builds the 1D arrays.  Since short's do not have
            // a "BoxedStream" (and ergo, do not have a ShortStream.toArray method), this must be
            // used to dispatch-build *BOTH* a short[] and a Short[]

            rec.array1DGenerator = primitiveOrBoxedOutput1DArray
                ? rec::array1DGeneratorBoolean
                : (JsonArray ja) -> jsonArrToBoxedStream(ja, rec).toArray(Boolean[]::new);

            return rec;
        }

        private static RECORD<Number, Stream<Number>> getNumberStreamRec
            (Number defaultValue, int FLAGS, Function<String, Number> optionalUserParser)
        {
            RECORD<Number, Stream<Number>> rec = new RECORD<>(
                defaultValue,
                FLAGS,
                Number.class,               // Class of the Stream.Builder "accept" Parameter
                (JsonNumber jn) -> true,    // Checks the JsonNumber retrieved
                StringParse::isDouble,      // String-tester (for parsing number-strings)
                Float::parseFloat,          // default-parser (number-string to float)
                (Number n) -> n,            // numberConverter (JAPPROX_ON_AEX *AND* usual-ans)
                (BigDecimal bd) -> { throw new ArithmeticException("Invalid Input"); },
                optionalUserParser
            );

            rec.array1DGenerator = (JsonArray ja) ->
                jsonArrToBoxedStream(ja, rec).toArray(Number[]::new);

            return rec;
        }


        // ****************************************************************************************
        // ****************************************************************************************
        // Static RECORD Factory/Builder Methods  --  Other-Streams
        // ****************************************************************************************
        // ****************************************************************************************


        private static RECORD<String, Stream<String>>
            getStringStreamRec(String defaultValue, int FLAGS)
        {
            RECORD<String, Stream<String>> rec = new RECORD<String, Stream<String>> (
                defaultValue,
                FLAGS,
                String.class,       // Class of the Stream.Builder "accept" Parameter
                null,               // Checks the JsonNumber retrieved
                null,               // String-tester (for parsing number-strings)
                null,               // default-parser (number-string to float)
                null,               // numberConverter (JAPPROX_ON_AEX *AND* usual-ans)
                null,               // Generates AEX on fail
                null                // optionalUserParser
            );

            rec.array1DGenerator = (JsonArray ja) ->
                strArrayToStreamINTERNAL(ja, rec).toArray(String[]::new);

            return rec;
        }

        @SuppressWarnings("unchecked") // Array.newInstance returns "Object" not 
        private static <X> RECORD<X, Stream<X>>
            getObjectStreamRec(X defaultValue, int FLAGS, Class<X> returnClass)
        {
            RECORD<X, Stream<X>> rec = new RECORD<>(
                defaultValue,
                FLAGS,
                returnClass,        // Class of the Stream.Builder "accept" Parameter
                null,               // Checks the JsonNumber retrieved
                null,               // String-tester (for parsing number-strings)
                null,               // default-parser (number-string to float)
                null,               // numberConverter (JAPPROX_ON_AEX *AND* usual-ans)
                null,
                null                // optionalUserParser
            );

            rec.array1DGenerator = (JsonArray ja) ->
               objArrayToStreamINTERNAL(ja, rec).toArray
                   ((int length) -> (X[]) Array.newInstance(returnClass, length));

            return rec;
        }


        // ****************************************************************************************
        // ****************************************************************************************
        // Static RECORD Factory/Builder ==> HELPERS FOR THE FACTORY-METHODS
        // ****************************************************************************************
        // ****************************************************************************************
        //
        // REMEMBER: The 1-D Arrays ==> int[], long[], double[] are built directly from a 
        //           PrimitiveStream using PrimStream.toArray, they don't need a "helper"


        // This method is only used if the input was "Short", so it is actually not "Unchecked"
        // but the Java-Compiler isn't smart enough to see that.
        @SuppressWarnings("unchecked")
        private short[] array1DGeneratorShort(JsonArray ja)
        {
            short[] retArrShort = new short[ja.size()];

            return boxedStreamToPrimitiveArray(
                jsonArrToBoxedStream(ja, (RECORD<Short, Stream<Short>>) this),
                ja,
                short.class,
                (Short s, int i) -> retArrShort[i] = s.shortValue(),
                retArrShort
            );
        }

        // This method is only used if the input was "Byte", so it is actually not "Unchecked"
        // but the Java-Compiler isn't smart enough to see that.
        @SuppressWarnings("unchecked")
        private byte[] array1DGeneratorByte(JsonArray ja)
        {
            byte[] retArrByte = new byte[ja.size()];

            return boxedStreamToPrimitiveArray(
                jsonArrToBoxedStream(ja, (RECORD<Byte, Stream<Byte>>) this),
                ja,
                byte.class,
                (Byte s, int i) -> retArrByte[i] = s.byteValue(),
                retArrByte
            );
        }

        // This method is only used if the input was "Float", so it is actually not "Unchecked"
        // but the Java-Compiler isn't smart enough to see that.
        @SuppressWarnings("unchecked")
        private float[] array1DGeneratorFloat(JsonArray ja)
        {
            float[] retArrFloat = new float[ja.size()];

            return boxedStreamToPrimitiveArray(
                jsonArrToBoxedStream(ja, (RECORD<Float, Stream<Float>>) this),
                ja,
                float.class,
                (Float s, int i) -> retArrFloat[i] = s.floatValue(),
                retArrFloat
            );
        }

        // This method is only used if the input was "Boolean", so it is actually not "Unchecked"
        // but the Java-Compiler isn't smart enough to see that.
        @SuppressWarnings("unchecked")
        private boolean[] array1DGeneratorBoolean(JsonArray ja)
        {
            boolean[] retArrBoolean = new boolean[ja.size()];

            return boxedStreamToPrimitiveArray(
                booleanArrayToBoxedStreamINTERNAL
                    (ja, (RECORD<Boolean, Stream<Boolean>>) this),
                ja,
                boolean.class,
                (Boolean s, int i) -> retArrBoolean[i] = s.booleanValue(),
                retArrBoolean
            );
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // PRIMARY CONVERTER FOR THREE STREAM FUNCTIONS
    // ********************************************************************************************
    // ********************************************************************************************
    //
    // NOTE: There is just no-way to document this damned thing.  *ALL IT IS DOING* is telling you
    //       that a Json-Array like [3, 4, 5] maps to a Java-Array like [3, 4, 5].  The extra
    //       work is checking for things like ["3", 4, 5] (where the 3 is a String), since this
    //       is completely legal in JSON, but not Java.  AND ALSO: [3.0, 4.1, 5.2] can be mapped
    //       to [3, 4, 5] - if and only if the FLAGS are properly set by the user...
    //
    // The whole value of this is the error-checking, and the ability to TIGHTEN AND RELAX the
    // requirements.  It makes using a REST-API (which communicates with the outside world using
    // JSON), a whole bunch of ONE-LINE statments.  (This HELPS a lot, but it is so AWFUL to look
    // at)

    /**
     * Builds a Primitive-Stream from a {@link JsonArray}
     * 
     * @param ja The {@link JsonArray}
     * @param rec The configurations
     * 
     * @throws JsonNullPrimitiveArrException <EMBED CLASS='external-html'
     *      DATA-FILE-ID=RARR_PS_JNPAEX>
     * 
     * @throws JsonArithmeticArrException <EMBED CLASS='external-html' DATA-FILE-ID=RARR_PS_JAAEX>
     * @throws JsonStrParseArrException <EMBED CLASS='external-html' DATA-FILE-ID=RARR_PS_JSPAEX>
     * @throws JsonTypeArrException <EMBED CLASS='external-html' DATA-FILE-ID=RARR_PS_JTAEX>
     */
    protected static <T, U> U jsonArrToStream(JsonArray ja, RECORD<T, U> rec)
    {
        rec.ja = ja;
        rec.c.run();    // Construct a new Stream-Builder

        int SIZE = ja.size();
        JsonValue jv;

        for (int i=0; i < SIZE; i++)

            switch ((jv = ja.get(i)).getValueType())
            {
                // javax.json.JsonValue.ValueType.NULL
                case NULL:
                    if (rec.handlerNull != null) rec.handlerNull.run();
                    else throw new JsonNullPrimitiveArrException(ja, i, NUMBER, rec.CLASS);
                    break;

                // javax.json.JsonValue.ValueType.NUMBER
                case NUMBER:

                    JsonNumber jn = (JsonNumber) jv;

                    // Guaranteed to work properly ==> This is the "definition of RJA_AEX"
                    //
                    // "numberConverter" is just Number.intValue, longValue, doubleValue
                    // Number.intValue(), longValue(), doubleValue() **DO NOT** throw any
                    // exceptions.  They round (if necessary), or return MAX_INT, MAX_LONG, etc...
                    // (also, only if necessary)

                    if (rec.RJA_AEX || rec.jsonNumWillFit.test(jn))
                        rec.a.accept(rec.numberConverter.apply(jn.numberValue()));

                    else if (rec.handlerAEX != null) rec.handlerAEX.run();

                    else throw new JsonArithmeticArrException
                        (getAEX(jn, rec.numberConverterExThrow), ja, i, NUMBER, jv, rec.CLASS);

                    break;

                // javax.json.JsonValue.ValueType.STRING
                case STRING: rec.handlerJsonString.accept(jv, i); break;

                // javax.json.JsonValue.ValueType.TRUE, FALSE, ARRAY, OBJECT
                default:
                    if (rec.handlerWrongType != null) rec.handlerWrongType.run();
                    else throw new JsonTypeArrException(ja, i, NUMBER, jv, rec.CLASS);
            }

        // Run Stream.Builder.build(); 
        return rec.b.get();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // THREE JSON-ARRAY  ==>  JAVA-STREAM METHODS (int-stream, double-stream, long-stream)
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />Invokes: {@link #jsonArrToStream(JsonArray, RECORD)}
     * <BR />Passes: Java {@code IntStream} Configurtion-Record
     * <BR />Removes: Any {@link JFlag} masks which might insert null-entries in the return-stream
     * <BR />For information about the {@link JFlag} parameter, click the method link above.
     * 
     * <BR /><BR />Producing a standard java {@code int[]} array from an {@code IntStream} is a
     * trivial-converstion:
     * 
     * <DIV CLASS=LOC>{@code
     * int[] arr = intArrayToStream(ja, -1, 0, null).toArray();
     * }</DIV>
     */
    public static IntStream intArrayToStream
        (JsonArray ja, int defaultValue, int FLAGS, ToIntFunction<String> optionalUserParser)
    {
        return jsonArrToStream(
            ja, RECORD.getIntStreamRec
                (defaultValue, FLAGS & NOT_ALLOWED_RET_NULL_MASKS, optionalUserParser)
        );
    }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #jsonArrToStream(JsonArray, RECORD)}
     * <BR />Passes: Java {@code LongStream} Configurtion-Record
     * <BR />Removes: Any {@link JFlag} masks which might insert null-entries in the return-stream
     * <BR />For information about the {@link JFlag} parameter, click the method link above.
     * 
     * <BR /><BR />Producing a standard java {@code long[]} array from a {@code LongStream} is a
     * trivial-converstion:
     * 
     * <DIV CLASS=LOC>{@code
     * long[] arr = longArrayToStream(ja, -1, 0, null).toArray();
     * }</DIV>
     */
    public static LongStream longArrayToStream
        (JsonArray ja, long defaultValue, int FLAGS, ToLongFunction<String> optionalUserParser)
    {
        return jsonArrToStream(
            ja, RECORD.getLongStreamRec
                (defaultValue, FLAGS & NOT_ALLOWED_RET_NULL_MASKS, optionalUserParser)
        );
    }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #jsonArrToStream(JsonArray, RECORD)}
     * <BR />Passes: Java {@code DoubleStream} Configurtion-Record
     * <BR />Removes: Any {@link JFlag} masks which might insert null-entries in the return-stream
     * <BR />For information about the {@link JFlag} parameter, click the method link above.
     * 
     * <BR /><BR />Producing a standard java {@code double[]} array from a {@code DoubleStream} is
     * a trivial-converstion:
     * 
     * <DIV CLASS=LOC>{@code
     * double[] arr = doubleArrayToStream(ja, -1, 0, null).toArray();
     * }</DIV>
     */
    public static DoubleStream doubleArrayToStream
        (JsonArray ja, double defaultValue, int FLAGS, ToDoubleFunction<String> optionalUserParser)
    {
        return jsonArrToStream(
            ja, RECORD.getDoubleStreamRec
                (defaultValue, FLAGS & NOT_ALLOWED_RET_NULL_MASKS, optionalUserParser)
        );
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // PRIMARY CONVERTER FOR STREAM OF BOXED-TYPES
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Builds a Stream of Boxed-Type Numbers from a {@link JsonArray}
     * @param rec The configurations
     * @throws JsonNullPrimitiveArrException <EMBED CLASS='external-html'
     *      DATA-FILE-ID=RARR_BS_JNPAEX>
     * @throws JsonArithmeticArrException <EMBED CLASS='external-html' DATA-FILE-ID=RARR_BS_JAAEX>
     * @throws JsonStrParseArrException <EMBED CLASS='external-html' DATA-FILE-ID=RARR_BS_JSPAEX>
     * @throws JsonTypeArrException <EMBED CLASS='external-html' DATA-FILE-ID=RARR_BS_JTAEX>
     */
    protected static <T, U> U jsonArrToBoxedStream(JsonArray ja, RECORD<T, U> rec)
    {
        rec.c.run();    // Construct a new Stream-Builder
        rec.ja = ja;

        int SIZE = ja.size();
        JsonValue jv;

        for (int i=0; i < SIZE; i++)

            switch ((jv = ja.get(i)).getValueType())
            {
                // javax.json.JsonValue.ValueType.NULL
                case NULL: rec.handlerNull.run(); break;

                // javax.json.JsonValue.ValueType.NUMBER
                case NUMBER:

                    JsonNumber jn = (JsonNumber) jv;

                    // Guaranteed to work properly ==> This is the "definition of RJA_AEX"
                    //
                    // Number.intValue(), longValue(), doubleValue() **DO NOT** throw any
                    // exceptions.  They round (if necessary), or return MAX_INT, MAX_LONG, etc...
                    // (also, only if necessary)

                    if (rec.RJA_AEX ||  rec.jsonNumWillFit.test(jn))
                        rec.a.accept(rec.numberConverter.apply(jn.numberValue()));

                    else if (rec.handlerAEX != null) rec.handlerAEX.run();

                    else throw new JsonArithmeticArrException
                        (getAEX(jn, rec.numberConverterExThrow), ja, i, NUMBER, jv, rec.CLASS);

                    break;

                // javax.json.JsonValue.ValueType.STRING
                case STRING: rec.handlerJsonString.accept(jv, i); break;

                // OBJECT, ARRAY, TRUE, FALSE
                default:
                    if (rec.handlerWrongType != null) rec.handlerWrongType.run();
                    else throw new JsonTypeArrException(ja, i, NUMBER, jv, rec.CLASS);
            }

        // Run Stream.Builder.build()
        return rec.b.get();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Json-Array to Java Arrays of Primitives
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Converts a Java Boxed Stream to a Primitive Array.
     * @param <T> The generic-type of the {@code java.util.stream.Stream}
     * @param <U> The returned primitive-array type
     * @param boxedStream A Java Boxed Stream
     * @param arrayBuilder A consumer which inserts a Boxed-Number into the Primitive-Array
     * @param ja The {@link JsonArray} that generated the Boxed-Stream.  Needed for error-output
     * @param returnClass The {@code java.lang.Class} (generic-type parameter) for the
     * {@code Stream}.  In other words, the {@code Class} for type-parameter {@code <T>}.
     * This is only needed if there is an exception, for proper &amp; readable error-reporting.
     */
    protected static <T, U> U boxedStreamToPrimitiveArray(
            Stream<T>           boxedStream,
            JsonArray           ja,
            Class<T>            returnClass,
            ObjIntConsumer<T>   arrayBuilder,
            U                   retArr
        )
    {
        // Since the array-index is used inside of a LAMBDA, this "EffectivelyFinal" counter
        // class becomes necessary.

        Counter counter = new Counter(-1);

        // Don't forget, Stream's are not guaranteed to be processed in order, unless an
        // explicit request is made using something like 'forEachOrdered'

        boxedStream.forEachOrdered((T boxedPrimitive) ->
        {
            int i = counter.addOne();   // "Final, or Effectively Final"

            // A Primitive-Array (like int[], long[], boolean[] etc...) may not have null
            if (boxedPrimitive == null)
                throw new JsonNullPrimitiveArrException(ja, i, NUMBER, returnClass);

            // The 'arrayBuilder' just assigns the value to the array[i]
            arrayBuilder.accept(boxedPrimitive, i);
        });
    
        return retArr;
    }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #shortArrayToBoxedStream(JsonArray, short, int, Function)}
     * <BR />And: {@link #boxedStreamToPrimitiveArray(Stream, JsonArray, Class, ObjIntConsumer,
     *      Object)}
     * <BR />
     * <BR />Converts: {@link JsonArray} to {@code Stream<Short>} and then to {@code short[]}
     * <BR />Removes: Any {@link JFlag} masks which might insert null-entries in the return-array
     * <BR />
     * <BR />For information about using {@code FLAGS}, see:
     * <B>{@link #jsonArrToBoxedStream(JsonArray, RECORD)}</B>
     */
    public static short[] shortArray
        (JsonArray ja, short defaultValue, int FLAGS, ToShortFunction<String> optionalUserParser)
    {
        short[] retArr = new short[ja.size()];

        return boxedStreamToPrimitiveArray(
            shortArrayToBoxedStream(
                // If there are any "Return null if..." JFlag's, they are eliminated
                ja, defaultValue, FLAGS & NOT_ALLOWED_RET_NULL_MASKS,

                // IMPORTANT, If the user didn't pass a parser, it is imperative that this is null!
                (optionalUserParser != null)
                    ? (String s) -> optionalUserParser.applyAsShort(s)
                    : null
            ),
            ja,
            short.class,
            (Short s, int i) -> retArr[i] = s.shortValue(),
            retArr
        );
    }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #byteArrayToBoxedStream(JsonArray, byte, int, Function)}
     * <BR />And: {@link #boxedStreamToPrimitiveArray(Stream, JsonArray, Class, ObjIntConsumer,
     *      Object)}
     * <BR />
     * <BR />Converts: {@link JsonArray} to {@code Stream<Byte>} and then to {@code byte[]}
     * <BR />Removes: Any {@link JFlag} masks which might insert null-entries in the return-array
     * <BR />
     * <BR />For information about using {@code FLAGS}, see:
     * <B>{@link #jsonArrToBoxedStream(JsonArray, RECORD)}</B>
     */
    public static byte[] byteArray
        (JsonArray ja, byte defaultValue, int FLAGS, ToByteFunction<String> optionalUserParser)
    {
        byte[] retArr = new byte[ja.size()];

        return boxedStreamToPrimitiveArray(
            byteArrayToBoxedStream(
                // If there are any "Return null if..." JFlag's, they are eliminated
                ja, defaultValue, FLAGS & NOT_ALLOWED_RET_NULL_MASKS,

                // IMPORTANT, If the user didn't pass a parser, it is imperative that this is null!
                (optionalUserParser != null)
                    ? (String s) -> optionalUserParser.applyAsByte(s)
                    : null
            ),
            ja,
            byte.class,
            (Byte s, int i) -> retArr[i] = s.byteValue(),
            retArr
        );
    }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #floatArrayToBoxedStream(JsonArray, float, int, Function)}
     * <BR />And: {@link #boxedStreamToPrimitiveArray(Stream, JsonArray, Class, ObjIntConsumer,
     *      Object)}
     * <BR />
     * <BR />Converts: {@link JsonArray} to {@code Stream<Float>} and then to {@code float[]}
     * <BR />Removes: Any {@link JFlag} masks which might insert null-entries in the return-array
     * <BR />
     * <BR />For information about using {@code FLAGS}, see:
     * <B>{@link #jsonArrToBoxedStream(JsonArray, RECORD)}</B>
     */
    public static float[] floatArray
        (JsonArray ja, float defaultValue, int FLAGS, ToFloatFunction<String> optionalUserParser)
    {
        float[] retArr = new float[ja.size()];

        return boxedStreamToPrimitiveArray(
            floatArrayToBoxedStream(
                // If there are any "Return null if..." JFlag's, they are eliminated
                ja, defaultValue, FLAGS & NOT_ALLOWED_RET_NULL_MASKS,

                // IMPORTANT, If the user didn't pass a parser, it is imperative that this is null!
                (optionalUserParser != null)
                    ? (String s) -> optionalUserParser.applyAsFloat(s)
                    : null
            ),
            ja,
            float.class,
            (Float s, int i) -> retArr[i] = s.floatValue(),
            retArr
        );
    }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #booleanArrayToBoxedStream(JsonArray, boolean, int, Function)}
     * <BR />And: {@link #boxedStreamToPrimitiveArray(Stream, JsonArray, Class, ObjIntConsumer,
     *      Object)}
     * <BR />
     * <BR />Converts: {@link JsonArray} to {@code Stream<Boolean>} and then to {@code boolean[]}
     * <BR />Removes: Any {@link JFlag} masks which might insert null-entries in the return-array
     * <BR />
     * <BR />For information about using {@code FLAGS}, see:
     * <B>{@link #jsonArrToBoxedStream(JsonArray, RECORD)}</B>
     */
    public static boolean[] booleanArray(
            JsonArray ja, boolean defaultValue, int FLAGS,
            Predicate<String> optionalUserParser
        )
    {
        boolean[] retArr = new boolean[ja.size()];

        return boxedStreamToPrimitiveArray(
            booleanArrayToBoxedStream(
                // If there are any "Return null if...", they are eliminated
                ja, defaultValue, FLAGS & NOT_ALLOWED_RET_NULL_MASKS,

                // IMPORTANT, If the user didn't pass a parser, it is imperative that this is null!
                (optionalUserParser != null) ? (String s) -> optionalUserParser.test(s) : null
            ),
            ja,
            boolean.class,
            (Boolean s, int i) -> retArr[i] = s.booleanValue(),
            retArr
        );
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Json-Array to Stream of Boxed-Number Types
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />Invokes: {@link #jsonArrToBoxedStream(JsonArray, RECORD)}
     * <BR />Fills in Configuration Record for Integer-Retrieval
     * <BR />For more Information about the {@link JFlag} Parameter, Click the Method-Link above.
     * <BR />
     * <BR />Producing a Boxed-Integer Array from this Method is as Follows:
     * <DIV CLASS=LOC>{@code
     * Integer[] arr = integerArrayToBoxedStream(ja, -1, 0 null).toArray(Integer[]::new);
     * }</DIV>
     */
    public static Stream<Integer> integerArrayToBoxedStream
        (JsonArray ja, int defaultValue, int FLAGS, Function<String, Integer> optionalUserParser)
    {
        return jsonArrToBoxedStream
            (ja, RECORD.getINTEGERStreamRec(defaultValue, FLAGS, optionalUserParser));
    }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #jsonArrToBoxedStream(JsonArray, RECORD)}
     * <BR />Fills in Configuration Record for Short-Retrieval
     * <BR />For more Information about the {@link JFlag} Parameter, Click the Method-Link above.
     * <BR />
     * <BR />Producing a Boxed-Short Array from this Method is as Follows:
     * <DIV CLASS=LOC>{@code
     * Short[] arr = shortArrayToBoxedStream(ja, -1, 0 null).toArray(Short[]::new);
     * }</DIV>
     */
    public static Stream<Short> shortArrayToBoxedStream
        (JsonArray ja, short defaultValue, int FLAGS, Function<String, Short> optionalUserParser)
    {
        return jsonArrToBoxedStream
            (ja, RECORD.getSHORTStreamRec(defaultValue, FLAGS, optionalUserParser, false));
    }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #jsonArrToBoxedStream(JsonArray, RECORD)}
     * <BR />Fills in Configuration Record for Byte-Retrieval
     * <BR />For more Information about the {@link JFlag} Parameter, Click the Method-Link above.
     * <BR />
     * <BR />Producing a Boxed-Byte Array from this Method is as Follows:
     * <DIV CLASS=LOC>{@code
     * Byte[] arr = byteArrayToBoxedStream(ja, -1, 0 null).toArray(Byte[]::new);
     * }</DIV>
     */
    public static Stream<Byte> byteArrayToBoxedStream
        (JsonArray ja, byte defaultValue, int FLAGS, Function<String, Byte> optionalUserParser)
    {
        return jsonArrToBoxedStream
            (ja, RECORD.getBYTEStreamRec(defaultValue, FLAGS, optionalUserParser, false));
    }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #jsonArrToBoxedStream(JsonArray, RECORD)}
     * <BR />Fills in Configuration Record for Long-Retrieval
     * <BR />For more Information about the {@link JFlag} Parameter, Click the Method-Link above.
     * <BR />
     * <BR />Producing a Boxed-Long Array from this Method is as Follows:
     * <DIV CLASS=LOC>{@code
     * Long[] arr = longArrayToBoxedStream(ja, -1, 0 null).toArray(Long[]::new);
     * }</DIV>
     */
    public static Stream<Long> longArrayToBoxedStream
        (JsonArray ja, long defaultValue, int FLAGS, Function<String, Long> optionalUserParser)
    {
        return jsonArrToBoxedStream
            (ja, RECORD.getLONGStreamRec(defaultValue, FLAGS, optionalUserParser));
    }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #jsonArrToBoxedStream(JsonArray, RECORD)}
     * <BR />Fills in Configuration Record for Double-Retrieval
     * <BR />For more Information about the {@link JFlag} Parameter, Click the Method-Link above.
     * <BR />
     * <BR />Producing a Boxed-Double Array from this Method is as Follows:
     * <DIV CLASS=LOC>{@code
     * Double[] arr = doubleArrayToBoxedStream(ja, -1, 0 null).toArray(Double[]::new);
     * }</DIV>
     */
    public static Stream<Double> doubleArrayToBoxedStream
        (JsonArray ja, double defaultValue, int FLAGS, Function<String, Double> optionalUserParser)
    {
        return jsonArrToBoxedStream
            (ja, RECORD.getDOUBLEStreamRec(defaultValue, FLAGS, optionalUserParser));
    }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #jsonArrToBoxedStream(JsonArray, RECORD)}
     * <BR />Fills in Configuration Record for Float-Retrieval
     * <BR />For more Information about the {@link JFlag} Parameter, Click the Method-Link above.
     * <BR />
     * <BR />Producing a Boxed-Float Array from this Method is as Follows:
     * <DIV CLASS=LOC>{@code
     * Float[] arr = floatArrayToBoxedStream(ja, -1, 0 null).toArray(Float[]::new);
     * }</DIV>
     */
    public static Stream<Float> floatArrayToBoxedStream
        (JsonArray ja, float defaultValue, int FLAGS, Function<String, Float> optionalUserParser)
    {
        return jsonArrToBoxedStream
            (ja, RECORD.getFLOATStreamRec(defaultValue, FLAGS, optionalUserParser, false));
    }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #jsonArrToBoxedStream(JsonArray, RECORD)}
     * <BR />Fills in Configuration Record for Number-Retrieval
     * <BR />For more Information about the {@link JFlag} Parameter, Click the Method-Link above.
     * <BR />
     * <BR />Producing a Boxed-Number Array from this Method is as Follows:
     * <DIV CLASS=LOC>{@code
     * Number[] arr = numberArrayToBoxedStream(ja, -1, 0 null).toArray(Number[]::new);
     * }</DIV>
     */
    public static Stream<Number> numberArrayToBoxedStream
        (JsonArray ja, Number defaultValue, int FLAGS, Function<String, Number> optionalUserParser)
    {
        return jsonArrToBoxedStream
            (ja, RECORD.getNumberStreamRec(defaultValue, FLAGS, optionalUserParser));
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // More Types
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Converts a {@link JsonArray} into a {@code Stream<String>}.  A Java {@code Stream<String>}
     * is easily converted to a {@code String[]}-Array via a call to:
     * 
     * <DIV CLASS=LOC>{@code
     * String[] sArr = strArrayToStream(myJsonArray, null, 0).toArray(String[]::new);
     * }</DIV>
     * 
     * @param ja Any {@code JsonArray}, but preferrably one which contains instances of
     * {@link JsonString}
     * 
     * @param defaultValue When used in conjunction with {@code 'FLAGS'}, this default-value may be
     * inserted into the output-array when error cases occur at particular array-index locations.
     * 
     * @param FLAGS Optional flags.  See {@link JFlag} for details.
     * 
     * @return A Java {@code Stream<String>}.
     */
    public static Stream<String> strArrayToStream(JsonArray ja, String defaultValue, int FLAGS)
    { return strArrayToStreamINTERNAL(ja, RECORD.getStringStreamRec(defaultValue, FLAGS)); }

    private static Stream<String> strArrayToStreamINTERNAL
        (JsonArray ja, RECORD<String, Stream<String>> rec)
    {
        int         SIZE    = ja.size();
        JsonValue   jv      = null;

        rec.c.run();    // Construct a new Stream-Builder
        rec.ja = ja;

        for (int i=0; i < SIZE; i++)

            switch ((jv = ja.get(i)).getValueType())
            {
                // javax.json.JsonValue.ValueType.NULL
                case NULL: rec.handlerNull.run(); break;

                // javax.json.JsonValue.ValueType.STRING
                case STRING: rec.a.accept(((JsonString) jv).getString()); break;

                // OBJECT, ARRAY, TRUE, FALSE, NUMBER
                default:

                    if (rec.RTS_WT) rec.a.accept(jv.toString());

                    else if (rec.handlerWrongType != null) rec.handlerWrongType.run();

                    else throw new JsonTypeArrException(ja, i, STRING, jv, String.class);
            }

        // Run Stream.Builder.build()
        return rec.b.get();
    }

    /**
     * Converts a {@link JsonArray} into a {@code Stream<Boolean>}.  A Java {@code Stream<Boolean>}
     * is easily converted to a {@code Boolean[]}-Array via a call to the lines below.  Note that
     * in this example, the return array is an array of {@code Boolean} objects; it is not a
     * primitive {@code boolean[]} array.  (To parse into a primitive array, use
     * {@link #booleanArray(JsonArray, boolean, int, Predicate)})
     * 
     * <DIV CLASS=LOC>{@code
     * Boolean[] bArr = booleanArrayToBoxedStream(myJsonArray, false, 0, null)
     *      .toArray(Boolean[]::new);
     * }</DIV>
     * 
     * @param ja Any {@code JsonArray}, but preferrably one which contains instances of
     * {@link JsonValue#TRUE} or {@link JsonValue#FALSE}
     * 
     * @param defaultValue When used in conjunction with {@code 'FLAGS'}, this default-value may be
     * inserted into the output-array when error cases occur at particular array-index locations.
     * 
     * @param FLAGS Optional flags.  See {@link JFlag} for details.
     * 
     * @param optionalUserParser If the appropriate flags are set, if a {@link JsonString} is
     * encountered while processing the {@code JsonArray}, an attempt to parse the {@code String}
     * into a {@code Boolean} will be made using this {@code String}-parser.
     * 
     * @return A Java {@code Stream<Boolean>}.
     */
    public static Stream<Boolean> booleanArrayToBoxedStream(
            JsonArray ja, boolean defaultValue, int FLAGS,
            Function<String, Boolean> optionalUserParser
        )
    {
        return booleanArrayToBoxedStreamINTERNAL(
            ja,
            RECORD.getBOOLEANStreamRec
                (defaultValue, FLAGS, optionalUserParser, false)
        );
    }

    private static Stream<Boolean> booleanArrayToBoxedStreamINTERNAL
        (JsonArray ja, RECORD<Boolean, Stream<Boolean>> rec)
    {
        int         SIZE    = ja.size();
        JsonValue   jv      = null;

        rec.c.run();    // Construct a new Stream-Builder
        rec.ja = ja;

        for (int i=0; i < SIZE; i++)

            switch ((jv = ja.get(i)).getValueType())
            {
                case NULL:      rec.handlerNull.run(); break;
                case TRUE:      rec.a.accept(true); break;
                case FALSE:     rec.a.accept(false); break;
                case STRING:    rec.handlerJsonString.accept(jv, i); break;

                // javax.json.JsonValue.ValueType.NUMBER, OBJECT, ARRAY
                default:
                    if (rec.handlerWrongType != null) rec.handlerWrongType.run();
                    else throw new JsonTypeArrException(ja, i, TRUE, jv, Boolean.class);
            }

        // Run Stream.Builder.build()
        return rec.b.get();
    }

    /**
     * Converts a {@link JsonArray} into a {@code Stream<T>}.  A Java {@code Stream<T>}
     * is easily converted to a {@code T[]}-Array via a call to the line below. 
     * 
     * <DIV CLASS=LOC>{@code
     * MyClass[] bArr = objArrayToStream(myJsonArray, null, 0, MyClass.class)
     *      .toArray(MyClass[]::new);
     * }</DIV>
     * 
     * @param <T> This is the 'type' of the array being built.  If there were a class, for example,
     * named class {@code 'Automobile'}, the value passed to parameter {@code 'returnClass'} would
     * simply be {@code Automobile.class}.
     * 
     * @param ja Any {@code JsonArray}, but preferrably one which contains instances of
     * {@link JsonValue#TRUE} or {@link JsonValue#FALSE}
     * 
     * @param defaultValue When used in conjunction with {@code 'FLAGS'}, this default-value may be
     * inserted into the output-array when error cases occur at particular array-index locations.
     * 
     * @param FLAGS Optional flags.  See {@link JFlag} for details.
     * 
     * @param returnClass The {@code java.lang.Class} of the Object being built
     * 
     * @return A Java {@code Stream<T>}.
     */
    public static <T> Stream<T> objArrayToStream
        (JsonArray ja, T defaultValue, int FLAGS, Class<T> returnClass)
    {
        return objArrayToStreamINTERNAL
            (ja, RECORD.getObjectStreamRec(defaultValue, FLAGS, returnClass));
    }

    private static <T> Stream<T> objArrayToStreamINTERNAL
        (JsonArray ja, RECORD<T, Stream<T>> rec)
    {
        int                     SIZE    = ja.size();
        JsonValue               jv      = null;

        rec.c.run();    // Construct a new Stream-Builder
        rec.ja = ja;

        for (int i=0; i < SIZE; i++)

            switch ((jv = ja.get(i)).getValueType())
            {
                // javax.json.JsonValue.ValueType.NULL
                case NULL:
                    rec.handlerNull.run();
                    break;

                // javax.json.JsonValue.ValueType.OBJECT
                case OBJECT:
                    rec.a.accept(ReadJSON.getObject(((JsonObject) jv), rec.CLASS));
                    break;

                // javax.json.JsonValue.ValueType.NUMBER, STRING, TRUE, FALSE, ARRAY
                default:
                    if (rec.handlerWrongType != null) rec.handlerWrongType.run();
                    else throw new JsonTypeArrException(ja, i, TRUE, jv, rec.CLASS);
            }

        // Run Stream.Builder.build()
        return rec.b.get();
    }

    /**
     * Parses Multi-Dimensional JSON Array's into Multi-Dimensional Java Array's.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=GLASS_FISH_NOTE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=READ_ARR_JDIMN>
     *
     * @see Json
     * @see JsonArray
     */
    @Torello.JavaDoc.StaticFunctional
    @Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JSON_JDHBI")
    public static class DimN
    {
        private DimN() { }

        /**
         * Check user input, and throws exceptions if the array-class has not been properly
         * chosen.
         * @param retArrClass This must be a primitive-array class, possibly of multiple dimensions
         * 
         * @param rootClass The expected "root class".  For {@code int[][].class}, the root class
         * would be {@code int.class}.
         * 
         * @return Parameter {@code retArrClass} is the return value of this checker method
         * 
         * @throws IllegalArgumentExcetion If parameter {@code retArrClass}:
         * <BR /><BR /><OL CLASS=JDOL>
         * <LI>If calling {@code retArrClass.isArray()} returns {@code FALSE}</LI>
         * <LI>If the root-array type is not the appropriate type for the method that was called
         *      </LI>
         * </OL>
         */
        private static <T> Class<T> CHECK_ARRAY_CLASS(Class<T> retArrClass, Class<?> rootClass)
        {
            if (! retArrClass.isArray()) throw new IllegalArgumentException(
                "The class you have passed to parameter 'retArrClass' " +
                "[" + retArrClass.getSimpleName() + "], is not an array"
            );

            Class<?> componentClass = retArrClass.getComponentType();

            while (componentClass.isArray()) componentClass = componentClass.getComponentType();

            if (! rootClass.equals(componentClass)) throw new IllegalArgumentException(
                "The class you have passed to parameter 'retArrClass' " +
                "[" + retArrClass.getSimpleName() + "], is not a(n) " +
                rootClass.getSimpleName() + "-array."
            );

            return retArrClass;
        }

        private static Class<?> GET_ARRAY_BASE_COMPONENT_CLASS_AND_CHECK
            (Class<?> retArrClass, Object defaultValue)
        {
            if (! retArrClass.isArray()) throw new IllegalArgumentException(
                "The class you have passed to parameter 'retArrClass' " +
                "[" + retArrClass.getSimpleName() + "], is not an array"
            );

            Class<?> componentClass = retArrClass.getComponentType();

            while (componentClass.isArray()) componentClass = componentClass.getComponentType();

            if (    (defaultValue != null)
                &&  componentClass.isAssignableFrom(defaultValue.getClass())
            )

                throw new IllegalArgumentException(
                    "The User Provided Default Value of type: "+
                    "[" + defaultValue.getClass().getName() + "], cannot be assigned to the " +
                    "Component-Type of the Array: " +
                    "[" + componentClass.getName() + "]"
                );

            return componentClass;
        }



        // ****************************************************************************************
        // ****************************************************************************************
        // Primitive Multi-Dimensional Array Methods
        // ****************************************************************************************
        // ****************************************************************************************


        /**
         * Convenience Method.
         * <BR />Invokes: {@link #jsonArrToJavaArr(JsonArray, ReadArrJSON.RECORD, Class)}
         * <BR />Passes: {@code int} Configuration-RECORD
         * <BR />Removes: Any {@code FLAGS} that would produce a null array-entry
         * <BR />
         * <BR />See link above for more {@link JFlag} explanations.
         * <BR /><B>NOTE:</B> {@code retArrClass} must be a multi-dimensinal {@code int}-array.
         * <BR />(See last <B>"return-type"</B> parameter in example below)
         * 
         * <DIV CLASS=LOC>{@code
         * int[][] arr = ReadArrJSON.DimN.intArr(jsonArray, -1, 0, null, int[][].class);
         * }</DIV>
         */
        public static <T> T intArr(
                JsonArray ja, int defaultValue, int FLAGS,
                ToIntFunction<String> optionalUserParser, Class<T> retArrClass
            )
        {
            return jsonArrToJavaArr(
                ja,
                RECORD.getIntStreamRec
                    (defaultValue, FLAGS & NOT_ALLOWED_RET_NULL_MASKS, optionalUserParser),
                CHECK_ARRAY_CLASS(retArrClass, int.class)
            );
        }

        /**
         * Convenience Method.
         * <BR />Invokes: {@link #jsonArrToJavaArr(JsonArray, ReadArrJSON.RECORD, Class)}
         * <BR />Passes: {@code long} Configuration-RECORD
         * <BR />Removes: Any {@code FLAGS} that would produce a null array-entry
         * <BR />
         * <BR />See link above for more {@link JFlag} explanations.
         * <BR /><B>NOTE:</B> {@code retArrClass} must be a multi-dimensinal {@code long}-array.
         * <BR />(See last <B>"return-type"</B> parameter in example below)
         * 
         * <DIV CLASS=LOC>{@code
         * long[][] arr = ReadArrJSON.DimN.longArr(jsonArray, -1, 0, null, long[][].class);
         * }</DIV>
         */
        public static <T> T longArr(
                JsonArray ja, long defaultValue, int FLAGS,
                ToLongFunction<String> optionalUserParser, Class<T> retArrClass
            )
        {
            return jsonArrToJavaArr(
                ja,
                RECORD.getLongStreamRec
                    (defaultValue, FLAGS & NOT_ALLOWED_RET_NULL_MASKS, optionalUserParser),
                CHECK_ARRAY_CLASS(retArrClass, long.class)
            );
        }

        /**
         * Convenience Method.
         * <BR />Invokes: {@link #jsonArrToJavaArr(JsonArray, ReadArrJSON.RECORD, Class)}
         * <BR />Passes: {@code double} Configuration-RECORD
         * <BR />Removes: Any {@code FLAGS} that would produce a null array-entry
         * <BR />
         * <BR />See link above for more {@link JFlag} explanations.
         * <BR /><B>NOTE:</B> {@code retArrClass} must be a multi-dimensinal {@code double}-array.
         * <BR />(See last <B>"return-type"</B> parameter in example below)
         * 
         * <DIV CLASS=LOC>{@code
         * double[][] arr = ReadArrJSON.DimN.doubleArr(jsonArray, -1, 0, null, double[][].class);
         * }</DIV>
         */
        public static <T> T doubleArr(
                JsonArray ja, double defaultValue, int FLAGS,
                ToDoubleFunction<String> optionalUserParser, Class<T> retArrClass
            )
        {
            return jsonArrToJavaArr(
                ja,
                RECORD.getDoubleStreamRec
                    (defaultValue, FLAGS & NOT_ALLOWED_RET_NULL_MASKS, optionalUserParser),
                CHECK_ARRAY_CLASS(retArrClass, double.class)
            );
        }

        /**
         * Convenience Method.
         * <BR />Invokes: {@link #jsonArrToJavaArr(JsonArray, ReadArrJSON.RECORD, Class)}
         * <BR />Passes: {@code short} Configuration-RECORD
         * <BR />Removes: Any {@code FLAGS} that would produce a null array-entry
         * <BR />
         * <BR />See link above for more {@link JFlag} explanations.
         * <BR /><B>NOTE:</B> {@code retArrClass} must be a multi-dimensinal {@code short}-array.
         * <BR />(See last <B>"return-type"</B> parameter in example below)
         * 
         * <DIV CLASS=LOC>{@code
         * short[][] arr = ReadArrJSON.DimN.shortArr(jsonArray, -1, 0, null, short[][].class);
         * }</DIV>
         */
        public static <T> T shortArr(
                JsonArray ja, short defaultValue, int FLAGS,
                ToShortFunction<String> optionalUserParser, Class<T> retArrClass
            )
        {
            return jsonArrToJavaArr(
                ja,
                RECORD.getSHORTStreamRec(
                    defaultValue, FLAGS & NOT_ALLOWED_RET_NULL_MASKS,    
                    (optionalUserParser != null)
                        ? (String s) -> optionalUserParser.applyAsShort(s)
                        : null,
                    true
                ),
                CHECK_ARRAY_CLASS(retArrClass, short.class)
            );
        }

        /**
         * Convenience Method.
         * <BR />Invokes: {@link #jsonArrToJavaArr(JsonArray, ReadArrJSON.RECORD, Class)}
         * <BR />Passes: {@code byte} Configuration-RECORD
         * <BR />Removes: Any {@code FLAGS} that would produce a null array-entry
         * <BR />
         * <BR />See link above for more {@link JFlag} explanations.
         * <BR /><B>NOTE:</B> {@code retArrClass} must be a multi-dimensinal {@code byte}-array.
         * <BR />(See last <B>"return-type"</B> parameter in example below)
         * 
         * <DIV CLASS=LOC>{@code
         * byte[][] arr = ReadArrJSON.DimN.byteArr(jsonArray, -1, 0, null, byte[][].class);
         * }</DIV>
         */
        public static <T> T byteArr(
                JsonArray ja, byte defaultValue, int FLAGS,
                ToByteFunction<String> optionalUserParser, Class<T> retArrClass
            )
        {
            return jsonArrToJavaArr(
                ja,
                RECORD.getBYTEStreamRec(
                    defaultValue, FLAGS & NOT_ALLOWED_RET_NULL_MASKS,    
                    (optionalUserParser != null)
                        ? (String s) -> optionalUserParser.applyAsByte(s)
                        : null,
                    true
                ),
                CHECK_ARRAY_CLASS(retArrClass, byte.class)
            );
        }

        /**
         * Convenience Method.
         * <BR />Invokes: {@link #jsonArrToJavaArr(JsonArray, ReadArrJSON.RECORD, Class)}
         * <BR />Passes: {@code float} Configuration-RECORD
         * <BR />Removes: Any {@code FLAGS} that would produce a null array-entry
         * <BR />
         * <BR />See link above for more {@link JFlag} explanations.
         * <BR /><B>NOTE:</B> {@code retArrClass} must be a multi-dimensinal {@code float}-array.
         * <BR />(See last <B>"return-type"</B> parameter in example below)
         * 
         * <DIV CLASS=LOC>{@code
         * float[][] arr = ReadArrJSON.DimN.floatArr(jsonArray, -1, 0, null, float[][].class);
         * }</DIV>
         */
        public static <T> T floatArr(
                JsonArray ja, float defaultValue, int FLAGS,
                ToFloatFunction<String> optionalUserParser, Class<T> retArrClass
            )
        {
            return jsonArrToJavaArr(
                ja,
                RECORD.getFLOATStreamRec(
                    defaultValue, FLAGS & NOT_ALLOWED_RET_NULL_MASKS,    
                    (optionalUserParser != null)
                        ? (String s) -> optionalUserParser.applyAsFloat(s)
                        : null,
                    true
                ),
                CHECK_ARRAY_CLASS(retArrClass, float.class)
            );
        }

        /**
         * Convenience Method.
         * <BR />Invokes: {@link #jsonArrToJavaArr(JsonArray, ReadArrJSON.RECORD, Class)}
         * <BR />Passes: {@code boolean} Configuration-RECORD
         * <BR />Removes: Any {@code FLAGS} that would produce a null array-entry
         * <BR />
         * <BR />See link above for more {@link JFlag} explanations.
         * <BR /><B>NOTE:</B> {@code retArrClass} must be a multi-dimensinal {@code boolean}-array.
         * <BR />(See last <B>"return-type"</B> parameter in example below)
         * 
         * <DIV CLASS=LOC>{@code
         * boolean[][] arr = ReadArrJSON.DimN.booleanArr
         *      (jsonArray, -1, 0, null, boolean[][].class);
         * }</DIV>
         */
        public static <T> T booleanArr(
                JsonArray ja, boolean defaultValue, int FLAGS,
                Predicate<String> optionalUserParser, Class<T> retArrClass
            )
        {
            return jsonArrToJavaArr(
                ja,
                RECORD.getBOOLEANStreamRec(
                    defaultValue, FLAGS & NOT_ALLOWED_RET_NULL_MASKS,    
                    (optionalUserParser != null)
                        ? (String s) -> optionalUserParser.test(s)
                        : null,
                    true
                ),
                CHECK_ARRAY_CLASS(retArrClass, boolean.class)
            );
        }


        // ****************************************************************************************
        // ****************************************************************************************
        // Boxed-Primitive Multi-Dimensional Array Methods
        // ****************************************************************************************
        // ****************************************************************************************


        /**
         * Convenience Method.
         * <BR />Invokes: {@link #jsonArrToJavaArr(JsonArray, ReadArrJSON.RECORD, Class)}
         * <BR />Passes: {@code Integer} Configuration-RECORD
         * <BR />See link above for more {@link JFlag} explanations.
         * <BR /><B>NOTE:</B> {@code retArrClass} must be a multi-dimensinal {@code Integer}-array.
         * <BR />(See last <B>"return-type"</B> parameter in example below)
         * 
         * <DIV CLASS=LOC>{@code
         * Integer[][] arr = ReadArrJSON.DimN.arrINTEGER(jsonArray, -1, 0, null, Integer[][].class);
         * }</DIV>
         */
        public static <T> T arrINTEGER(
                JsonArray ja, int defaultValue, int FLAGS,
                Function<String, Integer> optionalUserParser, Class<T> retArrClass
            )
        {
            return jsonArrToJavaArr(
                ja,
                RECORD.getINTEGERStreamRec(defaultValue, FLAGS, optionalUserParser),
                CHECK_ARRAY_CLASS(retArrClass, Integer.class)
            );
        }

        /**
         * Convenience Method.
         * <BR />Invokes: {@link #jsonArrToJavaArr(JsonArray, ReadArrJSON.RECORD, Class)}
         * <BR />Passes: {@code Long} Configuration-RECORD
         * <BR />See link above for more {@link JFlag} explanations.
         * <BR /><B>NOTE:</B> {@code retArrClass} must be a multi-dimensinal {@code Long}-array.
         * <BR />(See last <B>"return-type"</B> parameter in example below)
         * 
         * <DIV CLASS=LOC>{@code
         * Long[][] arr = ReadArrJSON.DimN.arrLONG(jsonArray, -1, 0, null, Long[][].class);
         * }</DIV>
         */
        public static <T> T arrLONG(
                JsonArray ja, long defaultValue, int FLAGS,
                Function<String, Long> optionalUserParser, Class<T> retArrClass
            )
        {
            return jsonArrToJavaArr(
                ja,
                RECORD.getLONGStreamRec(defaultValue, FLAGS, optionalUserParser),
                CHECK_ARRAY_CLASS(retArrClass, Long.class)
            );
        }

        /**
         * Convenience Method.
         * <BR />Invokes: {@link #jsonArrToJavaArr(JsonArray, ReadArrJSON.RECORD, Class)}
         * <BR />Passes: {@code Double} Configuration-RECORD
         * <BR />See link above for more {@link JFlag} explanations.
         * <BR /><B>NOTE:</B> {@code retArrClass} must be a multi-dimensinal {@code Double}-array.
         * <BR />(See last <B>"return-type"</B> parameter in example below)
         * 
         * <DIV CLASS=LOC>{@code
         * Double[][] arr = ReadArrJSON.DimN.arrDOUBLE(jsonArray, -1, 0, null, Double[][].class);
         * }</DIV>
         */
        public static <T> T arrDOUBLE(
                JsonArray ja, double defaultValue, int FLAGS,
                Function<String, Double> optionalUserParser, Class<T> retArrClass
            )
        {
            return jsonArrToJavaArr(
                ja,
                RECORD.getDOUBLEStreamRec(defaultValue, FLAGS, optionalUserParser),
                CHECK_ARRAY_CLASS(retArrClass, Double.class)
            );
        }

        /**
         * Convenience Method.
         * <BR />Invokes: {@link #jsonArrToJavaArr(JsonArray, ReadArrJSON.RECORD, Class)}
         * <BR />Passes: {@code Short} Configuration-RECORD
         * <BR />See link above for more {@link JFlag} explanations.
         * <BR /><B>NOTE:</B> {@code retArrClass} must be a multi-dimensinal {@code Short}-array.
         * <BR />(See last <B>"return-type"</B> parameter in example below)
         * 
         * <DIV CLASS=LOC>{@code
         * Short[][] arr = ReadArrJSON.DimN.arrSHORT(jsonArray, -1, 0, null, Short[][].class);
         * }</DIV>
         */
        public static <T> T arrSHORT(
                JsonArray ja, short defaultValue, int FLAGS,
                Function<String, Short> optionalUserParser, Class<T> retArrClass
            )
        {
            return jsonArrToJavaArr(
                ja,
                RECORD.getSHORTStreamRec(defaultValue, FLAGS, optionalUserParser, true),
                CHECK_ARRAY_CLASS(retArrClass, Short.class)
            );
        }

        /**
         * Convenience Method.
         * <BR />Invokes: {@link #jsonArrToJavaArr(JsonArray, ReadArrJSON.RECORD, Class)}
         * <BR />Passes: {@code Byte} Configuration-RECORD
         * <BR />See link above for more {@link JFlag} explanations.
         * <BR /><B>NOTE:</B> {@code retArrClass} must be a multi-dimensinal {@code Byte}-array.
         * <BR />(See last <B>"return-type"</B> parameter in example below)
         * 
         * <DIV CLASS=LOC>{@code
         * Byte[][] arr = ReadArrJSON.DimN.arrBYTE(jsonArray, -1, 0, null, Byte[][].class);
         * }</DIV>
         */
        public static <T> T arrBYTE(
                JsonArray ja, byte defaultValue, int FLAGS,
                Function<String, Byte> optionalUserParser, Class<T> retArrClass
            )
        {
            return jsonArrToJavaArr(
                ja,
                RECORD.getBYTEStreamRec(defaultValue, FLAGS, optionalUserParser, true),
                CHECK_ARRAY_CLASS(retArrClass, Byte.class)
            );
        }

        /**
         * Convenience Method.
         * <BR />Invokes: {@link #jsonArrToJavaArr(JsonArray, ReadArrJSON.RECORD, Class)}
         * <BR />Passes: {@code Float} Configuration-RECORD
         * <BR />See link above for more {@link JFlag} explanations.
         * <BR /><B>NOTE:</B> {@code retArrClass} must be a multi-dimensinal {@code Float}-array.
         * <BR />(See last <B>"return-type"</B> parameter in example below)
         * 
         * <DIV CLASS=LOC>{@code
         * Float[][] arr = ReadArrJSON.DimN.arrFLOAT(jsonArray, -1, 0, null, Float[][].class);
         * }</DIV>
         */
        public static <T> T arrFLOAT(
                JsonArray ja, float defaultValue, int FLAGS,
                Function<String, Float> optionalUserParser, Class<T> retArrClass
            )
        {
            return jsonArrToJavaArr(
                ja,
                RECORD.getFLOATStreamRec(defaultValue, FLAGS, optionalUserParser, true),
                CHECK_ARRAY_CLASS(retArrClass, Float.class)
            );
        }

        /**
         * Convenience Method.
         * <BR />Invokes: {@link #jsonArrToJavaArr(JsonArray, ReadArrJSON.RECORD, Class)}
         * <BR />Passes: {@code Boolean} Configuration-RECORD
         * <BR />See link above for more {@link JFlag} explanations.
         * <BR /><B>NOTE:</B> {@code retArrClass} must be a multi-dimensinal {@code Boolean}-array.
         * <BR />(See last <B>"return-type"</B> parameter in example below)
         * 
         * <DIV CLASS=LOC>{@code
         * Boolean[][] arr = ReadArrJSON.DimN.arrBOOLEAN
         *      (jsonArray, false, 0, null, Boolean[][].class);
         * }</DIV>
         */
        public static <T> T arrBOOLEAN(
                JsonArray ja, boolean defaultValue, int FLAGS,
                Function<String, Boolean> optionalUserParser, Class<T> retArrClass
            )
        {
            return jsonArrToJavaArr(
                ja,
                RECORD.getBOOLEANStreamRec(defaultValue, FLAGS, optionalUserParser, true),
                CHECK_ARRAY_CLASS(retArrClass, Boolean.class)
            );
        }

        /**
         * Convenience Method.
         * <BR />Invokes: {@link #jsonArrToJavaArr(JsonArray, ReadArrJSON.RECORD, Class)}
         * <BR />Passes: {@code Number} Configuration-RECORD
         * <BR />See link above for more {@link JFlag} explanations.
         * <BR /><B>NOTE:</B> {@code retArrClass} must be a multi-dimensinal {@code Number}-array.
         * <BR />(See last <B>"return-type"</B> parameter in example below)
         * 
         * <DIV CLASS=LOC>{@code
         * Number[][] arr = ReadArrJSON.DimN.arrNumber(jsonArray, -1, 0, null, Number[][].class);
         * }</DIV>
         */
        public static <T> T arrNumber(
                JsonArray ja, Number defaultValue, int FLAGS,
                Function<String, Number> optionalUserParser, Class<T> retArrClass
            )
        {
            return jsonArrToJavaArr(
                ja,
                RECORD.getNumberStreamRec(defaultValue, FLAGS, optionalUserParser),
                CHECK_ARRAY_CLASS(retArrClass, Number.class)
            );
        }


        // ****************************************************************************************
        // ****************************************************************************************
        // Non-Primitive Multi-Dimensional Array Methods
        // ****************************************************************************************
        // ****************************************************************************************


        /**
         * Convenience Method.
         * <BR />Invokes: {@link #jsonArrToJavaArr(JsonArray, ReadArrJSON.RECORD, Class)}
         * <BR />Passes: {@code String} Configuration-RECORD
         * <BR />See link above for more {@link JFlag} explanations.
         * <BR /><B>NOTE:</B> {@code retArrClass} must be a multi-dimensinal {@code String}-array.
         * <BR />(See last <B>"return-type"</B> parameter in example below)
         * 
         * <DIV CLASS=LOC>{@code
         * String[][] arr = ReadArrJSON.DimN.strArr(jsonArray, null, 0, String[][].class);
         * }</DIV>
         */
        public static <T> T strArr
            (JsonArray ja, String defaultValue, int FLAGS, Class<T> retArrClass)
        {
            return jsonArrToJavaArr(
                ja, 
                RECORD.getStringStreamRec(defaultValue, FLAGS),
                CHECK_ARRAY_CLASS(retArrClass, String.class)
            );
        }

        /**
         * Convenience Method.
         * <BR />Invokes: {@link #jsonArrToJavaArr(JsonArray, ReadArrJSON.RECORD, Class)}
         * <BR />Passes: {@code Object} Configuration-RECORD
         * <BR />See link above for more {@link JFlag} explanations.
         * <BR /><B>NOTE:</B> {@code retArrClass} must be a multi-dimensinal {@code Object}-array.
         * <BR />(See last <B>"return-type"</B> parameter in example below)
         * 
         * <DIV CLASS=LOC>{@code
         * MyClass[][] arr = ReadArrJSON.DimN.strArr(jsonArray, null, 0, MyClass[][].class);
         * }</DIV>
         */
        @SuppressWarnings({"rawtypes", "unchecked"})
        public static <T, U> T objArr
            (JsonArray ja, Object defaultValue, int FLAGS, Class<T> retArrClass)
        {
            Class baseClass = // (Class<U>)
                GET_ARRAY_BASE_COMPONENT_CLASS_AND_CHECK(retArrClass, defaultValue);

            return jsonArrToJavaArr
                (ja, RECORD.getObjectStreamRec(baseClass.cast(defaultValue), FLAGS, baseClass), retArrClass);
        }


        // ****************************************************************************************
        // ****************************************************************************************
        // The General Purpose Transformer Method
        // ****************************************************************************************
        // ****************************************************************************************


        /**
         * The array processor for this class.  Handles all multi-dimensional array processing
         * requests.
         * 
         * @param <T> The array type being returned.  This {@code java.lang.Class} must be an
         * array-class.
         * 
         * @param ja Any {@link JsonArray}
         * @param rec The Configuration-Record
         * @param retArrClass The class of the return array type.
         * 
         * @return An array of type {@code T}
         * 
         * @throws JsonNullPrimitiveArrException <EMBED CLASS='external-html'
         *      DATA-FILE-ID=RARR_BS_JNPAEX>
         * @throws JsonArithmeticArrException <EMBED CLASS='external-html' DATA-FILE-ID=RARR_BS_JAAEX>
         * @throws JsonStrParseArrException <EMBED CLASS='external-html' DATA-FILE-ID=RARR_BS_JSPAEX>
         * @throws JsonTypeArrException <EMBED CLASS='external-html' DATA-FILE-ID=RARR_BS_JTAEX>
         */
        @SuppressWarnings("unchecked")
        protected static <T> T jsonArrToJavaArr
            (JsonArray ja, RECORD<?, ?> rec, Class<T> retArrClass)
        {
            // If this is requesting a one-dimensional array, get it using the 1D-Generator,
            // and simply return that array.  This requires a cast because there is no way to prove
            // to the Java-Compiler that <T> is equal to any return-value at all.
            //
            // Remember that this is only guaranteed (it works!) because the helper methods are all
            // protected or private, and it has been guaranteed through rigorous testing, and
            // preventing the user from playing with it!

            if (StringParse.countCharacters(retArrClass.getSimpleName(), '[') == 1)
                return (T) rec.array1DGenerator.apply(ja);

            // Otherwise, this is not a single-dimension (1D) array.  Instead, the JsonArray needs
            // to be iterated, and this method called, recursively, on each of the sub-arrays.
            //
            // NOTE: 'compClass' will also be an array, but with one fewer dimensions

            Class<?>    compClass   = retArrClass.getComponentType();
            int         SIZE        = ja.size();
            T           retArr      = (T) Array.newInstance(compClass, SIZE);
            JsonValue   jv          = null;

            for (int i=0; i < SIZE; i++)

                switch ((jv = ja.get(i)).getValueType())
                {
                    // javax.json.JsonValue.ValueType.NULL
                    case NULL: Array.set(retArr, i, null); break;

                    // javax.json.JsonValue.ValueType.ARRAY (JsonArray)
                    case ARRAY:
                        Array.set
                            (retArr, i, jsonArrToJavaArr((JsonArray) jv, rec, compClass));
                        break;

                    // javax.json.JsonValue.ValueType.TRUE, FALSE, NUMBER, STRING, OBJECT
                    default:
                        if (rec.IN_NSAT)        Array.set(retArr, i, null);
                        else if (rec.S_NSAT)    continue;
                        else throw new JsonTypeArrException(ja, i, ARRAY, jv, retArrClass);
                }

            return retArr;
        }
    }
}