Streaming JSON Output

/**
 * The JsonOutput class defines the operations used to serialize Java objects into JSON strings.
 * Provides streaming output capabilities and fine-grained control over JSON generation.
 */
public class JsonOutput implements Closeable {
    
    // Configuration methods
    
    /**
     * Specify whether the serialized JSON object should be formatted with line breaks and indentation ("pretty printed").
     * 
     * @param enablePrettyPrinting false for compact format; true for "pretty printing" (default: true)
     * @return this JsonOutput object
     */
    public JsonOutput setPrettyPrint(boolean enablePrettyPrinting);
    
    /**
     * Specify whether the serialized JSON object should include a "class" property whose value is the
     * fully-qualified class name of the Java object being serialized.
     * 
     * @param writeClassName Whether to include the "class" property (default: true)
     * @return this JsonOutput object
     */
    public JsonOutput writeClassName(boolean writeClassName);
    
    // Object construction methods
    
    /**
     * Begin a new JSON object.
     * 
     * @return this JsonOutput object
     */
    public JsonOutput beginObject();
    
    /**
     * Set the name of a new JSON object property.
     * 
     * @param name JSON object property name
     * @return this JsonOutput object
     * @throws JsonException if top item on serialization object stack isn't a JsonObject
     * @throws java.util.NoSuchElementException if serialization object stack is empty
     */
    public JsonOutput name(String name);
    
    /**
     * End the current JSON object.
     * 
     * @return this JsonOutput object
     * @throws JsonException if top item on serialization object stack isn't a JsonObject
     * @throws java.util.NoSuchElementException if serialization object stack is empty
     */
    public JsonOutput endObject();
    
    // Array construction methods
    
    /**
     * Begin a new JSON array.
     * 
     * @return this JsonOutput object
     */
    public JsonOutput beginArray();
    
    /**
     * End the current JSON array.
     * 
     * @return this JsonOutput object
     * @throws JsonException if top item on serialization object stack isn't a JsonCollection
     * @throws java.util.NoSuchElementException if serialization object stack is empty
     */
    public JsonOutput endArray();
    
    // Value writing methods
    
    /**
     * Serialize the specified Java object as a JSON value.
     * Uses the default maximum depth limit.
     * 
     * @param value Java object to serialize
     * @return this JsonOutput object
     * @throws JsonException if allowed depth has been reached
     */
    public JsonOutput write(Object value);
    
    /**
     * Serialize the specified Java object as a JSON value.
     * 
     * @param value Java object to serialize
     * @param maxDepth maximum depth of nested object traversal
     * @return this JsonOutput object
     * @throws JsonException if allowed depth has been reached
     */
    public JsonOutput write(Object value, int maxDepth);
    
    // Resource management
    
    /**
     * Close the output stream.
     * 
     * @throws JsonException if JSON stream isn't empty or an I/O exception is encountered
     * @throws java.util.NoSuchElementException if serialization object stack is empty
     */
    public void close();
}

/**
 * Default maximum depth for object traversal during serialization
 */
public static final int MAX_DEPTH = 100;

import org.openqa.selenium.json.Json;
import org.openqa.selenium.json.JsonOutput;
import java.io.StringWriter;

Json json = new Json();
StringWriter writer = new StringWriter();

try (JsonOutput output = json.newOutput(writer)) {
    output.beginObject()
          .name("name").write("John")
          .name("age").write(30)
          .name("active").write(true)
          .endObject();
}

String result = writer.toString();
// Result: {"name":"John","age":30,"active":true}

StringWriter writer = new StringWriter();

try (JsonOutput output = json.newOutput(writer)) {
    output.setPrettyPrint(true)  // Enable pretty printing
          .beginObject()
          .name("user")
          .beginObject()
          .name("name").write("John")
          .name("age").write(30)
          .endObject()
          .name("timestamp").write(System.currentTimeMillis())
          .endObject();
}

String result = writer.toString();
/* Result:
{
  "user": {
    "name": "John",
    "age": 30
  },
  "timestamp": 1703508600000
}
*/

StringWriter writer = new StringWriter();

