com.cedarsoftware.util.io

Class JsonReader

java.lang.Object

com.cedarsoftware.util.io.JsonReader

All Implemented Interfaces:

Closeable, AutoCloseable

public class JsonReader
extends Object
implements Closeable

Read an object graph in JSON format and make it available in Java objects, or in a "Map of Maps." (untyped representation). This code handles cyclic references and can deserialize any Object graph without requiring a class to be 'Serializeable' or have any specific methods on it. It will handle classes with non public constructors.

Usages:

• Call the static method: JsonReader.objectToJava(String json). This will return a typed Java object graph.
• Call the static method: JsonReader.jsonToMaps(String json). This will return an untyped object representation of the JSON String as a Map of Maps, where the fields are the Map keys, and the field values are the associated Map's values. You can call the JsonWriter.objectToJava() method with the returned Map, and it will serialize the Graph into the identical JSON stream from which it was read.
• Instantiate the JsonReader with an InputStream: JsonReader(InputStream in) and then call readObject(). Cast the return value of readObject() to the Java class that was the root of the graph.
• Instantiate the JsonReader with an InputStream: JsonReader(InputStream in, true) and then call readObject(). The return value will be a Map of Maps.

Author:

John DeRegnaucourt ([email protected])
Copyright (c) Cedar Software LLC

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	JsonReader.BigDecimalReader
static class	JsonReader.BigIntegerReader
static class	JsonReader.CalendarReader
static interface	JsonReader.ClassFactory
static class	JsonReader.ClassReader
static class	JsonReader.CollectionFactory Use to create new instances of collection interfaces (needed for empty collections)
static class	JsonReader.DateReader
static interface	JsonReader.JsonClassReader
static class	JsonReader.LocaleReader
static class	JsonReader.MapFactory Use to create new instances of Map interfaces (needed for empty Maps)
static class	JsonReader.SqlDateReader
static class	JsonReader.StringBufferReader
static class	JsonReader.StringBuilderReader
static class	JsonReader.StringReader
static class	JsonReader.TimestampReader
static class	JsonReader.TimeZoneReader

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAX_CODE_POINT
static char	MIN_HIGH_SURROGATE
static char	MIN_LOW_SURROGATE
static int	MIN_SUPPLEMENTARY_CODE_POINT

Constructor Summary

Constructors

Constructor and Description
JsonReader()
JsonReader(InputStream in)
JsonReader(InputStream in, boolean noObjects)

Method Summary

Methods

