com.cedarsoftware.util.io

Class JsonWriter

java.lang.Object

com.cedarsoftware.util.io.JsonWriter

All Implemented Interfaces:

Closeable, Flushable, AutoCloseable

public class JsonWriter
extends Object
implements Closeable, Flushable

Output a Java object graph in JSON format. This code handles cyclic references and can serialize any Object graph without requiring a class to be 'Serializeable' or have any specific methods on it.

• Call the static method: JsonWriter.objectToJson(employee). This will convert the passed in 'employee' instance into a JSON String.
• Using streams:

       JsonWriter writer = new JsonWriter(stream);
       writer.write(employee);
       writer.close();

  This will write the 'employee' object to the passed in OutputStream.

That's it. This can be used as a debugging tool. Output an object graph using the above code. You can copy that JSON output into this site which formats it with a lot of whitespace to make it human readable: http://jsonformatter.curiousconcept.com

This will output any object graph deeply (or null). Object references are properly handled. For example, if you had A->B, B->C, and C->A, then A will be serialized with a B object in it, B will be serialized with a C object in it, and then C will be serialized with a reference to A (ref), not a redefinition of A.

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	JsonWriter.JsonClassWriter Implement this interface to custom the JSON output for a given class.
static interface	JsonWriter.JsonClassWriterBase
static interface	JsonWriter.JsonClassWriterEx Implement this interface to custom the JSON output for a given class.

Field Summary

Fields

Modifier and Type	Field and Description
static String	CUSTOM_WRITER_MAP
static String	DATE_FORMAT
static String	ENUM_PUBLIC_ONLY
static String	FIELD_SPECIFIERS
static String	ISO_DATE_FORMAT
static String	ISO_DATE_TIME_FORMAT
static String	NOT_CUSTOM_WRITER_MAP
static String	PRETTY_PRINT
static String	SHORT_META_KEYS
static String	TYPE
static String	TYPE_NAME_MAP
static String	WRITE_LONGS_AS_STRINGS

Constructor Summary

Constructors

Constructor and Description
JsonWriter(OutputStream out)
JsonWriter(OutputStream out, Map<String,Object> optionalArgs)

Method Summary

Modifier and Type	Method and Description
void	addNotCustomWriter(Class c) For no custom writing to occur for the passed in Class.
void	addWriter(Class c, JsonWriter.JsonClassWriterBase writer) Add a custom writer which will manage writing objects of the passed in Class in JSON format.
void	close()
static boolean	ensureJsonPrimitiveKeys(Map map)
void	flush()
static String	formatJson(String json) Format the passed in JSON string in a nice, human readable format.
protected Map	getObjectsReferenced() Provide access to subclasses.
protected Map	getObjectsVisited() Provide access to subclasses.
protected String	getSubstituteTypeName(String typeName)
protected String	getSubstituteTypeNameIfExists(String typeName)
boolean	getWriteLongsAsStrings()
boolean	isPrettyPrint()
boolean	isPublicEnumsOnly()
protected void	newLine()
static String	objectToJson(Object item)
static String	objectToJson(Object item, Map<String,Object> optionalArgs) Convert a Java Object to a JSON String.
protected void	tabIn()
protected void	tabOut()
protected void	traceFields(Deque<Object> stack, Object obj, Map<Class,List<Field>> fieldSpecifiers) Reach-ability trace to visit all objects within the graph to be written.
protected void	traceReferences(Object root) Walk object graph and visit each instance, following each field, each Collection, Map and so on.
void	write(Object obj) Write the passed in Java object in JSON format.
boolean	writeArrayElementIfMatching(Class arrayComponentClass, Object o, boolean showType, Writer output)
protected boolean	writeCustom(Class arrayComponentClass, Object o, boolean showType, Writer output)
boolean	writeIfMatching(Object o, boolean showType, Writer output)
void	writeImpl(Object obj, boolean showType) Main entry point (mostly used internally, but may be called from a Custom JSON writer).
void	writeImpl(Object obj, boolean showType, boolean allowRef, boolean allowCustom) Main entry point (mostly used internally, but may be called from a Custom JSON writer).
static void	writeJsonUtf8String(String s, Writer output) Write out special characters "\b, \f, \t, \n, \r", as such, backslash as \\ quote as \" and values less than an ASCII space (20hex) as "\\u00xx" format, characters in the range of ASCII space to a '~' as ASCII, and anything higher in UTF-8.

