JsonReader (json-io 4.6.0 API)

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.jsonToJava(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.objectToJson() method with the returned Map, and it will serialize the Graph into the equivalent 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 interface`	`JsonReader.ClassFactory` Subclass this interface and create a class that will return a new instance of the passed in Class (c).
`static interface`	`JsonReader.ClassFactoryEx` Subclass this interface and create a class that will return a new instance of the passed in Class (c).
`static class`	`JsonReader.CollectionFactory` Use to create new instances of collection interfaces (needed for empty collections)
`static interface`	`JsonReader.Factory`
`static interface`	`JsonReader.JsonClassReader` Implement this interface to add a custom JSON reader.
`static interface`	`JsonReader.JsonClassReaderBase` Implement this interface to add a custom JSON reader.
`static interface`	`JsonReader.JsonClassReaderEx` Implement this interface to add a custom JSON reader.
`static class`	`JsonReader.MapFactory` Use to create new instances of Map interfaces (needed for empty Maps)
`static interface`	`JsonReader.MissingFieldHandler` Used to react to fields missing when reading an object.

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`CUSTOM_READER_MAP`
`static String`	`JSON_READER`
`static String`	`MISSING_FIELD_HANDLER`
`protected JsonReader.MissingFieldHandler`	`missingFieldHandler`
`static String`	`NOT_CUSTOM_READER_MAP`
`protected Set<Class>`	`notCustom`
`static String`	`OBJECT_RESOLVER`
`protected ConcurrentMap<Class,JsonReader.JsonClassReaderBase>`	`readers`
`static String`	`TYPE_NAME_MAP`
`static String`	`UNKNOWN_OBJECT`
`static String`	`USE_MAPS`

Constructor Summary

Constructors
Constructor and Description
`JsonReader()`
`JsonReader(InputStream inp)`
`JsonReader(InputStream inp, boolean useMaps)`
`JsonReader(InputStream inp, Map<String,Object> optionalArgs)`
`JsonReader(Map<String,Object> optionalArgs)` Use this constructor if you already have a JsonObject graph and want to parse it into Java objects by calling jsonReader.jsonObjectsToJava(rootJsonObject) after constructing the JsonReader.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addNotCustomReader(Class c)` Force json-io to use it's internal generic approach to writing the passed in class, even if a Custom JSON reader is specified for its parent class.
`void`	`addReader(Class c, JsonReader.JsonClassReaderBase reader)` Call this method to add your custom JSON reader to json-io.
`static void`	`assignInstantiator(Class c, JsonReader.Factory f)` For difficult to instantiate classes, you can add your own ClassFactory or ClassFactoryEx which will be called when the passed in class 'c' is encountered.
`void`	`close()`
`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.
`Map`	`getArgs()`
`Map<Long,JsonObject>`	`getObjectsRead()`
`Object`	`getRefTarget(JsonObject jObj)`
`Object`	`jsonObjectsToJava(JsonObject root)` Convert a root JsonObject that represents parsed JSON, into an actual Java object.
`static Object`	`jsonToJava(InputStream inputStream, Map<String,Object> optionalArgs)` Convert the passed in JSON string into a Java object graph.
`static Object`	`jsonToJava(String json)` Convert the passed in JSON string into a Java object graph.
`static Object`	`jsonToJava(String json, Map<String,Object> optionalArgs)` Convert the passed in JSON string into a Java object graph.
`static Map`	`jsonToMaps(InputStream inputStream, Map<String,Object> optionalArgs)` Map args = ["USE_MAPS": true] Use JsonReader.jsonToJava(inputStream, args) Note that the return type will match the JSON type (array, object, string, long, boolean, or null).
`static Map`	`jsonToMaps(String json)` Map args = ["USE_MAPS": true] Use JsonReader.jsonToJava(String json, args) Note that the return type will match the JSON type (array, object, string, long, boolean, or null).
`static Map`	`jsonToMaps(String json, Map<String,Object> optionalArgs)` Map args = ["USE_MAPS": true] Use JsonReader.jsonToJava(String json, args) Note that the return type will match the JSON type (array, object, string, long, boolean, or null).
`static Object`	`newInstance(Class c)`
`static Object`	`newInstance(Class c, JsonObject jsonObject)`
`Object`	`readObject()` Read JSON input from the stream that was set up in the constructor, turning it into Java Maps (JsonObject's).
`void`	`setMissingFieldHandler(JsonReader.MissingFieldHandler handler)`
`protected boolean`	`useMaps()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - CUSTOM_READER_MAP
```
public static final String CUSTOM_READER_MAP
```
    See Also:
    
    Constant Field Values
  - NOT_CUSTOM_READER_MAP
```
public static final String NOT_CUSTOM_READER_MAP
```
    See Also:
    
    Constant Field Values
  - USE_MAPS
```
public static final String USE_MAPS
```
    See Also:
    
    Constant Field Values
  - UNKNOWN_OBJECT
```
public static final String UNKNOWN_OBJECT
```
    See Also:
    
    Constant Field Values
  - JSON_READER
```
public static final String JSON_READER
```
    See Also:
    
    Constant Field Values
  - OBJECT_RESOLVER
```
public static final String OBJECT_RESOLVER
```
    See Also:
    
    Constant Field Values
  - TYPE_NAME_MAP
```
public static final String TYPE_NAME_MAP
```
    See Also:
    
    Constant Field Values
  - MISSING_FIELD_HANDLER
```
public static final String MISSING_FIELD_HANDLER
```
    See Also:
    
    Constant Field Values
  - readers
```
protected final ConcurrentMap<Class,JsonReader.JsonClassReaderBase> readers
```
  - missingFieldHandler
```
protected JsonReader.MissingFieldHandler missingFieldHandler
```
  - notCustom
```
protected final Set<Class> notCustom
```
- Constructor Detail
  - JsonReader
```
public JsonReader()
```
  - JsonReader
```
public JsonReader(InputStream inp)
```
  - JsonReader
```
public JsonReader(Map<String,Object> optionalArgs)
```
    Use this constructor if you already have a JsonObject graph and want to parse it into Java objects by calling jsonReader.jsonObjectsToJava(rootJsonObject) after constructing the JsonReader.
    
    Parameters:
    
    optionalArgs - Map of optional arguments for the JsonReader.
  - JsonReader
```
public JsonReader(InputStream inp,
                  boolean useMaps)
```
  - JsonReader
```
public JsonReader(InputStream inp,
                  Map<String,Object> optionalArgs)
```
- Method Detail
  - assignInstantiator
```
public static void assignInstantiator(Class c,
                                      JsonReader.Factory f)
```
    For difficult to instantiate classes, you can add your own ClassFactory or ClassFactoryEx 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.)
    
    Parameters:
    
    c - Class to assign an ClassFactory to
    
    f - ClassFactory that will create 'c' instances
  - addReader
