Interface JsonParser
-
- All Superinterfaces:
java.lang.AutoCloseable
,java.io.Closeable
public interface JsonParser extends java.io.Closeable
Provides forward, read-only access to JSON data in a streaming way. This is the most efficient way for reading JSON data. The classJson
contains methods to create parsers from input sources (InputStream
andReader
).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 createJsonParser
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 methodnext()
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
, andVALUE_NULL
.For example, for an empty JSON object ({ }), the parser generates the event
START_OBJECT
with the first call to the methodnext()
and the eventEND_OBJECT
with the second call to the methodnext()
. 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()
andhasNext()
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"
- See Also:
Json
,JsonParserFactory
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
JsonParser.Event
An event fromJsonParser
.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
close()
Closes this parser and frees any resources associated with the parser.java.math.BigDecimal
getBigDecimal()
Returns a JSON number as aBigDecimal
.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.java.lang.String
getString()
Returns aString
for the name in a name/value pair, for a string value or a number value.boolean
hasNext()
Returnstrue
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()
Returnstrue
if there are more parsing states. This method returnsfalse
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.java.util.NoSuchElementException
- if there are no more parsing states.
-
getString
java.lang.String getString()
Returns aString
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 isJsonParser.Event.KEY_NAME
,JsonParser.Event.VALUE_STRING
, orJsonParser.Event.VALUE_NUMBER
.- Returns:
- a name when the parser state is
JsonParser.Event.KEY_NAME
a string value when the parser state isJsonParser.Event.VALUE_STRING
a number value when the parser state isJsonParser.Event.VALUE_NUMBER
- Throws:
java.lang.IllegalStateException
- when the parser state is notKEY_NAME
,VALUE_STRING
, orVALUE_NUMBER
-
isIntegralNumber
boolean isIntegralNumber()
Returns true if the JSON number at the current parser state is a integral number. ABigDecimal
may be used to store the value internally and this method semantics are defined using itsscale()
. 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:
java.lang.IllegalStateException
- when the parser state is notVALUE_NUMBER
-
getInt
int getInt()
Returns a JSON number as an integer. The returned value is equal tonew 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 isJsonParser.Event.VALUE_NUMBER
.- Returns:
- an integer for a JSON number
- Throws:
java.lang.IllegalStateException
- when the parser state is notVALUE_NUMBER
- See Also:
BigDecimal.intValue()
-
getLong
long getLong()
Returns a JSON number as a long. The returned value is equal tonew 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 isJsonParser.Event.VALUE_NUMBER
.- Returns:
- a long for a JSON number
- Throws:
java.lang.IllegalStateException
- when the parser state is notVALUE_NUMBER
- See Also:
BigDecimal.longValue()
-
getBigDecimal
java.math.BigDecimal getBigDecimal()
Returns a JSON number as aBigDecimal
. TheBigDecimal
is created usingnew BigDecimal(getString())
. This method should only called when the parser state isJsonParser.Event.VALUE_NUMBER
.- Returns:
- a
BigDecimal
for a JSON number - Throws:
java.lang.IllegalStateException
- when the parser state is notVALUE_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 interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.Closeable
- Throws:
JsonException
- if an i/o error occurs (IOException would be cause of JsonException)
-
-