Changeset 13231 in josm for trunk/src/javax/json/stream/JsonParser.java
- Timestamp:
- 2017-12-23T02:40:43+01:00 (6 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/src/javax/json/stream/JsonParser.java
r6756 r13231 2 2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 3 * 4 * Copyright (c) 2011-201 3Oracle and/or its affiliates. All rights reserved.4 * Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved. 5 5 * 6 6 * The contents of this file are subject to the terms of either the GNU … … 9 9 * may not use this file except in compliance with the License. You can 10 10 * obtain a copy of the License at 11 * https:// glassfish.dev.java.net/public/CDDL+GPL_1_1.html12 * or packager/legal/LICENSE.txt. See the License for the specific11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1 12 * or LICENSE.txt. See the License for the specific 13 13 * language governing permissions and limitations under the License. 14 14 * 15 15 * When distributing the software, include this License Header Notice in each 16 * file and include the License file at packager/legal/LICENSE.txt.16 * file and include the License file at LICENSE.txt. 17 17 * 18 18 * GPL Classpath Exception: … … 44 44 import java.io.Closeable; 45 45 import java.math.BigDecimal; 46 import java.util.stream.Stream; 47 import java.util.Map; 48 49 import javax.json.JsonValue; 50 import javax.json.JsonObject; 51 import javax.json.JsonArray; 46 52 47 53 /** 48 54 * Provides forward, read-only access to JSON data in a streaming way. This 49 * is the most efficient way for reading JSON data. The class 55 * is the most efficient way for reading JSON data. 56 * This is the only way to parse and process JSON data that are too big to be loaded in memory. 57 * <p>The class 50 58 * {@link javax.json.Json} contains methods to create parsers from input 51 59 * sources ({@link java.io.InputStream} and {@link java.io.Reader}). … … 97 105 * 98 106 * <p> 99 * <a id="JsonParserExample2"/>100 * <p>101 107 * <b>For example</b>, for the following JSON: 102 108 * <pre> … … 113 119 * locations below (marked in bold): 114 120 * 115 * <p>116 121 * <pre> 117 122 * {<B>START_OBJECT</B> … … 124 129 * </pre> 125 130 * 126 * <p> 127 * The methods {@code next()} and {@code hasNext()} enable iteration over 131 * The methods {@link #next()} and {@link #hasNext()} enable iteration over 128 132 * parser events to process JSON data. {@code JsonParser} provides get methods 129 133 * to obtain the value at the current state of the parser. For example, the 130 134 * following code shows how to obtain the value "John" from the JSON above: 131 135 * 132 * <p>133 136 * <pre> 134 137 * <code> … … 140 143 * </pre> 141 144 * 145 * Starting in version 1.1, it is possible to build a partial JSON object 146 * model from the stream, at the current parser position. 147 * The methods {@link #getArray} and {@link #getObject} can be used to read in 148 * a {@code JsonArray} or {@code JsonObject}. For example, the following code 149 * shows how to obtain the phoneNumber in a JsonArray, from the JSON above: 150 * 151 * <pre><code> 152 * while (parser.hasNext() { 153 * Event event = parser.next(); 154 * if (event == JsonParser.Event.KEY_NAME ) { 155 * String key = getString(); 156 * event = parser.next(); 157 * if (key.equals("phoneNumber") { 158 * JsonArray phones = parser.getArray(); 159 * } 160 * } 161 * } 162 * </code></pre> 163 * 164 * The methods {@link #getArrayStream} and {@link #getObjectStream} can be used 165 * to get a stream of the elements of a {@code JsonArray} or {@code JsonObject}. 166 * For example, the following code shows another way to obtain John's phoneNumber 167 * in a {@code JsonArray} : 168 * 169 * <pre>{@code 170 * Event event = parser.next(); // START_OBJECT 171 * JsonArray phones = (JsonArray) 172 * parser.getObjectStream().filter(e->e.getKey().equals("phoneNumber")) 173 * .map(e->e.getValue()) 174 * .findFirst() 175 * .get(); 176 * }</pre> 177 * 178 * The methods {@link #skipArray} and {@link #skipObject} can be used to 179 * skip tokens and position the parser to {@code END_ARRAY} or 180 * {@code END_OBJECT}. 181 * <p> 182 * {@code JsonParser} can be used to parse sequence of JSON values that are not 183 * enclosed in a JSON array, e.g. { } { }. The following code demonstrates how 184 * to parse such sequence. 185 * <pre><code> 186 * JsonParser parser = Json.createParser(...); 187 * while (parser.hasNext) { 188 * parser.next(); // advance parser state 189 * JsonValue value = parser.getValue(); 190 * } 191 * </code></pre> 192 * 142 193 * @see javax.json.Json 143 194 * @see JsonParserFactory 144 * @author Jitendra Kotamraju145 195 */ 146 196 public interface JsonParser extends /*Auto*/Closeable { … … 223 273 * @throws java.util.NoSuchElementException if there are no more parsing 224 274 * states. 275 * @return the event for the next parsing state 225 276 */ 226 277 Event next(); … … 319 370 320 371 /** 321 * getJsonValue(JsonObject.class) is valid in the START_OBJECT state and 322 * moves the cursor to END_OBJECT. 323 * 324 * getJsonValue(JsonArray.class) is valid in the START_ARRAY state 325 * and moves the cursor to END_ARRAY. 326 * 327 * getJsonValue(JsonString.class) is valid in the VALUE_STRING state. 328 * 329 * getJsonValue(JsonNumber.class) is valid in the VALUE_NUMBER state. 330 * 331 * @param clazz 332 * @return 333 * 334 public <T extends JsonValue> T getJsonValue(Class<T> clazz); 335 */ 372 * Returns a {@code JsonObject} and advances the parser to the 373 * corresponding {@code END_OBJECT}. 374 * 375 * @return the {@code JsonObject} at the current parser position 376 * 377 * @throws IllegalStateException when the parser state is not 378 * {@code START_OBJECT} 379 * 380 * @since 1.1 381 */ 382 default public JsonObject getObject() { 383 throw new UnsupportedOperationException(); 384 } 385 386 /** 387 * Returns a {@code JsonValue} at the current parser position. 388 * If the parser state is {@code START_ARRAY}, the behavior is 389 * the same as {@link #getArray}. If the parser state is 390 * {@code START_OBJECT}, the behavior is the same as 391 * {@link #getObject}. For all other cases, if applicable, the JSON value is 392 * read and returned. 393 * 394 * @return the {@code JsonValue} at the current parser position. 395 * @throws IllegalStateException when the parser state is 396 * {@code END_OBJECT} or {@code END_ARRAY} 397 * 398 * @since 1.1 399 */ 400 default public JsonValue getValue() { 401 throw new UnsupportedOperationException(); 402 } 403 404 /** 405 * Returns a {@code JsonArray} and advance the parser to the 406 * the corresponding {@code END_ARRAY}. 407 * 408 * @return the {@code JsonArray} at the current parser position 409 * 410 * @throws IllegalStateException when the parser state is not 411 * {@code START_ARRAY} 412 * 413 * @since 1.1 414 */ 415 default public JsonArray getArray() { 416 throw new UnsupportedOperationException(); 417 } 418 419 /** 420 * Returns a stream of the {@code JsonArray} elements. 421 * The parser state must be {@code START_ARRAY}. 422 * The elements are read lazily, on an as-needed basis, as 423 * required by the stream operations. 424 * If the stream operations do not consume 425 * all of the array elements, {@link skipArray} can be used to 426 * skip the unprocessed array elements. 427 * 428 * @return a stream of elements of the {@code JsonArray} 429 * 430 * @throws IllegalStateException when the parser state is not 431 * {@code START_ARRAY} 432 * 433 * @since 1.1 434 */ 435 default public Stream<JsonValue> getArrayStream() { 436 throw new UnsupportedOperationException(); 437 } 438 439 /** 440 * Returns a stream of the {@code JsonObject}'s 441 * name/value pairs. The parser state must be {@code START_OBJECT}. 442 * The name/value pairs are read lazily, on an as-needed basis, as 443 * required by the stream operations. 444 * If the stream operations do not consume 445 * all of the object's name/value pairs, {@link skipObject} can be 446 * used to skip the unprocessed elements. 447 * 448 * @return a stream of name/value pairs of the {@code JsonObject} 449 * 450 * @throws IllegalStateException when the parser state is not 451 * {@code START_OBJECT} 452 * 453 * @since 1.1 454 */ 455 default public Stream<Map.Entry<String,JsonValue>> getObjectStream() { 456 throw new UnsupportedOperationException(); 457 } 458 459 /** 460 * Returns a stream of {@code JsonValue} from a sequence of 461 * JSON values. The values are read lazily, on an as-needed basis, 462 * as needed by the stream operations. 463 * 464 * @return a Stream of {@code JsonValue} 465 * 466 * @throws IllegalStateException if the parser is in an array or object. 467 * 468 * @since 1.1 469 */ 470 default public Stream<JsonValue> getValueStream() { 471 throw new UnsupportedOperationException(); 472 } 473 474 /** 475 * Advance the parser to {@code END_ARRAY}. 476 * If the parser is in array context, i.e. it has previously 477 * encountered a {@code START_ARRAY} without encountering the 478 * corresponding {@code END_ARRAY}, the parser is advanced to 479 * the corresponding {@code END_ARRAY}. 480 * If the parser is not in any array context, nothing happens. 481 * 482 * @since 1.1 483 */ 484 default public void skipArray() { 485 throw new UnsupportedOperationException(); 486 } 487 488 /** 489 * Advance the parser to {@code END_OBJECT}. 490 * If the parser is in object context, i.e. it has previously 491 * encountered a {@code START_OBJECT} without encountering the 492 * corresponding {@code END_OBJECT}, the parser is advanced to 493 * the corresponding {@code END_OBJECT}. 494 * If the parser is not in any object context, nothing happens. 495 * 496 * @since 1.1 497 */ 498 default public void skipObject() { 499 throw new UnsupportedOperationException(); 500 } 336 501 337 502 /** … … 344 509 @Override 345 510 void close(); 346 347 511 }
Note:
See TracChangeset
for help on using the changeset viewer.