javax.json.stream

## Interface JsonParser

- All Superinterfaces:
    AutoCloseable, Closeable

      public interface JsonParser
      extends Closeable

  Provides forward, read-only access to JSON data in a streaming way. This is the most efficient way for reading JSON data. The class `Json` contains methods to create parsers from input sources (`InputStream` and `Reader`).

  The following example demonstrates how to create a parser from a string that contains an empty JSON array:

       JsonParser parser = Json.createParser(new StringReader("[]"));

  The class `JsonParserFactory` also contains methods to create `JsonParser` instances. `JsonParserFactory` is preferred when creating multiple parser instances. A sample usage is shown in the following example:

       JsonParserFactory factory = Json.createParserFactory();
       JsonParser parser1 = factory.createParser(...);
       JsonParser parser2 = factory.createParser(...);

  `JsonParser` parses JSON using the pull parsing programming model. In this model the client code controls the thread and calls the method `next()` to advance the parser to the next state after processing each element. The parser can generate the following events: `START_OBJECT`, `END_OBJECT`, `START_ARRAY`, `END_ARRAY`, `KEY_NAME`, `VALUE_STRING`, `VALUE_NUMBER`, `VALUE_TRUE`, `VALUE_FALSE`, and `VALUE_NULL`.

  For example, for an empty JSON object ({ }), the parser generates the event `START_OBJECT` with the first call to the method `next()` and the event `END_OBJECT` with the second call to the method `next()`. The following code demonstrates how to access these events:

       Event event = parser.next(); // START_OBJECT
       event = parser.next();       // END_OBJECT

  For example, for the following JSON:

       {
         "firstName": "John", "lastName": "Smith", "age": 25,
         "phoneNumber": [
             { "type": "home", "number": "212 555-1234" },
             { "type": "fax", "number": "646 555-4567" }
          ]
       }

  calls to the method `next()` result in parse events at the specified locations below (marked in bold):

       {START_OBJECT
         "firstName"KEY_NAME: "John"VALUE_STRING, "lastName"KEY_NAME: "Smith"VALUE_STRING, "age"KEY_NAME: 25VALUE_NUMBER,
         "phoneNumber"KEY_NAME : [START_ARRAY
             {START_OBJECT "type"KEY_NAME: "home"VALUE_STRING, "number"KEY_NAME: "212 555-1234"VALUE_STRING }END_OBJECT,
             {START_OBJECT "type"KEY_NAME: "fax"VALUE_STRING, "number"KEY_NAME: "646 555-4567"VALUE_STRING }END_OBJECT
          ]END_ARRAY
       }END_OBJECT

  The methods `next()` and `hasNext()` enable iteration over parser events to process JSON data. `JsonParser` provides get methods to obtain the value at the current state of the parser. For example, the following code shows how to obtain the value "John" from the JSON above:

       Event event = parser.next(); // START_OBJECT
       event = parser.next();       // KEY_NAME
       event = parser.next();       // VALUE_STRING
       parser.getString();          // "John"

  Author:
    Jitendra Kotamraju
  See Also:
    `Json`, `JsonParserFactory`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `JsonParser.Event` An event from `JsonParser`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Closes this parser and frees any resources associated with the parser.
    `BigDecimal` | `getBigDecimal()` Returns a JSON number as a `BigDecimal`.
    `int` | `getInt()` Returns a JSON number as an integer.
    `JsonLocation` | `getLocation()` Return the location that corresponds to the parser's current state in the JSON input source.
    `long` | `getLong()` Returns a JSON number as a long.
    `String` | `getString()` Returns a `String` for the name in a name/value pair, for a string value or a number value.
    `boolean` | `hasNext()` Returns `true` if there are more parsing states.
    `boolean` | `isIntegralNumber()` Returns true if the JSON number at the current parser state is a integral number.
    `JsonParser.Event` | `next()` Returns the event for the next parsing state.

- - ### Method Detail

    - #### hasNext

          boolean hasNext()

      Returns `true` if there are more parsing states. This method returns `false` if the parser reaches the end of the JSON text.
      Returns:
        `true` if there are more parsing states.
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonParsingException` - if the parser encounters invalid JSON when advancing to next state.

    - #### next

          JsonParser.Event next()

      Returns the event for the next parsing state.
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonParsingException` - if the parser encounters invalid JSON when advancing to next state.
        `NoSuchElementException` - if there are no more parsing states.

    - #### getString

          String getString()

      Returns a `String` for the name in a name/value pair, for a string value or a number value. This method should only be called when the parser state is `JsonParser.Event.KEY_NAME`, `JsonParser.Event.VALUE_STRING`, or `JsonParser.Event.VALUE_NUMBER`.
      Returns:
        a name when the parser state is `JsonParser.Event.KEY_NAME` a string value when the parser state is `JsonParser.Event.VALUE_STRING` a number value when the parser state is `JsonParser.Event.VALUE_NUMBER`
      Throws:
        `IllegalStateException` - when the parser state is not `KEY_NAME`, `VALUE_STRING`, or `VALUE_NUMBER`

    - #### isIntegralNumber

          boolean isIntegralNumber()

      Returns true if the JSON number at the current parser state is a integral number. A `BigDecimal` may be used to store the value internally and this method semantics are defined using its `scale()`. If the scale is zero, then it is considered integral type. This integral type information can be used to invoke an appropriate accessor method to obtain a numeric value as in the following example:

           JsonParser parser = ...
           if (parser.isIntegralNumber()) {
               parser.getInt();     // or other methods to get integral value
           } else {
               parser.getBigDecimal();
           }

      Returns:
        true if this number is a integral number, otherwise false
      Throws:
        `IllegalStateException` - when the parser state is not `VALUE_NUMBER`

    - #### getInt

          int getInt()

      Returns a JSON number as an integer. The returned value is equal to `new BigDecimal(getString()).intValue()`. Note that this conversion can lose information about the overall magnitude and precision of the number value as well as return a result with the opposite sign. This method should only be called when the parser state is `JsonParser.Event.VALUE_NUMBER`.
      Returns:
        an integer for a JSON number
      Throws:
        `IllegalStateException` - when the parser state is not `VALUE_NUMBER`
      See Also:
        `BigDecimal.intValue()`

    - #### getLong

          long getLong()

      Returns a JSON number as a long. The returned value is equal to `new BigDecimal(getString()).longValue()`. Note that this conversion can lose information about the overall magnitude and precision of the number value as well as return a result with the opposite sign. This method is only called when the parser state is `JsonParser.Event.VALUE_NUMBER`.
      Returns:
        a long for a JSON number
      Throws:
        `IllegalStateException` - when the parser state is not `VALUE_NUMBER`
      See Also:
        `BigDecimal.longValue()`

    - #### getBigDecimal

          BigDecimal getBigDecimal()

      Returns a JSON number as a `BigDecimal`. The `BigDecimal` is created using `new BigDecimal(getString())`. This method should only called when the parser state is `JsonParser.Event.VALUE_NUMBER`.
      Returns:
        a `BigDecimal` for a JSON number
      Throws:
        `IllegalStateException` - when the parser state is not `VALUE_NUMBER`

    - #### getLocation

          JsonLocation getLocation()

      Return the location that corresponds to the parser's current state in the JSON input source. The location information is only valid in the current parser state (or until the parser is advanced to a next state).
      Returns:
        a non-null location corresponding to the current parser state in JSON input source

    - #### close

          void close()

      Closes this parser and frees any resources associated with the parser. This method closes the underlying input source.
      Specified by:
        `close` in interface `AutoCloseable`
      Specified by:
        `close` in interface `Closeable`
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.