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 Torello.JavaDoc.StaticFunctional;
import Torello.JavaDoc.JDHeaderBackgroundImg;
import Torello.JavaDoc.LinkJavaSource;

import Torello.JavaDoc.IntoHTMLTable;
import static Torello.JavaDoc.IntoHTMLTable.Background.GreenDither;
import static Torello.JavaDoc.IntoHTMLTable.Background.BlueDither;

import java.util.Objects;

import java.util.stream.Stream;
import java.util.stream.IntStream;
import java.util.stream.LongStream;
import java.util.stream.DoubleStream;

import java.util.function.ToIntFunction;
import java.util.function.ToLongFunction;
import java.util.function.ToDoubleFunction;
import java.util.function.Predicate;
import java.util.function.Function;

import javax.json.JsonArray;
import javax.json.Json;

import static Torello.Java.JSON.JFlag.NOT_ALLOWED_RET_NULL_MASKS;


/**
 * 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=RJA_DIM_N>
 * <EMBED CLASS='external-html' DATA-FILE-ID=JSON_BINDING_NOTE>
 * 
 * <BR /><HR> <BR />
 * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN>
 *
 * <EMBED CLASS=globalDefs DATA-A_AN=A>
 * @see Json
 * @see JsonArray
 */
@StaticFunctional
@JDHeaderBackgroundImg(EmbedTagFileID="RJA_JDHBI_DIM_N")
public class RJArrDimN
{
    private RJArrDimN() { }


    private static final boolean REFERENCE_1D_ARRAY = true;
    private static final boolean BOXED_1D_ARRAY     = true;
    private static final boolean PRIMITIVE_1D_ARRAY = false;


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


    /**
     * <EMBED CLASS=defs DATA-A_AN=An DATA-TYPE=int DATA-DEFVAL="-1">
     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_PRIM>
     */
    @IntoHTMLTable(background=GreenDither, title="Multi-Dimensional Array of Primitive-Integers")
    @LinkJavaSource(handle="BASIC_TYPES", name="INTEGER")
    @LinkJavaSource(handle="STREAM_BUILDER", name="intStream")
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForDimNArrays")
    public static <T> T intArr(
            final JsonArray             ja,
            final int                   defaultValue,
            final int                   FLAGS,
            final ToIntFunction<String> optionalUserParser,
            final Class<T>              retArrClass
        )
    {
        return ProcessMultiDimJsonArray.jsonArrayToJava(
            ja,
            // new SettingsRec<Integer, IntStream>(
            SETTINGS_REC_BUILDER.createForDimNArrays(
                defaultValue,
                FLAGS & NOT_ALLOWED_RET_NULL_MASKS,
                (optionalUserParser == null) ? null : optionalUserParser::applyAsInt,
                BASIC_TYPES.PRIMITIVE_INTEGER(),
                STREAM_BUILDER.intStream(),
                PRIMITIVE_1D_ARRAY
            ),
            RJArrDimN.CHECK_ARRAY_CLASS(retArrClass, int.class)
        );
    }

    /**
     * <EMBED CLASS=defs DATA-TYPE=long DATA-DEFVAL="-1">
     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_PRIM>
     */
    @IntoHTMLTable(background=BlueDither,
        title="Multi-Dimensional Array of Primitive Long-Integers")
    @LinkJavaSource(handle="BASIC_TYPES", name="LONG")
    @LinkJavaSource(handle="STREAM_BUILDER", name="longStream")
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForDimNArrays")
    public static <T> T longArr(
            final JsonArray                 ja,
            final long                      defaultValue,
            final int                       FLAGS,
            final ToLongFunction<String>    optionalUserParser,
            final Class<T>                  retArrClass
        )
    {
        return ProcessMultiDimJsonArray.jsonArrayToJava(
            ja,
            // new SettingsRec<Long, LongStream>(
            SETTINGS_REC_BUILDER.createForDimNArrays(
                defaultValue,
                FLAGS & NOT_ALLOWED_RET_NULL_MASKS,
                (optionalUserParser == null) ? null : optionalUserParser::applyAsLong,
                BASIC_TYPES.PRIMITIVE_LONG(),
                STREAM_BUILDER.longStream(),
                PRIMITIVE_1D_ARRAY
            ),
            RJArrDimN.CHECK_ARRAY_CLASS(retArrClass, long.class)
        );
    }

