Package com.cedarsoftware.io

Class JsonWriter

java.lang.Object
com.cedarsoftware.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.

  • Constructor Details

    • JsonWriter

      public JsonWriter(OutputStream out)
      Parameters:
      out - OutputStream to which the JSON will be written. Uses the default WriteOptions.
      See Also:

    • 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:

  • Method Details

    • getWriteOptions

      public WriteOptions getWriteOptions()
      Description copied from interface: WriterContext
      Gets the write options for the current serialization
      Specified by:
      getWriteOptions in interface WriterContext
      Returns:
      WriteOptions

    • getObjVisited

      protected Map<Object,Long> getObjVisited()
      Map containing all objects that were visited within input object graph

    • getObjsReferenced

      public Map<Object,Long> getObjsReferenced()
      Map containing all objects that were referenced within input object graph.
      Specified by:
      getObjsReferenced in interface WriterContext

    • 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<?> clazz, Object o, boolean showType, Writer output) throws IOException
      Perform the actual custom writing for an array element that has a custom writer.
      Parameters:
      clazz - 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

    • 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.

    • processFields

      protected void processFields(Deque<Object[]> stack, Object obj, int depth)
      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.
      Specified by:
      writeImpl in interface WriterContext
      Parameters:
      obj - Object to be written
      showType - if set to true, the @type tag will be output.
      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 AutoCloseable
      Specified by:
      close in interface Closeable

    • writeBasicString

      public static void writeBasicString(Writer writer, String s) throws IOException
      Writes out a string without special characters. Use for labels, etc. when you know you will not need extra formattting for UTF-8 or tabs, quotes and newlines in the string
      Parameters:
      writer - Writer to which the UTF-8 string will be written to
      s - String to be written in UTF-8 format on the output stream.
      Throws:
      IOException - if an error occurs writing to the output stream.

    • writeJsonUtf8String

      public static void writeJsonUtf8String(Writer output, String s) throws IOException
      Writes a JSON string value to the output, properly escaped according to JSON specifications. Handles control characters, quotes, backslashes, and properly processes Unicode code points. Uses default string length limit for backward compatibility.
      Parameters:
      output - The Writer to write to
      s - The string to be written as a JSON string value
      Throws:
      IOException - If an I/O error occurs

    • writeJsonUtf8String

      public static void writeJsonUtf8String(Writer output, String s, int maxStringLength) throws IOException
      Writes a JSON string value to the output, properly escaped according to JSON specifications. Handles control characters, quotes, backslashes, and properly processes Unicode code points.
      Parameters:
      output - The Writer to write to
      s - The string to be written as a JSON string value
      maxStringLength - Maximum allowed string length to prevent memory issues
      Throws:
      IOException - If an I/O error occurs

    • writeFieldName

      public void writeFieldName(String name) throws IOException
      Writes a JSON field name followed by a colon. Example: writeFieldName("name") produces "name": Automatically writes a comma before the field name if this is not the first field.
      Specified by:
      writeFieldName in interface WriterContext
      Parameters:
      name - the field name to write (without quotes)
      Throws:
      IOException - if an I/O error occurs

    • writeStringField

      public void writeStringField(String name, String value) throws IOException
      Writes a complete JSON string field with automatic comma handling. Example: writeStringField("name", "John") produces ,"name":"John" This method writes a LEADING comma, making it suitable for fields after the first field. For the first field in an object, either omit the comma manually or use writeFieldName() followed by the value.
      Specified by:
      writeStringField in interface WriterContext
      Parameters:
      name - the field name
      value - the string value (may be null)
      Throws:
      IOException - if an I/O error occurs

    • writeObjectField

      public void writeObjectField(String name, Object value) throws IOException
      Writes a complete JSON object field with automatic serialization and comma handling. Example: writeObjectField("address", addressObj) produces ,"address":{...} This method writes a LEADING comma, making it suitable for fields after the first field. For the first field in an object, either omit the comma manually or use writeFieldName() followed by writeImpl().
      Specified by:
      writeObjectField in interface WriterContext
      Parameters:
      name - the field name
      value - the object to serialize (may be null)
      Throws:
      IOException - if an I/O error occurs

    • writeStartObject

      public void writeStartObject() throws IOException
      Writes a JSON object opening brace. Automatically writes a comma if needed based on context.
      Specified by:
      writeStartObject in interface WriterContext
      Throws:
      IOException - if an I/O error occurs
      See Also:

    • writeEndObject

      public void writeEndObject() throws IOException
      Writes a JSON object closing brace. Pops the object context from the stack.
      Specified by:
      writeEndObject in interface WriterContext
      Throws:
      IOException - if an I/O error occurs
      See Also:

    • writeStartArray

      public void writeStartArray() throws IOException
      Writes a JSON array opening bracket. Automatically writes a comma if needed based on context.
      Specified by:
      writeStartArray in interface WriterContext
      Throws:
      IOException - if an I/O error occurs
      See Also:

    • writeEndArray

      public void writeEndArray() throws IOException
      Writes a JSON array closing bracket. Pops the array context from the stack.
      Specified by:
      writeEndArray in interface WriterContext
      Throws:
      IOException - if an I/O error occurs
      See Also:

    • writeValue

      public void writeValue(String value) throws IOException
      Writes a JSON string value with proper quote escaping. Example: writeValue("Hello") produces "Hello" Automatically writes a comma if this is an array element and not the first element.
      Specified by:
      writeValue in interface WriterContext
      Parameters:
      value - the string value to write (may be null)
      Throws:
      IOException - if an I/O error occurs

    • writeValue

      public void writeValue(Object value) throws IOException
      Writes a JSON value by serializing the given object. Example: writeValue(myObject) produces the full JSON representation Automatically writes a comma if this is an array element and not the first element.
      Specified by:
      writeValue in interface WriterContext
      Parameters:
      value - the object to serialize (may be null)
      Throws:
      IOException - if an I/O error occurs

    • writeArrayFieldStart

      public void writeArrayFieldStart(String name) throws IOException
      Writes a complete JSON array field start with automatic comma handling. Example: writeArrayFieldStart("items") produces ,"items":[ Manages context by marking the object field written and pushing array context.
      Specified by:
      writeArrayFieldStart in interface WriterContext
      Parameters:
      name - the field name
      Throws:
      IOException - if an I/O error occurs

    • writeObjectFieldStart

      public void writeObjectFieldStart(String name) throws IOException
      Writes a complete JSON object field start with automatic comma handling. Example: writeObjectFieldStart("config") produces ,"config":{ Manages context by marking the object field written and pushing object context.
      Specified by:
      writeObjectFieldStart in interface WriterContext
      Parameters:
      name - the field name
      Throws:
      IOException - if an I/O error occurs

    • writeNumberField

      public void writeNumberField(String name, Number value) throws IOException
      Writes a complete JSON number field with automatic comma handling. Example: writeNumberField("count", 42) produces ,"count":42
      Specified by:
      writeNumberField in interface WriterContext
      Parameters:
      name - the field name
      value - the number value (may be null)
      Throws:
      IOException - if an I/O error occurs

    • writeBooleanField

      public void writeBooleanField(String name, boolean value) throws IOException
      Writes a complete JSON boolean field with automatic comma handling. Example: writeBooleanField("active", true) produces ,"active":true
      Specified by:
      writeBooleanField in interface WriterContext
      Parameters:
      name - the field name
      value - the boolean value
      Throws:
      IOException - if an I/O error occurs