org.openjax.json

Class JsonReader

java.lang.Object

java.io.Reader

java.io.FilterReader

org.libj.io.ReplayReader

org.openjax.json.JsonReader

All Implemented Interfaces:

Closeable, AutoCloseable, Iterable<String>, Readable, Iterator<String>

public class JsonReader
extends ReplayReader
implements Iterable<String>, Iterator<String>

Validating Reader for JSON streams that reads JSON tokens sequentially, while asserting the content conforms to the RFC 4627 specification.

This implementation provides the following features:

• Regular read of JSON tokens, sequentially returning each token String: readToken(). (Please see readToken() for a definition of: token).
• Optimized read of JSON tokens, sequentially returning the int starting position of each token: readTokenStart(). (This position can be dereferenced via: buf()).
• Implements the Iterable interface, to sequentially iterate over each token: iterator().
• Caches and indexes each token: getIndex().
• Allows to read back previously read tokens: setIndex(int).
• Support partial reads of tokens with read(), read(char[]). and read(char[], int, int) methods.

Nested Class Summary

Nested classes/interfaces inherited from class org.libj.io.ReplayReader

ReplayReader.ReadbackCharArrayWriter

Field Summary

Fields inherited from class org.libj.io.ReplayReader

buffer, closed

Fields inherited from class java.io.FilterReader

in

Fields inherited from class java.io.Reader

lock

Constructor Summary

Constructors

Constructor and Description
JsonReader(Reader reader) Construct a new JsonReader for JSON content to be read from the specified Reader, that ignores inter-token whitespace.
JsonReader(Reader reader, boolean ignoreWhitespace) Construct a new JsonReader for JSON content to be read from the specified Reader.

Method Summary

Modifier and Type	Method and Description
protected char[]	buf() Returns the char[] buffer of the underlying JsonReplayReader.
protected int	getEndPosition(int index) Returns the end position at index.
int	getIndex() Returns the index of the most recently read token.
int	getPosition() Returns the buffer position of the most recently read char.
protected int	getStartPosition(int index) Returns the start position at index.
boolean	hasNext() Returns true if the iteration has more tokens.
Iterator<String>	iterator() Returns this JsonReader, since it is itself an implementation of the Iterator interface.
void	mark(int readlimit)
String	next() Returns the next token in the iteration.
int	read() Reads a single character, and transparently unescapes string-literal unicode (" ") and two-character ("\n") escape codes into UTF-8 as defined in RFC 4627, Section 2.5.
int	read(char[] cbuf) Reads characters into an array, and transparently unescapes string-literal unicode (" ") and two-character ("\n") escape codes into UTF-8, as defined in RFC 4627, Section 2.5.
int	read(char[] cbuf, int off, int len) Reads characters into a portion of an array, and transparently unescapes string-literal unicode (" ") and two-character ("\n") escape codes into UTF-8, as defined in RFC 4627, Section 2.5.
String	readToken() Read the next JSON token.
protected int	readTokenStart() Read until the end of the next token, and return the start index of the token that was just read.
void	reset()
void	setIndex(int index) Sets the token index of this reader, such that getIndex() returns the specified index.
protected void	setPosition(int p) Set the buffer to position p, such that a subsequent call to read() will return the char at p + 1.
int	size() Returns the number of tokens read thus far.

Methods inherited from class org.libj.io.ReplayReader

close, markSupported, ready, skip

Methods inherited from class java.io.Reader

read

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Methods inherited from interface java.util.Iterator

forEachRemaining, remove

Constructor Detail

JsonReader

public JsonReader(Reader reader)

Construct a new JsonReader for JSON content to be read from the specified Reader, that ignores inter-token whitespace. This constructor is equivalent to calling new JsonReader(reader, true).

Parameters:

reader - The Reader from which JSON is to be read.

JsonReader

public JsonReader(Reader reader,
                  boolean ignoreWhitespace)

Construct a new JsonReader for JSON content to be read from the specified Reader.

Parameters:

reader - The Reader from which JSON is to be read.

ignoreWhitespace - If ignoreWhitespace == false, inter-token whitespace will not be skipped.

Method Detail

getIndex

public int getIndex()

Returns the index of the most recently read token.

Returns:

The index of the most recently read token.

setIndex

public void setIndex(int index)

Sets the token index of this reader, such that getIndex() returns the specified index. Note, that calling readToken() after this method will return the token with index index + 1.

Parameters:

index - The index to be set.

Throws:

IllegalArgumentException - If index < -1 || size() <= index.

size

public int size()

Returns the number of tokens read thus far. The value returned by this method defines the upper bound of setIndex(int).

Returns:

The number of tokens read thus far. The value returned by this method defines the upper bound of setIndex(int).

getStartPosition

protected int getStartPosition(int index)

Returns the start position at index.

Parameters:

index - The token index.

Returns:

The start position at index.

getEndPosition

protected int getEndPosition(int index)

Returns the end position at index.

Parameters:

index - The token index.

Returns:

The end position at index.

setPosition

protected void setPosition(int p)

Set the buffer to position p, such that a subsequent call to read() will return the char at p + 1.

Parameters:

p - The position.

Throws:

IllegalArgumentException - If p is negative, or if p is greater than the length of the underlying buffer.

