Package Torello.JSON

Class JFlag

  • public class JFlag
extends java.lang.Object
    Exception-Flags that may be passed to the ReadJSON methods which accept a 'FLAGS' parameter.

    FLAG PRECEDENCE:
    If a user actually has multiple masks for the same error case, class ReadJSON has an internal precedence / priority used for obeying the user-provided flag-masks. The flags that handle "On Any" or "On All" are always obeyed last. If the user has provided error or exception specific flags, those always take precedence over the "Any & All" mask.

    SPECIFICALLY: RETURN_NULL_ON_WRONG_JSONTYPE takes precedence over RETURN_DEFVAL_ON_ANY_ALL

    If a user has provided multiple masks for the same case, and both of those masks are error or exception flags, then a 'null' return takes precedence over a default-value return.

    SPECIFICALLY: RETURN_NULL_ON_WRONG_JSONTYPE takes precedence over RETURN_DEFVAL_ON_WRONG_JSONTYPE

    ROCKET-SCIENCE NOTE:
    The following code has been directly cut and pasted - from one of the internal, protected 'GET' methods found in RJInternal. It is the code for handling an 'ArrayIndexOutOfBoundsException'. (See below that the Flag Precedence rules are pretty straight-forward - and certainly are not rocket-science!). 

     if (index >= ja.size())
 {
     if ((FLAGS & RETURN_NULL_ON_IOB) != 0)          return null;
     if ((FLAGS & RETURN_DEFVAL_ON_IOB) != 0)        return defaultValue;
     if ((FLAGS & RETURN_NULL_ON_ANY_ALL) != 0)      return null;
     if ((FLAGS & RETURN_DEFVAL_ON_ANY_ALL) != 0)    return defaultValue;

     ja.get(index); // Throw an IndexOutOfBoundsException
 }


    The complete set of handlers for these flags may be viewed inside the exception-handler methods in class RJInternal.

    The flag-handlers for the RJArrIntoPrimArray and RJArrDimN classes are available for viewing (but buried) inside that class. To see those flag-handlers / exception-case-handlers, simply click the HILITED button in the Navigation Bar there (or the View Here: link on that page).

    Java Bit-Wise Logic Syntax:
    As a simple reminder for how to "glue" together several flags, the following (simple) bit-wise operator allows the programmer to place several flags inside of a single integer:

    Java Line of Code:
     int myFlags = RETURN_DEFVAL_ON_ANY_ALL | RETURN_PARSE_ON_STR | RETURN_JAPPROX_ON_AEX;

    The above flags-integer would guarantee that any / all JsonString elements found which are intended to be represented as numbers are parsed into numbers. It would furthermore use the standard JDK "rounding process" for numbers that will not fit into their desired type.

    Any other exceptions that might occur while processing a Json Element will produce whatever Default-Value has been passed to the method parameter defaultValue.

    Null-Flags & Primitives:
    There are quite a number of flags in this class that allow a user to request that certain values be returned when a "null" is encountered in a Json-Object or Array. Furthermore, there are also flags that provide a means for to request 'null' be returned under certain Error-Conditions or when unacceptable values are retrieved.

    Any JFlag that is would intend a 'null' to be returned from a function that returns primitives, or any JFlag that asks 'null' be inserted into a Primitive-Array, Primitive-Stream or sent to a Primitive-Consumer will be, summarily, ignored.

    It should be clear that although a NullPointerException could, theoretically, be thrown in such circumstances, because this Java-JSON Package tries to heavily emphasize detailed Exception-Throws in Error-Situations, the usual NPE is not used in this package. In fact, what actually does happen is a non-trivial decision process that needs some clarifying.

    If a JFlag is passed to a method that requests Java-Null be returned to a method that returns primitives, or assigns or passes primitives to other Data-Structures, then:

    • That JFlag is simply ignored, and treated as if its bit-mask simply had not been passed as element of the input 'FLAGS' parameter.
    • If the scenario that is addressed by the flag which is being ignored would result in a particular JsonExeption being thrown, then that case-specific exception shall throw.
    • It is most important to recognize that passing a Null-Return JFlag to the method of a class that deals with Java-Primitives, in and of itself, will not cause an exception to throw. Instead, and quite the contrary, incongruous flags are simply ignored, and the Error-Case addressed by the ignored flag is never encountered, then no exception shall throw.


    Here is brief sample of the logic which deals with "Null-Requesting Flags". Note that the variable 'NULLS' is false whenever the output is a primitive. 

    if (NULLS && ((FLAGS & RETURN_NULL_ON_SPEX) > 0))   handlerSPEX = this::AN;
