org.json.stream

Class JSONStreamReader

java.lang.Object

org.json.stream.JSONStreamReader

Direct Known Subclasses:

JSONLimitStreamReader

public class JSONStreamReader
extends java.lang.Object

Reads a JSON document as a stream of JSON events. Uses an iterator model to produce each event. Similar to a StAX event model in XML processing.

For a streaming equivalent for writing JSON data, see the JSONWriter and JSONStringer classes.

A simple example of how to use this class:

 JSONStreamReader reader = new JSONStreamReader(JSON_TEXT);

 while(reader.hasNext()) {
     ParseState state = reader.nextState();
     switch(state) {
         case KEY:
             System.out.println("KEY = " + reader.nextKey() );
             break;
         case NULL_VALUE:
         case BOOLEAN_VALUE:
         case NUMBER_VALUE:
         case STRING_VALUE:
             System.out.println(state + " = " + reader.nextValue());
             break;
         default:
             System.out.println(state);
     }
 }
 

A more complete example can be found by reading the JSONObjectBuilder source code.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	JSONStreamReader.ParseState States of the internal state machine.

Field Summary

Fields

Modifier and Type	Field and Description
protected BufferedAppendable	bufferedAppender
protected JSONLexer	lexer
protected ALStack<JSONLexer.Token>	objectStack
protected JSONStreamReader.ParseState	state

Constructor Summary

Constructors

Constructor and Description
JSONStreamReader(java.io.InputStream inputStream, java.nio.charset.Charset charset) Construct a JSONStreamReader from an InputStream and a supplied Charset.
JSONStreamReader(java.io.Reader reader) Construct a JSONStreamReader from a Reader.
JSONStreamReader(java.lang.String s) Construct a JSONStreamReader from a String.

Method Summary

Modifier and Type	Method and Description
<T extends java.lang.Appendable> T	appendNextNumberValue(T writer) If the ParseState was JSONStreamReader.ParseState.NUMBER_VALUE, append the number sequence to the given Appendable.
<T extends java.lang.Appendable> T	appendNextStringValue(T writer) If the ParseState was JSONStreamReader.ParseState.STRING_VALUE, append the decoded value to the given Appendable.
JSONStreamReader.ParseState	currentState() Return the current state of the parser, including any of the internal states.
protected java.math.BigDecimal	decodeBigDecimal(java.lang.String val) Parse a number as a BigDecimal strictly according to the JSON specification.
protected java.math.BigInteger	decodeBigInteger(java.lang.String val, boolean isDbl) Parse a number as a BigInteger strictly according to the JSON specification.
protected double	decodeDouble(java.lang.String val, boolean isDbl) Decode a number as a double strictly according to the JSON specification.
protected int	decodeInt(java.lang.String val, boolean isDbl) Parse a number as an int strictly according to the JSON specification.
protected long	decodeLong(java.lang.String val, boolean isDbl) Parse a number as a long strictly according to the JSON specification.
protected java.lang.Object	decodeNull() Return an object that represents a JSON null value.
protected java.lang.Number	decodeNumber(java.lang.String val, boolean isDbl) Decode a number strictly according to the JSON specification.
ParsePosition	getParsePosition() Indicates the current position of the scanner.
int	getStackDepth() Get the depth of nested objects, arrays, or values.
boolean	hasNext() Are there more parse states remaining in the source stream.
java.math.BigDecimal	nextBigDecimalValue() If the ParseState was JSONStreamReader.ParseState.NUMBER_VALUE, return the value as a BigDecimal.
java.math.BigInteger	nextBigIntegerValue() If the ParseState was JSONStreamReader.ParseState.NUMBER_VALUE, return the value as a BigInteger.
boolean	nextBooleanValue() If the ParseState was JSONStreamReader.ParseState.BOOLEAN_VALUE, return the value as a boolean.
double	nextDoubleValue() If the ParseState was JSONStreamReader.ParseState.NUMBER_VALUE, return the value as a double.
int	nextIntValue() If the ParseState was JSONStreamReader.ParseState.NUMBER_VALUE, return the value as an int.
java.lang.String	nextKey() If the ParseState was JSONStreamReader.ParseState.KEY, return the text of the key name.
long	nextLongValue() If the ParseState was JSONStreamReader.ParseState.NUMBER_VALUE, return the value as a long.
java.lang.Object	nextNullValue() If the ParseState was JSONStreamReader.ParseState.NULL_VALUE, return the value as a NULL object.
java.lang.Number	nextNumberValue() If the ParseState was JSONStreamReader.ParseState.NUMBER_VALUE, return the value as a Number.
JSONStreamReader.ParseState	nextState() Advance the parser onto the next state in the source stream, and return a JSONStreamReader.ParseState representing the state that was encountered.
java.lang.String	nextStringValue() If the ParseState was JSONStreamReader.ParseState.STRING_VALUE, return the value as a String.
java.lang.Object	nextValue() If the ParseState was JSONStreamReader.ParseState.NULL_VALUE, JSONStreamReader.ParseState.BOOLEAN_VALUE, JSONStreamReader.ParseState.NUMBER_VALUE, or JSONStreamReader.ParseState.STRING_VALUE, return the value as an Object.
JSONStreamReader.ParseState	skipToEndStructure() Skip over the content of the current object or array, including any nested objects or arrays.
java.lang.String	toString() Returns a string representation of the stream reader, including its current position in the source stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