    /**
     * <EMBED CLASS=defs DATA-TYPE=double DATA-DEFVAL="-1.0">
     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_PRIM>
     */
    @IntoHTMLTable(background=GreenDither,
        title="Multi-Dimensional Array of Primitive-Doubles")
    @LinkJavaSource(handle="BASIC_TYPES", name="DOUBLE")
    @LinkJavaSource(handle="STREAM_BUILDER", name="doubleStream")
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForDimNArrays")
    public static <T> T doubleArr(
            final JsonArray                 ja,
            final double                    defaultValue,
            final int                       FLAGS,
            final ToDoubleFunction<String>  optionalUserParser,
            final Class<T>                  retArrClass
        )
    {
        return ProcessMultiDimJsonArray.jsonArrayToJava(
            ja,
            // new SettingsRec<Double, DoubleStream>(
            SETTINGS_REC_BUILDER.createForDimNArrays(
                defaultValue,
                FLAGS & NOT_ALLOWED_RET_NULL_MASKS,    
                (optionalUserParser == null) ? null : optionalUserParser::applyAsDouble,
                BASIC_TYPES.PRIMITIVE_DOUBLE(),
                STREAM_BUILDER.doubleStream(),
                PRIMITIVE_1D_ARRAY
            ),
            RJArrDimN.CHECK_ARRAY_CLASS(retArrClass, double.class)
        );
    }

    /**
     * <EMBED CLASS=defs DATA-TYPE=short DATA-DEFVAL="-1">
     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_PRIM>
     */
    @IntoHTMLTable(background=BlueDither,
        title="Multi-Dimensional Array of Primitive Short-Integers")
    @LinkJavaSource(handle="BASIC_TYPES", name="SHORT")
    @LinkJavaSource(handle="STREAM_BUILDER", name="normalStream")
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForDimNArrays")
    public static <T> T shortArr(
            final JsonArray                 ja,
            final short                     defaultValue,
            final int                       FLAGS,
            final ToShortFunction<String>   optionalUserParser,
            final Class<T>                  retArrClass
        )
    {
        return ProcessMultiDimJsonArray.jsonArrayToJava(
            ja,
            // new SettingsRec<Short, Stream<Short>>(
            SETTINGS_REC_BUILDER.createForDimNArrays(
                defaultValue,
                FLAGS & NOT_ALLOWED_RET_NULL_MASKS,    
                (optionalUserParser == null) ? null : optionalUserParser::applyAsShort,
                BASIC_TYPES.BOXED_SHORT(),
                STREAM_BUILDER.normalStream(),
                PRIMITIVE_1D_ARRAY
            ),
            RJArrDimN.CHECK_ARRAY_CLASS(retArrClass, short.class)
        );
    }

    /**
     * <EMBED CLASS=defs DATA-TYPE=byte DATA-DEFVAL="-1">
     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_PRIM>
     */
    @IntoHTMLTable(background=GreenDither,
        title="Multi-Dimensional Array of Primitive-Bytes")
    @LinkJavaSource(handle="BASIC_TYPES", name="BYTE")
    @LinkJavaSource(handle="STREAM_BUILDER", name="normalStream")
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForDimNArrays")
    public static <T> T byteArr(
            final JsonArray                 ja,
            final byte                      defaultValue,
            final int                       FLAGS,
            final ToByteFunction<String>    optionalUserParser,
            final Class<T>                  retArrClass
        )
    {
        return ProcessMultiDimJsonArray.jsonArrayToJava(
            ja,
            // new SettingsRec<Byte, Stream<Byte>>(
            SETTINGS_REC_BUILDER.createForDimNArrays(
                defaultValue,
                FLAGS & NOT_ALLOWED_RET_NULL_MASKS,    
                (optionalUserParser == null) ? null : optionalUserParser::applyAsByte,
                BASIC_TYPES.BOXED_BYTE(),
                STREAM_BUILDER.normalStream(),
                PRIMITIVE_1D_ARRAY
            ),
            RJArrDimN.CHECK_ARRAY_CLASS(retArrClass, byte.class)
        );
    }