try (JsonOutput output = json.newOutput(writer)) {
    output.beginArray()
          .write("apple")
          .write("banana")
          .write("cherry")
          .endArray();
}

String result = writer.toString();
// Result: ["apple","banana","cherry"]

StringWriter writer = new StringWriter();

try (JsonOutput output = json.newOutput(writer)) {
    output.setPrettyPrint(true)
          .beginObject()
          .name("users")
          .beginArray()
          
          // First user
          .beginObject()
          .name("id").write(1)
          .name("name").write("John")
          .name("roles")
          .beginArray()
          .write("admin")
          .write("user")
          .endArray()
          .endObject()
          
          // Second user
          .beginObject()
          .name("id").write(2)
          .name("name").write("Jane")
          .name("roles")
          .beginArray()
          .write("user")
          .endArray()
          .endObject()
          
          .endArray()
          .name("totalCount").write(2)
          .endObject();
}

String result = writer.toString();
/* Result:
{
  "users": [
    {
      "id": 1,
      "name": "John",
      "roles": ["admin", "user"]
    },
    {
      "id": 2,
      "name": "Jane", 
      "roles": ["user"]
    }
  ],
  "totalCount": 2
}
*/

StringWriter writer = new StringWriter();

// Custom object for serialization
Person person = new Person("John Doe", 30);

try (JsonOutput output = json.newOutput(writer)) {
    output.writeClassName(false)  // Don't include class names
          .setPrettyPrint(false)   // Compact output
          .write(person);           // Serialize the object
}

String result = writer.toString();
// Result: {"name":"John Doe","age":30}

// Create a deeply nested object structure
NestedObject deepObject = createDeeplyNestedObject();

StringWriter writer = new StringWriter();

try (JsonOutput output = json.newOutput(writer)) {
    // Limit depth to prevent infinite recursion or very deep structures
    output.write(deepObject, 5);  // Max depth of 5 levels
}

String result = writer.toString();

// Stream to StringBuilder
StringBuilder sb = new StringBuilder();
try (JsonOutput output = json.newOutput(sb)) {
    output.beginObject()
          .name("message").write("Hello World")
          .endObject();
}

// Stream to System.out
try (JsonOutput output = json.newOutput(System.out)) {
    output.beginObject()
          .name("message").write("Printed to console")
          .endObject();
}

// Stream to FileWriter
try (FileWriter fileWriter = new FileWriter("output.json");
     JsonOutput output = json.newOutput(fileWriter)) {
    output.beginObject()
          .name("data").write(myData)
          .endObject();
}

StringWriter writer = new StringWriter();

try (JsonOutput output = json.newOutput(writer)) {
    output.beginObject()
          .name("name").write("John");
    
    // Conditionally add properties
    if (includeAge) {
        output.name("age").write(30);
    }
    
    if (includeEmail && email != null) {
        output.name("email").write(email);
    }
    
    output.endObject();
}

StringWriter writer = new StringWriter();

try (JsonOutput output = json.newOutput(writer)) {
    output.beginObject()
          .name("data");
    
    try {
        // This might throw an exception due to circular references or depth limits
        output.write(potentiallyProblematicObject, 10);
    } catch (JsonException e) {
        // Handle serialization error - write error info instead
        output.beginObject()
              .name("error").write("Serialization failed")
              .name("message").write(e.getMessage())
              .endObject();
    }
    
    output.endObject();
} catch (JsonException e) {
    System.err.println("JSON output error: " + e.getMessage());
}

List<String> items = Arrays.asList("apple", "banana", "cherry");
Map<String, Integer> counts = Map.of("apples", 5, "bananas", 3, "cherries", 8);

StringWriter writer = new StringWriter();

try (JsonOutput output = json.newOutput(writer)) {
    output.beginObject()
          .name("items").write(items)      // Automatic array serialization
          .name("counts").write(counts)    // Automatic object serialization
          .endObject();
}

String result = writer.toString();
// Result: {"items":["apple","banana","cherry"],"counts":{"apples":5,"bananas":3,"cherries":8}}