package Torello.Java.JSON;

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

import java.util.function.Function;

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

/**
 * Builds on the J2EE Standard Release JSON Parsing Tools by providing additional
 * help with converting JSON Data into the Best-Fit
 * <B STYLE='color: red'><CODE>java.lang.Number</CODE></B>
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=GLASS_FISH_NOTE>
 * 
 * @see Json
 * @see JsonObject
 * @see JsonArray
 */
@Torello.JavaDoc.StaticFunctional
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JSON_JDHBI")
public class ReadNumberJSON
{
    // This is a static class.  Has no program state.
    private ReadNumberJSON() { }


    // ********************************************************************************************
    // ********************************************************************************************
    // Number from JsonArray
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Retrieve a {@link JsonArray} element, and transform it to a {@code java.lang.Number}.
     * <EMBED CLASS=defs DATA-JTYPE=JsonNumber DATA-TYPE='java.lang.Number'>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JR_NUMBER>
     * 
     * @param ja            Any instance of {@link JsonArray}
     * @param index         <EMBED CLASS='external-html' DATA-FILE-ID=JR_INDEX_JA>
     * @param throwOnNull   <EMBED CLASS='external-html' DATA-FILE-ID=JR_TON_JA>
     * @return              <EMBED CLASS='external-html' DATA-FILE-ID=JR_RET_TON_JA>
     * 
     * @throws IndexOutOfBoundsException If {@code 'index'} is out of the bounds of {@code 'ja'}
     * @throws JsonTypeArrException      <EMBED CLASS='external-html' DATA-FILE-ID=JR_JTAEX>
     * @throws JsonNullArrException      <EMBED CLASS='external-html' DATA-FILE-ID=JR_JNAEX>
     * 
     * @see JsonValue#getValueType()
     * @see RJInternal#convertToNumber(JsonNumber) 
     */
    public static Number get(JsonArray ja, int index, boolean throwOnNull)
    {
        // This will throw an IndexOutOfBoundsException if the index is out of bounds.
        JsonValue jv = ja.get(index);

        switch (jv.getValueType())
        {
            case NULL:

                // This is simple-stuff (not rocket-science).  "Type Mapping" Code has to worry
                // about what the meaning of "null" should be.

                if (throwOnNull) throw new JsonNullArrException(ja, index, NUMBER, Number.class);
                else return null;

            case NUMBER: return convertToNumber((JsonNumber) jv);

            // The JsonValue at the specified array-index does not contain a JsonString.
            default: throw new JsonTypeArrException(ja, index, NUMBER, jv, Number.class);
        }
    }

    /**
     * Retrieve a {@link JsonArray} element, and transform it to a {@code java.lang.Number}.
     * <EMBED CLASS=defs DATA-TYPE='java.lang.Number' DATA-JTYPE=JsonNumber>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JR_NUMBER>
     * 
     * @param ja            Any instance of {@link JsonArray}
     * @param index         The array index containing the element to retrieve.
     * @param FLAGS         Return-value / exception-throw constants defined in {@link JFlag}
     * @param defaultValue  <EMBED CLASS='external-html' DATA-FILE-ID=JRF_DEFV>
     * @return              <EMBED CLASS='external-html' DATA-FILE-ID=JRF_RET_JA>
     * 
     * @throws IndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=JRF_IOOBEX>
     * @throws JsonNullArrException      <EMBED CLASS='external-html' DATA-FILE-ID=JRF_JNAEX>
     * @throws JsonTypeArrException      <EMBED CLASS='external-html' DATA-FILE-ID=JRF_JTAEX>
     * 
     * @see RJInternal#GET(JsonArray, int, int, Number, Class, Function, Function)
     * @see RJInternal#convertToNumber(JsonNumber)
     */
    public static Number get(JsonArray ja, int index, int FLAGS, Number defaultValue)
    { return GET(ja, index, FLAGS, defaultValue, Number.class, RJInternal::convertToNumber, null); }