    /**
     * <EMBED CLASS=defs DATA-TYPE=float DATA-DEFVAL="-1.0f">
     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_PRIM>
     */
    @IntoHTMLTable(background=BlueDither,
        title="Multi-Dimensional Array of Primitive-Floats")
    @LinkJavaSource(handle="BASIC_TYPES", name="FLOAT")
    @LinkJavaSource(handle="STREAM_BUILDER", name="normalStream")
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForDimNArrays")
    public static <T> T floatArr(
            final JsonArray                 ja,
            final float                     defaultValue,
            final int                       FLAGS,
            final ToFloatFunction<String>   optionalUserParser,
            final Class<T>                  retArrClass
        )
    {
        return ProcessMultiDimJsonArray.jsonArrayToJava(
            ja,
            // new SettingsRec<Float, Stream<Float>>(
            SETTINGS_REC_BUILDER.createForDimNArrays(
                defaultValue,
                FLAGS & NOT_ALLOWED_RET_NULL_MASKS,    
                (optionalUserParser == null) ? null : optionalUserParser::applyAsFloat,
                BASIC_TYPES.BOXED_FLOAT(),
                STREAM_BUILDER.normalStream(),
                PRIMITIVE_1D_ARRAY
            ),
            RJArrDimN.CHECK_ARRAY_CLASS(retArrClass, float.class)
        );
    }

    /**
     * <EMBED CLASS=defs DATA-TYPE=boolean DATA-DEFVAL="false">
     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_PRIM>
     */
    @IntoHTMLTable(background=GreenDither, title="Multi-Dimensional Array of Primitive-Booleans")
    @LinkJavaSource(handle="BASIC_TYPES", name="BOOLEAN")
    @LinkJavaSource(handle="STREAM_BUILDER", name="normalStream")
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForDimNArrays")
    public static <T> T booleanArr(
            final JsonArray         ja,
            final boolean           defaultValue,
            final int               FLAGS,
            final Predicate<String> optionalUserParser,
            final Class<T>          retArrClass
        )
    {
        return ProcessMultiDimJsonArray.jsonArrayToJava(
            ja,
            // new SettingsRec<Boolean, Stream<Boolean>>(
            SETTINGS_REC_BUILDER.createForDimNArrays(
                defaultValue,
                FLAGS & NOT_ALLOWED_RET_NULL_MASKS,    
                (optionalUserParser == null) ? null : optionalUserParser::test,
                BASIC_TYPES.BOXED_BOOLEAN(),
                STREAM_BUILDER.normalStream(),
                PRIMITIVE_1D_ARRAY
            ),
            RJArrDimN.CHECK_ARRAY_CLASS(retArrClass, boolean.class)
        );
    }


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


    /**
     * <EMBED CLASS=defs DATA-A_AN=An DATA-TYPE=Integer DATA-METH_NAME=INTEGER DATA-DEF_VAL="-1">
     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_BOXED>
     */
    @IntoHTMLTable(background=BlueDither, title="Multi-Dimensional Array of Boxed-Integers")
    @LinkJavaSource(handle="BASIC_TYPES", name="INTEGER")
    @LinkJavaSource(handle="STREAM_BUILDER", name="normalStream")
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForDimNArrays")
    public static <T> T arrINTEGER(
            final JsonArray                 ja,
            final int                       defaultValue,
            final int                       FLAGS,
            final Function<String, Integer> optionalUserParser,
            final Class<T>                  retArrClass
        )
    {
        return ProcessMultiDimJsonArray.jsonArrayToJava(
            ja,
            // new SettingsRec<Integer, Stream<Integer>>(
            SETTINGS_REC_BUILDER.createForDimNArrays(
                defaultValue,
                FLAGS,
                optionalUserParser,
                BASIC_TYPES.BOXED_INTEGER(),
                STREAM_BUILDER.normalStream(),
                BOXED_1D_ARRAY
            ),
            RJArrDimN.CHECK_ARRAY_CLASS(retArrClass, Integer.class)
        );
    }

