Overview (JSR 353 (JSON Processing) API 1.0-b06 API)

JSON Processing Packages
Package	Description
javax.json	Provides an object model API to process JSON.
javax.json.spi	Service Provider Interface (SPI) to plug in implementations for JSON processing objects.
javax.json.stream	Provides a streaming API to parse and generate JSON.

The Java API for JSON Processing provides portable APIs to parse, generate, transform, and query JSON using the streaming API or the object model API.

The Streaming API provides a way to parsing and generation of JSON in a streaming fashion. It hands over parsing and generation control to the programmer. The streaming API provides an event-based parser and allows an application developer to ask for the next event rather than handling the event in a callback. This gives a developer more procedural control over the processing of the JSON. Application code can process or discard the parser event, and ask for the next event(pull the event). The streaming model is adequate for local processing where random access of other parts of the data is not required. Similarly, the streaming API provides a way to generate well-formed JSON to a stream by writing one event at a time.

The object model API creates a random access tree-like structure that represents the JSON data in memory. The tree can then be navigated and queried. This programming model is the most flexible and enables processing that requires random access to the complete contents of the tree. However, it is often not as efficient as the streaming model and requires more memory. The object model generates JSON output by navigating the entire tree at once.

The Streaming API

The streaming API is similar to the StAX API for XML and consists of the interfaces JsonParser and JsonGenerator. JsonParser contains methods to parse JSON data using the streaming model. JsonGenerator contains methods to write JSON data to an ouptut source.

JsonParser provides forward, read-only access to JSON data using the pull parsing programming model. In this model the application code controls the thread and calls methods in the parser interface to move the parser forward or to obtain JSON data from the current state of the parser. Refer to this example for more details.

JsonGenerator provides methods to write JSON to a stream. The generator writes name/value pairs in JSON objects and values in JSON arrays. Refer to this example for more details.

The streaming API is a low-level API designed to process large amounts of JSON data efficiently. Other JSON frameworks (such as JSON binding) can be implemented using this API.

The Object Model API

The object model API is similar to the DOM API for XML. It is a high-level API that provides immutable object models for JSON object and array structures. These JSON structures are represented as object models using the Java types JsonObject and JsonArray. JsonObject provides a Map view to access the unordered collection of zero or more name/value pairs from the model. Similarly, JsonArray provides a List view to access the ordered sequence of zero or more values from the model.

The object model API uses builder patterns to create these object models. Application code can use the interface JsonObjectBuilder to create models that represent JSON objects. The resulting model is of type JsonObject. Refer to this example for more details. Application code can use the interface JsonArrayBuilder to create models that represent JSON arrays. The resulting model is of type JsonArray. Refer to this example for more details.

These object models can also be created from an input source (such as InputStream or Reader) using the interface JsonReader. This example shows how to read and create an empty JsonArray model using the interface JsonReader. Similarly, these object models can be written to an output source (such as OutputStream or Writer) using the class JsonWriter. This example shows how to write an empty JsonObject model using the interface JsonWriter.