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