```
public void addReader(Class c,
                      JsonReader.JsonClassReaderBase reader)
```
    Call this method to add your custom JSON reader to json-io. It will associate the Class 'c' to the reader you pass in. The readers are found with isAssignableFrom(). If this is too broad, causing too many classes to be associated to the custom reader, you can indicate that json-io should not use a custom reader for a particular class, by calling the addNotCustomReader() method.
    
    Parameters:
    
    c - Class to assign a custom JSON reader to
    
    reader - The JsonClassReader which will read the custom JSON format of 'c'
  - addNotCustomReader
```
public void addNotCustomReader(Class c)
```
    Force json-io to use it's internal generic approach to writing the passed in class, even if a Custom JSON reader is specified for its parent class.
    
    Parameters:
    
    c - Class to which to force no custom JSON reading to occur. Normally, this is not needed, however, if a reader is assigned to a parent class of 'c', then calling this method on 'c' will prevent any custom reader from processing class 'c'
  - setMissingFieldHandler
```
public void setMissingFieldHandler(JsonReader.MissingFieldHandler handler)
```
  - getArgs
```
public Map getArgs()
```
    Returns:
    
    The arguments used to configure the JsonReader. These are thread local.
  - jsonToJava
```
public static Object jsonToJava(String json)
```
    Convert the passed in JSON string into a Java object graph.
    
    Parameters:
    
    json - String JSON input
    
    Returns:
    
    Java object graph matching JSON input
  - jsonToJava
```
public static Object jsonToJava(String json,
                                Map<String,Object> optionalArgs)
```
    Convert the passed in JSON string into a Java object graph.
    
    Parameters:
    
    json - String JSON input
    
    optionalArgs - Map of optional parameters to control parsing. See readme file for details.
    
    Returns:
    
    Java object graph matching JSON input
  - jsonToJava
```
public static Object jsonToJava(InputStream inputStream,
                                Map<String,Object> optionalArgs)
```
    Convert the passed in JSON string into a Java object graph.
    
    Parameters:
    
    inputStream - InputStream containing JSON input
    
    optionalArgs - Map of optional parameters to control parsing. See readme file for details.
    
    Returns:
    
    Java object graph matching JSON input
  - jsonToMaps
```
public static Map jsonToMaps(String json)
```
    Map args = ["USE_MAPS": true] Use JsonReader.jsonToJava(String json, args) Note that the return type will match the JSON type (array, object, string, long, boolean, or null). No longer recommended: Use jsonToJava with USE_MAPS:true
    
    Parameters:
    
    json - String of JSON content
    
    Returns:
    
    Map representing JSON content. Each object is represented by a Map.
  - jsonToMaps
```
public static Map jsonToMaps(String json,
                             Map<String,Object> optionalArgs)
```
    Map args = ["USE_MAPS": true] Use JsonReader.jsonToJava(String json, args) Note that the return type will match the JSON type (array, object, string, long, boolean, or null). No longer recommended: Use jsonToJava with USE_MAPS:true
    
    Parameters:
    
    json - String of JSON content
    
    optionalArgs - Map of optional arguments to control customization. See readme file for details on these options.
    
    Returns:
    
    Map where each Map representa an object in the JSON input.
  - jsonToMaps
```
public static Map jsonToMaps(InputStream inputStream,
                             Map<String,Object> optionalArgs)
```
    Map args = ["USE_MAPS": true] Use JsonReader.jsonToJava(inputStream, args) Note that the return type will match the JSON type (array, object, string, long, boolean, or null). No longer recommended: Use jsonToJava with USE_MAPS:true
    
    Parameters:
    
    inputStream - containing JSON content
    
    optionalArgs - Map of optional arguments to control customization. See readme file for details on these options.
    
    Returns:
    
    Map containing the content from the JSON input. Each Map represents an object from the input.
  - getObjectsRead
```
public Map<Long,JsonObject> getObjectsRead()
```
  - getRefTarget
```
public Object getRefTarget(JsonObject jObj)
```
  - readObject
```
public Object readObject()
```
    Read JSON input from the stream that was set up in the constructor, turning it into Java Maps (JsonObject's). Then, if requested, the JsonObjects can be converted into Java instances.
    
    Returns:
    
    Java Object graph constructed from InputStream supplying JSON serialized content.
  - jsonObjectsToJava
```
public Object jsonObjectsToJava(JsonObject root)
```
    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.
  - useMaps
```
protected boolean useMaps()
```
  - convertParsedMapsToJava
```
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. 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.
  - newInstance
```
public static Object newInstance(Class c)
```
  - newInstance
```
public static Object newInstance(Class c,
                                 JsonObject jsonObject)
```
  - close
```
public void close()
```
    Specified by:
    
    close in interface Closeable
    
    Specified by:
    
    close in interface AutoCloseable

Class JsonReader

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

CUSTOM_READER_MAP

NOT_CUSTOM_READER_MAP

USE_MAPS

UNKNOWN_OBJECT

JSON_READER

OBJECT_RESOLVER

TYPE_NAME_MAP

MISSING_FIELD_HANDLER

readers

missingFieldHandler

notCustom

Constructor Detail

JsonReader

JsonReader

JsonReader

JsonReader

JsonReader

Method Detail

assignInstantiator

addReader

addNotCustomReader

setMissingFieldHandler

getArgs

jsonToJava

jsonToJava

jsonToJava

jsonToMaps

jsonToMaps

jsonToMaps

getObjectsRead

getRefTarget

readObject

jsonObjectsToJava

useMaps

convertParsedMapsToJava

newInstance

newInstance

close