lexer

protected final JSONLexer lexer

objectStack

protected final ALStack<JSONLexer.Token> objectStack

bufferedAppender

protected final BufferedAppendable bufferedAppender

state

protected JSONStreamReader.ParseState state

Constructor Detail

JSONStreamReader

public JSONStreamReader(java.io.Reader reader)

Construct a JSONStreamReader from a Reader.

Parameters:

reader - A reader.

JSONStreamReader

public JSONStreamReader(java.io.InputStream inputStream,
                        java.nio.charset.Charset charset)

Construct a JSONStreamReader from an InputStream and a supplied Charset.

Parameters:

inputStream - the input stream containing the JSON data

charset - the character set with which to interpret the input stream

JSONStreamReader

public JSONStreamReader(java.lang.String s)

Construct a JSONStreamReader from a String.

Parameters:

s - A source string.

Method Detail

hasNext

public boolean hasNext()

Are there more parse states remaining in the source stream.

Returns:

true if there are more parse states remaining, otherwise false

nextState

public JSONStreamReader.ParseState nextState()
                                      throws JSONException

Advance the parser onto the next state in the source stream, and return a JSONStreamReader.ParseState representing the state that was encountered.

Returns:

one of the ParseState values

Throws:

JSONException - there was a problem with the source stream

nextKey

public java.lang.String nextKey()
                         throws JSONException

If the ParseState was JSONStreamReader.ParseState.KEY, return the text of the key name.

This method advances the parser onto the next state.

Returns:

the parsed text of the key

Throws:

JSONException - there was a problem with the source stream

nextValue

public java.lang.Object nextValue()
                           throws JSONException

If the ParseState was JSONStreamReader.ParseState.NULL_VALUE, JSONStreamReader.ParseState.BOOLEAN_VALUE, JSONStreamReader.ParseState.NUMBER_VALUE, or JSONStreamReader.ParseState.STRING_VALUE, return the value as an Object. The values that can be returned here are:

• JSONObject.NULL
• Boolean.TRUE or Boolean.FALSE
• A Double, Long, Integer, BigInteger, or BigDecimal
• A String

This method advances the parser onto the next state.

Returns:

an Object of the type described above

Throws:

JSONException

nextStringValue

public java.lang.String nextStringValue()
                                 throws JSONException

If the ParseState was JSONStreamReader.ParseState.STRING_VALUE, return the value as a String.

This method advances the parser onto the next state.

Returns:

a String value

Throws:

JSONException

appendNextStringValue

public <T extends java.lang.Appendable> T appendNextStringValue(T writer)
                                                         throws JSONException

If the ParseState was JSONStreamReader.ParseState.STRING_VALUE, append the decoded value to the given Appendable.

This method is suitable for cases where very long String data is expected, for instance for base-64 encoded data.

This method advances the parser onto the next state.

Type Parameters:

T - the type of Appendable, returned to the caller

Parameters:

writer - the writer to which the String value will be written

Returns:

the given Appendable object

Throws:

JSONException

nextBooleanValue

public boolean nextBooleanValue()
                         throws JSONException

If the ParseState was JSONStreamReader.ParseState.BOOLEAN_VALUE, return the value as a boolean.

If the JSON value is not parseable as a boolean, as defined by the JSON grammar, a JSONException will be thrown.

This method advances the parser onto the next state.

Returns:

a boolean value

Throws:

JSONException

nextNullValue

public java.lang.Object nextNullValue()
                               throws JSONException

If the ParseState was JSONStreamReader.ParseState.NULL_VALUE, return the value as a NULL object.

If the JSON value is not parseable as a null, as defined by the JSON grammar, a JSONException will be thrown.

This method advances the parser onto the next state.

Returns:

the JSONObject.NULL value

Throws:

JSONException

nextNumberValue

public java.lang.Number nextNumberValue()
                                 throws JSONException

If the ParseState was JSONStreamReader.ParseState.NUMBER_VALUE, return the value as a Number.

The number type returned is one of:

• A Double
• A Long
• An Integer
• A BigDecimal
• A BigInteger

This method advances the parser onto the next state.

Returns:

a value that is a subclass of the Number class

Throws:

JSONException

appendNextNumberValue

public <T extends java.lang.Appendable> T appendNextNumberValue(T writer)
                                                         throws JSONException

If the ParseState was JSONStreamReader.ParseState.NUMBER_VALUE, append the number sequence to the given Appendable.

This method is suitable for cases where the caller wishes to perform their own conversion of number values into a corresponding Object type.

This method advances the parser onto the next state.

Type Parameters:

T - the type of Appendable, returned to the caller

Parameters:

writer - the writer to which the number sequence will be written