Modifier and Type	Method and Description
static void	addNotCustomReader(Class c)
static void	addReader(Class c, JsonReader.JsonClassReader reader)
protected void	assignField(Deque<JsonObject<String,Object>> stack, JsonObject jsonObj, Field field, Object rhs) Map Json Map object field to Java object field.
static void	assignInstantiator(Class c, JsonReader.ClassFactory f) For difficult to instantiate classes, you can add your own ClassFactory which will be called when the passed in class 'c' is encountered.
static BigDecimal	bigDecimalFrom(Object value)
static BigInteger	bigIntegerFrom(Object value)
void	close()
protected Object	convertMapsToObjects(JsonObject<String,Object> root) Walk a JsonObject (Map of String keys to values) and return the Java object equivalent filled in as best as possible (everything except unresolved reference fields or unresolved array/collection elements).
protected Object	convertParsedMapsToJava(JsonObject root) This method converts a root Map, (which contains nested Maps and so forth representing a Java Object graph), to a Java object instance.
protected Object	createJavaObjectInstance(Class clazz, JsonObject jsonObj) This method creates a Java Object instance based on the passed in parameters.
static Class	getRawType(Type t)
static boolean	isLogicalPrimitive(Class c)
static boolean	isPrimitive(Class c)
Object	jsonObjectsToJava(JsonObject root) Convert a root JsonObject that represents parsed JSON, into an actual Java object.
static Object	jsonToJava(String json) Convert the passed in JSON string into a Java object graph.
static Map	jsonToMaps(String json) Convert the passed in JSON string into a Java object graph that consists solely of Java Maps where the keys are the fields and the values are primitives or other Maps (in the case of objects).
protected static Object	readIfMatching(Object o, Class compType, Deque<JsonObject<String,Object>> stack)
Object	readObject() Finite State Machine (FSM) used to parse the JSON input into JsonObject's (Maps).
static void	setUseUnsafe(boolean state)
static Object	toJava(String json) Deprecated.
static Map	toMaps(String json) Deprecated.
protected void	traverseArray(Deque<JsonObject<String,Object>> stack, JsonObject<String,Object> jsonObj) Traverse the JsonObject associated to an array (of any type).
protected void	traverseCollection(Deque<JsonObject<String,Object>> stack, JsonObject jsonObj) Process java.util.Collection and it's derivatives.
protected void	traverseCollectionNoObj(Deque<JsonObject<String,Object>> stack, JsonObject jsonObj) Process java.util.Collection and it's derivatives.
protected void	traverseFields(Deque<JsonObject<String,Object>> stack, JsonObject<String,Object> jsonObj) Walk the Java object fields and copy them from the JSON object to the Java object, performing any necessary conversions on primitives, or deep traversals for field assignments to other objects, arrays, Collections, or Maps.
protected void	traverseFieldsNoObj(Deque<JsonObject<String,Object>> stack, JsonObject<String,Object> jsonObj)
protected void	traverseMap(Deque<JsonObject<String,Object>> stack, JsonObject<String,Object> jsonObj) Process java.util.Map and it's derivatives.

Methods inherited from class java.lang.Object

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

Field Detail

MAX_CODE_POINT

public static final int MAX_CODE_POINT

See Also:

Constant Field Values

MIN_SUPPLEMENTARY_CODE_POINT

public static final int MIN_SUPPLEMENTARY_CODE_POINT

See Also:

Constant Field Values

MIN_LOW_SURROGATE

public static final char MIN_LOW_SURROGATE

See Also:

Constant Field Values

MIN_HIGH_SURROGATE

public static final char MIN_HIGH_SURROGATE

See Also:

Constant Field Values

Constructor Detail

JsonReader

public JsonReader()

JsonReader

public JsonReader(InputStream in)

JsonReader

public JsonReader(InputStream in,
          boolean noObjects)

Method Detail

setUseUnsafe

public static void setUseUnsafe(boolean state)

assignInstantiator

public static void assignInstantiator(Class c,
                      JsonReader.ClassFactory f)

For difficult to instantiate classes, you can add your own ClassFactory which will be called when the passed in class 'c' is encountered. Your ClassFactory will be called with newInstance(c) and your factory is expected to return a new instance of 'c'. This API is an 'escape hatch' to allow ANY object to be instantiated by JsonReader and is useful when you encounter a class that JsonReader cannot instantiate using its internal exhausting attempts (trying all constructors, varying arguments to them, etc.)

bigIntegerFrom

public static BigInteger bigIntegerFrom(Object value)
                                 throws IOException

Returns:

a BigInteger from the given input. A best attempt will be made to support as many input types as possible. For example, if the input is a Boolean, a BigInteger of 1 or 0 will be returned. If the input is a String "", a null will be returned. If the input is a Double, Float, or BigDecimal, a BigInteger will be returned that retains the integer portion (fractional part is dropped). The input can be a Byte, Short, Integer, or Long.

Throws:

IOException - if the input is something that cannot be converted to a BigInteger.

bigDecimalFrom

public static BigDecimal bigDecimalFrom(Object value)
                                 throws IOException

Returns:

a BigDecimal from the given input. A best attempt will be made to support as many input types as possible. For example, if the input is a Boolean, a BigDecimal of 1 or 0 will be returned. If the input is a String "", a null will be returned. The input can be a Byte, Short, Integer, Long, or BigInteger.

Throws:

IOException - if the input is something that cannot be converted to a BigDecimal.

