Package Torello.JSON

Class ReadJSON

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

    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.


    ReadJSON: Readers for Non-Primitive JSON Values

    ReadJSON is a static helper class dedicated to reading the non-primitive JSON value types handled by the Java-HTML JSON package. Unlike the boxed-primitive and primitive readers, this class focuses on higher-level JSON structures and user-defined object construction.

    This class exists specifically to handle the other JSON-mappable types: String, JsonArray, JsonObject, and user-provided object types (<T>).

    All numeric values, booleans, and primitive conversions are intentionally excluded from this class and are handled by the boxed-primitive and primitive reader classes elsewhere in the package.

    For user-defined types (<T>), the standard methods in this class expect the target type to expose a constructor that accepts a single JsonObject. This allows JSON-backed domain objects to be built in a direct, explicit, and predictable manner.

    This design keeps object construction visible and local, rather than hidden behind reflection, annotations, or automatic binding rules.


    Design Intent:
    ReadJSON is intentionally narrow in scope. It does not perform automatic binding, reflection-based mapping, or annotation processing. It reads exactly one JSON value, enforces the expected structure, and either returns the requested type or fails immediately with a descriptive error.

    Together with the primitive and boxed-primitive readers, this class completes the full set of JSON value handling needed by the Java-HTML JSON package — while keeping each concern isolated, explicit, and easy to reason about.


    POJO De-Serialization:
    The methods that appear to de-serialize a JSON-Object into a standard Java-Object do not automatically generate a Java-Type based solely on the properties present within a JsonObject. Automatic type-creation (as exists in libraries such as 'Lombok') is not a feature offered by this package. These methods can reduce quite a bit of the work needed to convert Json into Java by offering methods which extact JsonValue's using just a single line of code.

    The methods in this class which return or emit a user-provided Parameterized-Type <T> require the user specify a means for constructing instances of 'T'. This class expects one of the two cases:

    • User-Provided Type <T> has a single argument constructor which accepts a JsonObject as a parameter. In this case, standard Java Reflection is used to retrieve and extract this constructor.

    • A Java Functional-Interface / Lambda be provided that accepts a JsonObject and returns an instance of User-Provided Type <T>. Building or generating an instance of <T> is acheived, simply, by invoking this function with the JsonObject which was extracted from the array.
    See Also:
    Json, 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
    • 14 Method(s), 14 declared static
    • 0 Field(s)


    • Method Summary

       
      Object <T>: Retrieve a JsonObject and transform it to a POJO, using the POJO's Constructor
      Modifier and Type Method
      static <T> T getObject​(JsonArray ja, int index, Class<T> c, boolean throwOnNull)
      static <T> T getObject​(JsonObject jo, String propertyName, Class<T> c, boolean isOptional, boolean throwOnNull)
       
      Object <T>: Retrieve a JsonObject and transform it to a POJO, with a User-Provided Builder-Function
      Modifier and Type Method
      static <T> T getObject​(JsonArray ja, int index, Function<JsonObject,​? extends T> builderFunction, Class<T> c, boolean throwOnNull)
      static <T> T getObject​(JsonObject jo, String propertyName, Function<JsonObject,​? extends T> builderFunction, Class<T> c, boolean isOptional, boolean throwOnNull)
       
      Object <T>: Transform a JsonObject to a POJO, using the POJO's Constructor
      Modifier and Type Method
      static <T> T getObject​(JsonObject jo, Class<T> c)
       
      String: Retrieve a JsonString and Transform it to a Java String
      Modifier and Type Method
      static String getString​(JsonArray ja, int index, boolean throwOnNull)
      static String getString​(JsonObject jo, String propertyName, boolean isOptional, boolean throwOnNull)
       
      JsonObject: Retrieve a JsonObject
      Modifier and Type Method
      static JsonObject getJsonObject​(JsonArray ja, int index, boolean throwOnNull)
      static JsonObject getJsonObject​(JsonObject jo, String propertyName, boolean isOptional, boolean throwOnNull)
       
      JsonArray: Retrieve a JsonArray
      Modifier and Type Method
      static JsonArray getJsonArray​(JsonArray ja, int index, boolean throwOnNull)
      static JsonArray getJsonArray​(JsonObject jo, String propertyName, boolean isOptional, boolean throwOnNull)

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • getObject

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static <T> T getObject​(JsonArray ja,
                              int index,
                              java.lang.Class<T> c,
                              boolean throwOnNull)
        Retrieve a JsonArray element, and transform it to a Java Object (POJO).
        Type Parameters:
        T - This is the Java-Type to which the JsonObject is going to be bound / transformed.

        It is important to note that this method is not as smart as you might think. The Java-Type instance that is being created / instantiated must contain a consructor that accepts a JsonObject as a parameter in order to do the actual bindng. specifically, whatever class is passed to type parameter 'T', that class must have a single-parameter constructor whose parameter-type is JsonObject
        Parameters:
        ja - Any instance of JsonArray
        index - A valid index into 'ja'
        c - This is the class that will bind to the JsonObject parameter 'jo'.

        The class 'c' must have a constructor that accepts a JsonObject. If this class doesn't have such a constructor, then a JsonBindingException throws.
        throwOnNull - When TRUE is passed to this parameter, if the JsonObject property named 'propertyName' evaluates to Json-Null, then this method will throw a JsonNullObjException. When this parameter is FALSE, if the specified property contains Json-Null, then Java-Null is returned.
        Returns:
        An instance of Java-Type Type Parameter T, if the 'ja' array element located at 'index' uses the appropriate Json-Type - JsonObject.

        If the specified array element contains Json-Null, and 'throwOnNull' has been passed FALSE, then Java-Null is returned. If the element is null, and 'throwOnNull' is TRUE, then a JsonNullArrException throws.
        Throws:
        java.lang.IndexOutOfBoundsException - If 'index' is out of bounds of 'ja'
        java.lang.NullPointerException - If either 'c' or 'ja' are passed null
        InvalidClassException - Throws if a User-Provided class
        JsonTypeArrException - If the array-element (specified by 'index') does not actually contain a JsonObject (but rather, some other non-null Json-Type), then this exception throws.
        JsonNullArrException - If the JsonArray element specified by 'index' contains a Json-Null, and TRUE has been passed to 'throwOnNull'
        JsonBuildPOJOArrException - Throws if the JsonObject property specified by 'propertyName' cannot be instantiated into a Java POJO.

        If this method is using a constructor, then failing to retrieve or execute the constructor will cause this exception to be thrown. If this method is executing a User Provided Build-Function, and the function throws, then that exception will be wrapped into this one's 'cause' and re-thrown.
        Code:
        Exact Method Body:
         final JsonValue         jv      = NPE_CHECK_JA(ja).get(index);
 final Constructor<T>    ctor    = InvalidClassException.check(c);

 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, OBJECT, c);
         else                return null;

     case OBJECT:
         try 
             { return ctor.newInstance((JsonObject) jv); }

         catch (Exception e)
             { throw new JsonBuildPOJOArrException(e, ja, index, (JsonObject) jv, c); }

     // The JsonValue at the specified array-index does not contain a JsonObject.
     default: throw new JsonTypeArrException(ja, index, OBJECT, jv, c);
 }

      • getObject

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static <T> T getObject​(JsonObject jo,
                              java.lang.String propertyName,
                              java.lang.Class<T> c,
                              boolean isOptional,
                              boolean throwOnNull)
        Extract a JsonObject property, and transform it to a Java Object (POJO).
        Type Parameters:
        T - This is the Java-Type to which the JsonObject is going to be bound / transformed.

        It is important to note that this method is not as smart as you might think. The Java-Type instance that is being created / instantiated must contain a consructor that accepts a JsonObject as a parameter in order to do the actual bindng. specifically, whatever class is passed to type parameter 'T', that class must have a single-parameter constructor whose parameter-type is JsonObject
        Parameters:
        jo - Any instance of JsonObject.
        propertyName - Any property name contained by 'jo'
        isOptional - When TRUE is passed, if 'propertyName' is not actually listed in 'jo' this method shall return Java-Null gracefully. When FALSE is passed, if 'jo' does not have the specified property, a JsonPropMissingException will throw.

        If 'jo' actually has a property named 'propertyName', then the value passed to this parameter is fully irrelevant.
        throwOnNull - When TRUE is passed to this parameter, if the JsonArray element located at 'index' contains Json-Null, then this method will throw a JsonNullArrException. When this parameter is FALSE, if the specified array element contains Json-Null, then Java-Null is returned.
        Returns:
        An instance of Java-Type Type Parameter T', if the 'propertyName' is available inside 'jo', and that property uses the appropriate Json-Type - JsonObject.

        If the specified property contains Json-Null, and 'throwOnNull' has been passed FALSE, then Java-Null is returned. If the property is null, and 'throwOnNull' is TRUE, then a JsonNullObjException throws.

        If the specified property is simply missing, Java-Null is returned, unless 'isOptional' has been passed FALSE - in which case a JsonPropMissingException shall be thrown.
        Throws:
        JsonPropMissingException - This exception shall throw if the specified property is missing from the 'JsonObject' (parameter 'jo'). This exception throw can be avoided if 'TRUE' is passed to parameter 'isOptional'.
        java.lang.NullPointerException - If 'jo', 'propertyName' or 'c' are null
        InvalidClassException - Throws if a User-Provided class
        JsonTypeObjException - If the property (specified by 'propertyName') is extracted, but that property does not actually contain a JsonObject (but rather, some other non-null Json-Type), then this exception throws.
        JsonNullObjException - If the JsonObject property specified by 'propertyName' contains a Json-Null, and TRUE has been passed to 'throwOnNull'
        JsonBuildPOJOObjException - Throws if the JsonObject located at 'index' cannot be instantiated into a Java POJO.

        If this method is using a constructor, then failing to retrieve or execute the constructor will cause this exception to be thrown. If this method is executing a User Provided Build-Function, and the function throws, then that exception will be wrapped into this one's 'cause' and re-thrown.
        Code:
        Exact Method Body:
         final JsonValue         jv      = NPE_CHECK_JO(jo, propertyName);
 final Constructor<T>    ctor    = InvalidClassException.check(c);

 if (jv == null)
 {
     if (isOptional) return null;
     throw new JsonPropMissingException(jo, propertyName, OBJECT, c);
 }

 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, OBJECT, c);
         else                return null;

     case OBJECT:
         try 
             { return ctor.newInstance(jo); }

         catch (Exception e)
         {
             throw new JsonBuildPOJOObjException
                 (e, jo, propertyName, (JsonObject) jv, c);
         }

         // The JsonObject propertydoes not contain a JsonObject.
     default: throw new JsonTypeObjException(jo, propertyName, OBJECT, jv, c);
 }

      • getObject

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static <T> T getObject​
            (JsonArray ja,
             int index,
             java.util.function.Function<JsonObject,​? extends T> builderFunction,
             java.lang.Class<T> c,
             boolean throwOnNull)
        Reads one JsonObject from a JsonArray, and uses a Generator Function to build a POJO
        Identical To: Method ​ getObject()
        Primary Difference: Accepts a User-Provided "Builder" or "Generator" Function, rather a using a class constructor.
        See that method's documentation for throws and parameters explanation
        Code:
        Exact Method Body:
         final JsonValue jv = NPE_CHECK_JA(ja).get(index);

 switch (jv.getValueType())
 {
     case NULL:
         if (throwOnNull)    throw new JsonNullArrException(ja, index, OBJECT, c);
         else                return null;

     case OBJECT:
         try 
             { return builderFunction.apply((JsonObject) jv); }

         catch (Exception e)
             { throw new JsonBuildPOJOArrException(e, ja, index, (JsonObject) jv, c); }

     default: throw new JsonTypeArrException(ja, index, OBJECT, jv, c);
 }

      • getObject

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static <T> T getObject​
            (JsonObject jo,
             java.lang.String propertyName,
             java.util.function.Function<JsonObject,​? extends T> builderFunction,
             java.lang.Class<T> c,
             boolean isOptional,
             boolean throwOnNull)
        Reads one JsonObject from a JsonArray, and uses a Generator Function to build a POJO
        Identical To: Method ​ getObject()
        Primary Difference: Accepts a User-Provided "Builder" or "Generator" Function, rather a using a class constructor.
        See that method's documentation for throws and parameters explanation
        Code:
        Exact Method Body:
         final JsonValue jv = NPE_CHECK_JO(jo, propertyName);

 if (jv == null)
 {
     if (isOptional) return null;
     throw new JsonPropMissingException(jo, propertyName, OBJECT, c);
 }

 switch (jv.getValueType())
 {
     case NULL:
         if (throwOnNull)    throw new JsonNullObjException(jo, propertyName, OBJECT, c);
         else                return null;

     case OBJECT:
         try 
             { return builderFunction.apply((JsonObject) jv); }

         catch (Exception e)
         {
             throw new JsonBuildPOJOObjException
                 (e, jo, propertyName, (JsonObject) jv, c);
         }

     default: throw new JsonTypeObjException(jo, propertyName, OBJECT, jv, c);
 }

      • getObject

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static <T> T getObject​(JsonObject jo,
                              java.lang.Class<T> c)
        This class contains a lot of the reason / impetus for writing 'ReadJSON'. This does converts a JsonObject into a Java-Object. The actual binding must be implemented by the programmer - because the class-type that is passed to this method (parameter 'c') must have a constructor accepting this JsonObject.

        No Auto-Mapping:
        This method makes no effort to figure out which JsonObject properties should be bound to the POJO Object fields! Note, however, that all of the other one-line type conversion methods in this class is exactly why writing such a constuctor for your Java-Type's should be much easier.

        That really is the point of this JSON Package.
        Type Parameters:
        T - This is the Java-Type to which the JsonObject is going to be bound / transformed.

        It is important to note that this method is not as smart as you might think. The Java-Type instance that is being created / instantiated must contain a consructor that accepts a JsonObject as a parameter in order to do the actual bindng. specifically, whatever class is passed to type parameter 'T', that class must have a single-parameter constructor whose parameter-type is JsonObject
        Parameters:
        jo - This may be any JsonObject which can be bound to 'c'.
        c - This is the class that will bind to the JsonObject parameter 'jo'.

        The class 'c' must have a constructor that accepts a JsonObject. If this class doesn't have such a constructor, then a JsonBindingException throws.
        Returns:
        An instance of the class 'T', which is specified by 'c'
        Throws:
        JsonException - If any of the Java reflection-operations throw exceptions, those exceptions are wrapped into a JsonException instance, and then re-thrown with the original exception assigned to the Throwable.cause. Class JsonException is an unchecked / Runtime exception, while many of the cause exceptions are not. The possible cause exceptions are listed below.

        Description copied from: java.lang.Constructor.newInstance(Object... args), JDK 1.8
        ExceptionJDK Explanation
        IllegalAccessException if this Constructor object is enforcing Java language access control and the underlying constructor is inaccessible.
        IllegalArgumentException if the number of actual and formal parameters differ; if an unwrapping conversion for primitive arguments fails; or if, after possible unwrapping, a parameter value cannot be converted to the corresponding formal parameter type by a method invocation conversion; if this constructor pertains to an enum type.
        InstantiationException if the class that declares the underlying constructor represents an abstract class.
        InvocationTargetException if the underlying constructor throws an exception.
        ExceptionInInitializerError if the initialization provoked by this method fails.
        java.lang.NullPointerException - If 'jo' or 'c' are passed null
        InvalidClassException - Throws if a valid, single-argument, 'JsonObject' constructor is not present or is not accessible within 'c'
        Code:
        Exact Method Body:
         Objects.requireNonNull(jo, "You have passed null to Class Parameter 'jo'");
 Objects.requireNonNull(c, "You have passed null to Class Parameter 'c'");

 final Constructor<T> ctor = InvalidClassException.check(c);

 try
     { return ctor.newInstance(jo); }

 catch (Exception e)
 {
     // *MANY* possible Exception's may be thrown, and *ALL* are checked exceptions
     throw new JsonException(
         "Unable to instantiate class: [" + c.getName() + "] using provided " +
             "Java-Object\n" +
         "See Exception.getCause() for details.",
         e
     );
 }

      • getString

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.lang.String getString​(JsonArray ja,
                                         int index,
                                         boolean throwOnNull)
        Retrieve a JsonArray element, and transform it to a java.lang.String.
        Parameters:
        ja - Any instance of JsonArray
        index - A valid index into 'ja'
        throwOnNull - When TRUE is passed to this parameter, if the JsonObject property named 'propertyName' evaluates to Json-Null, then this method will throw a JsonNullObjException. When this parameter is FALSE, if the specified property contains Json-Null, then Java-Null is returned.
        Returns:
        An instance of Java-Type java.lang.String, if the 'ja' array element located at 'index' uses the appropriate Json-Type - JsonString.

        If the specified array element contains Json-Null, and 'throwOnNull' has been passed FALSE, then Java-Null is returned. If the element is null, and 'throwOnNull' is TRUE, then a JsonNullArrException throws.
        Throws:
        java.lang.IndexOutOfBoundsException - If 'index' is out of the bounds of 'ja'
        JsonTypeArrException - If the array-element (specified by 'index') does not actually contain a JsonString (but rather, some other non-null Json-Type), then this exception throws.
        JsonNullArrException - If the JsonArray element specified by 'index' contains a Json-Null, and TRUE has been passed to 'throwOnNull'
        java.lang.NullPointerException - If 'ja' is passed null.
        See Also:
        JsonValue.getValueType(), JsonValue.ValueType.STRING
        Code:
        Exact Method Body:
         // This will also throw an IndexOutOfBoundsException if the index is out of bounds.
 final JsonValue jv = NPE_CHECK_JA(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, STRING, String.class);
         else return null;

     case STRING: return ((JsonString) jv).getString();

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

      • getString

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.lang.String getString​(JsonObject jo,
                                         java.lang.String propertyName,
                                         boolean isOptional,
                                         boolean throwOnNull)
        Extract a JsonObject property, and transform it to a java.lang.String.
        Parameters:
        jo - Any instance of JsonObject.
        propertyName - Any property name contained by 'jo'
        isOptional - When TRUE is passed, if 'propertyName' is not actually listed in 'jo' this method shall return Java-Null gracefully. When FALSE is passed, if 'jo' does not have the specified property, a JsonPropMissingException will throw.

        If 'jo' actually has a property named 'propertyName', then the value passed to this parameter is fully irrelevant.
        throwOnNull - When TRUE is passed to this parameter, if the JsonArray element located at 'index' contains Json-Null, then this method will throw a JsonNullArrException. When this parameter is FALSE, if the specified array element contains Json-Null, then Java-Null is returned.
        Returns:
        An instance of Java-Type java.lang.String', if the 'propertyName' is available inside 'jo', and that property uses the appropriate Json-Type - JsonString.

        If the specified property contains Json-Null, and 'throwOnNull' has been passed FALSE, then Java-Null is returned. If the property is null, and 'throwOnNull' is TRUE, then a JsonNullObjException throws.

        If the specified property is simply missing, Java-Null is returned, unless 'isOptional' has been passed FALSE - in which case a JsonPropMissingException shall be thrown.
        Throws:
        JsonPropMissingException - This exception shall throw if the specified property is missing from the 'JsonObject' (parameter 'jo'). This exception throw can be avoided if 'TRUE' is passed to parameter 'isOptional'.
        JsonTypeObjException - If the property (specified by 'propertyName') is extracted, but that property does not actually contain a JsonString (but rather, some other non-null Json-Type), then this exception throws.
        JsonNullObjException - If the JsonObject property specified by 'propertyName' contains a Json-Null, and TRUE has been passed to 'throwOnNull'
        java.lang.NullPointerException - if either 'jo' or 'propertyName' are null
        See Also:
        JsonValue.getValueType(), JsonValue.ValueType.STRING
        Code:
        Exact Method Body:
         final JsonValue jv = NPE_CHECK_JO(jo, propertyName);

 if (jv == null)
 {
     if (isOptional) return null;
     throw new JsonPropMissingException(jo, propertyName, STRING, String.class);
 }

 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, STRING, String.class);

         else return null;

     case STRING: return ((JsonString) jv).getString();

     // The JsonObject propertydoes not contain a JsonString.
     default: throw new JsonTypeObjException(jo, propertyName, STRING, jv, String.class);
 }

      • getJsonObject

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static JsonObject getJsonObject​(JsonArray ja,
                                       int index,
                                       boolean throwOnNull)
        Extract an instance of JsonObject from an instance of JsonArray.
        Parameters:
        ja - Any instance of JsonArray
        index - A valid index into 'ja'
        throwOnNull - When TRUE is passed to this parameter, if the JsonObject property named 'propertyName' evaluates to Json-Null, then this method will throw a JsonNullObjException. When this parameter is FALSE, if the specified property contains Json-Null, then Java-Null is returned.
        Returns:
        The requested JsonObject, or null (only if null's have been permitted).
        Throws:
        java.lang.IndexOutOfBoundsException - If 'index' is out of bounds of 'ja'
        JsonTypeArrException - If the array-element (specified by 'index') does not actually contain a JsonObject (but rather, some other non-null Json-Type), then this exception throws.
        JsonNullArrException - If the JsonArray element specified by 'index' contains a Json-Null, and TRUE has been passed to 'throwOnNull'
        java.lang.NullPointerException - If 'ja' is passed null
        See Also:
        JsonValue.getValueType(), JsonValue.ValueType.OBJECT
        Code:
        Exact Method Body:
         // This will also throw an IndexOutOfBoundsException if the index is out of bounds.
 final JsonValue jv = NPE_CHECK_JA(ja).get(index);

 switch (jv.getValueType())
 {
     case NULL:
         if (throwOnNull)
             throw new JsonNullArrException(ja, index, OBJECT, JsonObject.class);
         else
             return null;

     case OBJECT: return (JsonObject) jv;

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

      • getJsonObject

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static JsonObject getJsonObject​(JsonObject jo,
                                       java.lang.String propertyName,
                                       boolean isOptional,
                                       boolean throwOnNull)
        Extract an instance of JsonObject from an instance of JsonObject.
        Parameters:
        jo - Any instance of JsonObject.
        propertyName - Name of the JSON property that should be contained within 'jo'
        isOptional - When TRUE is passed, if 'propertyName' is not actually listed in 'jo' this method shall return Java-Null gracefully. When FALSE is passed, if 'jo' does not have the specified property, a JsonPropMissingException will throw.

        If 'jo' actually has a property named 'propertyName', then the value passed to this parameter is fully irrelevant.
        throwOnNull - When TRUE is passed to this parameter, if the JsonArray element located at 'index' contains Json-Null, then this method will throw a JsonNullArrException. When this parameter is FALSE, if the specified array element contains Json-Null, then Java-Null is returned.
        Returns:
        The requested JsonObject, or null (only if null's have been permitted).
        Throws:
        JsonPropMissingException - This exception shall throw if the specified property is missing from the 'JsonObject' (parameter 'jo'). This exception throw can be avoided if 'TRUE' is passed to parameter 'isOptional'.
        JsonTypeObjException - If the property (specified by 'propertyName') is extracted, but that property does not actually contain a JsonObject (but rather, some other non-null Json-Type), then this exception throws.
        JsonNullObjException - If the JsonObject property specified by 'propertyName' contains a Json-Null, and TRUE has been passed to 'throwOnNull'
        java.lang.NullPointerException - if either 'jo' or 'propertyName' are null
        See Also:
        JsonValue.getValueType(), JsonValue.ValueType.OBJECT
        Code:
        Exact Method Body:
         final JsonValue jv = NPE_CHECK_JO(jo, propertyName);

 if (jv == null)
 {
     if (isOptional) return null;
     throw new JsonPropMissingException(jo, propertyName, OBJECT, JsonObject.class);
 }

 switch (jv.getValueType())
 {
     case NULL:
         if (throwOnNull)
             throw new JsonNullObjException(jo, propertyName, OBJECT, JsonObject.class);
         else
             return null;

     case OBJECT: return (JsonObject) jv;

     // The JsonValue at the specified property does not contain a JsonObject.
     default:
         throw new JsonTypeObjException(jo, propertyName, OBJECT, jv, JsonObject.class);
 }

      • getJsonArray

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static JsonArray getJsonArray​(JsonArray ja,
                                     int index,
                                     boolean throwOnNull)
        Extract an instance of JsonArray from an instance of JsonArray.
        Parameters:
        ja - Any instance of JsonArray
        index - A valid index into 'ja'
        throwOnNull - When TRUE is passed to this parameter, if the JsonObject property named 'propertyName' evaluates to Json-Null, then this method will throw a JsonNullObjException. When this parameter is FALSE, if the specified property contains Json-Null, then Java-Null is returned.
        Returns:
        The requested JsonArray, or null (only if null's have been permitted).
        Throws:
        java.lang.IndexOutOfBoundsException - If 'index' is out of bounds of 'ja'
        JsonTypeArrException - If the array-element (specified by 'index') does not actually contain a JsonArray (but rather, some other non-null Json-Type), then this exception throws.
        JsonNullArrException - If the JsonArray element specified by 'index' contains a Json-Null, and TRUE has been passed to 'throwOnNull'
        java.lang.NullPointerException - if 'ja' is passed null
        See Also:
        JsonValue.getValueType(), JsonValue.ValueType.ARRAY
        Code:
        Exact Method Body:
         // This will also throw an IndexOutOfBoundsException if the index is out of bounds.
 final JsonValue jv = NPE_CHECK_JA(ja).get(index);

 switch (jv.getValueType())
 {
     case NULL:
         if (throwOnNull)
             throw new JsonNullArrException(ja, index, ARRAY, JsonArray.class);
         else
             return null;

     case ARRAY: return (JsonArray) jv;

     // The JsonValue at the specified property does not contain a JsonArray.
     default: throw new JsonTypeArrException(ja, index, ARRAY, jv, JsonArray.class);
 }

      • getJsonArray

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public static JsonArray getJsonArray​(JsonObject jo,
                                     java.lang.String propertyName,
                                     boolean isOptional,
                                     boolean throwOnNull)
        Extract an instance of JsonArray from an instance of JsonObject.
        Parameters:
        jo - Any instance of JsonObject.
        propertyName - Name of the JSON property that should be contained within 'jo'
        isOptional - When TRUE is passed, if 'propertyName' is not actually listed in 'jo' this method shall return Java-Null gracefully. When FALSE is passed, if 'jo' does not have the specified property, a JsonPropMissingException will throw.

        If 'jo' actually has a property named 'propertyName', then the value passed to this parameter is fully irrelevant.
        throwOnNull - When TRUE is passed to this parameter, if the JsonArray element located at 'index' contains Json-Null, then this method will throw a JsonNullArrException. When this parameter is FALSE, if the specified array element contains Json-Null, then Java-Null is returned.
        Returns:
        The requested JsonArray, or null (only if null's have been permitted).
        Throws:
        JsonPropMissingException - This exception shall throw if the specified property is missing from the 'JsonObject' (parameter 'jo'). This exception throw can be avoided if 'TRUE' is passed to parameter 'isOptional'.
        JsonTypeObjException - If the property (specified by 'propertyName') is extracted, but that property does not actually contain a JsonArray (but rather, some other non-null Json-Type), then this exception throws.
        JsonNullObjException - If the JsonObject property specified by 'propertyName' contains a Json-Null, and TRUE has been passed to 'throwOnNull'
        java.lang.NullPointerException - if either 'jo' or 'propertyName' are null
        See Also:
        JsonValue.getValueType(), JsonValue.ValueType.ARRAY
        Code:
        Exact Method Body:
         final JsonValue jv = NPE_CHECK_JO(jo, propertyName);

 if (jv == null)
 {
     if (isOptional) return null;
     throw new JsonPropMissingException(jo, propertyName, ARRAY, JsonArray.class);
 }

 switch (jv.getValueType())
 {
     case NULL:
         if (throwOnNull)
             throw new JsonNullObjException(jo, propertyName, ARRAY, JsonArray.class);
         else
             return null;

     case ARRAY: return (JsonArray) jv;

     // The JsonValue at the specified property does not contain a JsonArray.
     default:
         throw new JsonTypeObjException(jo, propertyName, ARRAY, jv, JsonArray.class);
 }