getPosition

public int getPosition()

Returns the buffer position of the most recently read char.

Returns:

The buffer position of the most recently read char.

readToken

public String readToken()
                 throws IOException,
                        JsonParseException

Read the next JSON token. A JSON token is one of:

• Structural:
  • A character that is one of:

    { } [ ] : ,

• A property key:
  • A string that matches:

     ^".*"$

• A property or array member value:
  • A string that matches:

     ^".*"$

  • A number that matches:

     ^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?([1-9]\d*))?$

  • A literal that matches:

     ^null|true|false$

• Whitespace:
  • Whitespace string that matches:

     ^[ \n\r\t]+$

Note: If this instance ignores whitespace, this method will skip whitespace tokens.

Returns:

The next JSON token, or null if the end of content has been reached.

Throws:

IOException - If an I/O error has occurred.

JsonParseException - If the content is not well formed.

mark

public void mark(int readlimit)

Overrides:

mark in class ReplayReader

reset

public void reset()

Overrides:

reset in class ReplayReader

read

public int read()
         throws IOException

Reads a single character, and transparently unescapes string-literal unicode (" ") and two-character ("\n") escape codes into UTF-8 as defined in RFC 4627, Section 2.5.

Characters read with this method advance the characters of the tokens to which they belong. Therefore, when partially reading a token with read(), subsequent calls to readToken() will return the remaining characters of the token that have not yet been returned by read(). Characters read with this method undergo the same token-level error checking as in readTokenStart() or readToken().

Returns:

The character read, as an integer in the range 0 to 65535 (0x00-0xffff), or -1 if the end of the stream has been reached.

Throws:

IOException - If an I/O error has occurred.

JsonParseException - If the content is not well formed.

See Also:

readTokenStart(), readToken()

read

public int read(char[] cbuf,
                int off,
                int len)
         throws IOException

Reads characters into a portion of an array, and transparently unescapes string-literal unicode (" ") and two-character ("\n") escape codes into UTF-8, as defined in RFC 4627, Section 2.5.

Characters read with this method advance the characters of the tokens to which they belong. Therefore, when partially reading a token with read(char[],int,int), subsequent calls to readToken() will return the remaining characters of the token that have not yet been returned by read(). Characters read with this method undergo the same token-level error checking as in readTokenStart() or readToken().

Parameters:

cbuf - Destination buffer.

off - Offset at which to start storing characters.

len - Maximum number of characters to read.

Returns:

The number of characters read, or -1 if the end of the stream has been reached.

Throws:

IOException - If an I/O error has occurred.

IndexOutOfBoundsException - If off is negative, or len is negative, or len is greater than cbuf.length - off.

JsonParseException - If the content is not well formed.

See Also:

readTokenStart(), readToken()

read

public int read(char[] cbuf)
         throws IOException

Reads characters into an array, and transparently unescapes string-literal unicode (" ") and two-character ("\n") escape codes into UTF-8, as defined in RFC 4627, Section 2.5.

Characters read with this method advance the characters of the tokens to which they belong. Therefore, when partially reading a token with read(char[]), subsequent calls to readToken() will return the remaining characters of the token that have not yet been returned by read(). Characters read with this method undergo the same token-level validation as in readTokenStart() or readToken().

Parameters:

cbuf - Destination buffer.

Returns:

The number of characters read, or -1 if the end of the stream has been reached.

Throws:

IOException - If an I/O error has occurred.

IndexOutOfBoundsException - If off is negative, or len is negative, or len is greater than cbuf.length - off.

JsonParseException - If the content is not well formed.

See Also:

readTokenStart(), readToken()

iterator

public Iterator<String> iterator()

Returns this JsonReader, since it is itself an implementation of the Iterator interface. The iterator iterates over the JSON token strings produced by JsonReader.readToken().

Specified by:

iterator in interface Iterable<String>

Returns:

This instance.

hasNext

public boolean hasNext()
                throws UncheckedIOException,
                       JsonParseException

Returns true if the iteration has more tokens. (In other words, returns true if next() would return a token rather than throw an exception).

Specified by:

hasNext in interface Iterator<String>

Returns:

true if the iteration has more tokens.

Throws:

UncheckedIOException - If an IOException occurs while reading from the underlying stream.

JsonParseException - If the content is not well formed.

next

public String next()
            throws UncheckedIOException,
                   JsonParseException

Returns the next token in the iteration.

Specified by:

next in interface Iterator<String>

Returns:

The next token in the iteration.

Throws:

NoSuchElementException - If the iteration has no more tokens.

UncheckedIOException - If an IOException occurs while reading from the underlying stream.

JsonParseException - If the content is not well formed.

readTokenStart

protected int readTokenStart()
                      throws IOException,
                             JsonParseException

Read until the end of the next token, and return the start index of the token that was just read. The end index of the token can be retrieved with a subsequent call to getPosition(). If the end of content has been reached, this method returns -1.

Returns:

The start index of the next token.

Throws:

IOException - If an I/O error has occurred.

JsonParseException - If the content is not well formed.

See Also:

nextToken()

buf

protected char[] buf()

Returns the char[] buffer of the underlying JsonReplayReader.

Returns:

The char[] buffer of the underlying JsonReplayReader.