Class RJArrIntoBoxedStream

  • public class RJArrIntoBoxedStream
extends java.lang.Object
    Each of the methods in this class, all of which are declared 'static', accept a standard JsonArray as input, and make a (User-Specified) "Best Efforts" attempt to convert each of these elements into a Boxed-Primitive Type. Once transformed, the computed & extracted values are then sent to a Java-Stream whose Generic-Type is comprised of the relevant Boxed-Type.

    Just to serve as a reminder, a Java 'Boxed Primitive' structure is nearly identical to a regular primitive value, save for the following differences:

    • Boxed Primitive's are wrapped in an (artificial) Object-Reference, and may be passed-by-reference, no different than any othe Java Object-Reference. (In reality they are variant of 'Value-Classes', and their wrappers do not actually exists)

    • Boxed-Types may be assigned null, and will not force NullPointerException to throw when they are assigned null - nor produce any other adverse or unintended issues..

    • Boxed-Types have several Class-Member functions to which their values may be applied


    Each Json-Array Element that is successfully converted into a Boxed-Value (or null) is subsequently used as input with a Java-Stream 'Stream.Builder<T>.accept(T t)' method. Note that the Generic-Type 'T' will be identical to (or a parent of) the Json-Array Method-Type that was selected (when this method was actually invoked).

    This class is capable of processing 7 of the 8 Java Boxed-Types that are available. The standard type 'java.lang.Character' is not accomodated by any of the Json Array-Processing Classes in this Json-Package. For each method in this class, the user is expected to provide a single JsonArray.
    Utilities for parsing Json Array's and sending the parsed values into a Java Strea of Boxed-Primitives.

    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

    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


    Optimize Loops:
    For each method within this class, there are actually two different variants of what is, essentially, the exact same method. Methods in this class whose name ends with the letters 'Rec' are methods that will produce what is known as a 'Settings Record', (see class SettingsRec<T, U>).

    Every one of the Json-Processing classes (in this Json Java-Package) that begin with the letters 'RJArr' are classes which iterate JsonArray's. First, the class does some form of processing and testing to ensure that the contents of the arrays are properly converted into standard Java-Types. After the elements of a JsonArray are successfully processed, they are then sent to either a Java-Array, a Stream or a User-Provided Consumer.

    In order to guarantee that there is a homogenous algorithm for processing these array indices, only four Java 'for-loops' have actually been written. (These loops may be easily inspected by clicking on the 'Hi-Lited Source-Code' button inside of class ProcessJsonArray). In this class, in order to differentiate between a JsonArray which is to be converted into a Java int[]-Array, and one which is to be placed into a Java long[]-Array, a particular "Settings Record" is constructed (which "configures" the loop's body).

    If only one invocation of a method is needed, then using the method that ends with 'Arr' should be perfectly sufficient! If the methods in this class are going to be invoked from inside of a loop (or invoked many times), then it would be much wiser to, first, obtain an instance of the SettingsRec, and then invoke the Array-Processing code yourself.

    In this way, generating twice as many short-lived, ephemeral, object instances (that are immediately discarded, and then collected by the Garbage-Collector) can be avoided. To do this is quite simple. Please review the documentation for the methods in this class whose name ends with 'Rec' - and look at the example code provided for how to use them.

    The Loop Optimized variants of the methods in this class are, very simple, two step procedures (as opposed to just a single method invocation).

    1. First, generate an instance of the SettingsRec class. Make sure to heed to Generic-Type Parameters returned by the Settings-Record Generator-Method you have called.

    2. Second, simply call the specified Json-Array Processing method from class ProcessJsonArray
    See Also:
    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
    • 16 Method(s), 16 declared static
    • 0 Field(s)


    • Method Summary

       
      Read the Contents of a Json-Array into a Java-Stream of Boxed-Primitives
      Modifier and Type Method
      static Stream<Boolean> booleanArr​(JsonArray ja, boolean defaultValue, int FLAGS, Function<String,​Boolean> optionalUserParser)
      static Stream<Byte> byteArr​(JsonArray ja, byte defaultValue, int FLAGS, Function<String,​Byte> optionalUserParser)
      static Stream<Double> doubleArr​(JsonArray ja, double defaultValue, int FLAGS, Function<String,​Double> optionalUserParser)
      static Stream<Float> floatArr​(JsonArray ja, float defaultValue, int FLAGS, Function<String,​Float> optionalUserParser)
      static Stream<Integer> intArr​(JsonArray ja, int defaultValue, int FLAGS, Function<String,​Integer> optionalUserParser)
      static Stream<Long> longArr​(JsonArray ja, long defaultValue, int FLAGS, Function<String,​Long> optionalUserParser)
      static Stream<Number> numberArr​(JsonArray ja, Number defaultValue, int FLAGS, Function<String,​Number> optionalUserParser)
      static Stream<Short> shortArr​(JsonArray ja, short defaultValue, int FLAGS, Function<String,​Short> optionalUserParser)
       
      Loop Optimization: Generate a Reusable SettingsRec Instance
      Modifier and Type Method
      static SettingsRec<Boolean,
           ​Stream<Boolean>>      		 booleanRec​(boolean defaultValue, int FLAGS, Function<String,​Boolean> optionalUserParser)
      static SettingsRec<Byte,
           ​Stream<Byte>>      		 byteRec​(byte defaultValue, int FLAGS, Function<String,​Byte> optionalUserParser)
      static SettingsRec<Double,
           ​Stream<Double>>      		 doubleRec​(double defaultValue, int FLAGS, Function<String,​Double> optionalUserParser)
      static SettingsRec<Float,
           ​Stream<Float>>      		 floatRec​(float defaultValue, int FLAGS, Function<String,​Float> optionalUserParser)
      static SettingsRec<Integer,
           ​Stream<Integer>>      		 intRec​(int defaultValue, int FLAGS, Function<String,​Integer> optionalUserParser)
      static SettingsRec<Long,
           ​Stream<Long>>      		 longRec​(long defaultValue, int FLAGS, Function<String,​Long> optionalUserParser)
      static SettingsRec<Number,
           ​Stream<Number>>      		 numberRec​(Number defaultValue, int FLAGS, Function<String,​Number> optionalUserParser)
      static SettingsRec<Short,
           ​Stream<Short>>      		 shortRec​(short defaultValue, int FLAGS, Function<String,​Short> optionalUserParser)

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • intArr

        🡇  ⇈  ⮫     External-Java:   ⮫  ⮫ 🗕  🗗  🗖 
        public static java.util.stream.Stream<java.lang.Integer> intArr​
            (JsonArray ja,
             int defaultValue,
             int FLAGS,
             java.util.function.Function<java.lang.String,​java.lang.Integer> optionalUserParser)
        Generate a Java Stream of Boxed-Integers
        Invokes:   ProcessJsonArray.numericToJava(JsonArray, SettingsRec)
        Passes:  Integer-Retrieval Settings-Record.
        See: Class JFlag for information about the 'FLAGS' parameter.
           
        Producing a Boxed-Integer Array from this Method is as Follows:

        Java Line of Code:
        Integer[] arr = RJArrIntoBoxedStream.intArr
    (ja, 0, 0, null).toArray(Integer[]::new);

      • shortArr

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫  ⮫ 🗕  🗗  🗖 
        public static java.util.stream.Stream<java.lang.Short> shortArr​
            (JsonArray ja,
             short defaultValue,
             int FLAGS,
             java.util.function.Function<java.lang.String,​java.lang.Short> optionalUserParser)
        Generate a Java Stream of Boxed Short-Integers
        Invokes:   ProcessJsonArray.numericToJava(JsonArray, SettingsRec)
        Passes:  Short-Retrieval Settings-Record.
        See: Class JFlag for information about the 'FLAGS' parameter.
           
        Producing a Boxed-Short Array from this Method is as Follows:

        Java Line of Code:
        Short[] arr = RJArrIntoBoxedStream.shortArr
    (ja, 0, 0, null).toArray(Short[]::new);

      • byteArr

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫  ⮫ 🗕  🗗  🗖 
        public static java.util.stream.Stream<java.lang.Byte> byteArr​
            (JsonArray ja,
             byte defaultValue,
             int FLAGS,
             java.util.function.Function<java.lang.String,​java.lang.Byte> optionalUserParser)
        Generate a Java Stream of Boxed-Bytes
        Invokes:   ProcessJsonArray.numericToJava(JsonArray, SettingsRec)
        Passes:  Byte-Retrieval Settings-Record.
        See: Class JFlag for information about the 'FLAGS' parameter.
           
        Producing a Boxed-Byte Array from this Method is as Follows:

        Java Line of Code:
        Byte[] arr = RJArrIntoBoxedStream.byteArr
    (ja, 0, 0, null).toArray(Byte[]::new);

      • longArr

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫  ⮫ 🗕  🗗  🗖 
        public static java.util.stream.Stream<java.lang.Long> longArr​
            (JsonArray ja,
             long defaultValue,
             int FLAGS,
             java.util.function.Function<java.lang.String,​java.lang.Long> optionalUserParser)
        Generate a Java Stream of Boxed Long-Integers
        Invokes:   ProcessJsonArray.numericToJava(JsonArray, SettingsRec)
        Passes:  Long-Retrieval Settings-Record.
        See: Class JFlag for information about the 'FLAGS' parameter.
           
        Producing a Boxed-Long Array from this Method is as Follows:

        Java Line of Code:
        Long[] arr = RJArrIntoBoxedStream.longArr
    (ja, 0, 0, null).toArray(Long[]::new);

      • doubleArr

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫  ⮫ 🗕  🗗  🗖 
        public static java.util.stream.Stream<java.lang.Double> doubleArr​
            (JsonArray ja,
             double defaultValue,
             int FLAGS,
             java.util.function.Function<java.lang.String,​java.lang.Double> optionalUserParser)
        Generate a Java Stream of Boxed-Doubles
        Invokes:   ProcessJsonArray.numericToJava(JsonArray, SettingsRec)
        Passes:  Double-Retrieval Settings-Record.
        See: Class JFlag for information about the 'FLAGS' parameter.
           
        Producing a Boxed-Double Array from this Method is as Follows:

        Java Line of Code:
        Double[] arr = RJArrIntoBoxedStream.doubleArr
    (ja, 0, 0, null).toArray(Double[]::new);

      • floatArr

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫  ⮫ 🗕  🗗  🗖 
        public static java.util.stream.Stream<java.lang.Float> floatArr​
            (JsonArray ja,
             float defaultValue,
             int FLAGS,
             java.util.function.Function<java.lang.String,​java.lang.Float> optionalUserParser)
        Generate a Java Stream of Boxed-Floats
        Invokes:   ProcessJsonArray.numericToJava(JsonArray, SettingsRec)
        Passes:  Float-Retrieval Settings-Record.
        See: Class JFlag for information about the 'FLAGS' parameter.
           
        Producing a Boxed-Float Array from this Method is as Follows:

        Java Line of Code:
        Float[] arr = RJArrIntoBoxedStream.floatArr
    (ja, 0, 0, null).toArray(Float[]::new);

      • booleanArr

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫  ⮫ 🗕  🗗  🗖 
        public static java.util.stream.Stream<java.lang.Boolean> booleanArr​
            (JsonArray ja,
             boolean defaultValue,
             int FLAGS,
             java.util.function.Function<java.lang.String,​java.lang.Boolean> optionalUserParser)
        Generate a Java Stream of Boxed-Booleans
        Invokes:   ProcessJsonArray.booleanToJava(JsonArray, SettingsRec)
        Passes:  Boolean-Retrieval Settings-Record.
        See: Class JFlag for information about the 'FLAGS' parameter.
           
        Producing a Boxed-Boolean Array from this Method is as Follows:

        Java Line of Code:
        Boolean[] arr = RJArrIntoBoxedStream.booleanArr
    (ja, true, 0, null).toArray(Boolean[]::new);

      • numberArr

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫  ⮫ 🗕  🗗  🗖 
        public static java.util.stream.Stream<java.lang.Number> numberArr​
            (JsonArray ja,
             java.lang.Number defaultValue,
             int FLAGS,
             java.util.function.Function<java.lang.String,​java.lang.Number> optionalUserParser)
        Generate a Java Stream of Best-Fit Boxed-Numbers
        Invokes:   ProcessJsonArray.numericToJava(JsonArray, SettingsRec)
        Passes:  Number-Retrieval Settings-Record.
        See: Class JFlag for information about the 'FLAGS' parameter.
           
        Producing a Boxed-Number Array from this Method is as Follows:

        Java Line of Code:
        Number[] arr = RJArrIntoBoxedStream.numberArr
    (ja, 0, 0, null).toArray(Number[]::new);

      • intRec

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫  ⮫ 🗕  🗗  🗖 
        public static SettingsRec<java.lang.Integer,​java.util.stream.Stream<java.lang.Integer>> intRec​
            (int defaultValue,
             int FLAGS,
             java.util.function.Function<java.lang.String,​java.lang.Integer> optionalUserParser)
        Generate a Settings-Record for a Stream of Boxed-Integers
        Generates:  Integer-Retrieval Settings-Record.
        Used For: The record produced from this method may be used as a parameter to invoke:
            ProcessJsonArray.numericToJava(JsonArray, SettingsRec)
        See: Class JFlag for information about the 'FLAGS' parameter.
           
        Producing a Boxed-Number Stream by using this record is a two step process.
        It may be acheived as Follows:

        Example:
        SettingsRec<Integer, Stream<Integer>> rec =
    RJArrIntoBoxedStream.intRec(0, 0, null);

// Reuse the same record in each loop-iteration: only 1 Constructor-Invocation
for (JsonArray ja : someJsonArraySource) ProcessJsonArray
    .numericToJava(ja, rec)         // Returns a Stream<Integer>
    .forEach(System.out::println);  // Prints out each number in the stream

      • shortRec

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫  ⮫ 🗕  🗗  🗖 
        public static SettingsRec<java.lang.Short,​java.util.stream.Stream<java.lang.Short>> shortRec​
            (short defaultValue,
             int FLAGS,
             java.util.function.Function<java.lang.String,​java.lang.Short> optionalUserParser)
        Generate a Settings-Record for a Stream of Boxed Short-Integers
        Generates:  Short-Retrieval Settings-Record.
        Used For: The record produced from this method may be used as a parameter to invoke:
            ProcessJsonArray.numericToJava(JsonArray, SettingsRec)
        See: Class JFlag for information about the 'FLAGS' parameter.
           
        Producing a Boxed-Number Stream by using this record is a two step process.
        It may be acheived as Follows:

        Example:
        SettingsRec<Short, Stream<Short>> rec =
    RJArrIntoBoxedStream.shortRec(0, 0, null);

// Reuse the same record in each loop-iteration: only 1 Constructor-Invocation
for (JsonArray ja : someJsonArraySource) ProcessJsonArray
    .numericToJava(ja, rec)         // Returns a Stream<Short>
    .forEach(System.out::println);  // Prints out each number in the stream

      • byteRec

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫  ⮫ 🗕  🗗  🗖 
        public static SettingsRec<java.lang.Byte,​java.util.stream.Stream<java.lang.Byte>> byteRec​
            (byte defaultValue,
             int FLAGS,
             java.util.function.Function<java.lang.String,​java.lang.Byte> optionalUserParser)
        Generate a Settings-Record for a Stream of Boxed-Bytes
        Generates:  Byte-Retrieval Settings-Record.
        Used For: The record produced from this method may be used as a parameter to invoke:
            ProcessJsonArray.numericToJava(JsonArray, SettingsRec)
        See: Class JFlag for information about the 'FLAGS' parameter.
           
        Producing a Boxed-Number Stream by using this record is a two step process.
        It may be acheived as Follows:

        Example:
        SettingsRec<Byte, Stream<Byte>> rec =
    RJArrIntoBoxedStream.byteRec(0, 0, null);

// Reuse the same record in each loop-iteration: only 1 Constructor-Invocation
for (JsonArray ja : someJsonArraySource) ProcessJsonArray
    .numericToJava(ja, rec)         // Returns a Stream<Byte>
    .forEach(System.out::println);  // Prints out each number in the stream

      • longRec

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫  ⮫ 🗕  🗗  🗖 
        public static SettingsRec<java.lang.Long,​java.util.stream.Stream<java.lang.Long>> longRec​
            (long defaultValue,
             int FLAGS,
             java.util.function.Function<java.lang.String,​java.lang.Long> optionalUserParser)
        Generate a Settings-Record for a Stream of Boxed Long-Integers
        Generates:  Long-Retrieval Settings-Record.
        Used For: The record produced from this method may be used as a parameter to invoke:
            ProcessJsonArray.numericToJava(JsonArray, SettingsRec)
        See: Class JFlag for information about the 'FLAGS' parameter.
           
        Producing a Boxed-Number Stream by using this record is a two step process.
        It may be acheived as Follows:

        Example:
        SettingsRec<Long, Stream<Long>> rec =
    RJArrIntoBoxedStream.longRec(0, 0, null);

// Reuse the same record in each loop-iteration: only 1 Constructor-Invocation
for (JsonArray ja : someJsonArraySource) ProcessJsonArray
    .numericToJava(ja, rec)         // Returns a Stream<Long>
    .forEach(System.out::println);  // Prints out each number in the stream

      • doubleRec

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫  ⮫ 🗕  🗗  🗖 
        public static SettingsRec<java.lang.Double,​java.util.stream.Stream<java.lang.Double>> doubleRec​
            (double defaultValue,
             int FLAGS,
             java.util.function.Function<java.lang.String,​java.lang.Double> optionalUserParser)
        Generate a Settings-Record for a Stream of Boxed-Doubles
        Generates:  Double-Retrieval Settings-Record.
        Used For: The record produced from this method may be used as a parameter to invoke:
            ProcessJsonArray.numericToJava(JsonArray, SettingsRec)
        See: Class JFlag for information about the 'FLAGS' parameter.
           
        Producing a Boxed-Number Stream by using this record is a two step process.
        It may be acheived as Follows:

        Example:
        SettingsRec<Double, Stream<Double>> rec =
    RJArrIntoBoxedStream.doubleRec(0, 0, null);

// Reuse the same record in each loop-iteration: only 1 Constructor-Invocation
for (JsonArray ja : someJsonArraySource) ProcessJsonArray
    .numericToJava(ja, rec)         // Returns a Stream<Double>
    .forEach(System.out::println);  // Prints out each number in the stream

      • floatRec

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫  ⮫ 🗕  🗗  🗖 
        public static SettingsRec<java.lang.Float,​java.util.stream.Stream<java.lang.Float>> floatRec​
            (float defaultValue,
             int FLAGS,
             java.util.function.Function<java.lang.String,​java.lang.Float> optionalUserParser)
        Generate a Settings-Record for a Stream of Boxed-Floats
        Generates:  Float-Retrieval Settings-Record.
        Used For: The record produced from this method may be used as a parameter to invoke:
            ProcessJsonArray.numericToJava(JsonArray, SettingsRec)
        See: Class JFlag for information about the 'FLAGS' parameter.
           
        Producing a Boxed-Number Stream by using this record is a two step process.
        It may be acheived as Follows:

        Example:
        SettingsRec<Float, Stream<Float>> rec =
    RJArrIntoBoxedStream.floatRec(0, 0, null);

// Reuse the same record in each loop-iteration: only 1 Constructor-Invocation
for (JsonArray ja : someJsonArraySource) ProcessJsonArray
    .numericToJava(ja, rec)         // Returns a Stream<Float>
    .forEach(System.out::println);  // Prints out each number in the stream

      • booleanRec

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫  ⮫ 🗕  🗗  🗖 
        public static SettingsRec<java.lang.Boolean,​java.util.stream.Stream<java.lang.Boolean>> booleanRec​
            (boolean defaultValue,
             int FLAGS,
             java.util.function.Function<java.lang.String,​java.lang.Boolean> optionalUserParser)
        Generate a Settings-Record for a Stream of Boxed-Booleans
        Generates:  Boolean-Retrieval Settings-Record.
        Used For: The record produced from this method may be used as a parameter to invoke:
            ProcessJsonArray.booleanToJava(JsonArray, SettingsRec)
        See: Class JFlag for information about the 'FLAGS' parameter.
           
        Producing a Boxed-Number Stream by using this record is a two step process.
        It may be acheived as Follows:

        Example:
        SettingsRec<Boolean, Stream<Boolean>> rec =
    RJArrIntoBoxedStream.booleanRec(true, 0, null);

// Reuse the same record in each loop-iteration: only 1 Constructor-Invocation
for (JsonArray ja : someJsonArraySource) ProcessJsonArray
    .booleanToJava(ja, rec)         // Returns a Stream<Boolean>
    .forEach(System.out::println);  // Prints out each number in the stream

      • numberRec

        🡅  ⇈  ⮫     External-Java:   ⮫  ⮫ 🗕  🗗  🗖 
        public static SettingsRec<java.lang.Number,​java.util.stream.Stream<java.lang.Number>> numberRec​
            (java.lang.Number defaultValue,
             int FLAGS,
             java.util.function.Function<java.lang.String,​java.lang.Number> optionalUserParser)
        Generate a Settings-Record for a Stream of Best-Fit Boxed-Numbers
        Generates:  Number-Retrieval Settings-Record.
        Used For: The record produced from this method may be used as a parameter to invoke:
            ProcessJsonArray.numericToJava(JsonArray, SettingsRec)
        See: Class JFlag for information about the 'FLAGS' parameter.
           
        Producing a Boxed-Number Stream by using this record is a two step process.
        It may be acheived as Follows:

        Example:
        SettingsRec<Number, Stream<Number>> rec =
    RJArrIntoBoxedStream.numberRec(0, 0, null);

// Reuse the same record in each loop-iteration: only 1 Constructor-Invocation
for (JsonArray ja : someJsonArraySource) ProcessJsonArray
    .numericToJava(ja, rec)         // Returns a Stream<Number>
    .forEach(System.out::println);  // Prints out each number in the stream