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

Class JSONWriter

  • public class JSONWriter
extends java.lang.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 Summary

      Constructors 
      Constructor Description
      JSONWriter​(java.io.OutputStream out)
      Creates a new JSON writer with default capacity (4KB) and no indentation.
      JSONWriter​(java.io.OutputStream out, IndentConfig indentConfig)
      Creates a new JSON writer with default capacity and optional indentation.
      JSONWriter​(java.nio.channels.WritableByteChannel channel)
      Creates a new JSON writer with default capacity (4KB) and no indentation.
      JSONWriter​(java.nio.channels.WritableByteChannel channel, int bufferCapacity)
      Creates a new JSON writer with specified buffer capacity and no indentation.
      JSONWriter​(java.nio.channels.WritableByteChannel channel, int bufferCapacity, IndentConfig indentConfig)
      Creates a new JSON writer with specified buffer capacity and optional indentation.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void close()
      Flushes and closes the writer.
      void flush()
      Flushes any buffered data to the channel.
      void writeBoolean​(boolean value)
      Writes a boolean value.
      void writeEndArray()
      Writes the end of a JSON array ']'.
      void writeEndObject()
      Writes the end of a JSON object '}'.
      void writeKey​(java.lang.String key)
      Writes an object key (property name).
      void writeNull()
      Writes a null value.
      void writeNumber​(java.lang.Number value)
      Writes a number value.
      void writeStartArray()
      Writes the start of a JSON array '['.
      void writeStartObject()
      Writes the start of a JSON object '{'.
      void writeString​(java.lang.String value)
      Writes a string value.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • JSONWriter

        public JSONWriter​(java.io.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​(java.io.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​(java.nio.channels.WritableByteChannel channel)
        Creates a new JSON writer with default capacity (4KB) and no indentation.
        Parameters:
        channel - the channel to write to

      • JSONWriter

        public JSONWriter​(java.nio.channels.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​(java.nio.channels.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 Detail

      • writeStartObject

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

      • writeEndObject

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

      • writeStartArray

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

      • writeEndArray

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

      • writeKey

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

      • writeString

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

      • writeNumber

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

      • writeBoolean

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

      • writeNull

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

      • flush

        public void flush()
           throws java.io.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:
        java.io.IOException - if there is an error sending data

      • close

        public void close()
           throws java.io.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:
        java.io.IOException - if there is an error flushing data