package Torello.Java.JSON;

import Torello.JavaDoc.StaticFunctional;
import Torello.JavaDoc.LinkJavaSource;
import Torello.JavaDoc.JDHeaderBackgroundImg;

import Torello.Java.Function.IntIntTConsumer;

import javax.json.Json;
import javax.json.JsonArray;
import javax.json.JsonString;
import javax.json.JsonObject;

import java.util.function.Consumer;
import java.util.function.Function;

/**
 * Utilities for parsing Json Array's and sending the parsed values into a Java Consumer
 * Functional-Interface.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=GLASS_FISH_NOTE>
 * <EMBED CLASS='external-html' DATA-FILE-ID=RJA_INTO_CONS>
 * <EMBED CLASS='external-html' DATA-FILE-ID=JSON_BINDING_NOTE>
 *
 * @see Json
 * @see JsonArray
 */
@StaticFunctional
@JDHeaderBackgroundImg(EmbedTagFileID="RJA_JDHBI_CONS")
public class RJArrIntoConsumer
{
    private RJArrIntoConsumer() { }

    /**
     * Converts a {@link JsonArray} into a {@code Stream<T>}.  It is important to remember that
     * the package {@code Torello.Java.JSON} does not attempt to generate Java-Type's or their
     * Constructors.  The 'Type' of the {@code Stream<T>} that is returned by this method (the
     * value of {@code 'T'}) must be an Object-Class that contains a Constructor that accepts a
     * {@code JsonObject} as input.
     * 
     * <BR /><BR />This package does not perform the type of Auto-Type-Generation that is done by
     * Lombok or Jackson.
     * 
     * @param <T> This is the 'type' of the array being built.  If there were a class, for example,
     * named {@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 the class
     * that has been specified by Type-Parameter {@code 'T'}
     * 
     * @param defaultValue When used in conjunction with {@code 'FLAGS'}, this default-value may be
     * inserted into the output-array when error-cases occur while interpreting the array contents.
     * 
     * @param FLAGS Optional flags.  See {@link JFlag} for details.
     * 
     * @param consumerClass The {@code java.lang.Class} of the {@code Consumer}-Type
     * currently being used.
     */
    @LinkJavaSource(handle="BASIC_TYPES", name="OBJECT", paramCount=1)
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForConsumers")
    public static <T> void objArr(
            final JsonArray     ja,
            final T             defaultValue,
            final int           FLAGS,
            final Class<T>      consumerClass,
            final Consumer<T>   c
        )
    {
        ProcessJsonArray.objToJava(
            ja,
            // new SettingsRec<T, Void>
            SETTINGS_REC_BUILDER.createForConsumers
                (defaultValue, FLAGS, null, c, BASIC_TYPES.OBJECT(consumerClass))
        );
    }

    /**
     * Idential to {@link #objArr(JsonArray, Object, int, Class, Consumer)}, except this
     * method-overload variant allows a user to provide just about any Lambda-Function to produce
     * the instance of {@code 'returnClass'}.  This alleviates the requirement to only build 
     * objects which contain a constructor that accepts a {@link JsonObject}), and instead allows
     * <B><I>any</I></B> object to be constructed, so long as a Builder-Lambda
     * ({@code 'objBuilder'}) is provided
     * 
     * @param objBuilder This should be any Lambda-Functionthat accepts a {@link JsonObject}, and
     * produces an instance of {@code Class<T>}.
     */
    @LinkJavaSource(handle="BASIC_TYPES", name="OBJECT", paramCount=2)
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForConsumers")
    public static <T> void objArr(
            final JsonArray                 ja,
            final T                         defaultValue,
            final int                       FLAGS,
            final Function<JsonObject, T>   objBuilder,
            final Class<T>                  consumerClass,
            final Consumer<T>               c
        )
    {
        ProcessJsonArray.objToJava(
            ja,
            // new SettingsRec<T, Void>
            SETTINGS_REC_BUILDER.createForConsumers
                (defaultValue, FLAGS, null, c, BASIC_TYPES.OBJECT(objBuilder, consumerClass))
        );
    }