else if ((FLAGS & RETURN_DEFVAL_ON_SPEX) > 0)       handlerSPEX = this::AD;
else if ((FLAGS & SKIP_ON_SPEX) > 0)                handlerSPEX = this::NOOP;
else if (NULLS && RN_AA)                            handlerSPEX = this::AN;
else if (RD_AA)                                     handlerSPEX = this::AD;
else if (S_AA)                                      handlerSPEX = this::NOOP;
else                                                handlerSPEX = null;

    In the above code-snippet, if the user has requested that a 'null' be returned whenever an exception should throw due to a faulty String-Parse operation, instead, that request is ignored if variable 'NULLS' is FALSE. In such a scenario, if there are no other pertinent JFlag-Masks that reside inside the 'FLAGS' parameter, then whatever String-Parse exception was going to be avoided, instead, throws.



    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
    • 0 Method(s)
    • 61 Field(s), 61 declared static, 61 declared final


    • Field Detail

      • RETURN_NULL_ON_ANY_ALL

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final int RETURN_NULL_ON_ANY_ALL
        This is a "Primary Flag" that indicates the reader should always return null for any exception-throw or error case that could possibly occur.

        Flag Precedence:
        When this flag is set, it always has the lowest precedence compared to all other flags. Specifically, if this flag, and the flag RETURN_DEFVAL_ON_AEX were both set, and an ArithmeticException were going to be thrown, the user-provided default-value would be returned, rather than null.

        If both flag RN_AA and RD_AA are set, 'null' will always be returned, rather than the default-value.

        Abbreviation:
        The flag-mask RN_AA is an abbreviated but identical value that may be used if brevity is a higher priority than readability.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final int RETURN_NULL_ON_ANY_ALL = 1;

      • RETURN_DEFVAL_ON_ANY_ALL

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final int RETURN_DEFVAL_ON_ANY_ALL
        This is a "Primary Flag" that indicates the reader should always return the user-provided default-value for any exception-throw or error case that could possibly occur.

        Flag Precedence:
        When this flag is set, it always has the lowest precedence compared to all other flags. Specifically, if this flag, and the flag RETURN_NULL_ON_AEX were both set, and an ArithmeticException were going to be thrown, null would be returned, rather than the user-provided default-value.

        If both flag RN_AA and RD_AA are set, 'null' will always be returned, rather than the default-value.

        Abbreviation:
        The flag-mask RN_AA is an abbreviated but identical value that may be used if brevity is a higher priority than readability.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final int RETURN_DEFVAL_ON_ANY_ALL = RN_AA << 1;

      • RETURN_NULL_ON_IOB

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final int RETURN_NULL_ON_IOB
        Instructs a get method to return null if an IndexOutOfBoundsException would otherwise be thrown. This flag-mask is only useful with methods that accept JsonArray and 'index' parameters.

        Abbreviation:
        The flag-mask RN_IOB is an abbreviated but identical value that may be used if brevity is a higher priority than readability.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final int RETURN_NULL_ON_IOB = RD_AA << 1;

      • RETURN_DEFVAL_ON_IOB

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final int RETURN_DEFVAL_ON_IOB
        Instructs a get method to return the user-provided 'defaultValue' if an IndexOutOfBoundsException would otherwise be thrown. This flag-mask is only useful to methods which accept JsonArray and 'index' parameters.

        Abbreviation:
        The flag-mask RD_IOB is an abbreviated but identical value that may be used if brevity is a higher priority than readability.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final int RETURN_DEFVAL_ON_IOB = RN_IOB << 1;

      • RETURN_NULL_ON_MISSING

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final int RETURN_NULL_ON_MISSING
        Instructs a get method to return null when a specified property isn't actually present in a JsonObject. This flag-mask is only useful to methods that accept a 'propertyName' and JsonObject parameter.

        Abbreviation:
        The flag-mask RN_M is an abbreviated but identical value that may be used if brevity is a higher priority than readability.
        See Also:
        JsonPropMissingException, Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final int RETURN_NULL_ON_MISSING = RD_IOB << 1;

      • RETURN_DEFVAL_ON_MISSING

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final int RETURN_DEFVAL_ON_MISSING
        Instructs a get method to return a user-provided 'defaultValue' when a specified property isn't actually present in a JsonObject. This flag-mask is only useful to methods that accept a 'propertyName' and JsonObject parameter.

        Abbreviation:
        The flag-mask RD_M is an abbreviated but identical value that may be used if brevity is a higher priority than readability.
        See Also:
        JsonPropMissingException, Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final int RETURN_DEFVAL_ON_MISSING = RN_M << 1;

      • RETURN_JAPPROX_ON_AEX

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final int RETURN_JAPPROX_ON_AEX
        Instructs a get method to use a Standard Java Alternative / Rounding Method if an ArithmeticException would otherwise be thrown.

        The exact process for 'fitting' a number that is too big for a particular primitive is the implemented in class java.math.BigDecimal. Below are the explanations for fitting a number into an int and a float.

        Description copied from class: java.math.BigDecimal.intValue(), JDK 1.8
        This conversion is analogous to the narrowing primitive conversion from double to short as defined in section 5.1.3 of The Java™ Language Specification: any fractional part of this BigDecimal will be discarded, and if the resulting "BigInteger" is too big to fit in an int, only the low-order 32 bits are returned. Note that this conversion can lose information about the overall magnitude and precision of this BigDecimal value as well as return a result with the opposite sign.

        Description copied from class: java.math.BigDecimal.floatValue(), JDK 1.8
        This conversion is similar to the narrowing primitive conversion from double to float as defined in section 5.1.3 of The Java™ Language Specification: if this BigDecimal has too great a magnitude to represent as a float, it will be converted to Float.NEGATIVE_INFINITY or Float.POSITIVE_INFINITY as appropriate. Note that even when the return value is finite, this conversion can lose information about the precision of the BigDecimal value.

        Abbreviation:
        The flag-mask RJA_AEX is an abbreviated but identical value that may be used if brevity is a higher priority than readability.
        See Also:
        JsonArithmeticArrException, JsonArithmeticObjException, Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final int RETURN_JAPPROX_ON_AEX = RD_AEX << 1;

      • RETURN_DEFVAL_ON_0LEN_STR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final int RETURN_DEFVAL_ON_0LEN_STR
        Instructs a get method to return the user-provided 'defaultValue' in cases where a JsonObject property or JsonArray index contains a zero-length JsonString

        Abbreviation:
        The flag-mask RD_ZLS is an abbreviated but identical value that may be used if brevity is a higher priority than readability.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final int RETURN_DEFVAL_ON_0LEN_STR = RN_ZLS << 1;

      • SKIP_ON_ANY_ALL

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final int SKIP_ON_ANY_ALL
        This is a "Primary Flag" that indicates the reader should always skip any array-entry for any exception-throw or error case that could possibly occur.

        Flag Precedence:
        When this flag is set, it always has the lowest precedence compared to all other flags. Specifically, if this flag, and the flag RETURN_DEFVAL_ON_AEX were both set, and an ArithmeticException were going to be thrown, the user-provided default-value would be placed into the output, rather than being skipped.

        If both flag S_AA and RN_AA are set, 'null' will always be placed into the output, before skipping the array-index, or using the default-value.

        Abbreviation:
        The flag-mask S_AA is an abbreviated but identical value that may be used if brevity is a higher priority than readability.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final int SKIP_ON_ANY_ALL = RD_SPEX << 1;

      • SKIP_ON_NULL

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final int SKIP_ON_NULL
        Instructs an array / stream builder method to skip an array element, if-and-when a JsonArray index contain a Json-Null.

        When an array-index location is skipped during a converstion, the returned stream will simply have a size shorter than the input JsonArray's size, shortened by the number of skipped-indices.

        Abbreviation:
        The flag-mask S_N is an abbreviated but identical value that may be used if brevity is a higher priority than readability.

        For Reading Arrays Only:
        This flag is ignored, completely, by all methods in ReadJSON, and is only useful in RJArrIntoPrimArray. Any flag which begins with 'SKIP' will only be applied to array-processing methods.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final int SKIP_ON_NULL = S_AA << 1;

      • SKIP_ON_AEX

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final int SKIP_ON_AEX
        Instructs an array / stream builder method to skip an array element, if-and-when if an ArithmeticException would otherwise be thrown.

        When an array-index location is skipped during a converstion, the returned stream will simply have a size shorter than the input JsonArray's size, shortened by the number of skipped-indices.

        Abbreviation:
        The flag-mask S_AEX is an abbreviated but identical value that may be used if brevity is a higher priority than readability.

        For Reading Arrays Only:
        This flag is ignored, completely, by all methods in ReadJSON, and is only useful in RJArrIntoPrimArray. Any flag which begins with 'SKIP' will only be applied to array-processing methods.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final int SKIP_ON_AEX = S_N << 1;

      • RETURN_PARSE_ON_STR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final int RETURN_PARSE_ON_STR
        Instructs an array / stream builder method to parse an array element into a number, if-and-when a JsonString is encountered.

        Abbreviation:
        The flag-mask RP_S is an abbreviated but identical value that may be used if brevity is a higher priority than readability.

        For Reading Arrays Only:
        This flag is ignored, completely, by all methods in ReadJSON, and is only useful in RJArrIntoPrimArray.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final int RETURN_PARSE_ON_STR = S_AEX << 1;

      • RETURN_NULL_ON_STR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final int RETURN_NULL_ON_STR
        Instructs a boxed-stream builder method to insert Java-Null into the boxed-stream whenever a JsonArray index contains a JsonString.

        This flag is ignored if passed to a primitive-stream builder method. A primitive-stream (and its associated builder) will not accept nulls.

        Abbreviation:
        The flag-mask RN_S is an abbreviated but identical value that may be used if brevity is a higher priority than readability.

        For Reading Arrays Only:
        This flag is ignored, completely, by all methods in ReadJSON, and is only useful in RJArrIntoPrimArray.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final int RETURN_NULL_ON_STR = RP_S << 1;

      • RETURN_DEFVAL_ON_STR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final int RETURN_DEFVAL_ON_STR
        Instructs an array / stream builder method to insert the user-provided 'defaultValue' whenever a JsonString is encountered at a particular index inside a JsonArray.

        Abbreviation:
        The flag-mask RD_S is an abbreviated but identical value that may be used if brevity is a higher priority than readability.

        For Reading Arrays Only:
        This flag is ignored, completely, by all methods in ReadJSON, and is only useful in RJArrIntoPrimArray.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final int RETURN_DEFVAL_ON_STR = RN_S << 1;

      • SKIP_ON_STR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final int SKIP_ON_STR
        Instructs an array / stream builder method to skip any JsonArray index-locations that contain a JsonString.

        When an array-index location is skipped during a converstion, the returned stream will simply have a size shorter than the input JsonArray's size, shortened by the number of skipped-indices.

        Abbreviation:
        The flag-mask S_S is an abbreviated but identical value that may be used if brevity is a higher priority than readability.

        For Reading Arrays Only:
        This flag is ignored, completely, by all methods in ReadJSON, and is only useful in RJArrIntoPrimArray. Any flag which begins with 'SKIP' will only be applied to array-processing methods.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final int SKIP_ON_STR = RD_S << 1;

      • SKIP_ON_0LEN_STR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final int SKIP_ON_0LEN_STR
        Instructs an array / stream builder method to skip any JsonArray index-locations that contain a Zero-Length JsonString.

        When an array-index location is skipped during a converstion, the returned stream will simply have a size shorter than the input JsonArray's size, shortened by the number of skipped-indices.

        Abbreviation:
        The flag-mask S_ZLS is an abbreviated but identical value that may be used if brevity is a higher priority than readability.

        For Reading Arrays Only:
        This flag is ignored, completely, by all methods in ReadJSON, and is only useful in RJArrIntoPrimArray. Any flag which begins with 'SKIP' will only be applied to array-processing methods.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final int SKIP_ON_0LEN_STR = S_S << 1;

      • SKIP_ON_SPEX

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final int SKIP_ON_SPEX
        Instructs an array / stream builder method to skip any JsonArray index-locations that contain a JsonString that, when parsed, generate any parse-exceptions, such as NumberFormatException.

        When an array-index location is skipped during a converstion, the returned stream will simply have a size shorter than the input JsonArray's size, shortened by the number of skipped-indices.

        SPEX: String Parse Exception

        Abbreviation:
        The flag-mask S_SPEX is an abbreviated but identical value that may be used if brevity is a higher priority than readability.

        For Reading Arrays Only:
        This flag is ignored, completely, by all methods in ReadJSON, and is only useful in RJArrIntoPrimArray. Any flag which begins with 'SKIP' will only be applied to array-processing methods.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final int SKIP_ON_SPEX = S_ZLS << 1;

      • SKIP_ON_WRONG_JSONTYPE

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final int SKIP_ON_WRONG_JSONTYPE
        Instructs an array / stream builder method to skip any JsonArray index-locations that contain an inapplicable Json-Type - such as JsonValue.TRUE, JsonValue.FALSE, JsonObject, a nested JsonArray etc...

        When an array-index location is skipped during a converstion, the returned stream will simply have a size shorter than the input JsonArray's size, shortened by the number of skipped-indices.

        Abbreviation:
        The flag-mask S_WT is an abbreviated but identical value that may be used if brevity is a higher priority than readability.

        For Reading Arrays Only:
        This flag is ignored, completely, by all methods in ReadJSON, and is only useful in RJArrIntoPrimArray. Any flag which begins with 'SKIP' will only be applied to array-processing methods.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final int SKIP_ON_WRONG_JSONTYPE = S_SPEX << 1;

      • INSERT_NULL_ON_NON_SUBARRAY_TYPE

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final int INSERT_NULL_ON_NON_SUBARRAY_TYPE
        Instructs the multi-dimensional array-builder method to place a null in an array when it encounters a JsonArray element that is not a sub-array, but rather some other non-null Json-Type This flag is only applicable when converting a JsonArray using one of the multi-dimensional array-processors in class RJArrDimN.

        Abbreviation:
        The flag-mask IN_NSAT is an abbreviated but identical value that may be used if brevity is a higher priority than readability.

        For Reading Multi-Dimensional Arrays Only:
        This flag is ignored, completely, by all methods in ReadJSON and in RJArrIntoPrimArray. It is only used in processing multi-dimensional arrays (by class RJArrDimN).
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final int INSERT_NULL_ON_NON_SUBARRAY_TYPE = RTS_WT << 1;

      • SKIP_ON_NON_SUBARRAY_TYPE

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final int SKIP_ON_NON_SUBARRAY_TYPE
        Instructs the multi-dimensional array-builder method to skip the element when it encounters a JsonArray element that is not a sub-array, but rather some other non-null Json-Type This flag is only applicable when converting a JsonArray using one of the multi-dimensional array-processors in class RJArrDimN.

        Abbreviation:
        The flag-mask S_NSAT is an abbreviated but identical value that may be used if brevity is a higher priority than readability.

        For Reading Multi-Dimensional Arrays Only:
        This flag is ignored, completely, by all methods in ReadJSON and in RJArrIntoPrimArray. It is only used in processing multi-dimensional arrays (by class RJArrDimN).
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final int SKIP_ON_NON_SUBARRAY_TYPE = IN_NSAT << 1;