addReader

public static void addReader(Class c,
             JsonReader.JsonClassReader reader)

addNotCustomReader

public static void addNotCustomReader(Class c)

readIfMatching

protected static Object readIfMatching(Object o,
                    Class compType,
                    Deque<JsonObject<String,Object>> stack)
                                throws IOException

Throws:

IOException

toJava

@Deprecated
public static Object toJava(String json)

Deprecated.

Convert the passed in JSON string into a Java object graph.

Parameters:

json - String JSON input

Returns:

Java object graph matching JSON input, or null if an error occurred.

jsonToJava

public static Object jsonToJava(String json)
                         throws IOException

Convert the passed in JSON string into a Java object graph.

Parameters:

json - String JSON input

Returns:

Java object graph matching JSON input

Throws:

IOException - If an I/O error occurs

toMaps

@Deprecated
public static Map toMaps(String json)

Deprecated.

Convert the passed in JSON string into a Java object graph that consists solely of Java Maps where the keys are the fields and the values are primitives or other Maps (in the case of objects).

Parameters:

json - String JSON input

Returns:

Java object graph of Maps matching JSON input, or null if an error occurred.

jsonToMaps

public static Map jsonToMaps(String json)
                      throws IOException

Convert the passed in JSON string into a Java object graph that consists solely of Java Maps where the keys are the fields and the values are primitives or other Maps (in the case of objects).

Parameters:

json - String JSON input

Returns:

Java object graph of Maps matching JSON input, or null if an error occurred.

Throws:

IOException - If an I/O error occurs

readObject

public Object readObject()
                  throws IOException

Finite State Machine (FSM) used to parse the JSON input into JsonObject's (Maps). Then, if requested, the JsonObjects are converted into Java instances.

Returns:

Java Object graph constructed from InputStream supplying JSON serialized content.

Throws:

IOException - for stream errors or parsing errors.

jsonObjectsToJava

public Object jsonObjectsToJava(JsonObject root)
                         throws IOException

Convert a root JsonObject that represents parsed JSON, into an actual Java object.

Parameters:

root - JsonObject instance that was the root object from the JSON input that was parsed in an earlier call to JsonReader.

Returns:

a typed Java instance that was serialized into JSON.

Throws:

IOException

convertParsedMapsToJava

protected Object convertParsedMapsToJava(JsonObject root)
                                  throws IOException

This method converts a root Map, (which contains nested Maps and so forth representing a Java Object graph), to a Java object instance. The root map came from using the JsonReader to parse a JSON graph (using the API that puts the graph into Maps, not the typed representation).

Parameters:

root - JsonObject instance that was the root object from the JSON input that was parsed in an earlier call to JsonReader.

Returns:

a typed Java instance that was serialized into JSON.

Throws:

IOException

convertMapsToObjects

protected Object convertMapsToObjects(JsonObject<String,Object> root)
                               throws IOException

Walk a JsonObject (Map of String keys to values) and return the Java object equivalent filled in as best as possible (everything except unresolved reference fields or unresolved array/collection elements).

Parameters:

root - JsonObject reference to a Map-of-Maps representation of the JSON input after it has been completely read.

Returns:

Properly constructed, typed, Java object graph built from a Map of Maps representation (JsonObject root).

Throws:

IOException - for stream errors or parsing errors.

traverseArray

protected void traverseArray(Deque<JsonObject<String,Object>> stack,
                 JsonObject<String,Object> jsonObj)
                      throws IOException

Traverse the JsonObject associated to an array (of any type). Convert and assign the list of items in the JsonObject (stored in the @items field) to each array element. All array elements are processed excluding elements that reference an unresolved object. These are filled in later.

Parameters:

stack - a Stack (Deque) used to support graph traversal.

jsonObj - a Map-of-Map representation of the JSON input stream.

Throws:

IOException - for stream errors or parsing errors.

traverseCollectionNoObj

