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
javax.json.Json contains methods to create parsers from input
sources (
java.io.InputStream and
java.io.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
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();
}