001package Torello.Java.JSON; 002 003import javax.json.*; // For JavaDoc links 004 005/** 006 * Exception-Flags that may be passed to the {@code ReadJSON} methods which accept a 007 * {@code 'FLAGS'} parameter. 008 * 009 * <BR /><BR /><B CLASS=JDDescLabel>FLAG PRECEDENCE:</B> 010 * 011 * <BR />If a user actually has multiple masks for the same error case, class 012 * {@link ReadJSON} has an internal precedence / priority used for obeying the user-provided 013 * flag-masks. The flags that handle "On Any" or "On All" are always obeyed last. If the 014 * user has provided error or exception specific flags, those always take precedence over 015 * the "Any & All" mask. 016 * 017 * <BR /><BR /><B>SPECIFICALLY: {@link #RETURN_NULL_ON_WRONG_JSONTYPE} <I>takes 018 * precedence</I> over {@link #RETURN_DEFVAL_ON_ANY_ALL}</B> 019 * 020 * <BR /><BR />If a user has provided multiple masks for the same case, and both of those 021 * masks are error or exception flags, then a 'null' return takes precedence over a 022 * default-value return. 023 * 024 * <BR /><BR /><B>SPECIFICALLY: {@link #RETURN_NULL_ON_WRONG_JSONTYPE} <I>takes 025 * precedence</I> over {@link #RETURN_DEFVAL_ON_WRONG_JSONTYPE}</B> 026 * 027 * <BR /><BR /><B CLASS=JDDescLabel>ROCKET-SCIENCE NOTE:</B> 028 * <BR />The following code has been directly cut and pasted - <I>from one of the internal, 029 * {@code protected} <B>{@code 'GET'}</B> methods</I> found in {@link RJInternal}. It is the 030 * code for handling an {@code 'ArrayIndexOutOfBoundsException'}. (See below that the 031 * <B STYLE='color: red;'>Flag Precedence</B> rules are pretty straight-forward - <I><B>and 032 * certainly are not rocket-science!</B></I>). 033 * 034 * <BR ><DIV CLASS=SNIP>{@code 035 * if (index >= ja.size()) 036 * { 037 * if ((FLAGS & RETURN_NULL_ON_IOB) != 0) return null; 038 * if ((FLAGS & RETURN_DEFVAL_ON_IOB) != 0) return defaultValue; 039 * if ((FLAGS & RETURN_NULL_ON_ANY_ALL) != 0) return null; 040 * if ((FLAGS & RETURN_DEFVAL_ON_ANY_ALL) != 0) return defaultValue; 041 * 042 * ja.get(index); // Throw an IndexOutOfBoundsException 043 * } 044 * }</DIV> 045 * 046 * <BR /><BR />The complete set of handlers for these flags may be viewed inside the 047 * exception-handler methods in class <B>{@link RJInternal}</B>. 048 * 049 * <BR /><BR />The flag-handlers for the <B>{@link RJArrIntoPrimArray}</B> and 050 * <B>{@link RJArrDimN}</B> classes are available for viewing (but buried) inside that 051 * class. To see those flag-handlers / exception-case-handlers, simply click the 052 * <B><CODE>HILITED</CODE></B> button in the Navigation Bar there (or the 053 * <CODE><B>View Here:</B></CODE> link on that page). 054 * 055 * <BR /><BR /><B CLASS=JDDescLabel>Java Bit-Wise Logic Syntax:</B> 056 * 057 * <BR />As a simple reminder for how to "glue" together several flags, the following (simple) 058 * bit-wise operator allows the programmer to place several flags inside of a single integer: 059 * 060 * <DIV CLASS=LOC>{@code 061 * int myFlags = RETURN_DEFVAL_ON_ANY_ALL | RETURN_PARSE_ON_STR | RETURN_JAPPROX_ON_AEX; 062 * }</DIV> 063 * 064 * <BR />The above flags-integer would guarantee that any / all <B>{@link JsonString}</B> elements 065 * found which are intended to be represented as numbers are parsed into numbers. It would 066 * furthermore use the standard JDK "rounding process" for numbers that will not fit into their 067 * desired type. 068 * 069 * <BR /><BR />Any other exceptions that might occur while processing a Json Element will produce 070 * whatever Default-Value has been passed to the method parameter {@code defaultValue}. 071 * 072 * <EMBED CLASS='external-html' DATA-FILE-ID=NULL_FLAGS_PRIM> 073 */ 074@Torello.JavaDoc.StaticFunctional 075public class JFlag 076{ 077 private JFlag() { } 078 079 /** 080 * This is a "Primary Flag" that indicates the reader should always 081 * <B STYLE='color: red;'>return null</B> for any exception-throw or error case that could 082 * possibly occur. 083 * 084 * <BR /><BR /><B CLASS=JDDescLabel>Flag Precedence:</B> 085 * 086 * <BR />When this flag is set, it always has the lowest precedence compared to all other 087 * flags. Specifically, if this flag, and the flag {@link #RETURN_DEFVAL_ON_AEX} were 088 * <B><I>both set</I></B>, and an {@code ArithmeticException} were going to be thrown, the 089 * user-provided default-value would be returned, rather than null. 090 * 091 * <BR /><BR />If both flag {@link #RN_AA} and {@link #RD_AA} are set, 'null' will always 092 * be returned, rather than the default-value. 093 * 094 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 095 * 096 * <BR />The flag-mask <B>{@link #RN_AA}</B> is an abbreviated but identical value that may be 097 * used if brevity is a higher priority than readability. 098 */ 099 public static final int RETURN_NULL_ON_ANY_ALL = 1; 100 101 /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_ANY_ALL}</B> */ 102 public static final int RN_AA = RETURN_NULL_ON_ANY_ALL; 103 104 /** 105 * This is a "Primary Flag" that indicates the reader should always return the 106 * user-provided default-value for any exception-throw or error case that could possibly 107 * occur. 108 * 109 * <BR /><BR /><B CLASS=JDDescLabel>Flag Precedence:</B> 110 * 111 * <BR />When this flag is set, it always has the lowest precedence compared to all other 112 * flags. Specifically, if this flag, and the flag {@link #RETURN_NULL_ON_AEX} were 113 * <B><I>both set</I></B>, and an {@code ArithmeticException} were going to be thrown, null 114 * would be returned, rather than the user-provided default-value. 115 * 116 * <BR /><BR />If both flag {@link #RN_AA} and {@link #RD_AA} are set, 'null' will always 117 * be returned, rather than the default-value. 118 * 119 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 120 * 121 * <BR />The flag-mask <B>{@link #RN_AA}</B> is an abbreviated but identical value that may be 122 * used if brevity is a higher priority than readability. 123 */ 124 public static final int RETURN_DEFVAL_ON_ANY_ALL = RN_AA << 1; 125 126 /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_ANY_ALL}</B> */ 127 public static final int RD_AA = RETURN_DEFVAL_ON_ANY_ALL; 128 129 /** 130 * Instructs a get method to <B STYLE='color: red;'>return null</B> if an 131 * <B STYLE='color: red;'>{@code IndexOutOfBoundsException}</B> would otherwise be thrown. 132 * This flag-mask is only useful with methods that accept <B>{@link JsonArray}</B> and 133 * {@code 'index'} parameters. 134 * 135 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 136 * 137 * <BR />The flag-mask <B>{@link #RN_IOB}</B> is an abbreviated but identical value that may be 138 * used if brevity is a higher priority than readability. 139 */ 140 public static final int RETURN_NULL_ON_IOB = RD_AA << 1; 141 142 /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_IOB}</B> */ 143 public static final int RN_IOB = RETURN_NULL_ON_IOB; 144 145 /** 146 * Instructs a get method to return the user-provided 147 * <B STYLE='color: red;'>{@code 'defaultValue'}</B> if an 148 * <B STYLE='color: red;'>{@code IndexOutOfBoundsException}</B> would otherwise be thrown. 149 * This flag-mask is only useful to methods which accept <B>{@link JsonArray}</B> and 150 * {@code 'index'} parameters. 151 * 152 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 153 * 154 * <BR />The flag-mask <B>{@link #RD_IOB}</B> is an abbreviated but identical value that may be 155 * used if brevity is a higher priority than readability. 156 */ 157 public static final int RETURN_DEFVAL_ON_IOB = RN_IOB << 1; 158 159 /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_IOB}</B> */ 160 public static final int RD_IOB = RETURN_DEFVAL_ON_IOB; 161 162 /** 163 * Instructs a get method to <B STYLE='color: red;'>return null</B> when a specified property 164 * <I>isn't actually present in a <B>{@link JsonObject}</B></I>. This flag-mask is only useful 165 * to methods that accept a {@code 'propertyName'} and {@code JsonObject} parameter. 166 * 167 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 168 * 169 * <BR />The flag-mask <B>{@link #RN_M}</B> is an abbreviated but identical value that may be 170 * used if brevity is a higher priority than readability. 171 * 172 * @see JsonPropMissingException 173 */ 174 public static final int RETURN_NULL_ON_MISSING = RD_IOB << 1; 175 176 /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_MISSING}</B> */ 177 public static final int RN_M = RETURN_NULL_ON_MISSING; 178 179 /** 180 * Instructs a get method to return a user-provided 181 * <B STYLE='color: red;'>{@code 'defaultValue'}</B> when a specified property <I> isn't 182 * actually present in a <B>{@link JsonObject}</B></I>. This flag-mask is only useful to 183 * methods that accept a {@code 'propertyName'} and {@code JsonObject} parameter. 184 * 185 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 186 * 187 * <BR />The flag-mask <B>{@link #RD_M}</B> is an abbreviated but identical value that may be 188 * used if brevity is a higher priority than readability. 189 * 190 * @see JsonPropMissingException 191 */ 192 public static final int RETURN_DEFVAL_ON_MISSING = RN_M << 1; 193 194 /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_MISSING}</B> */ 195 public static final int RD_M = RETURN_DEFVAL_ON_MISSING; 196 197 /** 198 * Instructs a get method to return <B STYLE='color: red;'>Java-Null</B> whenever a 199 * <B>{@link JsonObject}</B> property or <B>{@link JsonArray}</B> index contains 200 * <B STYLE='color: red;'>Json-Null</B>. 201 * 202 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 203 * 204 * <BR />The flag-mask <B>{@link #RN_N}</B> is an abbreviated but identical value that may be 205 * used if brevity is a higher priority than readability. 206 * 207 * @see JsonNullArrException 208 * @see JsonNullObjException 209 * @see JsonNullPrimitiveArrException 210 * @see JsonNullPrimitiveObjException 211 */ 212 public static final int RETURN_NULL_ON_NULL = RD_M << 1; 213 214 /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_NULL}</B> */ 215 public static final int RN_N = RETURN_NULL_ON_NULL; 216 217 /** 218 * Instructs a get method to return a user-provided 219 * <B STYLE='color: red;'>{@code 'defaultValue'}</B> whenever a <B>{@link JsonObject}</B> 220 * property or <B>{@link JsonArray}</B> index contains <B STYLE='color: red;'>Json-Null</B>. 221 * 222 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 223 * 224 * <BR />The flag-mask <B>{@link #RD_N}</B> is an abbreviated but identical value that may be 225 * used if brevity is a higher priority than readability. 226 * 227 * @see JsonNullArrException 228 * @see JsonNullObjException 229 * @see JsonNullPrimitiveArrException 230 * @see JsonNullPrimitiveObjException 231 */ 232 public static final int RETURN_DEFVAL_ON_NULL = RN_N << 1; 233 234 /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_NULL}</B> */ 235 public static final int RD_N = RETURN_DEFVAL_ON_NULL; 236 237 /** 238 * Instructs a get method to <B STYLE='color: red;'>return null</B> if an 239 * <B STYLE='color: red;'>{@code ArithmeticException}</B> would otherwise be thrown. 240 * 241 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 242 * 243 * <BR />The flag-mask <B>{@link #RN_AEX}</B> is an abbreviated but identical value that may be 244 * used if brevity is a higher priority than readability. 245 * 246 * @see JsonArithmeticArrException 247 * @see JsonArithmeticObjException 248 */ 249 public static final int RETURN_NULL_ON_AEX = RD_N << 1; 250 251 /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_AEX}</B> */ 252 public static final int RN_AEX = RETURN_NULL_ON_AEX; 253 254 /** 255 * Instructs a get method to return the user-provided 256 * <B STYLE='color: red;'>{@code 'defaultValue'}</B> if an 257 * <B STYLE='color: red;'>{@code ArithmeticException}</B> would otherwise be thrown. 258 * 259 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 260 * 261 * <BR />The flag-mask <B>{@link #RD_AEX}</B> is an abbreviated but identical value that may be 262 * used if brevity is a higher priority than readability. 263 * 264 * @see JsonArithmeticArrException 265 * @see JsonArithmeticObjException 266 */ 267 public static final int RETURN_DEFVAL_ON_AEX = RN_AEX << 1; 268 269 /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_AEX}</B> */ 270 public static final int RD_AEX = RETURN_DEFVAL_ON_AEX; 271 272 /** 273 * Instructs a get method to use a Standard Java Alternative / Rounding Method if an 274 * <B STYLE='color: red;'>{@code ArithmeticException}</B> would otherwise be thrown. 275 * 276 * <EMBED CLASS='external-html' DATA-FILE-ID=JRJF_APPROX> 277 * 278 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 279 * 280 * <BR />The flag-mask <B>{@link #RJA_AEX}</B> is an abbreviated but identical value that may 281 * be used if brevity is a higher priority than readability. 282 * 283 * @see JsonArithmeticArrException 284 * @see JsonArithmeticObjException 285 */ 286 public static final int RETURN_JAPPROX_ON_AEX = RD_AEX << 1; 287 288 /** Identical to flag-mask field <B>{@link #RETURN_JAPPROX_ON_AEX}</B> */ 289 public static final int RJA_AEX = RETURN_JAPPROX_ON_AEX; 290 291 /** 292 * Instructs a get method to <B STYLE='color: red;'>return null</B> in cases where a 293 * <B>{@link JsonObject}</B> property or <B>{@link JsonArray}</B> index does not contain the 294 * expected <B>Json-Type</B> 295 * 296 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 297 * 298 * <BR />The flag-mask <B>{@link #RN_WT}</B> is an abbreviated but identical value that may be 299 * used if brevity is a higher priority than readability. 300 * 301 * @see JsonTypeArrException 302 * @see JsonTypeObjException 303 */ 304 public static final int RETURN_NULL_ON_WRONG_JSONTYPE = RJA_AEX << 1; 305 306 /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_WRONG_JSONTYPE}</B> */ 307 public static final int RN_WT = RETURN_NULL_ON_WRONG_JSONTYPE; 308 309 /** 310 * Instructs a get method to return the user-provided 311 * <B STYLE='color: red;'>{@code 'defaultValue'}</B> in cases where a <B>{@link JsonObject}</B> 312 * property or <B>{@link JsonArray}</B> index does not contain the expected <B>Json-Type</B> 313 * 314 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 315 * 316 * <BR />The flag-mask <B>{@link #RD_WT}</B> is an abbreviated but identical value that may be 317 * used if brevity is a higher priority than readability. 318 * 319 * @see JsonTypeArrException 320 * @see JsonTypeObjException 321 */ 322 public static final int RETURN_DEFVAL_ON_WRONG_JSONTYPE = RN_WT << 1; 323 324 /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_WRONG_JSONTYPE}</B> */ 325 public static final int RD_WT = RETURN_DEFVAL_ON_WRONG_JSONTYPE; 326 327 /** 328 * Instructs a get method to <B STYLE='color: red;'>return null</B> in cases where a 329 * <B>{@link JsonObject}</B> property or <B>{@link JsonArray}</B> index contains a 330 * <B STYLE='color: red;'>zero-length</B> <B>{@link JsonString}</B> 331 * 332 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 333 * 334 * <BR />The flag-mask <B>{@link #RN_ZLS}</B> is an abbreviated but identical value that may be 335 * used if brevity is a higher priority than readability. 336 */ 337 public static final int RETURN_NULL_ON_0LEN_STR = RD_WT << 1; 338 339 /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_0LEN_STR}</B> */ 340 public static final int RN_ZLS = RETURN_NULL_ON_0LEN_STR; 341 342 /** 343 * Instructs a get method to return the user-provided 344 * <B STYLE='color: red;'>{@code 'defaultValue'}</B> in cases where a <B>{@link JsonObject}</B> 345 * property or <B>{@link JsonArray}</B> index contains a <B STYLE='color: red;'>zero-length</B> 346 * <B>{@link JsonString}</B> 347 * 348 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 349 * 350 * <BR />The flag-mask <B>{@link #RD_ZLS}</B> is an abbreviated but identical value that may be 351 * used if brevity is a higher priority than readability. 352 */ 353 public static final int RETURN_DEFVAL_ON_0LEN_STR = RN_ZLS << 1; 354 355 /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_0LEN_STR}</B> */ 356 public static final int RD_ZLS = RETURN_DEFVAL_ON_0LEN_STR; 357 358 /** 359 * Instructs a get method to <B STYLE='color: red;'>return null</B> in cases where the 360 * user-provided {@code 'parser'} function has thrown an exception. 361 * 362 * <BR /><BR /><B STYLE='color: red;'>SPEX: String Parse Exception</B> 363 * 364 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 365 * 366 * <BR />The flag-mask <B>{@link #RN_SPEX}</B> is an abbreviated but identical value that may 367 * be used if brevity is a higher priority than readability. 368 * 369 * @see JsonStrParseArrException 370 * @see JsonStrParseObjException 371 */ 372 public static final int RETURN_NULL_ON_SPEX = RD_ZLS << 1; 373 374 /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_SPEX}</B> */ 375 public static final int RN_SPEX = RETURN_NULL_ON_SPEX; 376 377 /** 378 * Instructs a get method to return the user-provided 379 * <B STYLE='color: red;'>{@code 'defaultValue'}</B> in cases where the user-provided 380 * {@code 'parser'} function has thrown an exception. 381 * 382 * <BR /><BR /><B STYLE='color: red;'>SPEX: String Parse Exception</B> 383 * 384 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 385 * 386 * <BR />The flag-mask <B>{@link #RD_SPEX}</B> is an abbreviated but identical value that may 387 * be used if brevity is a higher priority than readability. 388 * 389 * @see JsonStrParseArrException 390 * @see JsonStrParseObjException 391 */ 392 public static final int RETURN_DEFVAL_ON_SPEX = RN_SPEX << 1; 393 394 /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_SPEX}</B> */ 395 public static final int RD_SPEX = RETURN_DEFVAL_ON_SPEX; 396 397 398 // ******************************************************************************************** 399 // ******************************************************************************************** 400 // RJArrIntoPrimArray-Specific Flags 401 // ******************************************************************************************** 402 // ******************************************************************************************** 403 404 405 /** 406 * This is a "Primary Flag" that indicates the reader should always 407 * <B STYLE='color: red;'>skip</B> any array-entry for any exception-throw or error case that 408 * could possibly occur. 409 * 410 * <BR /><BR /><B CLASS=JDDescLabel>Flag Precedence:</B> 411 * 412 * <BR />When this flag is set, it always has the lowest precedence compared to all other 413 * flags. Specifically, if this flag, and the flag {@link #RETURN_DEFVAL_ON_AEX} were 414 * <B><I>both set</I></B>, and an {@code ArithmeticException} were going to be thrown, the 415 * user-provided default-value would be placed into the output, rather than being skipped. 416 * 417 * <BR /><BR />If both flag {@link #S_AA} and {@link #RN_AA} are set, 'null' will always 418 * be placed into the output, before skipping the array-index, or using the default-value. 419 * 420 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 421 * 422 * <BR />The flag-mask <B>{@link #S_AA}</B> is an abbreviated but identical value that may be 423 * used if brevity is a higher priority than readability. 424 */ 425 public static final int SKIP_ON_ANY_ALL = RD_SPEX << 1; 426 427 /** Identical to flag-mask field <B>{@link #SKIP_ON_ANY_ALL}</B> */ 428 public static final int S_AA = SKIP_ON_ANY_ALL; 429 430 /** 431 * Instructs an array / stream builder method to <B STYLE='color: red;'>skip</B> an array 432 * element, if-and-when a <B>{@link JsonArray}</B> index contain a <B>Json-Null</B>. 433 * 434 * <BR /><BR />When an array-index location is skipped during a converstion, the returned 435 * stream will simply have a size shorter than the input {@code JsonArray's} size<I>, shortened 436 * by the number of skipped-indices</I>. 437 * 438 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 439 * 440 * <BR />The flag-mask <B>{@link #S_N}</B> is an abbreviated but identical value that may be 441 * used if brevity is a higher priority than readability. 442 * 443 * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B> 444 * 445 * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only 446 * useful in {@link RJArrIntoPrimArray}. Any flag which begins with {@code 'SKIP'} will only 447 * be applied to array-processing methods. 448 */ 449 public static final int SKIP_ON_NULL = S_AA << 1; 450 451 /** Identical to flag-mask field <B>{@link #SKIP_ON_NULL}</B> */ 452 public static final int S_N = SKIP_ON_NULL; 453 454 /** 455 * Instructs an array / stream builder method to <B STYLE='color: red;'>skip</B> an array 456 * element, if-and-when if an <B STYLE='color: red;'>{@code ArithmeticException}</B> would 457 * otherwise be thrown. 458 * 459 * <BR /><BR />When an array-index location is skipped during a converstion, the returned 460 * stream will simply have a size shorter than the input {@code JsonArray's} size<I>, shortened 461 * by the number of skipped-indices</I>. 462 * 463 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 464 * 465 * <BR />The flag-mask <B>{@link #S_AEX}</B> is an abbreviated but identical value that may be 466 * used if brevity is a higher priority than readability. 467 * 468 * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B> 469 * 470 * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only 471 * useful in {@link RJArrIntoPrimArray}. Any flag which begins with {@code 'SKIP'} will only 472 * be applied to array-processing methods. 473 */ 474 public static final int SKIP_ON_AEX = S_N << 1; 475 476 /** Identical to flag-mask field <B>{@link #SKIP_ON_AEX}</B> */ 477 public static final int S_AEX = SKIP_ON_AEX; 478 479 /** 480 * Instructs an array / stream builder method to <B STYLE='color: red;'>parse</B> an array 481 * element into a number, if-and-when a <B>{@link JsonString}</B> is encountered. 482 * 483 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 484 * 485 * <BR />The flag-mask <B>{@link #RP_S}</B> is an abbreviated but identical value that may be 486 * used if brevity is a higher priority than readability. 487 * 488 * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B> 489 * 490 * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only 491 * useful in {@link RJArrIntoPrimArray}. 492 */ 493 public static final int RETURN_PARSE_ON_STR = S_AEX << 1; 494 495 /** Identical to flag-mask field <B>{@link #RETURN_PARSE_ON_STR}</B> */ 496 public static final int RP_S = RETURN_PARSE_ON_STR; 497 498 /** 499 * Instructs a boxed-stream builder method to insert <B STYLE='color: red;'>Java-Null</B> 500 * into the boxed-stream whenever a <B>{@link JsonArray}</B> index contains a 501 * {@link JsonString}. 502 * 503 * <BR /><BR />This flag is ignored if passed to a primitive-stream builder method. A 504 * primitive-stream (and its associated builder) will not accept nulls. 505 * 506 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 507 * 508 * <BR />The flag-mask <B>{@link #RN_S}</B> is an abbreviated but identical value that may be 509 * used if brevity is a higher priority than readability. 510 * 511 * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B> 512 * 513 * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only 514 * useful in {@link RJArrIntoPrimArray}. 515 */ 516 public static final int RETURN_NULL_ON_STR = RP_S << 1; 517 518 /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_STR}</B> */ 519 public static final int RN_S = RETURN_NULL_ON_STR; 520 521 /** 522 * Instructs an array / stream builder method to insert the user-provided 523 * <B STYLE='color: red;'>{@code 'defaultValue'}</B> whenever a {@link JsonString} is 524 * encountered at a particular index inside a {@link JsonArray}. 525 * 526 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 527 * 528 * <BR />The flag-mask <B>{@link #RD_S}</B> is an abbreviated but identical value that may be 529 * used if brevity is a higher priority than readability. 530 * 531 * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B> 532 * 533 * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only 534 * useful in {@link RJArrIntoPrimArray}. 535 */ 536 public static final int RETURN_DEFVAL_ON_STR = RN_S << 1; 537 538 /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_STR}</B> */ 539 public static final int RD_S = RETURN_DEFVAL_ON_STR; 540 541 /** 542 * Instructs an array / stream builder method to <B STYLE='color: red;'>skip</B> any 543 * {@link JsonArray} index-locations that contain a {@link JsonString}. 544 * 545 * <BR /><BR />When an array-index location is skipped during a converstion, the returned 546 * stream will simply have a size shorter than the input {@code JsonArray's} size<I>, shortened 547 * by the number of skipped-indices</I>. 548 * 549 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 550 * 551 * <BR />The flag-mask <B>{@link #S_S}</B> is an abbreviated but identical value that may be 552 * used if brevity is a higher priority than readability. 553 * 554 * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B> 555 * 556 * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only 557 * useful in {@link RJArrIntoPrimArray}. Any flag which begins with {@code 'SKIP'} will only 558 * be applied to array-processing methods. 559 */ 560 public static final int SKIP_ON_STR = RD_S << 1; 561 562 /** Identical to flag-mask field <B>{@link #SKIP_ON_STR}</B> */ 563 public static final int S_S = SKIP_ON_STR; 564 565 /** 566 * Instructs an array / stream builder method to <B STYLE='color: red;'>skip</B> any 567 * {@link JsonArray} index-locations that contain a <B STYLE='color: red'>Zero-Length</B> 568 * {@link JsonString}. 569 * 570 * <BR /><BR />When an array-index location is skipped during a converstion, the returned 571 * stream will simply have a size shorter than the input {@code JsonArray's} size<I>, shortened 572 * by the number of skipped-indices</I>. 573 * 574 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 575 * 576 * <BR />The flag-mask <B>{@link #S_ZLS}</B> is an abbreviated but identical value that may be 577 * used if brevity is a higher priority than readability. 578 * 579 * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B> 580 * 581 * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only 582 * useful in {@link RJArrIntoPrimArray}. Any flag which begins with {@code 'SKIP'} will only 583 * be applied to array-processing methods. 584 */ 585 public static final int SKIP_ON_0LEN_STR = S_S << 1; 586 587 /** Identical to flag-mask field <B>{@link #SKIP_ON_0LEN_STR}</B> */ 588 public static final int S_ZLS = SKIP_ON_0LEN_STR; 589 590 /** 591 * Instructs an array / stream builder method to <B STYLE='color: red;'>skip</B> any 592 * {@link JsonArray} index-locations that contain a {@link JsonString} that, when parsed, 593 * generate any parse-exceptions, such as {@code NumberFormatException}. 594 * 595 * <BR /><BR />When an array-index location is skipped during a converstion, the returned 596 * stream will simply have a size shorter than the input {@code JsonArray's} size<I>, shortened 597 * by the number of skipped-indices</I>. 598 * 599 * <BR /><BR /><B STYLE='color: red;'>SPEX: String Parse Exception</B> 600 * 601 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 602 * 603 * <BR />The flag-mask <B>{@link #S_SPEX}</B> is an abbreviated but identical value that may be 604 * used if brevity is a higher priority than readability. 605 * 606 * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B> 607 * 608 * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only 609 * useful in {@link RJArrIntoPrimArray}. Any flag which begins with {@code 'SKIP'} will only 610 * be applied to array-processing methods. 611 */ 612 public static final int SKIP_ON_SPEX = S_ZLS << 1; 613 614 /** Identical to flag-mask field <B>{@link #SKIP_ON_SPEX}</B> */ 615 public static final int S_SPEX = SKIP_ON_SPEX; 616 617 /** 618 * Instructs an array / stream builder method to <B STYLE='color: red;'>skip</B> any 619 * {@link JsonArray} index-locations that contain an inapplicable 620 * <B STYLE='color: red;'>Json-Type</B> - such as {@code JsonValue.TRUE}, 621 * {@code JsonValue.FALSE}, {@code JsonObject}, a nested {@code JsonArray} etc... 622 * 623 * <BR /><BR />When an array-index location is skipped during a converstion, the returned 624 * stream will simply have a size shorter than the input {@code JsonArray's} size<I>, shortened 625 * by the number of skipped-indices</I>. 626 * 627 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 628 * 629 * <BR />The flag-mask <B>{@link #S_WT}</B> is an abbreviated but identical value that may be 630 * used if brevity is a higher priority than readability. 631 * 632 * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B> 633 * 634 * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only 635 * useful in {@link RJArrIntoPrimArray}. Any flag which begins with {@code 'SKIP'} will only 636 * be applied to array-processing methods. 637 */ 638 public static final int SKIP_ON_WRONG_JSONTYPE = S_SPEX << 1; 639 640 /** Identical to flag-mask field <B>{@link #SKIP_ON_WRONG_JSONTYPE}</B> */ 641 public static final int S_WT = SKIP_ON_WRONG_JSONTYPE; 642 643 644 // ******************************************************************************************** 645 // ******************************************************************************************** 646 // ADDITIONAL: RJArrIntoPrimArray-Specific Flags 647 // ******************************************************************************************** 648 // ******************************************************************************************** 649 650 651 /** 652 * Instructs the {@code Stream<String>} (array/stream) builder method to invoke 653 * {@link JsonValue#toString} whenever a type other than {@link JsonString} is found in an 654 * array position. This flag is only applicable when converting a {@link JsonArray} into a 655 * {@code String[]}-Array. 656 * 657 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 658 * 659 * <BR />The flag-mask <B>{@link #RTS_WT}</B> is an abbreviated but identical value that may be 660 * used if brevity is a higher priority than readability. 661 * 662 * <BR /><BR /><B CLASS=JDDescLabel>For Specific Method Only:</B> 663 * 664 * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only 665 * useful in invocations of method {@link RJArrIntoStream#strArr}. 666 */ 667 public static final int RETURN_TOSTRING_ON_WRONGTYPE = S_WT << 1; 668 669 /** Identical to flag-mask field <B>{@link #RETURN_TOSTRING_ON_WRONGTYPE}</B> */ 670 public static final int RTS_WT = RETURN_TOSTRING_ON_WRONGTYPE; 671 672 673 // ******************************************************************************************** 674 // ******************************************************************************************** 675 // ADDITIONAL: RJArrDimN Specific Flags 676 // ******************************************************************************************** 677 // ******************************************************************************************** 678 679 680 /** 681 * Instructs the multi-dimensional array-builder method to place a null in an array when 682 * it encounters a {@link JsonArray} element that is not a sub-array, but rather some other 683 * non-null <B STYLE='color: red;'>Json-Type</B> This flag is only applicable when converting 684 * a {@link JsonArray} using one of the multi-dimensional array-processors in class 685 * {@link RJArrDimN}. 686 * 687 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 688 * 689 * <BR />The flag-mask <B>{@link #IN_NSAT}</B> is an abbreviated but identical value that may 690 * be used if brevity is a higher priority than readability. 691 * 692 * <BR /><BR /><B CLASS=JDDescLabel>For Reading Multi-Dimensional Arrays Only:</B> 693 * 694 * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON} and in 695 * {@link RJArrIntoPrimArray}. It is only used in processing multi-dimensional arrays (by 696 * class {@link RJArrDimN}). 697 */ 698 public static final int INSERT_NULL_ON_NON_SUBARRAY_TYPE = RTS_WT << 1; 699 700 /** Identical to flag-mask field <B>{@link #INSERT_NULL_ON_NON_SUBARRAY_TYPE}</B> */ 701 public static final int IN_NSAT = INSERT_NULL_ON_NON_SUBARRAY_TYPE; 702 703 /** 704 * Instructs the multi-dimensional array-builder method to skip the element when it encounters 705 * a {@link JsonArray} element that is not a sub-array, but rather some other non-null 706 * <B STYLE='color: red;'>Json-Type</B> This flag is only applicable when converting 707 * a {@link JsonArray} using one of the multi-dimensional array-processors in class 708 * {@link RJArrDimN}. 709 * 710 * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B> 711 * 712 * <BR />The flag-mask <B>{@link #S_NSAT}</B> is an abbreviated but identical value that may be 713 * used if brevity is a higher priority than readability. 714 * 715 * <BR /><BR /><B CLASS=JDDescLabel>For Reading Multi-Dimensional Arrays Only:</B> 716 * 717 * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON} and in 718 * {@link RJArrIntoPrimArray}. It is only used in processing multi-dimensional arrays (by 719 * class {@link RJArrDimN}). 720 */ 721 public static final int SKIP_ON_NON_SUBARRAY_TYPE = IN_NSAT << 1; 722 723 /** Identical to flag-mask field <B>{@link #SKIP_ON_NON_SUBARRAY_TYPE}</B> */ 724 public static final int S_NSAT = SKIP_ON_NON_SUBARRAY_TYPE; 725 726 /** 727 * These are eliminated / removed from any call to a method which returns either an array 728 * of Java Primitives or a Java Primitive Stream. These are also filtered from a call to class 729 * that invokes a Java Primitive-Consumer 730 * 731 * @see RJArrIntoPrimStream#intArr(JsonArray, int, int, ToIntFunction) 732 * @see RJArrIntoPrimStream#longArr(JsonArray, long, int, ToLongFunction) 733 * @see RJArrIntoPrimStream#doubleArr(JsonArray, double, int, ToDoubleFunction) 734 * 735 * @see RJArrIntoPrimConsumer 736 */ 737 public static final int NOT_ALLOWED_RET_NULL_MASKS = ~(RETURN_NULL_ON_ANY_ALL | 738 RETURN_NULL_ON_AEX | RETURN_NULL_ON_NULL | RETURN_NULL_ON_SPEX | RETURN_NULL_ON_STR | 739 RETURN_NULL_ON_0LEN_STR | RETURN_NULL_ON_WRONG_JSONTYPE | INSERT_NULL_ON_NON_SUBARRAY_TYPE); 740}