Class ReadArrJSON

  • public class ReadArrJSON
extends java.lang.Object
    JSON Binding Helper-Class:
    JSON-Binding is the art of converting data that has been stored, saved or transmitted using Java-Script Object Notation into a Primitive-Type or Object-Type of any Programming Language, for instance Java. JSON often arrives into Java-Program Memory from an external Internet Connection, and may have traveled hundreds or even thousands of miles from a Host-Server.

    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 is never completely assured.

    Being able to handle changes that might be made to an API (possibly from great distances away, and without the Software-Manager's consent) is the type of feature that robust JSON-Code simply has to offer.

    Binding-Helper Features:
    • 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
    • Primary Helper-Classes for the (Experimental) Google-Chrome Headless Browser Package
    Utilities for parsing Json Array's into Java Array's.

    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 tool included in the J2EE is available on GitHub, and that is the one used by the Java HTML JAR Library. (See: javax.json.* )

    Primary Classes Used: JsonArray and JsonObject
    The methods in this class simplify converting a JsonArray into one of the following types:

    • Simple Primitive-Array, such as: int[], double[] or boolean[]
    • Primitive-Stream (Java provides precisely three: IntStream, LongStream and DoubleStream)
    • Stream of Boxed-Primitives: Stream<Integer>, Stream<Boolean> etc...


    Below are some examples of JsonArray's. These arrays are perfectly legal in JSON, but present some problems to Java Programmers. A simple one line invocation follows in the example after this, for parsing these JSON-Arrays into Java-Arrays - without throwing exceptions:

    Java Script Object Notation (JSON):
    {
    "intArr" :          [1, 2, 3, 4, 5],
    "floatArr" :        [1.1, 2.2, 3.3, 4.4, 5.5],

    "intArrSurprise":   ["1", 2, "3", null, 5],
    "floatArrSurprise": ["1.1", 2.2, "3.3", true, 5.5]
}


    In the example code, below, the above JSON is parsed into Java-Arrays:

    Example:
    String          json    = Scrape.scrapePage(new URL("http://some.url.com/some/REST/endpoint"));
StringReader    sr      = new StringReader(json);
JsonObject      jo      = Json.createReader(sr).readObject();

// Simple Parse, without any problems
int[] intArr = ReadArrJSON.intArrToStream
    (jo.getJsonArray("intArr"), -1, 0, null).toArray();

// Simple Parse, without any problems
float[] floatArr = ReadArrJSON.floatArray
    (jo.getJsonArray("floatArr"), -1, 0 null);


// Flag RETURN_PARSE_ON_STR  ==>  Attempt to Parse String's into Integer's
// Flag RETURN_DEFVAL_ON_NULL ==>  Insert a "4" if there are any nulls in the array

int[] intSurprise = ReadArrJSON.intArrToStream(
        jo.getJsonArray("intArrSurprise"),
        4,
        RETURN_PARSE_ON_STR | RETURN_DEFVAL_ON_NULL,
        null
    )
    .toArray();

// Flag RETURN_PARSE_ON_STR  ==>  Attempt to Parse String's into Float's
// Flag RETURN_DEFVAL_ON_WRONG_JSONTYPE  ==>  Insert a "4.4" if there are any problematic types
    
float[] floatSurprise = ReadArrJSON.floatArray(
    jo.getJsonArray("floatArrSurprise"),
    4.4,
    RETURN_PARSE_ON_STR | RETURN_DEFVAL_ON_WRONG_JSONTYPE,
    null
);


    There are also methods provided in this class for generating a Stream<String> or a Stream<Object>.


    Boxed-Primitives & The Java Stream API
    Any java.util.stream.Stream may be easily converted into other types. The example below shows how to convert a Stream<T> into other types of containers, and it is hopefully obvious that 'T' should be substituted by any of the Boxed-Primitive Type's which are used in this class:
    Conversion-Target Stream-Method Invocation
    T[] Stream.toArray(T[]::new);
    List<T> Stream.collect(Collectors.toList());
    Vector<T> Stream.collect(Collectors.toCollection(Vector::new));
    TreeSet<T> Stream.collect(Collectors.toCollection(TreeSet::new));
    Iterator<T> Stream.iterator();


    Primitive Stream's
    Java has three Primitive-Stream types: IntStream, LongStream and DoubleStream. These are also easily converted into array's via the following:
    StreamArray
    IntStreamint[] arr = IntStream.toArray()
    LongStreamlong[] arr = LongStream.toArray()
    DoubleStreamdouble[] arr = DoubleStream.toArray()
    See Also:
    Json, Json, 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
    • 30 Method(s), 30 declared static
    • 7 Field(s), 7 declared static, 7 declared final


    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class
      static class  ReadArrJSON.DimN

    • Method Summary

       
      Stream<String>: Read a JsonArray into a Java Stream<String>
      Modifier and Type Method
      static Stream<String> strArrayToStream​(JsonArray ja, String defaultValue, int FLAGS)
       
      Stream<Object>: Read a JsonArray into a Java Stream<Object>
      Modifier and Type Method
      static <T> Stream<T> objArrayToStream​(JsonArray ja, T defaultValue, int FLAGS, Class<T> returnClass)
       
      Primitive-Stream: Read a JsonArray to a Primitive-Stream (easily converts to an array)
      Modifier and Type Method
      static DoubleStream doubleArrayToStream​(JsonArray ja, double defaultValue, int FLAGS, ToDoubleFunction<String> optionalUserParser)
      static IntStream intArrayToStream​(JsonArray ja, int defaultValue, int FLAGS, ToIntFunction<String> optionalUserParser)
      static LongStream longArrayToStream​(JsonArray ja, long defaultValue, int FLAGS, ToLongFunction<String> optionalUserParser)
       
      Boxed-Primitive Stream: Read a JsonArray into a Java Stream of Boxed-Types
      Modifier and Type Method
      static Stream<Boolean> booleanArrayToBoxedStream​(JsonArray ja, boolean defaultValue, int FLAGS, Function<String,​Boolean> optionalUserParser)
      static Stream<Byte> byteArrayToBoxedStream​(JsonArray ja, byte defaultValue, int FLAGS, Function<String,​Byte> optionalUserParser)
      static Stream<Double> doubleArrayToBoxedStream​(JsonArray ja, double defaultValue, int FLAGS, Function<String,​Double> optionalUserParser)
      static Stream<Float> floatArrayToBoxedStream​(JsonArray ja, float defaultValue, int FLAGS, Function<String,​Float> optionalUserParser)
      static Stream<Integer> integerArrayToBoxedStream​(JsonArray ja, int defaultValue, int FLAGS, Function<String,​Integer> optionalUserParser)
      static Stream<Long> longArrayToBoxedStream​(JsonArray ja, long defaultValue, int FLAGS, Function<String,​Long> optionalUserParser)
      static Stream<Number> numberArrayToBoxedStream​(JsonArray ja, Number defaultValue, int FLAGS, Function<String,​Number> optionalUserParser)
      static Stream<Short> shortArrayToBoxedStream​(JsonArray ja, short defaultValue, int FLAGS, Function<String,​Short> optionalUserParser)
       
      Primitive-Array: Read a JsonArray into a Simple Java (Un-Boxed) Primitive-Array
      Modifier and Type Method
      static boolean[] booleanArray​(JsonArray ja, boolean defaultValue, int FLAGS, Predicate<String> optionalUserParser)
      static byte[] byteArray​(JsonArray ja, byte defaultValue, int FLAGS, ToByteFunction<String> optionalUserParser)
      static float[] floatArray​(JsonArray ja, float defaultValue, int FLAGS, ToFloatFunction<String> optionalUserParser)
      static short[] shortArray​(JsonArray ja, short defaultValue, int FLAGS, ToShortFunction<String> optionalUserParser)
       
      Protected, Internal Methods
      Modifier and Type Method
      protected static <T,​U>
      U      		 boxedStreamToPrimitiveArray​(Stream<T> boxedStream, JsonArray ja, Class<T> returnClass, ObjIntConsumer<T> arrayBuilder, U retArr)
      protected static <T,​U>
      U      		 jsonArrToBoxedStream​(JsonArray ja, Torello.Java.JSON.ReadArrJSON.RECORD<T,​U> rec)
      protected static <T,​U>
      U      		 jsonArrToStream​(JsonArray ja, Torello.Java.JSON.ReadArrJSON.RECORD<T,​U> rec)

      • Methods inherited from class java.lang.Object

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