    /**
     * Iterates a {@link JsonArray} and passes the retrieved values to a User-Provided Consumer
     * 
     * @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.
     */
    @LinkJavaSource(handle="BASIC_TYPES", name="STRING_REC")
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForConsumers")
    public static void strArray(
            final JsonArray         ja, 
            final String            defaultValue,
            final int               FLAGS,
            final Consumer<String>  c
        )
    {
        ProcessJsonArray.strToJava(
            ja,
            // new SettingsRec<String, Void>
            SETTINGS_REC_BUILDER.createForConsumers
                (defaultValue, FLAGS, null, c, BASIC_TYPES.STRING_REC())
        );
    }




    // ********************************************************************************************
    // ********************************************************************************************
    // IntIntTConsumer Variant
    // ********************************************************************************************
    // ********************************************************************************************




    /**
     * Converts a {@link JsonArray} into a {@code Stream<T>}.  It is important to remember that
     * the package {@code Torello.Java.JSON} does not attempt to generate Java-Type's or their
     * Constructors.  The 'Type' of the {@code Stream<T>} that is returned by this method (the
     * value of {@code 'T'}) must be an Object-Class that contains a Constructor that accepts a
     * {@code JsonObject} as input.
     * 
     * <BR /><BR />This package does not perform the type of Auto-Type-Generation that is done by
     * Lombok or Jackson.
     * 
     * @param <T> This is the 'type' of the array being built.  If there were a class, for example,
     * named {@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 the class
     * that has been specified by Type-Parameter {@code 'T'}
     * 
     * @param defaultValue When used in conjunction with {@code 'FLAGS'}, this default-value may be
     * inserted into the output-array when error-cases occur while interpreting the array contents.
     * 
     * @param FLAGS Optional flags.  See {@link JFlag} for details.
     * 
     * @param consumerClass The {@code java.lang.Class} of the {@code IntIntTConsumer}-Type
     * currently being used.
     */
    @LinkJavaSource(handle="BASIC_TYPES", name="OBJECT", paramCount=1)
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForConsumers")
    public static <T> void objArr2(
            final JsonArray             ja,
            final T                     defaultValue,
            final int                   FLAGS,
            final Class<T>              consumerClass,
            final IntIntTConsumer<T>    c
        )
    {
        ProcessJsonArray.objToJava(
            ja,
            // new SettingsRec<T, Void>
            SETTINGS_REC_BUILDER.createForIIConsumers
                (defaultValue, FLAGS, null, c, BASIC_TYPES.OBJECT(consumerClass))
        );
    }

    /**
     * Idential to {@link #objArr2(JsonArray, Object, int, Class, IntIntTConsumer)}, except this
     * method-overload variant allows a user to provide just about any Lambda-Function to produce
     * the instance of {@code 'returnClass'}.  This alleviates the requirement to only build 
     * objects which contain a constructor that accepts a {@link JsonObject}), and instead allows
     * <B><I>any</I></B> object to be constructed, so long as a Builder-Lambda
     * ({@code 'objBuilder'}) is provided
     * 
     * @param objBuilder This should be any Lambda-Functionthat accepts a {@link JsonObject}, and
     * produces an instance of {@code Class<T>}.
     */
    @LinkJavaSource(handle="BASIC_TYPES", name="OBJECT", paramCount=2)
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForConsumers")
    public static <T> void objArr2(
            final JsonArray                 ja,
            final T                         defaultValue,
            final int                       FLAGS,
            final Function<JsonObject, T>   objBuilder,
            final Class<T>                  consumerClass,
            final IntIntTConsumer<T>        c
        )
    {
        ProcessJsonArray.objToJava(
            ja,
            // new SettingsRec<T, Void>
            SETTINGS_REC_BUILDER.createForIIConsumers
                (defaultValue, FLAGS, null, c, BASIC_TYPES.OBJECT(objBuilder, consumerClass))
        );
    }

    /**
     * Iterates a {@link JsonArray} and passes the retrieved values to a User-Provided Consumer
     * 
     * @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.
     */
    @LinkJavaSource(handle="BASIC_TYPES", name="STRING_REC")
    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForConsumers")
    public static void strArray2(
            final JsonArray                 ja, 
            final String                    defaultValue,
            final int                       FLAGS,
            final IntIntTConsumer<String>   c
        )
    {
        ProcessJsonArray.strToJava(
            ja,
            // new SettingsRec<String, Void>
            SETTINGS_REC_BUILDER.createForIIConsumers
                (defaultValue, FLAGS, null, c, BASIC_TYPES.STRING_REC())
        );
    }


}