Class JSONReader

java.lang.Object

com.leastfixedpoint.json.JSONReader

public class JSONReader
extends Object

Parse JSON text to Java values.

• JSON strings are represented as java.lang.String.
• JSON true and false are represented as java.lang.Boolean.
• JSON null is represented as JSONNull.INSTANCE.
• JSON numbers are represented as Java java.math.BigDecimal.
• JSON arrays are represented as java.util.List.
• JSON maps/objects are represented as java.util.Map.

Syntax errors are reported with JSONSyntaxError or, in case of short input, EOFException.

This class is able to read multiple adjacent JSON values from a single input stream. However, some care is needed when doing this, since this class maintains a one-character internal lookahead buffer. Reading a single JSON value generally consumes up to one character more than needed. For example, given a reader with ready input "123x", JSONReader will consume all four bytes. When reading multiple JSON values from a stream, it is important to use the same JSONReader object, since it will maintain its internal lookahead buffer between objects and so will not accidentally discard input.

Furthermore, when given a Reader that is not a LineNumberReader, this class creates a wrapping LineNumberReader, which may internally consume input from the underlying reader in a way not under our control.

Finally, this class can be used as a simple SAX-style JSON tokenizer; see nextLexeme() and the class JSONEventReader.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	JSONReader.Lexeme	Most JSON tokens are self-representing; the remainder are represented with instances of Lexeme.

Field Summary

Fields

Modifier and Type	Field	Description
protected int	_buffer
protected int	EOF
protected int	NO_TOKEN
protected LineNumberReader	reader

Constructor Summary

Constructors

Constructor	Description
JSONReader(Reader r)	Construct a reader that reads JSON text from the given Reader.

Method Summary

