Package Torello.JSON

Class ParsePrimJSON

  • public class ParsePrimJSON
extends java.lang.Object
    Builds on the J2EE Standard Release JSON Parsing Tools by providing additional help with converting JSON Data into Java Primitive-Types

    This class builds on the J2EE Standard 'Glass-Fish' JSON Processor


    There are several JSON Parsers available, and even more implementations for serializing and de-serializing data to/from JSON. The Glass Fish Tool is included in the J2EE, and is available on GitHub. That is the one used by the Java HTML JAR Library (See: javax.json.* )

    Primary Classes Used: JsonArray and JsonObject

    This comment-note is intentionally repeated, verbatim, at the top of all Json Reader Classes in this package.


    JSON to Java Binding:
    JSON-Binding is the art of converting data that has been stored, saved or transmitted using Java-Script Object Notation into a Java Primitive or Object-Type. JSON can arrive into Java-Program Memory from almost any source. If you are wondering why such a massive amount of "work" is necessary just to convert a Json Integer into Java Integer, the value added is the extraordinary amount of attention paid to user configuration, error checking, & exception messaging. Methods here don't require more than 1 or 2 lines of code, and guarantee that a thorough type checking is performed.

    Unlike Java-Types which are checked by the Java-Compiler each-and-every time a programmer compiles his project, any guarantee that JSON-Type Data is pristine, uncorrupted, and in any kind of pre-agreed format may or may not be assured. The methods here are able to handle changes that might be made to an API (possibly from great distances away, and without the Software-Manager's consent). If an error could occur, configuration flags can be used to determine default error-recovery behaviors. If an exception does throw, the exception messages printed will contain multiple lines of detailed information.

    • Utilizes the Java-Standard javax.json.* Package-Library, & its Glass-Fish Implementation
    • Handles the Transfer & Conversion of All Json-Type's into Java-Type's with just One Line of Code
    • Provides all manner of User-Configurable Exception-Handling & Error-Decision Management via Class JFlag
    • Provides a Fine-Grained Suite of Exception-Classes, all with Consistent & Meaningful Error-Messages. Json Files can occasionally grow extremely large, and error messaging details make debugging easier
    • Primary Helper-Classes for the (Experimental) Google-Chrome Browser Automation Package

    The goal of Torello.JSON is to provide small, static helper methods in the same spirit as java.util.Objects and java.util.Arrays: simple calls that keep JSON handling out of your application logic. Instead of repeating loops, type checks, null checks, and exception wiring at every call site, these methods centralize that work behind a consistent set of straight-forward “read value” operations.


    Reads a single JSON STRING value from a JsonArray or JsonObject and parse it into a Java primitive. with strict type checking.

    This class provides a precise and intentionally strict bridge between loosely-typed JSON data and Java’s fixed-width primitive types. JSON values may be missing, malformed, incorrectly typed, explicitly null, or numerically out of range; Java primitives permit none of these. Every method in this class performs full validation before returning a value.
    If the requested JSON element does not exist, is not of the expected JSON type, represents a JsonNull, or cannot be converted exactly into the requested primitive without loss of information, an exception is thrown with detailed diagnostic context. Fail-fast behavior is intentional: data errors should be detected immediately, not silently propagated.

    The API is deliberately symmetrical and minimal. Each primitive type is supported through two direct-access patterns:



    This class performs no coercion, inference, or structural traversal. It is a low-level, deterministic parsing utility intended for use inside higher-level JSON processing logic where correctness, predictability, and exact numeric fidelity are required.

    Optional User Parser
    All public entry points accept an optionalUserParser parameter. When this argument is non-null, the supplied lambda is invoked on the JSON string value and the standard Java parser is bypassed. This allows callers to support application-specific number formats while still keeping the rest of the validation in this class strict and diagnostic. To ignore this feature, simply pass null and the built-in Integer.parseInt / Long.parseLong / Double.parseDouble / etc. logic is used.

    For example, a payload may represent currency or decorated numbers as strings such as "$499.99", "(-21)", or "#21". A caller can supply a tiny parser that strips the decoration and delegates to Java's normal parsing rules:

    Example:
    // JSON:  { "price": "$499.99" }
double price = ParsePrimJSON.getDouble(
    jo, "price",
    (String s) -> Double.parseDouble(s.substring(1))
);

// JSON:  { "delta": "(-21)" }
int delta = ParsePrimJSON.getInt(
    jo, "delta",
    (String s) -> -Integer.parseInt(s.substring(1, s.length() - 1))
2);


    Note that Chat-GPT wrote this cute little summary-thing. This is a "high level overview" of a class, and the more coding I do in life, the more impossible it becomes to generate English Word explanations for anything.



    Method Parameters

    Parameter Explanation
    ja A JsonArray whose element (at index) is expected to contain a JsonString value to be parsed into a Java primitive.

    These methods are specifically for parsing strings (example: a JSON string like "123") into a Java numeric primitive (or boolean primitive).
    index The zero-based array index of the element being parsed from ja.
    jo A JsonObject whose property value (named propertyName) is expected to contain a JsonString to be parsed into a Java primitive.
    propertyName The name of the JsonObject property to retrieve from jo and parse.
    optionalUserParser A user-supplied parsing function.

    If non-null, this function is used to convert the JsonString content into the target Java boxed value (example: parse an integer from a string).

    This is intended for cases where the default parsing logic is insufficient (special formats, custom numeric rules, locale-sensitive parsing, etc.), or where you simply want to override parsing behavior.


    Single Character:
    Note that this class simply doesn't support any methods for reading a char. This is because their are just entirely too many possibilities, combinations & options for the appropriate "Default Behavior" when attempting to read a single character of data from any random JSON Data-Type.

    Remember that the JSON Specification does not posses any "Single-JSON-Character" Data-Type. Creating some kind of Flag-Controlled Reader for a 'char' that can capably decide what to do would be so overtly verbose, for something so simple, that it isn't worth the effort...
    See Also:
    JsonObject, JsonArray



    Stateless Class:
    This class neither contains any program-state, nor can it be instantiated. The @StaticFunctional Annotation may also be called 'The Spaghetti Report'. Static-Functional classes are, essentially, C-Styled Files, without any constructors or non-static member fields. It is a concept very similar to the Java-Bean's @Stateless Annotation.

    • 1 Constructor(s), 1 declared private, zero-argument constructor
    • 16 Method(s), 16 declared static
    • 0 Field(s)


    • Method Detail

      • parseInt

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static int parseInt​
            (JsonArray ja,
             int index,
             java.util.function.ToIntFunction<java.lang.String> optionalUserParser)
        Extract a JsonString from a JsonArray, and Parse into a Java 'int' Primitive
        Accepts: a JsonArray, along with an array index.
        Flags: Does not accept user configuration flags. Instead, throws all default exceptions on error.
        Returns: A Java int primitive
        See: Method GET(JsonArray, int, Class)
        User-Parser: Parmeter 'optionalUserParser' may be passed 'null'.
          When null, the parameter is ignored; Standard Java parse logic is used.
        Code:
        Exact Method Body:
         final JsonString js = GET(ja, index, int.class);

 try
 {
     return (optionalUserParser != null)
         ? optionalUserParser.applyAsInt(js.getString())
         : Integer.parseInt(js.getString().trim());
 }

 catch (Exception e)
     { throw new JsonStrParseArrException(e, ja, index, js, int.class); }

      • parseLong

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static long parseLong​
            (JsonArray ja,
             int index,
             java.util.function.ToLongFunction<java.lang.String> optionalUserParser)
        Extract a JsonString from a JsonArray, and Parse into a Java 'long' Primitive
        Accepts: a JsonArray, along with an array index.
        Flags: Does not accept user configuration flags. Instead, throws all default exceptions on error.
        Returns: A Java long primitive
        See: Method GET(JsonArray, int, Class)
        User-Parser: Parmeter 'optionalUserParser' may be passed 'null'.
          When null, the parameter is ignored; Standard Java parse logic is used.
        Code:
        Exact Method Body:
         final JsonString js = GET(ja, index, long.class);

 try
 {
     return (optionalUserParser != null)
         ? optionalUserParser.applyAsLong(js.getString())
         : Long.parseLong(js.getString().trim());
 }

 catch (Exception e)
     { throw new JsonStrParseArrException(e, ja, index, js, long.class); }

      • parseShort

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static short parseShort​
            (JsonArray ja,
             int index,
             ToShortFunction<java.lang.String> optionalUserParser)
        Extract a JsonString from a JsonArray, and Parse into a Java 'short' Primitive
        Accepts: a JsonArray, along with an array index.
        Flags: Does not accept user configuration flags. Instead, throws all default exceptions on error.
        Returns: A Java short primitive
        See: Method GET(JsonArray, int, Class)
        User-Parser: Parmeter 'optionalUserParser' may be passed 'null'.
          When null, the parameter is ignored; Standard Java parse logic is used.
        Code:
        Exact Method Body:
         final JsonString js = GET(ja, index, short.class);

 try
 {
     return (optionalUserParser != null)
         ? optionalUserParser.applyAsShort(js.getString())
         : Short.parseShort(js.getString().trim());
 }

 catch (Exception e)
     { throw new JsonStrParseArrException(e, ja, index, js, short.class); }

      • parseByte

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static byte parseByte​
            (JsonArray ja,
             int index,
             ToByteFunction<java.lang.String> optionalUserParser)
        Extract a JsonString from a JsonArray, and Parse into a Java 'byte' Primitive
        Accepts: a JsonArray, along with an array index.
        Flags: Does not accept user configuration flags. Instead, throws all default exceptions on error.
        Returns: A Java byte primitive
        See: Method GET(JsonArray, int, Class)
        User-Parser: Parmeter 'optionalUserParser' may be passed 'null'.
          When null, the parameter is ignored; Standard Java parse logic is used.
        Code:
        Exact Method Body:
         final JsonString js = GET(ja, index, byte.class);

 try
 {
     return (optionalUserParser != null)
         ? optionalUserParser.applyAsByte(js.getString())
         : Byte.parseByte(js.getString().trim());
 }

 catch (Exception e)
     { throw new JsonStrParseArrException(e, ja, index, js, byte.class); }

      • parseDouble

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static double parseDouble​
            (JsonArray ja,
             int index,
             java.util.function.ToDoubleFunction<java.lang.String> optionalUserParser)
        Extract a JsonString from a JsonArray, and Parse into a Java 'double' Primitive
        Accepts: a JsonArray, along with an array index.
        Flags: Does not accept user configuration flags. Instead, throws all default exceptions on error.
        Returns: A Java double primitive
        See: Method GET(JsonArray, int, Class)
        User-Parser: Parmeter 'optionalUserParser' may be passed 'null'.
          When null, the parameter is ignored; Standard Java parse logic is used.
        Code:
        Exact Method Body:
         final JsonString js = GET(ja, index, double.class);

 try
 {
     return (optionalUserParser != null)
         ? optionalUserParser.applyAsDouble(js.getString())
         : Double.parseDouble(js.getString().trim());
 }

 catch (Exception e)
     { throw new JsonStrParseArrException(e, ja, index, js, double.class); }

      • parseFloat

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static float parseFloat​
            (JsonArray ja,
             int index,
             ToFloatFunction<java.lang.String> optionalUserParser)
        Extract a JsonString from a JsonArray, and Parse into a Java 'float' Primitive
        Accepts: a JsonArray, along with an array index.
        Flags: Does not accept user configuration flags. Instead, throws all default exceptions on error.
        Returns: A Java float primitive
        See: Method GET(JsonArray, int, Class)
        User-Parser: Parmeter 'optionalUserParser' may be passed 'null'.
          When null, the parameter is ignored; Standard Java parse logic is used.
        Code:
        Exact Method Body:
         final JsonString js = GET(ja, index, float.class);

 try
 {
     return (optionalUserParser != null)
         ? optionalUserParser.applyAsFloat(js.getString())
         : Float.parseFloat(js.getString().trim());
 }

 catch (Exception e)
     { throw new JsonStrParseArrException(e, ja, index, js, float.class); }

      • parseBoolean

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static boolean parseBoolean​
            (JsonArray ja,
             int index,
             java.util.function.Predicate<java.lang.String> optionalUserParser)
        Extract a JsonString from a JsonArray, and Parse into a Java 'boolean' Primitive
        Accepts: a JsonArray, along with an array index.
        Flags: Does not accept user configuration flags. Instead, throws all default exceptions on error.
        Returns: A Java boolean primitive
        See: Method GET(JsonArray, int, Class)
        User-Parser: Parmeter 'optionalUserParser' may be passed 'null'.
          When null, the parameter is ignored; Standard Java parse logic is used.
        Code:
        Exact Method Body:
         final JsonString js = GET(ja, index, boolean.class);

 try
 {
     return (optionalUserParser != null)
         ? optionalUserParser.test(js.getString())
         : Boolean.parseBoolean(js.getString().trim());
 }

 catch (Exception e)
     { throw new JsonStrParseArrException(e, ja, index, js, boolean.class); }

      • parseInt

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static int parseInt​
            (JsonObject jo,
             java.lang.String propertyName,
             java.util.function.ToIntFunction<java.lang.String> optionalUserParser)
        Extract a JsonString from a JsonObject, and Parse into a Java 'int' Primitive
        Accepts: a JsonObject, along with property name, as a java.lang.String
        Flags: Does not accept user configuration flags. Instead, throws all default exceptions on error.
        Returns: A Java int primitive
        See: Method GET(JsonObject, String, Class)
        User-Parser: Parmeter 'optionalUserParser' may be passed 'null'.
          When null, the parameter is ignored; Standard Java parse logic is used.
        Code:
        Exact Method Body:
         final JsonString js = GET(jo, propertyName, int.class);

 try
 {
     return (optionalUserParser != null)
         ? optionalUserParser.applyAsInt(js.getString())
         : Integer.parseInt(js.getString().trim());
 }

 catch (Exception e)
     { throw new JsonStrParseObjException(e, jo, propertyName, js, int.class); }

      • parseLong

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static long parseLong​
            (JsonObject jo,
             java.lang.String propertyName,
             java.util.function.ToLongFunction<java.lang.String> optionalUserParser)
        Extract a JsonString from a JsonObject, and Parse into a Java 'long' Primitive
        Accepts: a JsonObject, along with property name, as a java.lang.String
        Flags: Does not accept user configuration flags. Instead, throws all default exceptions on error.
        Returns: A Java long primitive
        See: Method GET(JsonObject, String, Class)
        User-Parser: Parmeter 'optionalUserParser' may be passed 'null'.
          When null, the parameter is ignored; Standard Java parse logic is used.
        Code:
        Exact Method Body:
         final JsonString js = GET(jo, propertyName, long.class);

 try
 {
     return (optionalUserParser != null)
         ? optionalUserParser.applyAsLong(js.getString())
         : Long.parseLong(js.getString().trim());
 }

 catch (Exception e)
     { throw new JsonStrParseObjException(e, jo, propertyName, js, long.class); }

      • parseShort

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static short parseShort​
            (JsonObject jo,
             java.lang.String propertyName,
             ToShortFunction<java.lang.String> optionalUserParser)
        Extract a JsonString from a JsonObject, and Parse into a Java 'short' Primitive
        Accepts: a JsonObject, along with property name, as a java.lang.String
        Flags: Does not accept user configuration flags. Instead, throws all default exceptions on error.
        Returns: A Java short primitive
        See: Method GET(JsonObject, String, Class)
        User-Parser: Parmeter 'optionalUserParser' may be passed 'null'.
          When null, the parameter is ignored; Standard Java parse logic is used.
        Code:
        Exact Method Body:
         final JsonString js = GET(jo, propertyName, short.class);

 try
 {
     return (optionalUserParser != null)
         ? optionalUserParser.applyAsShort(js.getString())
         : Short.parseShort(js.getString().trim());
 }

 catch (Exception e)
     { throw new JsonStrParseObjException(e, jo, propertyName, js, short.class); }

      • parseByte

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static byte parseByte​
            (JsonObject jo,
             java.lang.String propertyName,
             ToByteFunction<java.lang.String> optionalUserParser)
        Extract a JsonString from a JsonObject, and Parse into a Java 'byte' Primitive
        Accepts: a JsonObject, along with property name, as a java.lang.String
        Flags: Does not accept user configuration flags. Instead, throws all default exceptions on error.
        Returns: A Java byte primitive
        See: Method GET(JsonObject, String, Class)
        User-Parser: Parmeter 'optionalUserParser' may be passed 'null'.
          When null, the parameter is ignored; Standard Java parse logic is used.
        Code:
        Exact Method Body:
         final JsonString js = GET(jo, propertyName, byte.class);

 try
 {
     return (optionalUserParser != null)
         ? optionalUserParser.applyAsByte(js.getString())
         : Byte.parseByte(js.getString().trim());
 }

 catch (Exception e)
     { throw new JsonStrParseObjException(e, jo, propertyName, js, byte.class); }

      • parseDouble

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static double parseDouble​
            (JsonObject jo,
             java.lang.String propertyName,
             java.util.function.ToDoubleFunction<java.lang.String> optionalUserParser)
        Extract a JsonString from a JsonObject, and Parse into a Java 'double' Primitive
        Accepts: a JsonObject, along with property name, as a java.lang.String
        Flags: Does not accept user configuration flags. Instead, throws all default exceptions on error.
        Returns: A Java double primitive
        See: Method GET(JsonObject, String, Class)
        User-Parser: Parmeter 'optionalUserParser' may be passed 'null'.
          When null, the parameter is ignored; Standard Java parse logic is used.
        Code:
        Exact Method Body:
         final JsonString js = GET(jo, propertyName, double.class);

 try
 {
     return (optionalUserParser != null)
         ? optionalUserParser.applyAsDouble(js.getString())
         : Double.parseDouble(js.getString().trim());
 }

 catch (Exception e)
     { throw new JsonStrParseObjException(e, jo, propertyName, js, double.class); }

      • parseFloat

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static float parseFloat​
            (JsonObject jo,
             java.lang.String propertyName,
             ToFloatFunction<java.lang.String> optionalUserParser)
        Extract a JsonString from a JsonObject, and Parse into a Java 'float' Primitive
        Accepts: a JsonObject, along with property name, as a java.lang.String
        Flags: Does not accept user configuration flags. Instead, throws all default exceptions on error.
        Returns: A Java float primitive
        See: Method GET(JsonObject, String, Class)
        User-Parser: Parmeter 'optionalUserParser' may be passed 'null'.
          When null, the parameter is ignored; Standard Java parse logic is used.
        Code:
        Exact Method Body:
         final JsonString js = GET(jo, propertyName, float.class);

 try
 {
     return (optionalUserParser != null)
         ? optionalUserParser.applyAsFloat(js.getString())
         : Float.parseFloat(js.getString().trim());
 }

 catch (Exception e)
     { throw new JsonStrParseObjException(e, jo, propertyName, js, float.class); }

      • parseBoolean

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static boolean parseBoolean​
            (JsonObject jo,
             java.lang.String propertyName,
             java.util.function.Predicate<java.lang.String> optionalUserParser)
        Extract a JsonString from a JsonObject, and Parse into a Java 'boolean' Primitive
        Accepts: a JsonObject, along with property name, as a java.lang.String
        Flags: Does not accept user configuration flags. Instead, throws all default exceptions on error.
        Returns: A Java boolean primitive
        See: Method GET(JsonObject, String, Class)
        User-Parser: Parmeter 'optionalUserParser' may be passed 'null'.
          When null, the parameter is ignored; Standard Java parse logic is used.
        Code:
        Exact Method Body:
         final JsonString js = GET(jo, propertyName, boolean.class);

 try
 {
     return (optionalUserParser != null)
         ? optionalUserParser.test(js.getString())
         : Boolean.parseBoolean(js.getString().trim());
 }

 catch (Exception e)
     { throw new JsonStrParseObjException(e, jo, propertyName, js, boolean.class); }