protected void traverseCollectionNoObj(Deque<JsonObject<String,Object>> stack,
                           JsonObject jsonObj)
                                throws IOException

Process java.util.Collection and it's derivatives. Collections are written specially so that the serialization does not expose the Collection's internal structure, for example a TreeSet. All entries are processed, except unresolved references, which are filled in later. For an indexable collection, the unresolved references are set back into the proper element location. For non-indexable collections (Sets), the unresolved references are added via .add().

Parameters:

stack - a Stack (Deque) used to support graph traversal.

jsonObj - a Map-of-Map representation of the JSON input stream.

Throws:

IOException - for stream errors or parsing errors.

traverseCollection

protected void traverseCollection(Deque<JsonObject<String,Object>> stack,
                      JsonObject jsonObj)
                           throws IOException

Process java.util.Collection and it's derivatives. Collections are written specially so that the serialization does not expose the Collection's internal structure, for example a TreeSet. All entries are processed, except unresolved references, which are filled in later. For an indexable collection, the unresolved references are set back into the proper element location. For non-indexable collections (Sets), the unresolved references are added via .add().

Parameters:

jsonObj - a Map-of-Map representation of the JSON input stream.

Throws:

IOException - for stream errors or parsing errors.

traverseMap

protected void traverseMap(Deque<JsonObject<String,Object>> stack,
               JsonObject<String,Object> jsonObj)
                    throws IOException

Process java.util.Map and it's derivatives. These can be written specially so that the serialization would not expose the derivative class internals (internal fields of TreeMap for example).

Parameters:

stack - a Stack (Deque) used to support graph traversal.

jsonObj - a Map-of-Map representation of the JSON input stream.

Throws:

IOException - for stream errors or parsing errors.

traverseFieldsNoObj

protected void traverseFieldsNoObj(Deque<JsonObject<String,Object>> stack,
                       JsonObject<String,Object> jsonObj)
                            throws IOException

Throws:

IOException

traverseFields

protected void traverseFields(Deque<JsonObject<String,Object>> stack,
                  JsonObject<String,Object> jsonObj)
                       throws IOException

Walk the Java object fields and copy them from the JSON object to the Java object, performing any necessary conversions on primitives, or deep traversals for field assignments to other objects, arrays, Collections, or Maps.

Parameters:

stack - Stack (Deque) used for graph traversal.

jsonObj - a Map-of-Map representation of the current object being examined (containing all fields).

Throws:

IOException

assignField

protected void assignField(Deque<JsonObject<String,Object>> stack,
               JsonObject jsonObj,
               Field field,
               Object rhs)
                    throws IOException

Map Json Map object field to Java object field.

Parameters:

stack - Stack (Deque) used for graph traversal.

jsonObj - a Map-of-Map representation of the current object being examined (containing all fields).

field - a Java Field object representing where the jsonObj should be converted and stored.

rhs - the JSON value that will be converted and stored in the 'field' on the associated Java target object.

Throws:

IOException - for stream errors or parsing errors.

getRawType

public static Class getRawType(Type t)

createJavaObjectInstance

protected Object createJavaObjectInstance(Class clazz,
                              JsonObject jsonObj)
                                   throws IOException

This method creates a Java Object instance based on the passed in parameters. If the JsonObject contains a key '@type' then that is used, as the type was explicitly set in the JSON stream. If the key '@type' does not exist, then the passed in Class is used to create the instance, handling creating an Array or regular Object instance.

The '@type' is not often specified in the JSON input stream, as in many cases it can be inferred from a field reference or array component type.

Parameters:

clazz - Instance will be create of this class.

jsonObj - Map-of-Map representation of object to create.

Returns:

a new Java object of the appropriate type (clazz) using the jsonObj to provide enough hints to get the right class instantiated. It is not populated when returned.

Throws:

IOException - for stream errors or parsing errors.

isPrimitive

public static boolean isPrimitive(Class c)

isLogicalPrimitive

public static boolean isLogicalPrimitive(Class c)

close

public void close()

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable