Module org.bluezoo.json

Package org.bluezoo.json

A compact, efficient JSON parsing and serialization library for Java.

Overview

This library provides fast, standards-compliant JSON parsing and writing with minimal memory overhead (26KB). Unlike object-mapping libraries such as GSON (290KB) or Jackson (600KB), this library uses an event-driven, streaming approach that enables:

  • Non-blocking I/O - Parse JSON as bytes arrive without blocking
  • Low memory footprint - Process large documents without loading them entirely into memory
  • High performance - Optimized tokenization with direct buffer parsing
  • Standards compliance - Fully conformant with RFC 8259 and ECMA-404

JSON Parsing

The parser follows an event-driven design similar to SAX for XML. The JSONParser is the main entry point and supports two usage models:

Asynchronous Streaming (Primary)

The parser is designed for non-blocking, data-driven architectures where JSON arrives incrementally (e.g., from network sockets, async file I/O, or message queues). 


 JSONParser parser = new JSONParser();
 parser.setContentHandler(new MyHandler());
 
 // Feed bytes as they arrive
 parser.receive(chunk1);
 parser.receive(chunk2);
 parser.receive(chunk3);
 
 // Signal completion
 parser.close();

Blocking (Convenience)

For simpler use cases, a blocking parse(InputStream) method is provided that internally delegates to the streaming API. 


 JSONParser parser = new JSONParser();
 parser.setContentHandler(new MyHandler());
 parser.parse(inputStream);

Content Handlers

Applications implement JSONContentHandler to receive parsing events. The JSONDefaultHandler provides a convenient base class with no-op implementations of all methods. 


 public class MyHandler extends JSONDefaultHandler {
     @Override
     public void key(String key) {
         System.out.println("Key: " + key);
     }
     
     @Override
     public void stringValue(String value) {
         System.out.println("String: " + value);
     }
 }

JSON Writing

The JSONWriter provides an NIO-first streaming API for generating JSON output. It writes directly to a WritableByteChannel or OutputStream with automatic buffering and optional pretty-printing. 


 JSONWriter writer = new JSONWriter(outputStream, IndentConfig.spaces(2));
 
 writer.writeStartObject();
   writer.writeKey("name");
   writer.writeString("Alice");
   writer.writeKey("age");
   writer.writeNumber(30);
 writer.writeEndObject();
 
 writer.close();

Performance Characteristics

  • Streaming tokens - Tokens are emitted as soon as recognized, enabling near-zero latency
  • Direct parsing - Numbers and strings are parsed directly from buffers without intermediate allocations
  • Configurable buffering - Buffer sizes can be tuned for different workloads (default 8KB)
  • Optional whitespace - Handlers can opt out of whitespace events to avoid string extraction overhead
  • BOM detection - Automatic UTF-8 BOM detection with fast path optimization

Standards Compliance

This library is fully conformant with the JSON specification as defined by RFC 8259 and ECMA-404. It has been validated against the comprehensive JSONTestSuite test corpus.

Thread Safety

Parser and writer instances are not thread-safe. Each thread should use its own instance. The parser can be reused for multiple documents by calling JSONParser.reset() between documents.

Error Handling

All parsing and writing errors are reported via JSONException, a checked exception that provides detailed error messages including line and column numbers (when available via JSONLocator).

Main Classes

JSONParser
Streaming JSON parser with async-first design
JSONWriter
NIO-based JSON writer with optional indentation
JSONContentHandler
Callback interface for receiving parsing events
JSONDefaultHandler
Convenient base class for content handlers
JSONException
Exception thrown for parsing and writing errors
IndentConfig
Configuration for JSON pretty-printing
Author:
Chris Burdess
See Also:
RFC 8259 - The JavaScript Object Notation (JSON) Data Interchange Format, ECMA-404 - The JSON Data Interchange Syntax