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

Class JSONParser

java.lang.Object
org.bluezoo.json.JSONParser
public class JSONParser extends Object
A streaming JSON parser using the push (receive) model.

Unlike traditional parsers that take an InputStream and block during parsing, this parser uses a non-blocking push model:

For convenience, a traditional blocking parse(InputStream) method is also provided which internally delegates to the streaming API.

Parsing events are delivered via JSONContentHandler as tokens are recognized. The parser handles BOM detection, then delegates directly to JSONTokenizer, which tokenizes against the raw bytes - UTF-8 decoding only ever happens for the actual content of a string value/key, never for structural characters, whitespace, numbers, or literals.

Buffer Management Contract

This parser follows the standard non-blocking streaming contract:

  • The caller provides a buffer in read mode (ready for get operations)
  • The parser consumes as many complete tokens as possible
  • After receive(ByteBuffer) returns, the buffer's position indicates where unconsumed data begins
  • If there is unconsumed data (partial token), the caller MUST call ByteBuffer.compact() before reading more data into the buffer
  • The next receive() call will continue from where parsing left off

Usage (Streaming)


 JSONParser parser = new JSONParser();
 parser.setContentHandler(myHandler);
 
 ByteBuffer buffer = ByteBuffer.allocate(8192);
 while (channel.read(buffer) > 0) {
     buffer.flip();
     parser.receive(buffer);
     buffer.compact();
 }
 parser.close();

Usage (InputStream)


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

Character Encoding

The parser assumes UTF-8 encoding by default. BOM detection is performed on the first chunk.
Author:
Chris Burdess

  • Constructor Details

    • JSONParser

      public JSONParser()
      Creates a new JSON parser with a default buffer size of 8KB.

    • JSONParser

      public JSONParser(int bufferSize)
      Creates a new JSON parser with the specified buffer size.
      Parameters:
      bufferSize - the initial size of the character buffer in bytes

  • Method Details

    • setContentHandler

      public void setContentHandler(JSONContentHandler handler)
      Register a content handler to be notified of parsing events.
      Parameters:
      handler - the content handler

    • parse

      public void parse(InputStream in) throws JSONException
      Parse a JSON document from an InputStream.

      This is a convenience method that reads the input stream in chunks and delegates to the streaming receive(ByteBuffer) API. The stream is read until EOF, then close() is called.

      The parser is automatically reset before parsing, allowing this method to be called multiple times to parse different documents.

      Note: This method does not close the InputStream.

      Parameters:
      in - the input stream to parse
      Throws:
      JSONException - if there is a parsing error

    • receive

      public void receive(ByteBuffer data) throws JSONException
      Receive bytes into the parser.

      Bytes are processed immediately. Parsing events are fired to the content handler as tokens are recognized. Incomplete tokens are left in the buffer - the position is set to the start of the incomplete token.

      Buffer Contract: The byte buffer must be in read mode (after flip()). After this method returns:

      • The buffer's position indicates where unconsumed data begins
      • If position() < limit(), there is a partial token that needs more data to complete
      • The caller MUST call buffer.compact() before reading more data into the buffer
      Parameters:
      data - the byte buffer to process (must be in read mode)
      Throws:
      JSONException - if there is a parsing error or stream is closed

    • close

      public void close() throws JSONException
      Close the parser, signaling end of input.

      This validates that the JSON document is complete. The closed state is signaled to the tokenizer, which will treat end-of-buffer as end-of-token (e.g., for numbers without delimiters like "42").

      After closing, further calls to receive() will throw an exception. Use reset() to prepare the parser for a new document.

      Throws:
      JSONException - if the document is incomplete or malformed

    • reset

      public void reset()
      Reset the parser to parse a new document.

      Clears all internal state, allowing the parser to be reused. This is called automatically by parse(InputStream).