Class JFlag


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

    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. It is the code for handling an 'ArrayIndexOutOfBoundsException'. (See below that the Flag Precedence rules are pretty straight-forward - and certainly 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
     }
    


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 field. It is very similar to the Java-Bean @Stateless Annotation.
  • 1 Constructor(s), 1 declared private, zero-argument constructor
  • 0 Method(s)
  • 56 Field(s), 56 declared static, 56 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.

        PRIORITY: 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.

        PRIORITY: 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_NULL_ON_0LEN_STR

        🡅  🡇    
        public static final int RETURN_NULL_ON_0LEN_STR
        Instructs a get method to return null in cases where a JsonObject property or JsonArray index contains a zero-length JsonString

        ABBREVIATION: The flag-mask RN_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_NULL_ON_0LEN_STR = RD_WT << 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;
        
      • RETURN_NULL_ON_SPEX

        🡅  🡇    
        public static final int RETURN_NULL_ON_SPEX
        Instructs a get method to return null in cases where the user-provided 'parser' function has thrown an exception.

        SPEX: String Parse Exception

        ABBREVIATION: The flag-mask RN_SPEX is an abbreviated but identical value that may be used if brevity is a higher priority than readability.
        See Also:
        JsonStrParseArrException, JsonStrParseObjException, Constant Field Values
        Code:
        Exact Field Declaration Expression:
        public static final int RETURN_NULL_ON_SPEX = RD_ZLS << 1;
        
      • RETURN_DEFVAL_ON_SPEX

        🡅  🡇    
        public static final int RETURN_DEFVAL_ON_SPEX
        Instructs a get method to return the user-provided 'defaultValue' in cases where the user-provided 'parser' function has thrown an exception.

        SPEX: String Parse Exception

        ABBREVIATION: The flag-mask RD_SPEX is an abbreviated but identical value that may be used if brevity is a higher priority than readability.
        See Also:
        JsonStrParseArrException, JsonStrParseObjException, Constant Field Values
        Code:
        Exact Field Declaration Expression:
        public static final int RETURN_DEFVAL_ON_SPEX = RN_SPEX << 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.

        PRIORITY: 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-indice.

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

        NOTE: This flag is ignored, completely, by all methods in ReadJSON, and is only useful in ReadArrJSON. 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-indice.

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

        NOTE: This flag is ignored, completely, by all methods in ReadJSON, and is only useful in ReadArrJSON. 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.

        NOTE: This flag is ignored, completely, by all methods in ReadJSON, and is only useful in ReadArrJSON.
        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.

        NOTE: This flag is ignored, completely, by all methods in ReadJSON, and is only useful in ReadArrJSON.
        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.

        NOTE: This flag is ignored, completely, by all methods in ReadJSON, and is only useful in ReadArrJSON.
        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-indice.

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

        NOTE: This flag is ignored, completely, by all methods in ReadJSON, and is only useful in ReadArrJSON. 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-indice.

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

        NOTE: This flag is ignored, completely, by all methods in ReadJSON, and is only useful in ReadArrJSON. 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-indice.

        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.

        NOTE: This flag is ignored, completely, by all methods in ReadJSON, and is only useful in ReadArrJSON. 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-indice.

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

        NOTE: This flag is ignored, completely, by all methods in ReadJSON, and is only useful in ReadArrJSON. 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;