Methods inherited from class java.lang.Object

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

Field Detail

CUSTOM_WRITER_MAP

public static final String CUSTOM_WRITER_MAP

See Also:

Constant Field Values

NOT_CUSTOM_WRITER_MAP

public static final String NOT_CUSTOM_WRITER_MAP

See Also:

Constant Field Values

DATE_FORMAT

public static final String DATE_FORMAT

See Also:

Constant Field Values

ISO_DATE_FORMAT

public static final String ISO_DATE_FORMAT

See Also:

Constant Field Values

ISO_DATE_TIME_FORMAT

public static final String ISO_DATE_TIME_FORMAT

See Also:

Constant Field Values

TYPE

public static final String TYPE

See Also:

Constant Field Values

PRETTY_PRINT

public static final String PRETTY_PRINT

See Also:

Constant Field Values

FIELD_SPECIFIERS

public static final String FIELD_SPECIFIERS

See Also:

Constant Field Values

ENUM_PUBLIC_ONLY

public static final String ENUM_PUBLIC_ONLY

See Also:

Constant Field Values

WRITE_LONGS_AS_STRINGS

public static final String WRITE_LONGS_AS_STRINGS

See Also:

Constant Field Values

TYPE_NAME_MAP

public static final String TYPE_NAME_MAP

See Also:

Constant Field Values

SHORT_META_KEYS

public static final String SHORT_META_KEYS

See Also:

Constant Field Values

Constructor Detail

JsonWriter

public JsonWriter(OutputStream out)

Parameters:

out - OutputStream to which the JSON will be written.

See Also:

JsonWriter(java.io.OutputStream, java.util.Map)

JsonWriter

public JsonWriter(OutputStream out,
                  Map<String,Object> optionalArgs)

Parameters:

out - OutputStream to which the JSON output will be written.

optionalArgs - (optional) Map of extra arguments indicating how dates are formatted, what fields are written out (optional). For Date parameters, use the public static DATE_TIME key, and then use the ISO_DATE or ISO_DATE_TIME indicators. Or you can specify your own custom SimpleDateFormat String, or you can associate a SimpleDateFormat object, in which case it will be used. This setting is for both java.util.Date and java.sql.Date. If the DATE_FORMAT key is not used, then dates will be formatted as longs. This long can be turned back into a date by using 'new Date(longValue)'.

Method Detail

getObjectsReferenced

protected Map getObjectsReferenced()

Provide access to subclasses.

Returns:

Map containing all objects that were referenced within input object graph.

getObjectsVisited

protected Map getObjectsVisited()

Provide access to subclasses.

Returns:

Map containing all objects that were visited within input object graph

getSubstituteTypeNameIfExists

protected String getSubstituteTypeNameIfExists(String typeName)

getSubstituteTypeName

protected String getSubstituteTypeName(String typeName)

objectToJson

public static String objectToJson(Object item)

Parameters:

item - Object (root) to serialized to JSON String.

Returns:

String of JSON format representing complete object graph rooted by item.

See Also:

objectToJson(Object, java.util.Map)

objectToJson

public static String objectToJson(Object item,
                                  Map<String,Object> optionalArgs)

Convert a Java Object to a JSON String.

Parameters:

item - Object to convert to a JSON String.

optionalArgs - (optional) Map of extra arguments indicating how dates are formatted, what fields are written out (optional). For Date parameters, use the public static DATE_TIME key, and then use the ISO_DATE or ISO_DATE_TIME indicators. Or you can specify your own custom SimpleDateFormat String, or you can associate a SimpleDateFormat object, in which case it will be used. This setting is for both java.util.Date and java.sql.Date. If the DATE_FORMAT key is not used, then dates will be formatted as longs. This long can be turned back into a date by using 'new Date(longValue)'.

Returns:

String containing JSON representation of passed in object root.

formatJson

public static String formatJson(String json)

Format the passed in JSON string in a nice, human readable format.

Parameters:

json - String input JSON

Returns:

String containing equivalent JSON, formatted nicely for human readability.

isPublicEnumsOnly

public boolean isPublicEnumsOnly()

isPrettyPrint

public boolean isPrettyPrint()

getWriteLongsAsStrings

public boolean getWriteLongsAsStrings()

tabIn

protected void tabIn()
              throws IOException

Throws:

IOException

newLine

protected void newLine()
                throws IOException

Throws:

IOException

tabOut

