001/* 002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 003 * 004 * Copyright (c) 2013-2018 Oracle and/or its affiliates. All rights reserved. 005 * 006 * The contents of this file are subject to the terms of either the GNU 007 * General Public License Version 2 only ("GPL") or the Common Development 008 * and Distribution License("CDDL") (collectively, the "License"). You 009 * may not use this file except in compliance with the License. You can 010 * obtain a copy of the License at 011 * https://oss.oracle.com/licenses/CDDL+GPL-1.1 012 * or LICENSE.txt. See the License for the specific 013 * language governing permissions and limitations under the License. 014 * 015 * When distributing the software, include this License Header Notice in each 016 * file and include the License file at LICENSE.txt. 017 * 018 * GPL Classpath Exception: 019 * Oracle designates this particular file as subject to the "Classpath" 020 * exception as provided by Oracle in the GPL Version 2 section of the License 021 * file that accompanied this code. 022 * 023 * Modifications: 024 * If applicable, add the following below the License Header, with the fields 025 * enclosed by brackets [] replaced by your own identifying information: 026 * "Portions Copyright [year] [name of copyright owner]" 027 * 028 * Contributor(s): 029 * If you wish your version of this file to be governed by only the CDDL or 030 * only the GPL Version 2, indicate your decision by adding "[Contributor] 031 * elects to include this software in this distribution under the [CDDL or GPL 032 * Version 2] license." If you don't indicate a single choice of license, a 033 * recipient has the option to distribute your version of this file under 034 * either the CDDL, the GPL Version 2 or to extend the choice of license to 035 * its licensees as provided above. However, if you add GPL Version 2 code 036 * and therefore, elected the GPL Version 2 license, then the option applies 037 * only if the new code is made subject to such option by the copyright 038 * holder. 039 */ 040 041package javax.json; 042 043import java.math.BigDecimal; 044import java.math.BigInteger; 045 046/** 047 * A builder for creating {@link JsonArray} models from scratch, and for 048 * modifying a existing {@code JsonArray}. 049 * 050 * <EMBED CLASS='external-html' DATA-FILE-ID=LICENSE DATA-CIETName=JsonArrayBuilder> 051 * 052 * <BR /><BR />A {@code JsonArrayBuilder} can start with an empty or a non-empty 053 * JSON array model. This interface provides methods to add, insert, remove 054 * and replace values in the JSON array model. 055 * 056 * <BR /><BR />Methods in this class can be chained to perform multiple values to 057 * the array. 058 * 059 * <BR /><BR />The class {@link javax.json.Json} contains methods to create the builder 060 * object. The example code below shows how to build an empty {@code JsonArray} 061 * instance. 062 * 063 * <BR /><DIV CLASS=SNIP>{@code 064 * JsonArray array = Json.createArrayBuilder().build(); 065 * }</DIV> 066 * 067 * <BR /><BR />The class {@link JsonBuilderFactory} also contains methods to create 068 * {@code JsonArrayBuilder} instances. A factory instance can be used to create 069 * multiple builder instances with the same configuration. This the preferred 070 * way to create multiple instances. 071 * 072 * <BR /><BR />The example code below shows how to build a {@code JsonArray} object 073 * that represents the following JSON array: 074 * 075 * <DIV CLASS=JSON>{@code 076 * [ 077 * { "type": "home", "number": "212 555-1234" }, 078 * { "type": "fax", "number": "646 555-4567" } 079 * ] 080 * }</DIV> 081 * 082 * <BR />The following code creates the JSON array above: 083 * 084 * <DIV CLASS=EXAMPLE>{@code 085 * JsonBuilderFactory factory = Json.createBuilderFactory(config); 086 * 087 * JsonArray value = factory 088 * .createArrayBuilder() 089 * .add(factory.createObjectBuilder() 090 * .add("type", "home") 091 * .add("number", "212 555-1234")) 092 * .add(factory.createObjectBuilder() 093 * .add("type", "fax") 094 * .add("number", "646 555-4567")) 095 * .build(); 096 * }</DIV> 097 * 098 * <BR />This class does <em>not</em> allow <code>null</code> to be used as a 099 * value while building the JSON array 100 * 101 * @see JsonObjectBuilder 102 */ 103public interface JsonArrayBuilder { 104 105 /** 106 * Adds a value to the array. 107 * 108 * @param value the JSON value 109 * @return this array builder 110 * @throws NullPointerException if the specified value is null 111 */ 112 JsonArrayBuilder add(JsonValue value); 113 114 /** 115 * Adds a value to the array as a {@link JsonString}. 116 * 117 * @param value the string value 118 * @return this array builder 119 * @throws NullPointerException if the specified value is null 120 */ 121 JsonArrayBuilder add(String value); 122 123 /** 124 * Adds a value to the array as a {@link JsonNumber}. 125 * 126 * @param value the number value 127 * @return this array builder 128 * @throws NullPointerException if the specified value is null 129 * 130 * @see JsonNumber 131 */ 132 JsonArrayBuilder add(BigDecimal value); 133 134 /** 135 * Adds a value to the array as a {@link JsonNumber}. 136 * 137 * @param value the number value 138 * @return this array builder 139 * @throws NullPointerException if the specified value is null 140 * 141 * @see JsonNumber 142 */ 143 JsonArrayBuilder add(BigInteger value); 144 145 /** 146 * Adds a value to the array as a {@link JsonNumber}. 147 * 148 * @param value the number value 149 * @return this array builder 150 * 151 * @see JsonNumber 152 */ 153 JsonArrayBuilder add(int value); 154 155 /** 156 * Adds a value to the array as a {@link JsonNumber}. 157 * 158 * @param value the number value 159 * @return this array builder 160 * 161 * @see JsonNumber 162 */ 163 JsonArrayBuilder add(long value); 164 165 /** 166 * Adds a value to the array as a {@link JsonNumber}. 167 * 168 * @param value the number value 169 * @return this array builder 170 * @throws NumberFormatException if the value is Not-a-Number (NaN) or 171 * infinity 172 * 173 * @see JsonNumber 174 */ 175 JsonArrayBuilder add(double value); 176 177 /** 178 * Adds a {@link JsonValue#TRUE} or {@link JsonValue#FALSE} value to the 179 * array. 180 * 181 * @param value the boolean value 182 * @return this array builder 183 */ 184 JsonArrayBuilder add(boolean value); 185 186 /** 187 * Adds a {@link JsonValue#NULL} value to the array. 188 * 189 * @return this array builder 190 */ 191 JsonArrayBuilder addNull(); 192 193 /** 194 * Adds a {@link JsonObject} from an object builder to the array. 195 * 196 * @param builder the object builder 197 * @return this array builder 198 * @throws NullPointerException if the specified builder is null 199 */ 200 JsonArrayBuilder add(JsonObjectBuilder builder); 201 202 /** 203 * Adds a {@link JsonArray} from an array builder to the array. 204 * 205 * @param builder the array builder 206 * @return this array builder 207 * @throws NullPointerException if the specified builder is null 208 */ 209 JsonArrayBuilder add(JsonArrayBuilder builder); 210 211 /** 212 * Adds all elements of the array in the specified array builder to the array. 213 * 214 * @param builder the array builder 215 * @return this array builder 216 * @throws NullPointerException if the specified builder is null 217 * 218 @since 1.1 219 */ 220 default JsonArrayBuilder addAll(JsonArrayBuilder builder) { 221 throw new UnsupportedOperationException(); 222 } 223 224 /** 225 * Inserts a value to the array at the specified position. Shifts the value 226 * currently at that position (if any) and any subsequent values to the right 227 * (adds one to their indices). Index starts with 0. 228 * 229 * @param index the position in the array 230 * @param value the JSON value 231 * @return this array builder 232 * @throws NullPointerException if the specified value is null 233 * @throws IndexOutOfBoundsException if the index is out of range 234 * {@code (index < 0 || index > array size)} 235 * 236 * @since 1.1 237 */ 238 default JsonArrayBuilder add(int index, JsonValue value) { 239 throw new UnsupportedOperationException(); 240 } 241 242 /** 243 * Adds a value to the array as a {@link JsonString} at the specified position. 244 * Shifts the value currently at that position (if any) and any subsequent values 245 * to the right (adds one to their indices). Index starts with 0. 246 * 247 * @param index the position in the array 248 * @param value the string value 249 * @return this array builder 250 * @throws NullPointerException if the specified value is null 251 * @throws IndexOutOfBoundsException if the index is out of range 252 * {@code (index < 0 || index > array size)} 253 * 254 * @since 1.1 255 */ 256 default JsonArrayBuilder add(int index, String value) { 257 throw new UnsupportedOperationException(); 258 } 259 260 /** 261 * Adds a value to the array as a {@link JsonNumber} at the specified position. 262 * Shifts the value currently at that position (if any) and any subsequent values 263 * to the right (adds one to their indices). Index starts with 0. 264 * 265 * @param index the position in the array 266 * @param value the number value 267 * @return this array builder 268 * @throws NullPointerException if the specified value is null 269 * @throws IndexOutOfBoundsException if the index is out of range 270 * {@code (index < 0 || index > array size)} 271 * 272 * @see JsonNumber 273 * 274 * @since 1.1 275 */ 276 default JsonArrayBuilder add(int index, BigDecimal value) { 277 throw new UnsupportedOperationException(); 278 } 279 280 /** 281 * Adds a value to the array as a {@link JsonNumber} at the specified position. 282 * Shifts the value currently at that position (if any) and any subsequent values 283 * to the right (adds one to their indices). Index starts with 0. 284 * 285 * @param index the position in the array 286 * @param value the number value 287 * @return this array builder 288 * @throws NullPointerException if the specified value is null 289 * @throws IndexOutOfBoundsException if the index is out of range 290 * {@code (index < 0 || index > array size)} 291 * 292 * @see JsonNumber 293 * 294 * @since 1.1 295 */ 296 default JsonArrayBuilder add(int index, BigInteger value) { 297 throw new UnsupportedOperationException(); 298 } 299 300 /** 301 * Adds a value to the array as a {@link JsonNumber} at the specified position. 302 * Shifts the value currently at that position (if any) and any subsequent values 303 * to the right (adds one to their indices). Index starts with 0. 304 * 305 * @param index the position in the array 306 * @param value the number value 307 * @return this array builder 308 * @throws IndexOutOfBoundsException if the index is out of range 309 * {@code (index < 0 || index > array size)} 310 * 311 * @see JsonNumber 312 * 313 * @since 1.1 314 */ 315 default JsonArrayBuilder add(int index, int value) { 316 throw new UnsupportedOperationException(); 317 } 318 319 /** 320 * Adds a value to the array as a {@link JsonNumber} at the specified position. 321 * Shifts the value currently at that position (if any) and any subsequent values 322 * to the right (adds one to their indices). Index starts with 0. 323 * 324 * @param index the position in the array 325 * @param value the number value 326 * @return this array builder 327 * @throws IndexOutOfBoundsException if the index is out of range 328 * {@code (index < 0 || index > array size)} 329 * 330 * @see JsonNumber 331 * 332 * @since 1.1 333 */ 334 default JsonArrayBuilder add(int index, long value) { 335 throw new UnsupportedOperationException(); 336 } 337 338 /** 339 * Adds a value to the array as a {@link JsonNumber} at the specified position. 340 * Shifts the value currently at that position (if any) and any subsequent values 341 * to the right (adds one to their indices). Index starts with 0. 342 * 343 * @param index the position in the array 344 * @param value the number value 345 * @return this array builder 346 * @throws NumberFormatException if the value is Not-a-Number (NaN) or 347 * infinity 348 * @throws IndexOutOfBoundsException if the index is out of range 349 * {@code (index < 0 || index > array size)} 350 * 351 * @see JsonNumber 352 * 353 * @since 1.1 354 */ 355 default JsonArrayBuilder add(int index, double value) { 356 throw new UnsupportedOperationException(); 357 } 358 359 /** 360 * Adds a {@link JsonValue#TRUE} or {@link JsonValue#FALSE} value to the 361 * array at the specified position. 362 * Shifts the value currently at that position (if any) and any subsequent values 363 * to the right (adds one to their indices). Index starts with 0. 364 * 365 * @param index the position in the array 366 * @param value the boolean value 367 * @return this array builder 368 * @throws IndexOutOfBoundsException if the index is out of range 369 * {@code (index < 0 || index > array size)} 370 * 371 * @since 1.1 372 */ 373 default JsonArrayBuilder add(int index, boolean value) { 374 throw new UnsupportedOperationException(); 375 } 376 377 /** 378 * Adds a {@link JsonValue#NULL} value to the array at the specified position. 379 * Shifts the value currently at that position (if any) and any subsequent values 380 * to the right (adds one to their indices). Index starts with 0. 381 * 382 * @param index the position in the array 383 * @return this array builder 384 * @throws IndexOutOfBoundsException if the index is out of range 385 * {@code (index < 0 || index > array size)} 386 * 387 * @since 1.1 388 */ 389 default JsonArrayBuilder addNull(int index) { 390 return add(index, JsonValue.NULL); 391 } 392 393 /** 394 * Adds a {@link JsonObject} from an object builder to the array at the specified position. 395 * Shifts the value currently at that position (if any) and any subsequent values 396 * to the right (adds one to their indices). Index starts with 0. 397 * 398 * @param index the position in the array 399 * @param builder the object builder 400 * @return this array builder 401 * @throws NullPointerException if the specified builder is null 402 * @throws IndexOutOfBoundsException if the index is out of range 403 * {@code (index < 0 || index > array size)} 404 * 405 * @since 1.1 406 */ 407 default JsonArrayBuilder add(int index, JsonObjectBuilder builder) { 408 throw new UnsupportedOperationException(); 409 } 410 411 /** 412 * Adds a {@link JsonArray} from an array builder to the array at the specified position. 413 * Shifts the value currently at that position (if any) and any subsequent values 414 * to the right (adds one to their indices). Index starts with 0. 415 * 416 * @param index the position in the array 417 * @param builder the array builder 418 * @return this array builder 419 * @throws NullPointerException if the specified builder is null 420 * @throws IndexOutOfBoundsException if the index is out of range 421 * {@code (index < 0 || index > array size)} 422 * 423 * @since 1.1 424 */ 425 default JsonArrayBuilder add(int index, JsonArrayBuilder builder) { 426 throw new UnsupportedOperationException(); 427 } 428 429 /** 430 * Replaces a value in the array with the specified value at the 431 * specified position. 432 * 433 * @param index the position in the array 434 * @param value the JSON value 435 * @return this array builder 436 * @throws NullPointerException if the specified value is null 437 * @throws IndexOutOfBoundsException if the index is out of range 438 * {@code (index < 0 || index >= array size)} 439 * 440 * @since 1.1 441 */ 442 default JsonArrayBuilder set(int index, JsonValue value) { 443 throw new UnsupportedOperationException(); 444 } 445 446 /** 447 * Replaces a value in the array with the specified value as a 448 * {@link JsonString} at the specified position. 449 * 450 * @param index the position in the array 451 * @param value the string value 452 * @return this array builder 453 * @throws NullPointerException if the specified value is null 454 * @throws IndexOutOfBoundsException if the index is out of range 455 * {@code (index < 0 || index >= array size)} 456 * 457 * @since 1.1 458 */ 459 default JsonArrayBuilder set(int index, String value) { 460 throw new UnsupportedOperationException(); 461 } 462 463 /** 464 * Replaces a value in the array with the specified value as a 465 * {@link JsonNumber} at the specified position. 466 * 467 * @param index the position in the array 468 * @param value the number value 469 * @return this array builder 470 * @throws NullPointerException if the specified value is null 471 * @throws IndexOutOfBoundsException if the index is out of range 472 * {@code (index < 0 || index >= array size)} 473 * 474 * @see JsonNumber 475 * 476 * @since 1.1 477 */ 478 default JsonArrayBuilder set(int index, BigDecimal value) { 479 throw new UnsupportedOperationException(); 480 } 481 482 /** 483 * Replaces a value in the array with the specified value as a 484 * {@link JsonNumber} at the specified position. 485 * 486 * @param index the position in the array 487 * @param value the number value 488 * @return this array builder 489 * @throws NullPointerException if the specified value is null 490 * @throws IndexOutOfBoundsException if the index is out of range 491 * {@code (index < 0 || index >= array size)} 492 * 493 * @see JsonNumber 494 * 495 * @since 1.1 496 */ 497 default JsonArrayBuilder set(int index, BigInteger value) { 498 throw new UnsupportedOperationException(); 499 } 500 501 /** 502 * Replaces a value in the array with the specified value as a 503 * {@link JsonNumber} at the specified position. 504 * 505 * @param index the position in the array 506 * @param value the number value 507 * @return this array builder 508 * @throws IndexOutOfBoundsException if the index is out of range 509 * {@code (index < 0 || index >= array size)} 510 * 511 * @see JsonNumber 512 * 513 * @since 1.1 514 */ 515 default JsonArrayBuilder set(int index, int value) { 516 throw new UnsupportedOperationException(); 517 } 518 519 /** 520 * Replaces a value in the array with the specified value as a 521 * {@link JsonNumber} at the specified position. 522 * 523 * @param index the position in the array 524 * @param value the number value 525 * @return this array builder 526 * @throws IndexOutOfBoundsException if the index is out of range 527 * {@code (index < 0 || index >= array size)} 528 * 529 * @see JsonNumber 530 * 531 * @since 1.1 532 */ 533 default JsonArrayBuilder set(int index, long value) { 534 throw new UnsupportedOperationException(); 535 } 536 537 /** 538 * Replaces a value in the array with the specified value as a 539 * {@link JsonNumber} at the specified position. 540 * 541 * @param index the position in the array 542 * @param value the number value 543 * @return this array builder 544 * @throws NumberFormatException if the value is Not-a-Number (NaN) or 545 * infinity 546 * @throws IndexOutOfBoundsException if the index is out of range 547 * {@code (index < 0 || index >= array size)} 548 * 549 * @see JsonNumber 550 * 551 * @since 1.1 552 */ 553 default JsonArrayBuilder set(int index, double value) { 554 throw new UnsupportedOperationException(); 555 } 556 557 /** 558 * Replaces a value in the array with 559 * a {@link JsonValue#TRUE} or {@link JsonValue#FALSE} value 560 * at the specified position. 561 * 562 * @param index the position in the array 563 * @param value the boolean value 564 * @return this array builder 565 * @throws IndexOutOfBoundsException if the index is out of range 566 * {@code (index < 0 || index >= array size)} 567 * 568 * @since 1.1 569 */ 570 default JsonArrayBuilder set(int index, boolean value) { 571 throw new UnsupportedOperationException(); 572 } 573 574 /** 575 * Replaces a value in the array with 576 * a {@link JsonValue#NULL} value at the specified position. 577 * 578 * @param index the position in the array 579 * @return this array builder 580 * @throws IndexOutOfBoundsException if the index is out of range 581 * {@code (index < 0 || index >= array size)} 582 * 583 * @since 1.1 584 */ 585 default JsonArrayBuilder setNull(int index) { 586 return set(index, JsonValue.NULL); 587 } 588 589 /** 590 * Replaces a value in the array with the specified value as a 591 * {@link JsonObject} from an object builder at the specified position. 592 * 593 * @param index the position in the array 594 * @param builder the object builder 595 * @return this array builder 596 * @throws NullPointerException if the specified builder is null 597 * @throws IndexOutOfBoundsException if the index is out of range 598 * {@code (index < 0 || index >= array size)} 599 * 600 * @since 1.1 601 */ 602 default JsonArrayBuilder set(int index, JsonObjectBuilder builder) { 603 throw new UnsupportedOperationException(); 604 } 605 606 /** 607 * Replaces a value in the array with the specified value as a 608 * {@link JsonArray} from an array builder at the specified position. 609 * 610 * @param index the position in the array 611 * @param builder the array builder 612 * @return this array builder 613 * @throws NullPointerException if the specified builder is null 614 * @throws IndexOutOfBoundsException if the index is out of range 615 * {@code (index < 0 || index >= array size)} 616 * 617 * @since 1.1 618 */ 619 default JsonArrayBuilder set(int index, JsonArrayBuilder builder) { 620 throw new UnsupportedOperationException(); 621 } 622 623 /** 624 * Remove the value in the array at the specified position. 625 * Shift any subsequent values to the left (subtracts one from their 626 * indices. 627 * 628 * @param index the position in the array 629 * @return this array builder 630 * @throws IndexOutOfBoundsException if the index is out of range 631 * {@code (index < 0 || index >= array size)} 632 * 633 * @since 1.1 634 */ 635 default JsonArrayBuilder remove(int index) { 636 throw new UnsupportedOperationException(); 637 } 638 639 /** 640 * Returns the current array. 641 * 642 * @return the current JSON array 643 */ 644 JsonArray build(); 645 646} 647