Modifier and Type	Method	Description
protected Object	_read()
protected List<Object>	array()
protected boolean	atEOF()
protected int	buffer()
protected boolean	check(char expected)
protected boolean	checkDrop(char expected)
protected char	curr()
protected void	drop()
void	expectEOF()	Consumes any whitespace in the stream, and returns normally if it then finds itself at the end of the stream.
LineNumberReader	getReader()	Retrieve the underlying LineNumberReader.
Object	nextLexeme()	Read the next JSON token from the input stream.
protected Object	number()
protected Map<String,Object>	object()
Object	read()	Reads and returns the next JSON value.
protected Object	readAtom(String atom, Object value)
static Object	readFrom(Reader r)	Reads and returns a single JSON value from the given Reader.
protected static Object	readFrom(Reader r, boolean ensureSingleValue)	Reads and returns a single JSON value from the given Reader.
static Object	readFrom(String s)	Reads and returns a single JSON value from the given input JSON source text.
static Object	readFrom(String s, boolean ensureSingleValue)	Reads and returns a single JSON value from the given input JSON source text.
JSONValue	readValue()	As read(), but wraps the result in JSONValue.
static JSONValue	readValue(Reader r)	Reads and returns a single JSONValue from the given Reader.
static JSONValue	readValue(String s)	Reads and returns a single JSONValue from the given input JSON source text.
static JSONValue	readValue(String s, boolean ensureSingleValue)	Reads and returns a single JSONValue from the given input JSON source text.
protected void	skipWhiteSpace()
protected Object	string(char sep)	Read a string with a specific delimiter (either ' or ")
protected Object	valueGuard(Object value)

Methods inherited from class java.lang.Object

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

Field Details

NO_TOKEN

protected int NO_TOKEN

EOF

protected int EOF

reader

protected LineNumberReader reader

_buffer

protected int _buffer

Constructor Details

JSONReader

public JSONReader(Reader r)

Construct a reader that reads JSON text from the given Reader. If the Reader is not a LineNumberReader, it is wrapped in a LineNumberReader.

Parameters:

r - Input to the JSONReader.

Method Details

getReader

public LineNumberReader getReader()

Retrieve the underlying LineNumberReader.

readFrom

public static Object readFrom(Reader r)
                       throws IOException

Reads and returns a single JSON value from the given Reader. Calls expectEOF() after reading, to ensure no trailing junk is present.

Throws:

IOException

readValue

public static JSONValue readValue(Reader r)
                           throws IOException

Reads and returns a single JSONValue from the given Reader. Calls expectEOF() after reading, to ensure no trailing junk is present.

Throws:

IOException

readFrom

public static Object readFrom(String s)
                       throws IOException

Reads and returns a single JSON value from the given input JSON source text. Calls expectEOF() after reading, to ensure no trailing junk is present.

Throws:

IOException

readValue

public static JSONValue readValue(String s)
                           throws IOException

Reads and returns a single JSONValue from the given input JSON source text. Calls expectEOF() after reading, to ensure no trailing junk is present.

Throws:

IOException

readFrom

public static Object readFrom(String s,
 boolean ensureSingleValue)
                       throws IOException

Reads and returns a single JSON value from the given input JSON source text. If ensureSingleValue is true, calls expectEOF() after reading, to ensure no trailing junk is present. Otherwise, ignores any input following the JSON value returned.

Throws:

IOException

readValue

public static JSONValue readValue(String s,
 boolean ensureSingleValue)
                           throws IOException

Reads and returns a single JSONValue from the given input JSON source text. If ensureSingleValue is true, calls expectEOF() after reading, to ensure no trailing junk is present. Otherwise, ignores any input following the JSON value returned.

Throws:

IOException

readFrom

protected static Object readFrom(Reader r,
 boolean ensureSingleValue)
                          throws IOException

Reads and returns a single JSON value from the given Reader. If ensureSingleValue is true, calls expectEOF() after reading, to ensure no trailing junk is present. Otherwise, leaves the given Reader in good condition to yield additional input. This is protected rather than public because reading multiple JSON values depends on the state of the internal lookahead buffer, which with this static method is clearly not preserved. It would be dangerous to encourage use of this method to read multiple JSON values from a stream. Instead, a long-running instance of JSONReader should be used to parse the whole stream.

Throws:

IOException

drop

protected void drop()
             throws IOException

Throws:

IOException

buffer

protected int buffer()
              throws IOException

Throws:

IOException

atEOF

protected boolean atEOF()
                 throws IOException

Throws:

IOException

curr

protected char curr()
             throws IOException

Throws:

IOException

check

protected boolean check(char expected)
                 throws IOException

Throws:

IOException

checkDrop

protected boolean checkDrop(char expected)
                     throws IOException

Throws:

IOException

skipWhiteSpace

protected void skipWhiteSpace()
                       throws IOException

Throws:

IOException

valueGuard

protected Object valueGuard(Object value)
                     throws JSONSyntaxError

Throws:

JSONSyntaxError

read

public Object read()
            throws IOException

Reads and returns the next JSON value. Throws EOFException if no complete JSON value is available.

Throws:

IOException

readValue

public JSONValue readValue()
                    throws IOException

As read(), but wraps the result in JSONValue.

Throws:

IOException

expectEOF

public void expectEOF()
               throws IOException

Consumes any whitespace in the stream, and returns normally if it then finds itself at the end of the stream. Throws JSONSyntaxError if, after consuming whitespace, some non-whitespace input remains to be consumed. Useful for enforcing rules about files containing some fixed number of JSON values and no more.

Throws:

IOException

readAtom

protected Object readAtom(String atom,
 Object value)
                   throws IOException

Throws:

IOException

nextLexeme

public Object nextLexeme()
                  throws IOException

Read the next JSON token from the input stream. Strings, numbers, booleans and null are returned as the Java representations of their JSON values, as described in the class comment for this class. Array and object delimiters are returned as instances of JSONReader.Lexeme. Throws EOFException at the end of the input.

Throws:

IOException

_read

protected Object _read()
                throws IOException

Throws:

IOException

object

protected Map<String,Object> object()
                             throws IOException

Throws:

IOException

array

protected List<Object> array()
                      throws IOException

Throws:

IOException

number

protected Object number()
                 throws IOException

Throws:

IOException

string

protected Object string(char sep)
                 throws IOException

Read a string with a specific delimiter (either ' or ")

Throws:

IOException