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 = 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: