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

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

public class JSONContext
extends Object

A JSON context used when parsing a JSON structure.

When a parsing ends, the state is held by this context, so that further parsings with a new input stream can be done. Consequently, the entity that launches a parsing have to ensure that the stack is empty, and optionally that the end of the stream was reached.

Between two chunks of JSON streams (that as a whole have to be well-formed), non-JSON objects can be injected between JSON atoms (that is to say, not within a string).

Author:
Philippe Poulard
See Also:
JSONParser, inject(Object)

Constructor Summary
JSONContext(JSONFactory factory, JSONHandler handler)
          Create a new JSON context with a default configuration (conformant to RFC 4627 with no option).
JSONContext(JSONFactory factory, JSONHandler handler, JSONConfiguration configuration)
          Create a new JSON context.
 
Method Summary
 void createRootIfNecessary()
          Create the JSON document if necessary (that is to say if not yet done).
 JSONConfiguration getJSONConfiguration()
          Return the JSON configuration.
 Object getJSONDocument(boolean completed)
          Get the JSON document hold by this context.
 JSONFactory getJSONFactory()
          Return the JSON factory.
 JSONHandler getJSONHandler()
          Return the JSON handler.
 JSONParser getJSONParser()
          Return the JSON parser.
 boolean hasNext()
          Indicates whether there remains characters to read in the input.
 boolean hostIsArray()
          Indicates whether the current host structure is a JSON array or not.
 boolean hostIsObject()
          Indicates whether the current host structure is a JSON object or not.
 boolean hostIsRoot()
          Indicates whether the current host structure is the root or not.
 void inject(Object item)
          Inject a custom item in the current structure.
 void inject(Object item, boolean asObject, boolean asArray)
          Inject a custom item in the current structure.
 void inject(QName name, Object item)
          Inject a custom item in the current structure.
 void inject(QName name, Object item, boolean asObject, boolean asArray)
          Inject a custom item in the current structure.
 boolean isCompleted()
          Indicates whether this context hold a well-formed JSON document or not.
 boolean lastIsArray()
          Indicates whether the last token read by the parser denotes a JSON array or not.
 boolean lastIsObject()
          Indicates whether the last token read by the parser denotes a JSON object or not.
 boolean lastIsStructure()
          Indicates whether the last token read by the parser denotes a structure (JSON array or JSON object) or not.
 boolean lastIsValue()
          Indicates whether the last sequence read by the parser was a JSON value (including array and object) or not.
 Object lastValue()
          Return the last value parsed.
 Object peekStructure()
          Peek the current structure from this context.
 void setConfiguration(JSONConfiguration configuration)
          Change the configuration of this context.
 void setFactory(JSONFactory factory)
          Change the factory of this context.
 void setHandler(JSONHandler handler)
          Change the handler of this context.
 void setQName(QName name)
          Set a name for the current value.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JSONContext

public JSONContext(JSONFactory factory,
                   JSONHandler handler,
                   JSONConfiguration configuration)
Create a new JSON context. The factory and the handler MUST be compatible.

Parameters:
factory - The factory for building JSON values.
handler - The handler that accept JSON values.
configuration - The configuration to use by the JSON parser.
See Also:
JSONParser.JSONParser(JSONContext)

JSONContext

public JSONContext(JSONFactory factory,
                   JSONHandler handler)
Create a new JSON context with a default configuration (conformant to RFC 4627 with no option). The factory and the handler MUST be compatible.

Parameters:
factory - The factory for building JSON values.
handler - The handler that accept JSON values.
See Also:
JSONParser.JSONParser(JSONContext)
Method Detail

getJSONHandler

public JSONHandler getJSONHandler()
Return the JSON handler.

Returns:
The JSON handler.

setHandler

public void setHandler(JSONHandler handler)
Change the handler of this context. The factory and the handler MUST be compatible.

Parameters:
handler - The handler to set.
See Also:
setFactory(JSONFactory)

getJSONConfiguration

public JSONConfiguration getJSONConfiguration()
Return the JSON configuration.

Returns:
The JSON configuration.

setConfiguration

public void setConfiguration(JSONConfiguration configuration)
Change the configuration of this context.

Parameters:
configuration - The configuration to set.

getJSONParser

public JSONParser getJSONParser()
Return the JSON parser.

Returns:
The JSON parser.

getJSONFactory

public JSONFactory getJSONFactory()
Return the JSON factory.

