Module org.bluezoo.json
Package org.bluezoo.json

Class JSONWriter

java.lang.Object
org.bluezoo.json.JSONWriter
public class JSONWriter extends Object
Streaming JSON writer with NIO-first design.

This class provides an efficient, streaming approach to JSON serialization that writes to a WritableByteChannel. The writer uses an internal buffer and automatically sends chunks to the channel when the buffer fills beyond a threshold.

This class does not perform well-formedness checking on its input: the user of the class is required to supply events in the correct order and close objects and arrays they open. However, it will escape characters supplied in string data.

Usage Example


 // Write to a file
 FileChannel channel = FileChannel.open(path, StandardOpenOption.WRITE, StandardOpenOption.CREATE);
 JSONWriter writer = new JSONWriter(channel);
 
 writer.writeStartObject();
 writer.writeKey("name");
 writer.writeString("Alice");
 writer.writeKey("age");
 writer.writeNumber(30);
 writer.writeEndObject();
 writer.close();
 
 // Or write to an OutputStream
 OutputStream out = ...;
 JSONWriter writer = new JSONWriter(Channels.newChannel(out));

Thread Safety

This class is NOT thread-safe. It is intended for use on a single thread.

Author:
Chris Burdess

  • Constructor Details

    • JSONWriter

      public JSONWriter(OutputStream out)
      Creates a new JSON writer with default capacity (4KB) and no indentation.
      Parameters:
      out - the output stream to write to

    • JSONWriter

      public JSONWriter(OutputStream out, IndentConfig indentConfig)
      Creates a new JSON writer with default capacity and optional indentation.
      Parameters:
      out - the output stream to write to
      indentConfig - the indentation configuration, or null for no indentation

    • JSONWriter

      public JSONWriter(WritableByteChannel channel)
      Creates a new JSON writer with default capacity (4KB) and no indentation.
      Parameters:
      channel - the channel to write to

    • JSONWriter

      public JSONWriter(WritableByteChannel channel, int bufferCapacity)
      Creates a new JSON writer with specified buffer capacity and no indentation.
      Parameters:
      channel - the channel to write to
      bufferCapacity - initial buffer capacity in bytes

    • JSONWriter

      public JSONWriter(WritableByteChannel channel, int bufferCapacity, IndentConfig indentConfig)
      Creates a new JSON writer with specified buffer capacity and optional indentation.
      Parameters:
      channel - the channel to write to
      bufferCapacity - initial buffer capacity in bytes
      indentConfig - the indentation configuration, or null for no indentation

  • Method Details

    • writeStartObject

      public void writeStartObject() throws IOException
      Writes the start of a JSON object '{'. This must be matched by a corresponding writeEndObject() call.
      Throws:
      IOException - if there is an error writing data

    • writeEndObject

      public void writeEndObject() throws IOException
      Writes the end of a JSON object '}'.
      Throws:
      IOException - if there is an error writing data

    • writeStartArray

      public void writeStartArray() throws IOException
      Writes the start of a JSON array '['. This must be matched by a corresponding writeEndArray() call.
      Throws:
      IOException - if there is an error writing data

    • writeEndArray

      public void writeEndArray() throws IOException
      Writes the end of a JSON array ']'.
      Throws:
      IOException - if there is an error writing data

    • writeKey

      public void writeKey(String key) throws IOException
      Writes an object key (property name).
      Parameters:
      key - the key name
      Throws:
      IOException - if there is an error writing data

    • writeString

      public void writeString(String value) throws IOException
      Writes a string value.
      Parameters:
      value - the string value
      Throws:
      IOException - if there is an error writing data

    • writeNumber

      public void writeNumber(Number value) throws IOException
      Writes a number value.
      Parameters:
      value - the number value
      Throws:
      IOException - if there is an error writing data

    • writeBoolean

      public void writeBoolean(boolean value) throws IOException
      Writes a boolean value.
      Parameters:
      value - the boolean value
      Throws:
      IOException - if there is an error writing data

    • writeNull

      public void writeNull() throws IOException
      Writes a null value.
      Throws:
      IOException - if there is an error writing data

    • flush

      public void flush() throws IOException
      Flushes any buffered data to the channel.

      This sends any remaining data in the buffer to the channel, even if the buffer is not full.

      Throws:
      IOException - if there is an error sending data

    • close

      public void close() throws IOException
      Flushes and closes the writer.

      After calling this method, the writer should not be used again. Note: This does NOT close the underlying channel - the caller is responsible for closing the channel.

      Throws:
      IOException - if there is an error flushing data