    /**
     * Retrieve a {@link JsonArray} element containing a {@link JsonString}, and transform it to a
     * {@code java.lang.Number}, with either a user-provided parser, or the standard java parser
     * 
     * <EMBED CLASS=defs DATA-TYPE='java.lang.Number' DATA-JTYPE=JsonString
     *  DATA-PARSER='new BigDecimal'>
     * 
     * <BR /><BR />If {@code 'parser'} is passed null, the default parser is used, which is just
     * the {@code java.math.BigDecimal} constructor which accepts a {@code String}.  What is done
     * with the parsed {@code BigDecimal} instance is explained below.
     * 
     * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=JR_NUM_PARSE>
     * 
     * @param ja             Any instance of {@link JsonArray}
     * @param index          The array index containing the {@link JsonString} element to retrieve.
     * @param FLAGS          Return-value / exception-throw constants defined in {@link JFlag}
     * @param defaultValue   <EMBED CLASS='external-html' DATA-FILE-ID=JRF_DEFV>
     * @param optionalParser <EMBED CLASS='external-html' DATA-FILE-ID=JRF_PARSER>
     * @return               <EMBED CLASS='external-html' DATA-FILE-ID=JRF_PARSERET_JA>
     * 
     * @throws IndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=JRF_IOOBEX>
     * @throws JsonStrParseArrException  <EMBED CLASS='external-html' DATA-FILE-ID=JRF_JSPAEX>
     * @throws JsonNullArrException      <EMBED CLASS='external-html' DATA-FILE-ID=JRF_JNAEX>
     * @throws JsonTypeArrException      <EMBED CLASS='external-html' DATA-FILE-ID=JRF_JTAEX>
     * 
     * @see RJInternal#PARSE(JsonObject, String, int, Number, Class, Function, Function, Function)
     * @see RJInternal#convertToNumber(String)
     */
    public static Number parse(
            JsonArray ja, int index, int FLAGS, Number defaultValue,
            Function<String, Number> optionalParser
        )
    {
        return PARSE(
            ja, index, FLAGS, defaultValue, Number.class, optionalParser,
            RJInternal::convertToNumber, null  /* Not Needed, convertToNumber won't throw */
        );
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Number from JsonObject
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Extract a {@link JsonObject} property, and transform it to a {@code java.lang.Number}.
     * <EMBED CLASS=defs DATA-TYPE='java.lang.Number' DATA-JTYPE=JsonNumber>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JR_NUMBER>
     * 
     * @param jo            Any instance of {@link JsonObject}.
     * @param propertyName  <EMBED CLASS='external-html' DATA-FILE-ID=JR_PN_JO>
     * @param isOptional    <EMBED CLASS='external-html' DATA-FILE-ID=JR_ISOPT_JO>
     * @param throwOnNull   <EMBED CLASS='external-html' DATA-FILE-ID=JR_TON_JO>
     * @return              <EMBED CLASS='external-html' DATA-FILE-ID=JR_RET_TON_JO>
     * 
     * @throws JsonPropMissingException <EMBED CLASS='external-html' DATA-FILE-ID=JR_JPMEX>
     * @throws JsonTypeObjException     <EMBED CLASS='external-html' DATA-FILE-ID=JR_JTOEX>
     * @throws JsonNullObjException     <EMBED CLASS='external-html' DATA-FILE-ID=JR_JNOEX>
     * 
     * @see JsonValue#getValueType()
     * @see RJInternal#convertToNumber(JsonNumber)
     */
    public static Number get
        (JsonObject jo, String propertyName, boolean isOptional, boolean throwOnNull)
    {
        if (! jo.containsKey(propertyName))
        {
            if (isOptional) return null;
            else throw new JsonPropMissingException(jo, propertyName, NUMBER, Number.class);
        }

        JsonValue jv = jo.get(propertyName);

        switch (jv.getValueType())
        {
            case NULL:

                // This is simple-stuff (not rocket-science).  "Type Mapping" Code has to worry
                // about what the meaning of "null" should be.

                if (throwOnNull) throw new JsonNullObjException
                    (jo, propertyName, NUMBER, Number.class);

                else return null;

            case NUMBER: return convertToNumber((JsonNumber) jv);

            // The JsonObject propertydoes not contain a JsonNumber.
            default: throw new JsonTypeObjException
                (jo, propertyName, NUMBER, jv, Number.class);
        }
    }

    /**
     * Retrieve a {@link JsonObject} property, and transform it to a {@code java.lang.Number}.
     * <EMBED CLASS=defs DATA-TYPE='java.lang.Number' DATA-JTYPE=JsonNumber>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JR_NUMBER>
     * 
     * @param jo            Any instance of {@link JsonObject}
     * @param propertyName  <EMBED CLASS='external-html' DATA-FILE-ID=JR_PN_JO>
     * @param FLAGS         Return-value / exception-throw constants defined in {@link JFlag}
     * @param defaultValue  <EMBED CLASS='external-html' DATA-FILE-ID=JRF_DEFV>
     * @return              <EMBED CLASS='external-html' DATA-FILE-ID=JRF_RET_JO>
     * 
     * @throws JsonPropMissingException <EMBED CLASS='external-html' DATA-FILE-ID=JRF_JPMEX>
     * @throws JsonNullObjException     <EMBED CLASS='external-html' DATA-FILE-ID=JRF_JNOEX>
     * @throws JsonTypeObjException     <EMBED CLASS='external-html' DATA-FILE-ID=JRF_JTOEX>
     * 
     * @see RJInternal#GET(JsonObject, String, int, Number, Class, Function, Function)
     * @see RJInternal#convertToNumber(JsonNumber)
     */
    public static Number get
        (JsonObject jo, String propertyName, int FLAGS, Number defaultValue)
    {
        return GET
            (jo, propertyName, FLAGS, defaultValue, Number.class, RJInternal::convertToNumber, null);
    }

    /**
     * Retrieve a {@link JsonObject} property containing a {@link JsonString}, and transform it to
     * a {@code java.lang.Number}, with either a user-provided parser, or the standard java
     * parser
     * 
     * <EMBED CLASS=defs DATA-TYPE='java.lang.Number' DATA-JTYPE=JsonString
     *  DATA-PARSER='new BigDecimal'>
     * 
     * <BR /><BR />If {@code 'parser'} is passed null, the default parser is used, which is just
     * the {@code java.math.BigDecimal} constructor which accepts a {@code String}.  What is done
     * with the parsed {@code BigDecimal} instance is explained below.
     * 
     * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=JR_NUM_PARSE>
     * 
     * @param jo             Any instance of {@link JsonObject}
     * @param propertyName   <EMBED CLASS='external-html' DATA-FILE-ID=JR_PN_JO>
     * @param FLAGS          Return-value / exception-throw constants defined in {@link JFlag}
     * @param defaultValue   <EMBED CLASS='external-html' DATA-FILE-ID=JRF_DEFV>
     * @param optionalParser <EMBED CLASS='external-html' DATA-FILE-ID=JRF_PARSER>
     * @return               <EMBED CLASS='external-html' DATA-FILE-ID=JRF_PARSERET_JO>
     * 
     * @throws JsonPropMissingException <EMBED CLASS='external-html' DATA-FILE-ID=JRF_JPMEX>
     * @throws JsonStrParseObjException <EMBED CLASS='external-html' DATA-FILE-ID=JRF_JSPOEX>
     * @throws JsonNullObjException     <EMBED CLASS='external-html' DATA-FILE-ID=JRF_JNOEX>
     * @throws JsonTypeObjException     <EMBED CLASS='external-html' DATA-FILE-ID=JRF_JTOEX>
     * 
     * @see RJInternal#PARSE(JsonObject, String, int, Number, Class, Function, Function, Function)
     * @see RJInternal#convertToNumber(String)
     */
    public static Number parse(
            JsonObject jo, String propertyName, int FLAGS, Number defaultValue,
            Function<String, Number> optionalParser
        )
    {
        return PARSE(
            jo, propertyName, FLAGS, defaultValue, Number.class, optionalParser,
            RJInternal::convertToNumber, null /* Not Needed, convertToNumber won't throw */
        );
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Number from JsonString Parse  **OR**  from JsonNumber
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS=defs DATA-TYPE=Number DATA-PARSER='new BigDecimal'>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JRXL_DESC_JA>
     * 
     * @param ja             Any {@link JsonArray}
     * @param i              Any index into the {@code JsonArray}
     * @param FLAGS          Return-value / exception-throw constants defined in {@link JFlag}
     * @param defaultValue   <EMBED CLASS='external-html' DATA-FILE-ID=JRXL_DEFVAL>
     * @param optionalParser <EMBED CLASS='external-html' DATA-FILE-ID=JRXL_PARSER>
     * @return               <EMBED CLASS='external-html' DATA-FILE-ID=JRXL_RET_JA>
     * 
     * @throws IndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=JRF_IOOBEX>
     * @throws JsonStrParseArrException  <EMBED CLASS='external-html' DATA-FILE-ID=JRXL_JSPAEX>
     * @throws JsonNullArrException      <EMBED CLASS='external-html' DATA-FILE-ID=JRXL_JNAEX>
     * @throws JsonTypeArrException      <EMBED CLASS='external-html' DATA-FILE-ID=JRXL_JTAEX>
     * 
     * @see #get(JsonArray, int, int, Number)
     * @see #parse(JsonArray, int, int, Number, Function)
     */
    public static Number get(
            JsonArray ja, int i, int FLAGS, Number defaultValue,
            Function<String, Number> optionalParser
        )
    {
        JsonValue.ValueType t;

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

    /**
     * <EMBED CLASS=defs DATA-TYPE=Number DATA-PARSER='new BigDecimal'>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JRXL_DESC_JO>
     * 
     * @param jo             Any {@link JsonObject}
     * @param propertyName   Any of the properties defined in the {@code JsonObject}
     * @param FLAGS          Return-value / exception-throw constants defined in {@link JFlag}
     * @param defaultValue   <EMBED CLASS='external-html' DATA-FILE-ID=JRXL_DEFVAL>
     * @param optionalParser <EMBED CLASS='external-html' DATA-FILE-ID=JRXL_PARSER>
     * @return               <EMBED CLASS='external-html' DATA-FILE-ID=JRXL_RET_JO>
     * 
     * @throws JsonPropMissingException <EMBED CLASS='external-html' DATA-FILE-ID=JRF_JPMEX>
     * @throws JsonStrParseObjException <EMBED CLASS='external-html' DATA-FILE-ID=JRXL_JSPOEX>
     * @throws JsonNullObjException     <EMBED CLASS='external-html' DATA-FILE-ID=JRXL_JNOEX>
     * @throws JsonTypeObjException     <EMBED CLASS='external-html' DATA-FILE-ID=JRXL_JTOEX>
     * 
     * @see #get(JsonObject, String, int, Number)
     * @see #parse(JsonObject, String, int, Number, Function)
     */
    public static Number get(
                JsonObject jo, String propertyName, int FLAGS, Number defaultValue,
                Function<String, Number> optionalParser
            )
    {
        JsonValue.ValueType t;

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