Module jakarta.json
Package jakarta.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. This is the only way to parse and process JSON data that are too big to be loaded in memory.

    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"
    Starting in version 1.1, it is possible to build a partial JSON object model from the stream, at the current parser position. The methods getArray() and getObject() can be used to read in a JsonArray or JsonObject. For example, the following code shows how to obtain the phoneNumber in a JsonArray, from the JSON above: 
    
 while (parser.hasNext() {
     Event event = parser.next();
     if (event == JsonParser.Event.KEY_NAME ) {
         String key = parser.getString();
         event = parser.next();
         if (key.equals("phoneNumber") {
             JsonArray phones = parser.getArray();
         }
     }
 }
    The methods getArrayStream() and getObjectStream() can be used to get a stream of the elements of a JsonArray or JsonObject. For example, the following code shows another way to obtain John's phoneNumber in a JsonArray : 
    
 Event event = parser.next(); // START_OBJECT
 JsonArray phones = (JsonArray)
     parser.getObjectStream().filter(e->e.getKey().equals("phoneNumber"))
                             .map(e->e.getValue())
                             .findFirst()
                             .get();
    The methods skipArray() and skipObject() can be used to skip tokens and position the parser to END_ARRAY or END_OBJECT.

    JsonParser can be used to parse sequence of JSON values that are not enclosed in a JSON array, e.g. { } { }. The following code demonstrates how to parse such sequence. 

    
 JsonParser parser = Json.createParser(...);
 while (parser.hasNext) {
     parser.next(); // advance parser state
     JsonValue value = parser.getValue();
 }
    See Also:
    Json, JsonParserFactory

    • 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.
        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.

      • currentEvent

        default JsonParser.Event currentEvent()
        Returns the event for the current parsing state.
        Returns:
        the event for the current parsing state
        Since:
        2.1

      • 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

      • getObject

        default JsonObject getObject()
        Returns a JsonObject and advances the parser to the corresponding END_OBJECT.
        Returns:
        the JsonObject at the current parser position
        Throws:
        JsonException - if an i/o error occurs (IOException would be cause of JsonException)
        IllegalStateException - when the parser state is not START_OBJECT
        JsonParsingException - if the parser encounters invalid JSON when advancing to next state.
        NoSuchElementException - if there are no more parsing states.
        Since:
        1.1

      • getValue

        default JsonValue getValue()
        Returns a JsonValue at the current parser position. If the parser state is START_ARRAY, the behavior is the same as getArray(). If the parser state is START_OBJECT, the behavior is the same as getObject(). For all other cases, if applicable, the JSON value is read and returned.
        Returns:
        the JsonValue at the current parser position.
        Throws:
        JsonException - if an i/o error occurs (IOException would be cause of JsonException)
        IllegalStateException - when the parser state is END_OBJECT or END_ARRAY
        JsonParsingException - if the parser encounters invalid JSON when advancing to next state.
        NoSuchElementException - if there are no more parsing states.
        Since:
        1.1

      • getArray

        default JsonArray getArray()
        Returns a JsonArray and advance the parser to the the corresponding END_ARRAY.
        Returns:
        the JsonArray at the current parser position
        Throws:
        JsonException - if an i/o error occurs (IOException would be cause of JsonException)
        IllegalStateException - when the parser state is not START_ARRAY
        JsonParsingException - if the parser encounters invalid JSON when advancing to next state.
        NoSuchElementException - if there are no more parsing states.
        Since:
        1.1

      • getArrayStream

        default Stream<JsonValue> getArrayStream()
        Returns a stream of the JsonArray elements. The parser state must be START_ARRAY. The elements are read lazily, on an as-needed basis, as required by the stream operations. If the stream operations do not consume all of the array elements, skipArray() can be used to skip the unprocessed array elements.
        Returns:
        a stream of elements of the JsonArray
        Throws:
        IllegalStateException - when the parser state is not START_ARRAY
        Since:
        1.1

      • getObjectStream

        default Stream<Map.Entry<String,​JsonValue>> getObjectStream()
        Returns a stream of the JsonObject's name/value pairs. The parser state must be START_OBJECT. The name/value pairs are read lazily, on an as-needed basis, as required by the stream operations. If the stream operations do not consume all of the object's name/value pairs, skipObject() can be used to skip the unprocessed elements.
        Returns:
        a stream of name/value pairs of the JsonObject
        Throws:
        IllegalStateException - when the parser state is not START_OBJECT
        Since:
        1.1

      • getValueStream

        default Stream<JsonValue> getValueStream()
        Returns a stream of JsonValue from a sequence of JSON values. The values are read lazily, on an as-needed basis, as needed by the stream operations.
        Returns:
        a Stream of JsonValue
        Throws:
        IllegalStateException - if the parser is in an array or object.
        Since:
        1.1

      • skipArray

        default void skipArray()
        Advance the parser to END_ARRAY. If the parser is in array context, i.e. it has previously encountered a START_ARRAY without encountering the corresponding END_ARRAY, the parser is advanced to the corresponding END_ARRAY. If the parser is not in any array context, nothing happens.
        Since:
        1.1

      • skipObject

        default void skipObject()
        Advance the parser to END_OBJECT. If the parser is in object context, i.e. it has previously encountered a START_OBJECT without encountering the corresponding END_OBJECT, the parser is advanced to the corresponding END_OBJECT. If the parser is not in any object context, nothing happens.
        Since:
        1.1

      • 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)