javax.json.stream
Interface JsonParser

All Superinterfaces:

Closeable, Iterable<JsonParser.Event>

public interface JsonParser
extends Iterable<JsonParser.Event>, Closeable

A JSON parser that allows forward, read-only access to JSON in a a streaming way. This is designed to be the most efficient way to read JSON text. The parser can be created from many input sources like Reader, InputStream, JsonArray and JsonObject.

For example, a parser for empty JSON array can be created as follows:

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

A parser can also be created using JsonParserFactory. If multiple parser instances are created, then creating them using a factory is preferred.

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

The parser is used to parse JSON in a pull manner by calling its iterator methods. The iterator's next() method causes the parser to advance to the next parse state.

For example 1:

For empty JSON object { }, the iterator would give {START_OBJECT }END_OBJECT parse events at the specified locations. Those events can be accessed using the following code.

 Iterator<Event> it = parser.iterator();
 Event event = it.next(); // START_OBJECT
 event = it.next();       // END_OBJECT
 

For example 2:

For the following JSON

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

the iterator would give

 {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
 

parse events at the specified locations.

Here, "John" value is accessed as follows:

 Iterator<Event> it = parser.iterator();
 Event event = it.next(); // START_OBJECT
 event = it.next();       // KEY_NAME
 event = it.next();       // VALUE_STRING
 parser.getString();      // "John"
 

Author:

Jitendra Kotamraju

See Also:

Json, JsonParserFactory

Nested Class Summary

static class

JsonParser.Event Event for parser state while parsing the JSON

Method Summary

void	close() Closes this parser and frees any resources associated with the parser.
BigDecimal	getBigDecimalValue() Returns JSON number as a BigDecimal.
int	getIntValue() Returns JSON number as an integer.
long	getLongValue() Returns JSON number as a long.
JsonNumber.JsonNumberType	getNumberType() Returns a number type that can hold JSON number.
String	getString() Returns a String for name(key), string value and number value.

Methods inherited from interface java.lang.Iterable

iterator

Method Detail

getString

String getString()

Returns a String for name(key), string value and number value. This method is only called when the parser state is one of JsonParser.Event.KEY_NAME, JsonParser.Event.VALUE_STRING, JsonParser.Event.VALUE_NUMBER.

Returns:

name when the parser state is JsonParser.Event.KEY_NAME. string value when the parser state is JsonParser.Event.VALUE_STRING. number value when the parser state is JsonParser.Event.VALUE_NUMBER.

Throws:

IllegalStateException - when the parser is not in one of KEY_NAME, VALUE_STRING, VALUE_NUMBER states

getNumberType

JsonNumber.JsonNumberType getNumberType()

Returns a number type that can hold JSON number. A BigDecimal may be used to store the numeric value of the number. If the scale of a value is non-zero, its number type is BIG_DECIMAL. If the scale is zero, and the value is numerically an integer. If the value can be exactly represented as an int, its type is INT; if the value can be exactly represented as a long, its type is LONG; otherwise, its type is BIG_DECIMAL.

This method can be used to get the correct number type for a number. For example:

 switch(parser.getNumberType()) {
     case INT :
         int i = parser.getIntValue(); break;
     case LONG :
         long l = parser.getLongValue(); break;
     case BIG_DECIMAL :
         BigDecimal bd = parser.getBigDecimalValue(); break;
 }
 

This method can only be called when the parser state is JsonParser.Event.VALUE_NUMBER

Returns:

a number type

Throws:

IllegalStateException - when the parser state is not VALUE_NUMBER

getIntValue

int getIntValue()

Returns 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 is only called when the parser is in JsonParser.Event.VALUE_NUMBER state.

Returns:

an integer for JSON number.

Throws:

IllegalStateException - when the parser state is not VALUE_NUMBER

See Also:

BigDecimal.intValue()

getLongValue

long getLongValue()

Returns 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 is in JsonParser.Event.VALUE_NUMBER state.

Returns:

a long for JSON number.

Throws:

IllegalStateException - when the parser state is not VALUE_NUMBER

See Also:

BigDecimal.longValue()

getBigDecimalValue

BigDecimal getBigDecimalValue()

Returns JSON number as a BigDecimal. The BigDecimal is created using new BigDecimal(getString()). This method is only called when the parser is in JsonParser.Event.VALUE_NUMBER state.

Returns:

a BigDecimal for JSON number

Throws:

IllegalStateException - when the parser state is not VALUE_NUMBER

close

void close()

Closes this parser and frees any resources associated with the parser. This doesn't close the underlying input source.

Specified by:

close in interface Closeable