JEP 198: Light-Weight JSON API

Summary

Provide a light-weight API for consuming and generating JSON documents and data streams.

Goals

• Parsing and generation of JSON RFC7159.

• Functionality meets needs of Java developers using JSON.

• Parsing APIs which allow a choice of parsing token stream, event (includes document hierarchy context) stream, or immutable tree representation views of JSON documents and data streams.

• Useful API subset for compact profiles and Java ME.

• Immutable value tree construction using a Builder-style API.

• Generator style API for JSON data stream output and for JSON "literals".

• A transformer API, which takes as input an existing value tree and produces a new value tree as result.

Non-goals

• Adherence to JSR 353.
• API support for JAXB style type-safe data binding.
• Event mutation/replacement API.
• Document tree mutation API.

Motivations

JSON has become the lingua franca for web services and it is time for Java SE to adopt functionality for interacting with and utilizing JSON documents and data streams. This proposal is designed provide the most commonly needed functionality and take advantage of Java 8/9 language and library features.

Description

It is expected that this JEP will be delivered as a set of new sub-packages in the java.util hierarchy and will consist of at least four modules; events, streams, trees, generators. No existing modules, packages, or classes are expected to be modified. The JSON API is not expected to have any dependencies that are not already part of the Java base module.

The stream events and document objects are immutable. Immutability enables dynamic footprint reductions by allowing instance sharing in both streams and document trees. Immutability is particularly important for tree transformations where most of the document tree is generally unmodified by the transformation and it is very desirable to have the original tree and the transformed tree share unmodified portions.

For parsing of JSON, two modes of usage will be provided: event streams and value trees. The event stream mode will provide in-order access to parse tokens or contextual events as they are individually parsed from the data stream (similar to SAX). The value tree mode will provide a navigable value hierarchy representing the entire document (similar to DOM). JSON data streams for output can be generated either from value trees or directly with a sequence of discrete operations (generator).

The APIs will support the following usage modes:

• Low-level parsing token stream push interface for chunked input data streams.

• Low-level parsing token stream pull interface for documents and blocking input sources.

• Low-level java.util.stream interface for parsing tokens.

• Mid-level java.util.stream interface for events incorporating document structure information.

• Mid-level pull java.util.stream for matched events similar to StAX.

• Immutable hierarchy of values (tree) constructed from JSON data stream.

• Tree constructed using Builder-style API.

• Tree transformer API. A new tree is result.

• JSON data stream output from trees.

• Generator style API for JSON data stream output and for JSON "literals".

Alternatives

There are existing JSON APIs for Java. The most popular of these generally offer more functionality than the planned API and/or don't take advantage of Java 8/9 language and library features.

Testing

Beyond functional testing the key metrics are going to be static and dynamic footprint evaluations for common use cases. User testing and feedback is also going to be important in evolving the initial API.