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).

• 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.

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.

• 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.

Binaries and dependency information for Maven, Gradle, Ivy and others can be found at https://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'
}

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.

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

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).

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