Returns:

the given Appendable object

Throws:

JSONException

nextBigDecimalValue

public java.math.BigDecimal nextBigDecimalValue()
                                         throws JSONException

If the ParseState was JSONStreamReader.ParseState.NUMBER_VALUE, return the value as a BigDecimal.

This method advances the parser onto the next state.

Returns:

a number value as a BigDecimal class

Throws:

JSONException

nextBigIntegerValue

public java.math.BigInteger nextBigIntegerValue()
                                         throws JSONException

If the ParseState was JSONStreamReader.ParseState.NUMBER_VALUE, return the value as a BigInteger.

If the JSON value is not parseable as a big integer, as defined by the JSON grammar, a JSONException will be thrown.

This method advances the parser onto the next state.

Returns:

a number value as a BigInteger class

Throws:

JSONException

nextDoubleValue

public double nextDoubleValue()
                       throws JSONException

If the ParseState was JSONStreamReader.ParseState.NUMBER_VALUE, return the value as a double.

This method advances the parser onto the next state.

Returns:

a double value

Throws:

JSONException

nextIntValue

public int nextIntValue()
                 throws JSONException

If the ParseState was JSONStreamReader.ParseState.NUMBER_VALUE, return the value as an int.

If the JSON value is not parseable as an int, as defined by the JSON grammar, a JSONException will be thrown.

This method advances the parser onto the next state.

Returns:

an int value

Throws:

JSONException

nextLongValue

public long nextLongValue()
                   throws JSONException

If the ParseState was JSONStreamReader.ParseState.NUMBER_VALUE, return the value as a long.

If the JSON value is not parseable as a long, as defined by the JSON grammar, a JSONException will be thrown.

This method advances the parser onto the next state.

Returns:

a long value

Throws:

JSONException

getStackDepth

public int getStackDepth()

Get the depth of nested objects, arrays, or values.

Returns:

the depth of nested objects, arrays, or values

getParsePosition

public ParsePosition getParsePosition()

Indicates the current position of the scanner.

Returns:

a ParsePosition representing the current location of the scanner

currentState

public JSONStreamReader.ParseState currentState()

Return the current state of the parser, including any of the internal states. Only required in exceptional circumstances.

Returns:

the current JSONStreamReader.ParseState

skipToEndStructure

public JSONStreamReader.ParseState skipToEndStructure()
                                               throws JSONException

Skip over the content of the current object or array, including any nested objects or arrays.

Returns:

the closing ParseState of the object or array

Throws:

JSONException

decodeNumber

protected java.lang.Number decodeNumber(java.lang.String val,
                                        boolean isDbl)
                                 throws JSONException

Decode a number strictly according to the JSON specification.

Parameters:

val - the String value to be decoded as a number

isDbl - true to indicate the value is a decimal or exponent value, otherwise false

Returns:

the number represented by the token sequence

Throws:

JSONException

decodeDouble

protected double decodeDouble(java.lang.String val,
                              boolean isDbl)
                       throws JSONException

Decode a number as a double strictly according to the JSON specification.

Parameters:

val - the String value to be decoded as a double

isDbl - true to indicate the value is a decimal or exponent value, otherwise false

Returns:

the number represented by the token sequence

Throws:

JSONException

decodeInt

protected int decodeInt(java.lang.String val,
                        boolean isDbl)
                 throws JSONException

Parse a number as an int strictly according to the JSON specification. No coercion of double or long values.

Parameters:

val - the String value to be decoded as an int

isDbl - true to indicate the value is a decimal or exponent value, otherwise false

Returns:

the number represented by the token sequence

Throws:

JSONException

decodeLong

protected long decodeLong(java.lang.String val,
                          boolean isDbl)
                   throws JSONException

Parse a number as a long strictly according to the JSON specification. No coercion of double values.

Parameters:

val - the String value to be decoded as a long

isDbl - true to indicate the value is a decimal or exponent value, otherwise false

Returns:

the number represented by the token sequence

Throws:

JSONException

decodeBigDecimal

protected java.math.BigDecimal decodeBigDecimal(java.lang.String val)
                                         throws JSONException

Parse a number as a BigDecimal strictly according to the JSON specification.

Parameters:

val - the String value to be decoded as a big decimal value

Returns:

the number represented by the token sequence

Throws:

JSONException

decodeBigInteger

protected java.math.BigInteger decodeBigInteger(java.lang.String val,
                                                boolean isDbl)
                                         throws JSONException

Parse a number as a BigInteger strictly according to the JSON specification.

Parameters:

val - the String value to be decoded as a big integer

isDbl - true to indicate the value is a decimal or exponent value, otherwise false

Returns:

the number represented by the token sequence

Throws:

JSONException

decodeNull

protected java.lang.Object decodeNull()
                               throws JSONException

Return an object that represents a JSON null value.

Returns:

a JSON null value

Throws:

JSONException

toString

public java.lang.String toString()

Returns a string representation of the stream reader, including its current position in the source stream.

Overrides:

toString in class java.lang.Object