Actson

Actson is a reactive JSON parser (sometimes referred to as non-blocking or asynchronous). It is event-based and can be used together with reactive libraries/tool-kits such as RxJava or Vert.x.

The library is very small and has no dependencies. It only requires Java 8 (or higher).

Why another JSON parser?

• Non-blocking. Other JSON parsers use blocking I/O (i.e. they read from an
  InputStream). If you want to develop a reactive application you should use
  non-blocking I/O (see the Reactive Manifesto).
• Big Data. Most parsers read the full JSON text into memory to map it to
  a POJO, for example. Actson can handle arbitrarily large JSON text. It is
  event-based and can be used for streaming.
• GeoRocket. Actson was primarily developed for GeoRocket,
  a high-performance reactive data store for geospatial files. We use
  Aalto XML to parse XML in a
  non-blocking way and we needed something similar for GeoRocket's
  GeoJSON support.

Usage

The following snippet demonstrates how you can use the parser sequentially.

// JSON text to parse
byte[] json = "{\"name\":\"Elvis\"}".getBytes(StandardCharsets.UTF_8);

JsonParser parser = new JsonParser(StandardCharsets.UTF_8);

int pos = 0; // position in the input JSON text
int event; // event returned by the parser
do {
    // feed the parser until it returns a new event
    while ((event = parser.nextEvent()) == JsonEvent.NEED_MORE_INPUT) {
        // provide the parser with more input
        pos += parser.getFeeder().feed(json, pos, json.length - pos);

        // indicate end of input to the parser
        if (pos == json.length) {
            parser.getFeeder().done();
        }
    }

    // handle event
    System.out.println("JSON event: " + event);
    if (event == JsonEvent.ERROR) {
        throw new IllegalStateException("Syntax error in JSON text");
    }
} while (event != JsonEvent.EOF);

Find more complex examples using RxJava or Vert.x below.

Examples

• SimpleExample.java
  shows sequential usage of Actson (basically the same as the example above).
• RxJavaExample.java
  demonstrates how you can use Actson and RxJava
  to parse JSON in an event-based manner. It uses an operator function
  JsonParserOperator.java
  that can be lifted into an Observable to transform byte arrays to JSON
  events.
• VertxExample.java
  shows how Actson can be used together with Vert.x. It does the same as
  SimpleExample.java
  or RxJavaExample.java
  but works completely asynchronously and non-blocking.
• WebServiceExample.java
  combines Vert.x, RxJava and Actson to a reactive web service. The HTTP service
  accepts JSON arrays and returns the number of elements in this array. It can
  handle arbitrarily large files and multiple requests in parallel without
  becoming unresponsive.
• PrettyPrinter.java
  demonstrates how you can use Actson to pretty-print a JSON object or array.
  Note: this is no perfect implementation of a pretty-printer. The output could
  still be nicer. It's just a sample application.

Download

Binaries and dependency information for Maven, Gradle, Ivy and others can be found at http://search.maven.org.

Example for Maven:

<dependencies>
    <dependency>
        <groupId>de.undercouch</groupId>
        <artifactId>actson</artifactId>
        <version>2.1.0</version>
    </dependency>
</dependencies>

Example for Gradle:

dependencies {
    implementation 'de.undercouch:actson:2.1.0'
}

Building

Execute the following command to compile the library and to run the unit tests:

./gradlew test

The script automatically downloads the correct Gradle version, so you won't have to do anything else. If everything runs successfully, you may create a .jar library:

./gradlew jar

The library will be located under the build/libs directory.

Similar libraries

• Jackson has a streaming API that
  produces JSON tokens/events.
• Aalto XML is similar to Actson
  but parses XML instead of JSON.

Acknowledgments

The event-based parser code and the JSON files used for testing are largely based on the file JSON_checker.c and the JSON test suite from JSON.org originally released under this license (basically MIT license).

License

Actson is released under the MIT license. See the LICENSE file for more information.