    /**
     * <EMBED CLASS=defs DATA-TYPE=Long DATA-METH_NAME=LONG DATA-DEF_VAL="-1">
     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_BOXED>
     */
    @IntoHTMLTable(background=GreenDither, title="Multi-Dimensional Array of Boxed Long-Integers")
    @LinkJavaSource(handle="BASIC_TYPES", name="LONG")
    @LinkJavaSource(handle="STREAM_BUILDER", name="normalStream")
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForDimNArrays")
    public static <T> T arrLONG(
            final JsonArray                 ja,
            final long                      defaultValue,
            final int                       FLAGS,
            final Function<String, Long>    optionalUserParser,
            final Class<T>                  retArrClass
        )
    {
        return ProcessMultiDimJsonArray.jsonArrayToJava(
            ja,
            // new SettingsRec<Long, Stream<Long>>(
            SETTINGS_REC_BUILDER.createForDimNArrays(
                defaultValue,
                FLAGS,
                optionalUserParser,
                BASIC_TYPES.BOXED_LONG(),
                STREAM_BUILDER.normalStream(),
                BOXED_1D_ARRAY
            ),
            RJArrDimN.CHECK_ARRAY_CLASS(retArrClass, Long.class)
        );
    }

    /**
     * <EMBED CLASS=defs DATA-TYPE=Double DATA-METH_NAME=DOUBLE DATA-DEF_VAL="-1.0">
     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_BOXED>
     */
    @IntoHTMLTable(background=BlueDither, title="Multi-Dimensional Array of Boxed-Doubles")
    @LinkJavaSource(handle="BASIC_TYPES", name="DOUBLE")
    @LinkJavaSource(handle="STREAM_BUILDER", name="normalStream")
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForDimNArrays")
    public static <T> T arrDOUBLE(
            final JsonArray                 ja,
            final double                    defaultValue,
            final int                       FLAGS,
            final Function<String, Double>  optionalUserParser,
            final Class<T>                  retArrClass
        )
    {
        return ProcessMultiDimJsonArray.jsonArrayToJava(
            ja,
            // new SettingsRec<Double, Stream<Double>>(
            SETTINGS_REC_BUILDER.createForDimNArrays(
                defaultValue,
                FLAGS,
                optionalUserParser,
                BASIC_TYPES.BOXED_DOUBLE(),
                STREAM_BUILDER.normalStream(),
                BOXED_1D_ARRAY
            ),
            RJArrDimN.CHECK_ARRAY_CLASS(retArrClass, Double.class)
        );
    }

    /**
     * <EMBED CLASS=defs DATA-TYPE=Short DATA-METH_NAME=SHORT DATA-DEF_VAL="-1">
     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_BOXED>
     */
    @IntoHTMLTable(background=GreenDither, title="Multi-Dimensional Array of Boxed Short-Integers")
    @LinkJavaSource(handle="BASIC_TYPES", name="SHORT")
    @LinkJavaSource(handle="STREAM_BUILDER", name="normalStream")
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForDimNArrays")
    public static <T> T arrSHORT(
            final JsonArray                 ja,
            final short                     defaultValue,
            final int                       FLAGS,
            final Function<String, Short>   optionalUserParser,
            final Class<T>                  retArrClass
        )
    {
        return ProcessMultiDimJsonArray.jsonArrayToJava(
            ja,
            // new SettingsRec<Short, Stream<Short>>(
            SETTINGS_REC_BUILDER.createForDimNArrays(
                defaultValue,
                FLAGS,
                optionalUserParser,
                BASIC_TYPES.BOXED_SHORT(),
                STREAM_BUILDER.normalStream(),
                BOXED_1D_ARRAY
            ),
            RJArrDimN.CHECK_ARRAY_CLASS(retArrClass, Short.class)
        );
    }

    /**
     * <EMBED CLASS=defs DATA-TYPE=Byte DATA-METH_NAME=BYTE DATA-DEF_VAL="-1">
     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_BOXED>
     */
    @IntoHTMLTable(background=BlueDither, title="Multi-Dimensional Array of Boxed-Bytes")
    @LinkJavaSource(handle="BASIC_TYPES", name="BYTE")
    @LinkJavaSource(handle="STREAM_BUILDER", name="normalStream")
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForDimNArrays")
    public static <T> T arrBYTE(
            final JsonArray                 ja,
            final byte                      defaultValue,
            final int                       FLAGS,
            final Function<String, Byte>    optionalUserParser,
            final Class<T>                  retArrClass
        )
    {
        return ProcessMultiDimJsonArray.jsonArrayToJava(
            ja,
            // new SettingsRec<Byte, Stream<Byte>>(
            SETTINGS_REC_BUILDER.createForDimNArrays(
                defaultValue,
                FLAGS,
                optionalUserParser,
                BASIC_TYPES.BOXED_BYTE(),
                STREAM_BUILDER.normalStream(),
                BOXED_1D_ARRAY
            ),
            RJArrDimN.CHECK_ARRAY_CLASS(retArrClass, Byte.class)
        );
    }

