javax.json.stream

Interface JsonParser

All Superinterfaces:

AutoCloseable, Closeable

public interface JsonParser
extends 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 next() method. The next() method causes the parser to advance to the next parse state.

For example 1:

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

 
 Event event = parser.next(); // START_OBJECT
 event = parser.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 next() 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:

 
 Event event = parser.next(); // START_OBJECT
 event = parser.next();       // KEY_NAME
 event = parser.next();       // VALUE_STRING
 parser.getString();          // "John"
 
 

Author:

Jitendra Kotamraju

See Also:

Json, JsonParserFactory

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	JsonParser.Event Event for parser state while parsing the JSON

Method Summary

Methods

Modifier and Type	Method and Description
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.NumberType	getNumberType() Returns a JSON number type for this number.
String	getString() Returns a String for name(key), string value and number value.
boolean	hasNext() Returns true if there are more parsing states.
JsonParser.Event	next() Returns the event for next parsing state.

Method Detail

hasNext

boolean hasNext()

Returns true if there are more parsing states. This method will return false if the parser reaches the end state of 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 incorrect JSON is encountered while advancing the parser to next state

next

JsonParser.Event next()

Returns the event for next parsing state.

Throws:

JsonException - if an i/o error occurs (IOException would be cause of JsonException)

JsonParsingException - if incorrect JSON is encountered while advancing the parser to next state

NoSuchElementException - if there are no more parsing states

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.NumberType getNumberType()

Returns a JSON number type for this number. A BigDecimal may be used to store the numeric value internally and the semantics of this method is defined using BigDecimal.scale(). If the scale of a value is zero, then its number type is INTEGER else DECIMAL.

The number type can be used to invoke appropriate accessor methods to get numeric value for the number.

For example:

 
 switch(getNumberType()) {
     case INTEGER :
         long l = getLongValue(); break;
     case DECIMAL :
         BigDecimal bd = getBigDecimalValue(); break;
 }
 
 

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