com.cedarsoftware.util.io

Class JsonWriter

java.lang.Object

com.cedarsoftware.util.io.JsonWriter

All Implemented Interfaces:

WriterContext, Closeable, Flushable, AutoCloseable

public class JsonWriter
extends Object
implements WriterContext, 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 'Serializable' 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. Use the JsonWriter PRETTY_PRINT option to format the JSON to be human-readable.

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

License

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 customize the JSON output for a given class.
static interface	JsonWriter.JsonClassWriterBase Deprecated.

Field Summary

Fields

Modifier and Type	Field and Description
protected static Set<String>	EMPTY_SET

Constructor Summary

Constructors

Constructor and Description
JsonWriter(OutputStream out)
JsonWriter(OutputStream out, WriteOptions writeOptions)

Method Summary

Modifier and Type	Method and Description
void	addNotCustomWriter(Class<?> c) Deprecated.
void	close()
static boolean	ensureJsonPrimitiveKeys(Map map) Ensure that all keys within the Map are String instances
void	flush()
static String	formatJson(String json) Deprecated. use JsonUtilities.formatJson(json);
static String	formatJson(String json, Map readingArgs, WriteOptions writeOptions) Deprecated. use JsonUtilities.formatJson(json, readOption, writeOptions);
void	newLine() Add newline (\n) to output
static String	objectToJson(Object item) Deprecated.
static String	objectToJson(Object item, WriteOptions writeOptions) Deprecated.
void	tabIn() Tab the output left (less indented)
void	tabOut() Tab the output right (more indented)
static String	toJson(Object item, WriteOptions writeOptions) Convert a Java Object to a JSON String.
static void	toJson(OutputStream stream, Object item, WriteOptions writeOptions) Convert a Java Object to a JSON String.
protected void	traceFields(Deque<Object> stack, Object obj) 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) Write the passed in array element to the JSON output, if any only if, there is a custom writer for the class of the instance 'o'.
protected boolean	writeCustom(Class<?> arrayComponentClass, Object o, boolean showType, Writer output) Perform the actual custom writing for an array element that has a custom writer.
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).
void	writeObject(Object obj, boolean showType, boolean bodyOnly) Allows you to use the current JsonWriter to write an object out.
boolean	writeUsingCustomWriter(Object o, boolean showType, Writer output) Write the passed in object (o) to the JSON output stream, if and only if, there is a custom writer associated to the Class of object (o).

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.cedarsoftware.util.io.WriterContext

getWriteOptions

Field Detail

EMPTY_SET

protected static final Set<String> EMPTY_SET

Constructor Detail

JsonWriter

public JsonWriter(OutputStream out)

Parameters:

out - OutputStream to which the JSON will be written. Uses the default WriteOptions.

See Also:

WriteOptions

JsonWriter

public JsonWriter(OutputStream out,
                  WriteOptions writeOptions)

Parameters:

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

writeOptions - WriteOptions containing many feature options to control the JSON output. Can be null, in which case the default WriteOptions will be used.

See Also:

Javadoc.

Method Detail

objectToJson

@Deprecated
public static String objectToJson(Object item)

Deprecated.

Parameters:

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

Returns:

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

See Also:

toJson(Object, WriteOptions)

objectToJson

@Deprecated
public static String objectToJson(Object item,
                                              WriteOptions writeOptions)

Deprecated.

Convert a Java Object to a JSON String.

Parameters:

item - Object to convert to a JSON String.

writeOptions - Feature arguments indicating how dates are formatted, what fields are written out (optional).

Returns:

String containing JSON representation of passed in object root.

See Also:

WriteOptions

toJson

public static String toJson(Object item,
                            WriteOptions writeOptions)

Convert a Java Object to a JSON String.

Parameters:

item - Object to convert to a JSON String.

writeOptions - (optional can be null for defaults) Map of extra arguments indicating how dates are formatted and 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.

toJson

public static void toJson(OutputStream stream,
                          Object item,
                          WriteOptions writeOptions)

Convert a Java Object to a JSON String.

Parameters:

stream - Outputstream that the generated JSON will be sent to.

item - Object root object from which to generate JSON .

writeOptions - (optional can be null for defaults) Map of extra arguments indicating how the JSON is formatted. From date formats, to special treatment for longs, null fields, etc.

formatJson

@Deprecated
public static String formatJson(String json)

Deprecated. use JsonUtilities.formatJson(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.

formatJson

@Deprecated
public static String formatJson(String json,
                                            Map readingArgs,
                                            WriteOptions writeOptions)

Deprecated. use JsonUtilities.formatJson(json, readOption, writeOptions);

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

Parameters:

json - String input JSON

readingArgs - (optional) Map of extra arguments for parsing json. Can be null.

writeOptions - (optional) Map of extra arguments for writing out json. Can be null.

Returns:

String containing equivalent JSON, formatted nicely for human readability.

tabIn

public void tabIn()
           throws IOException

Tab the output left (less indented)

Throws:

IOException

newLine

public void newLine()
             throws IOException

Add newline (\n) to output

Throws:

IOException

tabOut

public void tabOut()
            throws IOException

Tab the output right (more indented)

Throws:

IOException

writeUsingCustomWriter

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

Write the passed in object (o) to the JSON output stream, if and only if, there is a custom writer associated to the Class of object (o).

Parameters:

o - Object to be (potentially written)

showType - boolean indicating whether to show @type.

output - Writer where the actual JSON is being written to.

Returns:

boolean true if written, false is there is no custom writer for the passed in object.

writeArrayElementIfMatching

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

Write the passed in array element to the JSON output, if any only if, there is a custom writer for the class of the instance 'o'.

Parameters:

arrayComponentClass - Class type of the array

o - Object instance to write

showType - boolean indicating whether @type should be output.

output - Writer to write the JSON to (if there is a custom writer for o's Class).

Returns:

true if the array element was written, false otherwise.

writeCustom

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

Perform the actual custom writing for an array element that has a custom writer.

Parameters:

arrayComponentClass - Class type of the array

o - Object instance to write

showType - boolean indicating whether @type should be output.

output - Writer to write the JSON to (if there is a custom writer for o's Class).

Returns:

true if the array element was written, false otherwise.

Throws:

IOException

addNotCustomWriter

@Deprecated
public void addNotCustomWriter(Class<?> c)

Deprecated.

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

Parameters:

c - Class which should NOT have any custom writer associated to it. Use this to prevent a custom writer from being used due to inheritance.

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)

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 includedFields map if provided.

Parameters:

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

obj - Object root of graph 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 - if one occurs on the underlying output stream.

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 be checked for a matching custom writer to be used. This does not affect sub-objects, just the top-level 'obj' being passed in.

Throws:

IOException - if one occurs on the underlying output stream.

ensureJsonPrimitiveKeys

public static boolean ensureJsonPrimitiveKeys(Map map)

Ensure that all keys within the Map are String instances

Parameters:

map - Map to inspect that all keys are primitive. This allows the output JSON to be optimized into {"key1":value1, "key2": value2} format if all the keys of the Map are Strings. If not, then a Map is written as two arrays, a @keys array and an @items array. This allows support for Maps with non-String keys.

writeObject

public void writeObject(Object obj,
                        boolean showType,
                        boolean bodyOnly)
                 throws IOException

Description copied from interface: WriterContext

Allows you to use the current JsonWriter to write an object out.

Specified by:

writeObject in interface WriterContext

Parameters:

obj - Object to be written in JSON format

showType - boolean true means show the "@type" field, false eliminates it. Many times the type can be dropped because it can be inferred from the field or array type.

bodyOnly - write only the body of the object

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