protected void tabOut()
               throws IOException

Throws:

IOException

writeIfMatching

public boolean writeIfMatching(Object o,
                               boolean showType,
                               Writer output)

writeArrayElementIfMatching

public boolean writeArrayElementIfMatching(Class arrayComponentClass,
                                           Object o,
                                           boolean showType,
                                           Writer output)

writeCustom

protected boolean writeCustom(Class arrayComponentClass,
                              Object o,
                              boolean showType,
                              Writer output)
                       throws IOException

Throws:

IOException

addWriter

public void addWriter(Class c,
                      JsonWriter.JsonClassWriterBase writer)

Add a custom writer which will manage writing objects of the passed in Class in JSON format. The custom writer will be called for objects of the passed in class, including subclasses. If this is not desired, call addNotCustomWriter(c) which will force objects of the passed in Class to be written by the standard JSON writer.

Parameters:

c - Class to associate a custom JSON writer too

writer - JsonClassWriterBase which implements the appropriate subclass of JsonClassWriterBase (JsonClassWriter or JsonClassWriterEx).

addNotCustomWriter

public void addNotCustomWriter(Class c)

For no custom writing to occur for the passed in Class.

write

public void write(Object obj)

Write the passed in Java object in JSON format.

Parameters:

obj - Object any Java Object or JsonObject.

traceReferences

protected void traceReferences(Object root)

Walk object graph and visit each instance, following each field, each Collection, Map and so on. Tracks visited to handle cycles and to determine if an item is referenced elsewhere. If an object is never referenced more than once, no @id field needs to be emitted for it.

Parameters:

root - Object to be deeply traced. The objVisited and objsReferenced Maps will be written to during the trace.

traceFields

protected void traceFields(Deque<Object> stack,
                           Object obj,
                           Map<Class,List<Field>> fieldSpecifiers)

Reach-ability trace to visit all objects within the graph to be written. This API will handle any object, using either reflection APIs or by consulting a specified FIELD_SPECIFIERS map if provided.

Parameters:

stack - Deque used to manage decent into graph (rather than using Java stack.) This allows for much larger graph processing.

obj - Object root of graph

fieldSpecifiers - Map of optional field specifiers, which are used to override the field list returned by the JDK reflection operations. This allows a subset of the actual fields on an object to be serialized.

writeImpl

public void writeImpl(Object obj,
                      boolean showType)
               throws IOException

Main entry point (mostly used internally, but may be called from a Custom JSON writer). This method will write out whatever object type it is given, including JsonObject's. It will handle null, detecting if a custom writer should be called, array, array of JsonObject, Map, Map of JsonObjects, Collection, Collection of JsonObject, any regular object, or a JsonObject representing a regular object.

Parameters:

obj - Object to be written

showType - if set to true, the @type tag will be output. If false, it will be dropped.

Throws:

IOException

writeImpl

public void writeImpl(Object obj,
                      boolean showType,
                      boolean allowRef,
                      boolean allowCustom)
               throws IOException

Main entry point (mostly used internally, but may be called from a Custom JSON writer). This method will write out whatever object type it is given, including JsonObject's. It will handle null, detecting if a custom writer should be called, array, array of JsonObject, Map, Map of JsonObjects, Collection, Collection of JsonObject, any regular object, or a JsonObject representing a regular object.

Parameters:

obj - Object to be written

showType - if set to true, the @type tag will be output. If false, it will be

allowRef - if set to true, @ref will be used, otherwise 2+ occurrence will be output as full object.

allowCustom - if set to true, the object being called will allowed to be checked for a matching custom writer to be used. This does not affect subobjects, just the top-level 'obj' being passed in.

Throws:

IOException

ensureJsonPrimitiveKeys

public static boolean ensureJsonPrimitiveKeys(Map map)

writeJsonUtf8String

public static void writeJsonUtf8String(String s,
                                       Writer output)
                                throws IOException

Write out special characters "\b, \f, \t, \n, \r", as such, backslash as \\ quote as \" and values less than an ASCII space (20hex) as "\\u00xx" format, characters in the range of ASCII space to a '~' as ASCII, and anything higher in UTF-8.

Parameters:

s - String to be written in UTF-8 format on the output stream.

output - Writer to which the UTF-8 string will be written to

Throws:

IOException - if an error occurs writing to the output stream.

flush

public void flush()

Specified by:

flush in interface Flushable

close

public void close()

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable