org.inria.ns.reflex.util.json
Class JSONParser

java.lang.Object
  extended by org.inria.ns.reflex.util.json.JSONParser

public class JSONParser
extends Object

Read a stream of characters and parses it as a JSON structure.

Basically, it consist on reading the input, creating the relevant objects with the JSON factory, and passing them to the JSON handler with the JSON context that hold the target structure and the parser state. Since the parser state is separated from this parser, this allow to perform successive parsings as a whole without loosing the context.

A single structure can be parsed at once by the same instance. Once finished, the parser can be reused for reading a new structure.

The parsing doesn't end systematically when the parse() method returns, but when the input document has been read entirely. The context has method that indicates if the parsed structure is well-formed.

Push-parsing

Most common usage for parsing all the input at once.

Just call parse(Reader) (or another similar method).

Pull-parsing

Usage for parsing a single value on demand.

Just call once initialize(Reader). Then call parseNext() and repeat. Each new value parsed will be appended to the JSON context with the relevant method. Before getting the next value, hasNext() can be used. After getting the next value, JSONContext.lastIsValue() and JSONContext.lastValue() can be used.

Successive fragment parsing

This applies for push-parsing and pull-parsing.

It is possible to have a well-formed JSON structure splitted into several chunk of input sources. When an input source ends, the initialize(Reader) method can be invoked directly (pull) or implicitely by using parse(Reader).

This is a valuable feature allowing to append non-JSON objects within the parsed structure between two chunks of JSON code. See JSONContext.inject(Object) and similar methods.

Progressive scan

At the end of a well-formed JSON structure, the input source can contain non-JSON characters in order to cause a JSON error that stops the parsing. The user can check the state of the context and get the result built so far. This allow to have a continuous input source that contains a JSON structure followed by a non-JSON structure that would be parsed by another parser.

Example :

{ "xml": true }
<root/>

The JSON parser will fail at "<", but the JSON structure can be get with JSONContext.getJSONDocument(boolean). The next structure to parse with another parser can be get with getLastReader().

Code examples

Source code of Java examples are available in the SVN repository : org.inria.ns.reflex.jtests.json.JsonTest

Author:
Philippe Poulard

Constructor Summary
JSONParser(JSONContext context)
          Create a new JSON parser.
 
Method Summary
static char escapeJSONCharacter(Scanner scanner)
          Escape the next JSON character.
 Reader getLastReader()
          Return the last reader used.
 boolean hasNext()
          Indicates whether a value is available in the input.
 void initialize(Reader reader)
          Initialize this JSON parser according to its configuration.
static boolean isJSONLineBreak(char c)
          Indicates whether or not the given character is a JSON line break.
static boolean isJSONWhitespace(char c)
          Indicates whether the given character is a JSON whitespace.
 Object parse(InputSource source)
          Parse the input source.
 Object parse(InputStream stream)
          Parse the input stream.
 Object parse(Reader reader)
          Parse the character stream.
 Object parse(String string)
          Parse the characters in the given string as a JSON structure.
 Object parse(URL url)
          Parse the JSON structure located at the given URL.
 void parseNext()
          Parse a single JSON value from the current input source with the current configuration.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JSONParser

public JSONParser(JSONContext context)
Create a new JSON parser.

Parameters:
context - The context to use while parsing.
Method Detail

parse

public Object parse(InputSource source)
             throws IOException,
                    JSONException
Parse the input source.

Parameters:
source - The source to parse.
Returns:
The relevant JSON object supplied by the factory.
Throws:
IOException - When an I/O error occur.
JSONException - When the parsing fail.

parse

public Object parse(String string)
             throws IOException,
                    JSONException
Parse the characters in the given string as a JSON structure.

Parameters:
string - The string to parse.
Returns:
The relevant JSON object supplied by the factory.
Throws:
IOException - When an I/O error occur.
JSONException - When the parsing fail.

parse

public Object parse(URL url)
             throws IOException,
                    JSONException
Parse the JSON structure located at the given URL.

Parameters:
url - The source where to find the JSON structure.
Returns:
The relevant JSON object supplied by the factory.
Throws:
IOException - When an I/O error occur.
JSONException - When the parsing fail.

parse

public Object parse(InputStream stream)
             throws IOException,
                    JSONException
Parse the input stream.

Parameters:
stream - The stream to parse. The encoding used is guessed from the 4 first bytes of the input, as specified in RFC 4627.
Returns:
The relevant JSON object supplied by the factory.
Throws:
IOException - When an I/O error occur.
JSONException - When the parsing fail.

parse

public Object parse(Reader reader)
             throws IOException,
                    JSONException
Parse the character stream.

If the reader doesn't support marks, it is wrapped in a buffer.

Parameters:
reader - The character stream to parse.
Returns:
A JSON document supplied by the factory, or null if no JSON content were found.
Throws:
IOException - When an I/O error occur.
JSONException - When the parsing fail.
See Also:
JSONFactory#newJSONDocument(JSONParser)

parseNext

public void parseNext()
               throws IOException,
                      JSONException
Parse a single JSON value from the current input source with the current configuration. Once get, the JSON value is added to the JSON context with the relevant method.

Throws:
IOException
JSONException
See Also:
JSONContext

getLastReader

public Reader getLastReader()
                     throws IOException
Return the last reader used.

If this parser was used for scanning a JSON structure in the input, after the JSON structure has been processed the reader might be used for further scan ; this method allow to perform further reading.

Returns:
The last reader used by this parser, or null if the end of the stream was reached or an error occurred.
Throws:
IOException
See Also:
JSONConfiguration#isScanning()

escapeJSONCharacter

public static char escapeJSONCharacter(Scanner scanner)
                                throws IOException
Escape the next JSON character.

Parameters:
scanner - The scanner to read from.
Returns:
The next escaped character.
Throws:
IOException - When the escape sequence is invalid.

isJSONWhitespace

public static boolean isJSONWhitespace(char c)
Indicates whether the given character is a JSON whitespace.

A line break in JSON is either a LINE FEED (U+000A), a CARRIAGE RETURN (U+000D), an HORIZONTAL TAB (U+0009), or the SPACE (U+0020).

Parameters:
c - The character to test.
Returns:
true if it is a whitespace, false otherwise.
See Also:
isJSONLineBreak(char)

isJSONLineBreak

public static boolean isJSONLineBreak(char c)
Indicates whether or not the given character is a JSON line break.

A line break in JSON is either a LINE FEED (U+000A) or a CARRIAGE RETURN (U+000D).

Parameters:
c - The character to test.
Returns:
true if it is a line break, false otherwise.
See Also:
isJSONWhitespace(char)

initialize

public void initialize(Reader reader)
                throws IOException
Initialize this JSON parser according to its configuration.

Parameters:
reader - The reader that contains the JSON structure to parse.
Throws:
IOException - When an I/O error occur.
IllegalStateException - When this parser has already been initialized.

hasNext

public boolean hasNext()
                throws IOException
Indicates whether a value is available in the input.

Returns:
true if non ignorable characters are available, false if the input was read entirely.
Throws:
IOException - When an I/O error occurs.