source: josm/trunk/src/javax/json/JsonArrayBuilder.java@ 15724

Last change on this file since 15724 was 13231, checked in by Don-vip, 7 years ago

see #15682 - upgrade to JSR 374 (JSON Processing) API 1.1.2
File size: 21.4 KB
Line 
1/*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright (c) 2013-2017 Oracle and/or its affiliates. All rights reserved.
5 *
6 * The contents of this file are subject to the terms of either the GNU
7 * General Public License Version 2 only ("GPL") or the Common Development
8 * and Distribution License("CDDL") (collectively, the "License"). You
9 * may not use this file except in compliance with the License. You can
10 * obtain a copy of the License at
11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
12 * or LICENSE.txt. See the License for the specific
13 * language governing permissions and limitations under the License.
14 *
15 * When distributing the software, include this License Header Notice in each
16 * file and include the License file at LICENSE.txt.
17 *
18 * GPL Classpath Exception:
19 * Oracle designates this particular file as subject to the "Classpath"
20 * exception as provided by Oracle in the GPL Version 2 section of the License
21 * file that accompanied this code.
22 *
23 * Modifications:
24 * If applicable, add the following below the License Header, with the fields
25 * enclosed by brackets [] replaced by your own identifying information:
26 * "Portions Copyright [year] [name of copyright owner]"
27 *
28 * Contributor(s):
29 * If you wish your version of this file to be governed by only the CDDL or
30 * only the GPL Version 2, indicate your decision by adding "[Contributor]
31 * elects to include this software in this distribution under the [CDDL or GPL
32 * Version 2] license." If you don't indicate a single choice of license, a
33 * recipient has the option to distribute your version of this file under
34 * either the CDDL, the GPL Version 2 or to extend the choice of license to
35 * its licensees as provided above. However, if you add GPL Version 2 code
36 * and therefore, elected the GPL Version 2 license, then the option applies
37 * only if the new code is made subject to such option by the copyright
38 * holder.
39 */
40
41package javax.json;
42
43import java.math.BigDecimal;
44import java.math.BigInteger;
45
46/**
47 * A builder for creating {@link JsonArray} models from scratch, and for
48 * modifying a existing {@code JsonArray}.
49 * <p>A {@code JsonArrayBuilder} can start with an empty or a non-empty
50 * JSON array model. This interface provides methods to add, insert, remove
51 * and replace values in the JSON array model.</p>
52 * <p>Methods in this class can be chained to perform multiple values to
53 * the array.</p>
54 *
55 * <p>The class {@link javax.json.Json} contains methods to create the builder
56 * object. The example code below shows how to build an empty {@code JsonArray}
57 * instance.
58 * <pre>
59 * <code>
60 * JsonArray array = Json.createArrayBuilder().build();
61 * </code>
62 * </pre>
63 *
64 * <p>The class {@link JsonBuilderFactory} also contains methods to create
65 * {@code JsonArrayBuilder} instances. A factory instance can be used to create
66 * multiple builder instances with the same configuration. This the preferred
67 * way to create multiple instances.
68 *
69 * The example code below shows how to build a {@code JsonArray} object
70 * that represents the following JSON array:
71 *
72 * <pre>
73 * <code>
74 * [
75 * { "type": "home", "number": "212 555-1234" },
76 * { "type": "fax", "number": "646 555-4567" }
77 * ]
78 * </code>
79 * </pre>
80 *
81 * <p>The following code creates the JSON array above:
82 *
83 * <pre>
84 * <code>
85 * JsonBuilderFactory factory = Json.createBuilderFactory(config);
86 * JsonArray value = factory.createArrayBuilder()
87 * .add(factory.createObjectBuilder()
88 * .add("type", "home")
89 * .add("number", "212 555-1234"))
90 * .add(factory.createObjectBuilder()
91 * .add("type", "fax")
92 * .add("number", "646 555-4567"))
93 * .build();
94 * </code>
95 * </pre>
96 *
97 * <p>This class does <em>not</em> allow <tt>null</tt> to be used as a
98 * value while building the JSON array
99 *
100 * @see JsonObjectBuilder
101 */
102public interface JsonArrayBuilder {
103
104 /**
105 * Adds a value to the array.
106 *
107 * @param value the JSON value
108 * @return this array builder
109 * @throws NullPointerException if the specified value is null
110 */
111 JsonArrayBuilder add(JsonValue value);
112
113 /**
114 * Adds a value to the array as a {@link JsonString}.
115 *
116 * @param value the string value
117 * @return this array builder
118 * @throws NullPointerException if the specified value is null
119 */
120 JsonArrayBuilder add(String value);
121
122 /**
123 * Adds a value to the array as a {@link JsonNumber}.
124 *
125 * @param value the number value
126 * @return this array builder
127 * @throws NullPointerException if the specified value is null
128 *
129 * @see JsonNumber
130 */
131 JsonArrayBuilder add(BigDecimal value);
132
133 /**
134 * Adds a value to the array as a {@link JsonNumber}.
135 *
136 * @param value the number value
137 * @return this array builder
138 * @throws NullPointerException if the specified value is null
139 *
140 * @see JsonNumber
141 */
142 JsonArrayBuilder add(BigInteger value);
143
144 /**
145 * Adds a value to the array as a {@link JsonNumber}.
146 *
147 * @param value the number value
148 * @return this array builder
149 *
150 * @see JsonNumber
151 */
152 JsonArrayBuilder add(int value);
153
154 /**
155 * Adds a value to the array as a {@link JsonNumber}.
156 *
157 * @param value the number value
158 * @return this array builder
159 *
160 * @see JsonNumber
161 */
162 JsonArrayBuilder add(long value);
163
164 /**
165 * Adds a value to the array as a {@link JsonNumber}.
166 *
167 * @param value the number value
168 * @return this array builder
169 * @throws NumberFormatException if the value is Not-a-Number (NaN) or
170 * infinity
171 *
172 * @see JsonNumber
173 */
174 JsonArrayBuilder add(double value);
175
176 /**
177 * Adds a {@link JsonValue#TRUE} or {@link JsonValue#FALSE} value to the
178 * array.
179 *
180 * @param value the boolean value
181 * @return this array builder
182 */
183 JsonArrayBuilder add(boolean value);
184
185 /**
186 * Adds a {@link JsonValue#NULL} value to the array.
187 *
188 * @return this array builder
189 */
190 JsonArrayBuilder addNull();
191
192 /**
193 * Adds a {@link JsonObject} from an object builder to the array.
194 *
195 * @param builder the object builder
196 * @return this array builder
197 * @throws NullPointerException if the specified builder is null
198 */
199 JsonArrayBuilder add(JsonObjectBuilder builder);
200
201 /**
202 * Adds a {@link JsonArray} from an array builder to the array.
203 *
204 * @param builder the array builder
205 * @return this array builder
206 * @throws NullPointerException if the specified builder is null
207 */
208 JsonArrayBuilder add(JsonArrayBuilder builder);
209
210 /**
211 * Adds all elements of the array in the specified array builder to the array.
212 *
213 * @param builder the array builder
214 * @return this array builder
215 * @throws NullPointerException if the specified builder is null
216 *
217 @since 1.1
218 */
219 default JsonArrayBuilder addAll(JsonArrayBuilder builder) {
220 throw new UnsupportedOperationException();
221 }
222
223 /**
224 * Inserts a value to the array at the specified position. Shifts the value
225 * currently at that position (if any) and any subsequent values to the right
226 * (adds one to their indices). Index starts with 0.
227 *
228 * @param index the position in the array
229 * @param value the JSON value
230 * @return this array builder
231 * @throws NullPointerException if the specified value is null
232 * @throws IndexOutOfBoundsException if the index is out of range
233 * {@code (index < 0 || index > array size)}
234 *
235 * @since 1.1
236 */
237 default JsonArrayBuilder add(int index, JsonValue value) {
238 throw new UnsupportedOperationException();
239 }
240
241 /**
242 * Adds a value to the array as a {@link JsonString} at the specified position.
243 * Shifts the value currently at that position (if any) and any subsequent values
244 * to the right (adds one to their indices). Index starts with 0.
245 *
246 * @param index the position in the array
247 * @param value the string value
248 * @return this array builder
249 * @throws NullPointerException if the specified value is null
250 * @throws IndexOutOfBoundsException if the index is out of range
251 * {@code (index < 0 || index > array size)}
252 *
253 * @since 1.1
254 */
255 default JsonArrayBuilder add(int index, String value) {
256 throw new UnsupportedOperationException();
257 }
258
259 /**
260 * Adds a value to the array as a {@link JsonNumber} at the specified position.
261 * Shifts the value currently at that position (if any) and any subsequent values
262 * to the right (adds one to their indices). Index starts with 0.
263 *
264 * @param index the position in the array
265 * @param value the number value
266 * @return this array builder
267 * @throws NullPointerException if the specified value is null
268 * @throws IndexOutOfBoundsException if the index is out of range
269 * {@code (index < 0 || index > array size)}
270 *
271 * @see JsonNumber
272 *
273 * @since 1.1
274 */
275 default JsonArrayBuilder add(int index, BigDecimal value) {
276 throw new UnsupportedOperationException();
277 }
278
279 /**
280 * Adds a value to the array as a {@link JsonNumber} at the specified position.
281 * Shifts the value currently at that position (if any) and any subsequent values
282 * to the right (adds one to their indices). Index starts with 0.
283 *
284 * @param index the position in the array
285 * @param value the number value
286 * @return this array builder
287 * @throws NullPointerException if the specified value is null
288 * @throws IndexOutOfBoundsException if the index is out of range
289 * {@code (index < 0 || index > array size)}
290 *
291 * @see JsonNumber
292 *
293 * @since 1.1
294 */
295 default JsonArrayBuilder add(int index, BigInteger value) {
296 throw new UnsupportedOperationException();
297 }
298
299 /**
300 * Adds a value to the array as a {@link JsonNumber} at the specified position.
301 * Shifts the value currently at that position (if any) and any subsequent values
302 * to the right (adds one to their indices). Index starts with 0.
303 *
304 * @param index the position in the array
305 * @param value the number value
306 * @return this array builder
307 * @throws IndexOutOfBoundsException if the index is out of range
308 * {@code (index < 0 || index > array size)}
309 *
310 * @see JsonNumber
311 *
312 * @since 1.1
313 */
314 default JsonArrayBuilder add(int index, int value) {
315 throw new UnsupportedOperationException();
316 }
317
318 /**
319 * Adds a value to the array as a {@link JsonNumber} at the specified position.
320 * Shifts the value currently at that position (if any) and any subsequent values
321 * to the right (adds one to their indices). Index starts with 0.
322 *
323 * @param index the position in the array
324 * @param value the number value
325 * @return this array builder
326 * @throws IndexOutOfBoundsException if the index is out of range
327 * {@code (index < 0 || index > array size)}
328 *
329 * @see JsonNumber
330 *
331 * @since 1.1
332 */
333 default JsonArrayBuilder add(int index, long value) {
334 throw new UnsupportedOperationException();
335 }
336
337 /**
338 * Adds a value to the array as a {@link JsonNumber} at the specified position.
339 * Shifts the value currently at that position (if any) and any subsequent values
340 * to the right (adds one to their indices). Index starts with 0.
341 *
342 * @param index the position in the array
343 * @param value the number value
344 * @return this array builder
345 * @throws NumberFormatException if the value is Not-a-Number (NaN) or
346 * infinity
347 * @throws IndexOutOfBoundsException if the index is out of range
348 * {@code (index < 0 || index > array size)}
349 *
350 * @see JsonNumber
351 *
352 * @since 1.1
353 */
354 default JsonArrayBuilder add(int index, double value) {
355 throw new UnsupportedOperationException();
356 }
357
358 /**
359 * Adds a {@link JsonValue#TRUE} or {@link JsonValue#FALSE} value to the
360 * array at the specified position.
361 * Shifts the value currently at that position (if any) and any subsequent values
362 * to the right (adds one to their indices). Index starts with 0.
363 *
364 * @param index the position in the array
365 * @param value the boolean value
366 * @return this array builder
367 * @throws IndexOutOfBoundsException if the index is out of range
368 * {@code (index < 0 || index > array size)}
369 *
370 * @since 1.1
371 */
372 default JsonArrayBuilder add(int index, boolean value) {
373 throw new UnsupportedOperationException();
374 }
375
376 /**
377 * Adds a {@link JsonValue#NULL} value to the array at the specified position.
378 * Shifts the value currently at that position (if any) and any subsequent values
379 * to the right (adds one to their indices). Index starts with 0.
380 *
381 * @param index the position in the array
382 * @return this array builder
383 * @throws IndexOutOfBoundsException if the index is out of range
384 * {@code (index < 0 || index > array size)}
385 *
386 * @since 1.1
387 */
388 default JsonArrayBuilder addNull(int index) {
389 return add(index, JsonValue.NULL);
390 }
391
392 /**
393 * Adds a {@link JsonObject} from an object builder to the array at the specified position.
394 * Shifts the value currently at that position (if any) and any subsequent values
395 * to the right (adds one to their indices). Index starts with 0.
396 *
397 * @param index the position in the array
398 * @param builder the object builder
399 * @return this array builder
400 * @throws NullPointerException if the specified builder is null
401 * @throws IndexOutOfBoundsException if the index is out of range
402 * {@code (index < 0 || index > array size)}
403 *
404 * @since 1.1
405 */
406 default JsonArrayBuilder add(int index, JsonObjectBuilder builder) {
407 throw new UnsupportedOperationException();
408 }
409
410 /**
411 * Adds a {@link JsonArray} from an array builder to the array at the specified position.
412 * Shifts the value currently at that position (if any) and any subsequent values
413 * to the right (adds one to their indices). Index starts with 0.
414 *
415 * @param index the position in the array
416 * @param builder the array builder
417 * @return this array builder
418 * @throws NullPointerException if the specified builder is null
419 * @throws IndexOutOfBoundsException if the index is out of range
420 * {@code (index < 0 || index > array size)}
421 *
422 * @since 1.1
423 */
424 default JsonArrayBuilder add(int index, JsonArrayBuilder builder) {
425 throw new UnsupportedOperationException();
426 }
427
428 /**
429 * Replaces a value in the array with the specified value at the
430 * specified position.
431 *
432 * @param index the position in the array
433 * @param value the JSON value
434 * @return this array builder
435 * @throws NullPointerException if the specified value is null
436 * @throws IndexOutOfBoundsException if the index is out of range
437 * {@code (index < 0 || index >= array size)}
438 *
439 * @since 1.1
440 */
441 default JsonArrayBuilder set(int index, JsonValue value) {
442 throw new UnsupportedOperationException();
443 }
444
445 /**
446 * Replaces a value in the array with the specified value as a
447 * {@link JsonString} at the specified position.
448 *
449 * @param index the position in the array
450 * @param value the string value
451 * @return this array builder
452 * @throws NullPointerException if the specified value is null
453 * @throws IndexOutOfBoundsException if the index is out of range
454 * {@code (index < 0 || index >= array size)}
455 *
456 * @since 1.1
457 */
458 default JsonArrayBuilder set(int index, String value) {
459 throw new UnsupportedOperationException();
460 }
461
462 /**
463 * Replaces a value in the array with the specified value as a
464 * {@link JsonNumber} at the specified position.
465 *
466 * @param index the position in the array
467 * @param value the number value
468 * @return this array builder
469 * @throws NullPointerException if the specified value is null
470 * @throws IndexOutOfBoundsException if the index is out of range
471 * {@code (index < 0 || index >= array size)}
472 *
473 * @see JsonNumber
474 *
475 * @since 1.1
476 */
477 default JsonArrayBuilder set(int index, BigDecimal value) {
478 throw new UnsupportedOperationException();
479 }
480
481 /**
482 * Replaces a value in the array with the specified value as a
483 * {@link JsonNumber} at the specified position.
484 *
485 * @param index the position in the array
486 * @param value the number value
487 * @return this array builder
488 * @throws NullPointerException if the specified value is null
489 * @throws IndexOutOfBoundsException if the index is out of range
490 * {@code (index < 0 || index >= array size)}
491 *
492 * @see JsonNumber
493 *
494 * @since 1.1
495 */
496 default JsonArrayBuilder set(int index, BigInteger value) {
497 throw new UnsupportedOperationException();
498 }
499
500 /**
501 * Replaces a value in the array with the specified value as a
502 * {@link JsonNumber} at the specified position.
503 *
504 * @param index the position in the array
505 * @param value the number value
506 * @return this array builder
507 * @throws IndexOutOfBoundsException if the index is out of range
508 * {@code (index < 0 || index >= array size)}
509 *
510 * @see JsonNumber
511 *
512 * @since 1.1
513 */
514 default JsonArrayBuilder set(int index, int value) {
515 throw new UnsupportedOperationException();
516 }
517
518 /**
519 * Replaces a value in the array with the specified value as a
520 * {@link JsonNumber} at the specified position.
521 *
522 * @param index the position in the array
523 * @param value the number value
524 * @return this array builder
525 * @throws IndexOutOfBoundsException if the index is out of range
526 * {@code (index < 0 || index >= array size)}
527 *
528 * @see JsonNumber
529 *
530 * @since 1.1
531 */
532 default JsonArrayBuilder set(int index, long value) {
533 throw new UnsupportedOperationException();
534 }
535
536 /**
537 * Replaces a value in the array with the specified value as a
538 * {@link JsonNumber} at the specified position.
539 *
540 * @param index the position in the array
541 * @param value the number value
542 * @return this array builder
543 * @throws NumberFormatException if the value is Not-a-Number (NaN) or
544 * infinity
545 * @throws IndexOutOfBoundsException if the index is out of range
546 * {@code (index < 0 || index >= array size)}
547 *
548 * @see JsonNumber
549 *
550 * @since 1.1
551 */
552 default JsonArrayBuilder set(int index, double value) {
553 throw new UnsupportedOperationException();
554 }
555
556 /**
557 * Replaces a value in the array with
558 * a {@link JsonValue#TRUE} or {@link JsonValue#FALSE} value
559 * at the specified position.
560 *
561 * @param index the position in the array
562 * @param value the boolean value
563 * @return this array builder
564 * @throws IndexOutOfBoundsException if the index is out of range
565 * {@code (index < 0 || index >= array size)}
566 *
567 * @since 1.1
568 */
569 default JsonArrayBuilder set(int index, boolean value) {
570 throw new UnsupportedOperationException();
571 }
572
573 /**
574 * Replaces a value in the array with
575 * a {@link JsonValue#NULL} value at the specified position.
576 *
577 * @param index the position in the array
578 * @return this array builder
579 * @throws IndexOutOfBoundsException if the index is out of range
580 * {@code (index < 0 || index >= array size)}
581 *
582 * @since 1.1
583 */
584 default JsonArrayBuilder setNull(int index) {
585 return set(index, JsonValue.NULL);
586 }
587
588 /**
589 * Replaces a value in the array with the specified value as a
590 * {@link JsonObject} from an object builder at the specified position.
591 *
592 * @param index the position in the array
593 * @param builder the object builder
594 * @return this array builder
595 * @throws NullPointerException if the specified builder is null
596 * @throws IndexOutOfBoundsException if the index is out of range
597 * {@code (index < 0 || index >= array size)}
598 *
599 * @since 1.1
600 */
601 default JsonArrayBuilder set(int index, JsonObjectBuilder builder) {
602 throw new UnsupportedOperationException();
603 }
604
605 /**
606 * Replaces a value in the array with the specified value as a
607 * {@link JsonArray} from an array builder at the specified position.
608 *
609 * @param index the position in the array
610 * @param builder the array builder
611 * @return this array builder
612 * @throws NullPointerException if the specified builder is null
613 * @throws IndexOutOfBoundsException if the index is out of range
614 * {@code (index < 0 || index >= array size)}
615 *
616 * @since 1.1
617 */
618 default JsonArrayBuilder set(int index, JsonArrayBuilder builder) {
619 throw new UnsupportedOperationException();
620 }
621
622 /**
623 * Remove the value in the array at the specified position.
624 * Shift any subsequent values to the left (subtracts one from their
625 * indices.
626 *
627 * @param index the position in the array
628 * @return this array builder
629 * @throws IndexOutOfBoundsException if the index is out of range
630 * {@code (index < 0 || index >= array size)}
631 *
632 * @since 1.1
633 */
634 default JsonArrayBuilder remove(int index) {
635 throw new UnsupportedOperationException();
636 }
637
638 /**
639 * Returns the current array.
640 *
641 * @return the current JSON array
642 */
643 JsonArray build();
644
645}
646
Note: See TracBrowser for help on using the repository browser.