Package Torello.JSON

Class ReadPrimJSON

  • public class ReadPrimJSON
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 NUMBER or TRUE/FALSE value from a JsonArray or JsonObject and converts it into a Java primitive with strict type checking.

    This class provides a small, focused set of one-line helpers for extracting JSON values and converting them into Java primitive types. JSON data is loosely typed and may contain unexpected value kinds, missing properties, or explicit Json-Null values; Java primitives do not permit null and they require exact, well-defined conversions.

    Each method in this class performs thorough validation before returning a primitive result. When the JSON value is missing, is present but of the wrong JSON type, is Json-Null, or cannot be converted exactly (for example, a number that does not fit into the requested primitive width), this class throws an exception with detailed, diagnostic messaging. The intent is to catch data mistakes immediately and make failures obvious and actionable while traversing large or evolving JSON documents.

    The API is intentionally symmetrical: for each supported primitive there is a JsonArray overload (index-based) and a JsonObject overload (property-name-based). This class is deliberately low-level and strict: it reads primitives directly from JsonNumber and JsonValue TRUE/FALSE, and does not attempt higher-level binding or inference.


    Method Parameters

    Parameter Explanation
    ja A JsonArray whose element (at index) is being converted into a Java primitive value.
    index The zero-based array index of the element being read from ja.
    jo A JsonObject whose property value (named propertyName) is being converted into a Java primitive value.
    propertyName The name of the JsonObject property to retrieve from jo.


    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

      • getInt

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static int getInt​(JsonArray ja,
                         int index)
        Extract a JsonNumber from a JsonArray, and Transform it to 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)
        See Also:
        GET(JsonArray, int, Class), JsonNumber.intValueExact()
        Code:
        Exact Method Body:
         final JsonNumber jn = GET(ja, index, int.class);

 try
     { return jn.intValueExact(); }

 catch (ArithmeticException ae)
     { throw new JsonArithmeticArrException(ae, ja, index, NUMBER, jn, int.class); }

      • getLong

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static long getLong​(JsonArray ja,
                           int index)
        Extract a JsonNumber from a JsonArray, and Transform it to 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)
        See Also:
        GET(JsonArray, int, Class), JsonNumber.longValueExact()
        Code:
        Exact Method Body:
         final JsonNumber jn = GET(ja, index, long.class);

 try
     { return jn.longValueExact(); }

 catch (ArithmeticException ae)
     { throw new JsonArithmeticArrException(ae, ja, index, NUMBER, jn, long.class); }

      • getDouble

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static double getDouble​(JsonArray ja,
                               int index)
        Extract a JsonNumber from a JsonArray, and Transform it to 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)
        See Also:
        GET(JsonArray, int, Class), RJInternal.DOUBLE_WITH_CHECK(BigDecimal)
        Code:
        Exact Method Body:
         final JsonNumber jn = GET(ja, index, double.class);

 try
     { return RJInternal.DOUBLE_WITH_CHECK(jn.bigDecimalValue()); }

 catch (ArithmeticException ae)
     { throw new JsonArithmeticArrException(ae, ja, index, NUMBER, jn, double.class); }

      • getFloat

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static float getFloat​(JsonArray ja,
                             int index)
        Extract a JsonNumber from a JsonArray, and Transform it to 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)
        See Also:
        GET(JsonArray, int, Class), RJInternal.FLOAT_WITH_CHECK(BigDecimal)
        Code:
        Exact Method Body:
         final JsonNumber jn = GET(ja, index, float.class);

 try
     { return RJInternal.FLOAT_WITH_CHECK(jn.bigDecimalValue()); }

 catch (ArithmeticException ae)
     { throw new JsonArithmeticArrException(ae, ja, index, NUMBER, jn, float.class); }

      • getBoolean

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static boolean getBoolean​(JsonArray ja,
                                 int index)
        Extract Json-True or False from a JsonArray, and Transform it to 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
        Code:
        Exact Method Body:
         final JsonValue jv = ja.get(index);

 switch (jv.getValueType()) // throws IOB if necessary
 {
     case NULL: throw new JsonNullPrimitiveArrException
         (ja, index, TRUE, boolean.class);

     case TRUE:  return true;
     case FALSE: return false;

     default: throw new JsonTypeArrException
         (ja, index, TRUE, jv, boolean.class);
 }

      • getInt

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static int getInt​(JsonObject jo,
                         java.lang.String propertyName)
        Extract a JsonNumber from a JsonObject, and Transform it to 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)
        See Also:
        GET(JsonObject, String, Class), JsonNumber.intValueExact()
        Code:
        Exact Method Body:
         final JsonNumber jn = GET(jo, propertyName, int.class);

 try
     { return jn.intValueExact(); }

 catch (ArithmeticException ae)
     { throw new JsonArithmeticObjException(ae, jo, propertyName, NUMBER, jn, int.class); }

      • getLong

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static long getLong​(JsonObject jo,
                           java.lang.String propertyName)
        Extract a JsonNumber from a JsonObject, and Transform it to 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)
        See Also:
        GET(JsonObject, String, Class), JsonNumber.longValueExact()
        Code:
        Exact Method Body:
         final JsonNumber jn = GET(jo, propertyName, long.class);

 try
     { return jn.longValueExact(); }

 catch (ArithmeticException ae)
     { throw new JsonArithmeticObjException(ae, jo, propertyName, NUMBER, jn, long.class); }

      • getShort

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static short getShort​(JsonObject jo,
                             java.lang.String propertyName)
        Extract a JsonNumber from a JsonObject, and Transform it to 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)
        See Also:
        GET(JsonObject, String, Class), JsonNumber.longValueExact(), RJInternal.SHORT_FROM_LONG(long)
        Code:
        Exact Method Body:
         final JsonNumber jn = GET(jo, propertyName, short.class);

 try
     { return RJInternal.SHORT_FROM_LONG(jn.longValueExact()); }

 catch (ArithmeticException ae)
 {
     throw new JsonArithmeticObjException(ae, jo, propertyName, NUMBER, jn, short.class);
 }

      • getByte

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static byte getByte​(JsonObject jo,
                           java.lang.String propertyName)
        Extract a JsonNumber from a JsonObject, and Transform it to 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)
        See Also:
        GET(JsonObject, String, Class), JsonNumber.longValueExact(), RJInternal.BYTE_FROM_LONG(long)
        Code:
        Exact Method Body:
         final JsonNumber jn = GET(jo, propertyName, byte.class);

 try
     { return RJInternal.BYTE_FROM_LONG(jn.longValueExact()); }

 catch (ArithmeticException ae)
     { throw new JsonArithmeticObjException(ae, jo, propertyName, NUMBER, jn, byte.class); }

      • getDouble

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static double getDouble​(JsonObject jo,
                               java.lang.String propertyName)
        Extract a JsonNumber from a JsonObject, and Transform it to 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)
        See Also:
        GET(JsonObject, String, Class), RJInternal.DOUBLE_WITH_CHECK(BigDecimal)
        Code:
        Exact Method Body:
         final JsonNumber jn = GET(jo, propertyName, double.class);

 try
     { return RJInternal.DOUBLE_WITH_CHECK(jn.bigDecimalValue()); }

 catch (ArithmeticException ae)
 {
     throw new JsonArithmeticObjException(ae, jo, propertyName, NUMBER, jn, double.class);
 }

      • getFloat

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static float getFloat​(JsonObject jo,
                             java.lang.String propertyName)
        Extract a JsonNumber from a JsonObject, and Transform it to 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)
        See Also:
        GET(JsonObject, String, Class), RJInternal.FLOAT_WITH_CHECK(BigDecimal)
        Code:
        Exact Method Body:
         final JsonNumber jn = GET(jo, propertyName, float.class);

 try
     { return RJInternal.FLOAT_WITH_CHECK(jn.bigDecimalValue()); }

 catch (ArithmeticException ae)
 {
     throw new JsonArithmeticObjException(ae, jo, propertyName, NUMBER, jn, float.class);
 }

      • getBoolean

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static boolean getBoolean​(JsonObject jo,
                                 java.lang.String propertyName)
        Extract Json-True or False from a JsonObject, and Transform it to 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 Primitive boolean primitive
        Code:
        Exact Method Body:
         if (! jo.containsKey(propertyName)) throw new JsonPropMissingException
     (jo, propertyName, TRUE, boolean.class);

 final JsonValue jv = jo.get(propertyName);

 switch (jv.getValueType())
 {
     case NULL: throw new JsonNullPrimitiveObjException
         (jo, propertyName, TRUE, boolean.class);

     case TRUE:  return true;
     case FALSE: return false;

     default: throw new JsonTypeObjException
         (jo, propertyName, TRUE, jv, boolean.class);
 }

      • GET

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        protected static <T> JsonNumber GET​(JsonObject jo,
                                    java.lang.String propertyName,
                                    java.lang.Class<T> primitiveClass)
        This is an internal helper method for retrieving a property from a JsonObject, and converting it to one of the standard Java Types.
        Parameters:
        jo - Any instance of JsonObject
        propertyName - Any property name contained by 'jo'
        primitiveClass - Used for exception-reporting only. This is the final expect Java Primitive Type that will ultimately be returned to the user. It is passed as a convenience field when the null-primitive exception is thrown.
        Returns:
        The extracted JsonNumber.
        Throws:
        JsonNullPrimitiveObjException - If the specified property contains Json-Null
        JsonPropMissingException - If the property is missing, and 'isOptional' is FALSE.
        JsonTypeObjException - If the user specified property doesn't contain a JsonNumber
        JsonArithmeticObjException - If there any arithmetic problems during the conversion
        See Also:
        getInt(JsonObject, String), getLong(JsonObject, String), getShort(JsonObject, String), getByte(JsonObject, String), getDouble(JsonObject, String), getFloat(JsonObject, String)
        Code:
        Exact Method Body:
         // Here, a 'get' request was made for a property that isn't actually listed among the
 // properties in the provided JsonObject.  Since this internal 'GET' is used by methods
 // that are trying to return a Java Primitive (like 'int' or 'float'), then an exception
 // has to be thrown.  The option of returning 'null' isn't possible here!
    
 if (! jo.containsKey(propertyName)) throw new JsonPropMissingException
     (jo, propertyName, NUMBER, primitiveClass);

 final JsonValue jv = jo.get(propertyName);

 switch (jv.getValueType())
 {
     case NULL: throw new JsonNullPrimitiveObjException
         (jo, propertyName, NUMBER, primitiveClass);

     case NUMBER: return (JsonNumber) jv;

     // The JsonObject property does not contain a JsonNumber.
     default: throw new JsonTypeObjException
         (jo, propertyName, NUMBER, jv, primitiveClass);
 }