Returns:
The JSON factory.

setFactory

public void setFactory(JSONFactory factory)
Change the factory of this context. The factory and the handler MUST be compatible.

Parameters:
factory - The factory to set.
See Also:
setHandler(JSONHandler)

peekStructure

public Object peekStructure()
Peek the current structure from this context.

Returns:
The structure to which JSON values and members can be added.
See Also:
JSONHandler

getJSONDocument

public Object getJSONDocument(boolean completed)
                       throws JSONException
Get the JSON document hold by this context. This method should be called after parsing.

Parameters:
completed - Indicates whether the document have to be well-formed or not.
Returns:
A JSON document, or null if empty.
Throws:
JSONException - If the current structure didn't end.

isCompleted

public boolean isCompleted()
Indicates whether this context hold a well-formed JSON document or not.

Returns:
true if the JSON document is well-formed, false if further parsing have to be done.

hasNext

public boolean hasNext()
Indicates whether there remains characters to read in the input.

Returns:
true if at least 1 character can be read, false if the end of the input stream was reached.
See Also:
JSONParser.JSONParser(JSONContext)

createRootIfNecessary

public void createRootIfNecessary()
                           throws JSONException,
                                  IOException
Create the JSON document if necessary (that is to say if not yet done).

Throws:
JSONException
IOException
See Also:
JSONFactory#newJSONDocument(JSONParser)

inject

public void inject(QName name,
                   Object item,
                   boolean asObject,
                   boolean asArray)
            throws JSONException,
                   IOException
Inject a custom item in the current structure.

Parameters:
name - The name of the item. QNULL force the item to have no name, null to use the current name if any.
item - The item to inject.
asObject - true if the item have to be injected as a JSON object, false otherwise.
asArray - true if the item have to be injected as a JSON array, false otherwise.
Throws:
JSONException
IOException

inject

public void inject(Object item,
                   boolean asObject,
                   boolean asArray)
            throws JSONException,
                   IOException
Inject a custom item in the current structure. If a name has been set previously, it will be used.

Parameters:
item - The item to inject.
asObject - true if the item have to be injected as a JSON object, false otherwise.
asArray - true if the item have to be injected as a JSON array, false otherwise.
Throws:
JSONException
IOException

inject

public void inject(Object item)
            throws JSONException,
                   IOException
Inject a custom item in the current structure. If a name has been set previously, it will be used.

Parameters:
item - The item to inject.
Throws:
JSONException
IOException

inject

public void inject(QName name,
                   Object item)
            throws JSONException,
                   IOException
Inject a custom item in the current structure.

Parameters:
name - The name of the item. QNULL force the item to have no name, null to use the current name if any.
item - The item to inject.
Throws:
JSONException
IOException

setQName

public void setQName(QName name)
Set a name for the current value.

Parameters:
name - The name to set. null is allowed.

lastValue

public Object lastValue()
Return the last value parsed. null can stand either for the null value (if the factory can supply it) or for a JSON token.

Returns:
The value created by the relevant factory.
See Also:
lastIsValue()

lastIsStructure

public boolean lastIsStructure()
Indicates whether the last token read by the parser denotes a structure (JSON array or JSON object) or not.

Returns:
true if the last significative token read by the parser was "{" or "[".

lastIsObject

public boolean lastIsObject()
Indicates whether the last token read by the parser denotes a JSON object or not.

Returns:
true if the last significative token read by the parser was "{".
See Also:
lastIsStructure(), lastIsArray()

lastIsArray

public boolean lastIsArray()
Indicates whether the last token read by the parser denotes a JSON array or not.

Returns:
true if the last significative token read by the parser was "[".
See Also:
lastIsStructure(), lastIsObject()

lastIsValue

public boolean lastIsValue()
Indicates whether the last sequence read by the parser was a JSON value (including array and object) or not.

Returns:
true if a value is available, false if a token was read or EOF.
See Also:
lastValue(), hasNext()

hostIsObject

public boolean hostIsObject()
Indicates whether the current host structure is a JSON object or not.

Returns:
true if the current host structure is an object, false otherwise.

hostIsArray

public boolean hostIsArray()
Indicates whether the current host structure is a JSON array or not.

Returns:
true if the current host structure is an array, false otherwise.

hostIsRoot

public boolean hostIsRoot()
Indicates whether the current host structure is the root or not.

Returns:
true if the current host structure is the root, false otherwise.