    /**
     * <EMBED CLASS=defs DATA-TYPE=Float DATA-METH_NAME=FLOAT DATA-DEF_VAL="-1.0f">
     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_BOXED>
     */
    @IntoHTMLTable(background=GreenDither, title="Multi-Dimensional Array of Boxed-Floats")
    @LinkJavaSource(handle="BASIC_TYPES", name="FLOAT")
    @LinkJavaSource(handle="STREAM_BUILDER", name="normalStream")
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForDimNArrays")
    public static <T> T arrFLOAT(
            final JsonArray                 ja,
            final float                     defaultValue,
            final int                       FLAGS,
            final Function<String, Float>   optionalUserParser,
            final Class<T>                  retArrClass
        )
    {
        return ProcessMultiDimJsonArray.jsonArrayToJava(
            ja,
            // new SettingsRec<Float, Stream<Float>>(
            SETTINGS_REC_BUILDER.createForDimNArrays(
                defaultValue,
                FLAGS,
                optionalUserParser,
                BASIC_TYPES.BOXED_FLOAT(),
                STREAM_BUILDER.normalStream(),
                BOXED_1D_ARRAY
            ),
            RJArrDimN.CHECK_ARRAY_CLASS(retArrClass, Float.class)
        );
    }

    /**
     * <EMBED CLASS=defs DATA-TYPE=Boolean DATA-METH_NAME=BOOLEAN DATA-DEF_VAL=false>
     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_BOXED>
     */
    @IntoHTMLTable(background=BlueDither, title="Multi-Dimensional Array of Boxed-Booleans")
    @LinkJavaSource(handle="BASIC_TYPES", name="BOOLEAN")
    @LinkJavaSource(handle="STREAM_BUILDER", name="normalStream")
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForDimNArrays")
    public static <T> T arrBOOLEAN(
            final JsonArray                 ja,
            final boolean                   defaultValue,
            final int                       FLAGS,
            final Function<String, Boolean> optionalUserParser,
            final Class<T>                  retArrClass
        )
    {
        return ProcessMultiDimJsonArray.jsonArrayToJava(
            ja,
            // new SettingsRec<Boolean, Stream<Boolean>>(
            SETTINGS_REC_BUILDER.createForDimNArrays(
                defaultValue,
                FLAGS,
                optionalUserParser,
                BASIC_TYPES.BOXED_BOOLEAN(),
                STREAM_BUILDER.normalStream(),
                BOXED_1D_ARRAY
            ),
            RJArrDimN.CHECK_ARRAY_CLASS(retArrClass, Boolean.class)
        );
    }

    /**
     * <EMBED CLASS=defs DATA-TYPE=Number DATA-METH_NAME=Number DATA-DEF_VAL=0>
     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_BOXED>
     */
    @IntoHTMLTable(background=GreenDither, title="Multi-Dimensional Array of Best-Fit Boxed-Numbers")
    @LinkJavaSource(handle="BASIC_TYPES", name="NUMBER")
    @LinkJavaSource(handle="STREAM_BUILDER", name="normalStream")
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForDimNArrays")
    public static <T> T arrNumber(
            final JsonArray                 ja,
            final Number                    defaultValue,
            final int                       FLAGS,
            final Function<String, Number>  optionalUserParser,
            final Class<T>                  retArrClass
        )
    {
        return ProcessMultiDimJsonArray.jsonArrayToJava(
            ja,
            // new SettingsRec<Number, Stream<Number>>(
            SETTINGS_REC_BUILDER.createForDimNArrays(
                defaultValue,
                FLAGS,
                optionalUserParser,
                BASIC_TYPES.NUMBER_REC(),
                STREAM_BUILDER.normalStream(),
                BOXED_1D_ARRAY
            ),
            RJArrDimN.CHECK_ARRAY_CLASS(retArrClass, Number.class)
        );
    }


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


    /**
     * <BR>Invokes: {@link ProcessMultiDimJsonArray#jsonArrayToJava(JsonArray, SettingsRec, Class)}
     * <BR>Passes: {@code String} Configurations / SettingsRec
     * <BR>See: Class {@link JFlag} for more information about parameter {@code 'FLAGS'}.
     * <BR>Note: {@code retArrClass} must be a multi-dimensinal {@code String}-array.
     * <BR>:(See last <B>"return-type"</B> parameter in example below)
     * 
     * <BR>COL-SPAN-2:
     * <DIV CLASS=LOC>{@code
     * String[][] arr = ReadArrJSON.DimN.strArr(jsonArray, null, 0, String[][].class);
     * }</DIV>
     */
    @IntoHTMLTable(background=BlueDither, title="Multi-Dimensional Array of Strings")
    @LinkJavaSource(handle="BASIC_TYPES", name="STRING")
    @LinkJavaSource(handle="STREAM_BUILDER", name="normalStream")
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForDimNArrays")
    public static <T> T strArr(
            final JsonArray ja,
            final String    defaultValue,
            final int       FLAGS,
            final Class<T>  retArrClass
        )
    {
        return ProcessMultiDimJsonArray.jsonArrayToJava(
            ja, 
            // new SettingsRec<String, Stream<String>>(
            SETTINGS_REC_BUILDER.createForDimNArrays(
                defaultValue,
                FLAGS,
                null, // no optional user parser, input is supposed to be a string
                BASIC_TYPES.STRING_REC(),
                STREAM_BUILDER.normalStream(),
                REFERENCE_1D_ARRAY
            ),
            RJArrDimN.CHECK_ARRAY_CLASS(retArrClass, String.class)
        );
    }

    /**
     * <BR>Invokes: {@link ProcessMultiDimJsonArray#jsonArrayToJava(JsonArray, SettingsRec, Class)}
     * <BR>Passes: {@code Object} Configurations / SettingsRec
     * <BR>See: class {@link JFlag} for more information about parameter {@code 'FLAGS'}.
     * <BR>Note: {@code retArrClass} must be a multi-dimensinal {@code Object}-array.
     * <BR>:(See last <B>"return-type"</B> parameter in example below)
     * 
     * <BR>COL-SPAN-2:
     * <DIV CLASS=LOC>{@code
     * MyClass[][] arr = ReadArrJSON.DimN.strArr(jsonArray, null, 0, MyClass[][].class);
     * }</DIV>
     */
    @SuppressWarnings({"rawtypes", "unchecked"})
    @IntoHTMLTable(background=GreenDither, title="Multi-Dimensional Array of Object &lt;T&gt;")
    @LinkJavaSource(handle="BASIC_TYPES", name="OBJECT", paramCount=1)
    @LinkJavaSource(handle="STREAM_BUILDER", name="normalStream")
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForDimNArrays")
    public static <RET_ARR_CLASS> RET_ARR_CLASS objArr(
            final JsonArray             ja,
            final Object                defaultValue,
            final int                   FLAGS,
            final Class<RET_ARR_CLASS>  retArrClass
        )
    {
        throw new Torello.Java.ToDoException();

        /*
        Class baseClass = // (Class<U>)
            RJArrDimN.GET_ARRAY_BASE_COMPONENT_CLASS_AND_CHECK
                (retArrClass, defaultValue);

        return ProcessMultiDimJsonArray.jsonArrayToJava(
            ja,
            new SettingsRec /* <T, Stream<T>> * /(
                defaultValue,
                FLAGS,
                optionalUserParser,
                BASIC_TYPES.OBJECT(baseClass),
                STREAM_BUILDER.normalStream(),
                REFERENCE_1D_ARRAY
            ),
            retArrClass
        );
        */
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Two Helpers
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * 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 expectedRootClass 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 retArrClass:
     * If calling retArrClass.isArray() returns FALSE
     * If the root-array type is not the appropriate type for the method that was called
     */
    protected static <T> Class<T> CHECK_ARRAY_CLASS(
            final Class<T> retArrClass,
            final Class<?> expectedRootClass
        )
    {
        Objects.requireNonNull(retArrClass, "Return-Array Type, Parameter 'retArrClass' is null");

        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 (! expectedRootClass.equals(componentClass)) throw new IllegalArgumentException(
            "The class you have passed to parameter 'retArrClass' " +
            "[" + retArrClass.getSimpleName() + "], is not a(n) " +
            expectedRootClass.getSimpleName() + "-array."
        );

        return retArrClass;
    }
}