The JSON-P API: A JSON Processing Primer

The Java API for JSON Processing 1.0 (JSR 353) is a low-level, lightweight JSON parser and generator that provides the capacity to manipulate JSON data at the property and value level.

JSR 353 provides two JSON processing models: an object model and a streaming model. Both models can generate JSON data and output it to a stream, such as a flat file, and both models can read data.

However, the streaming model is especially efficient at processing high volumes of JSON data. This allows for the implementation of data import functionality and the transformation of such data on the fly.

Java EE 8 introduced two new APIs: JSON Binding 1.0 and Security 1.0. It also introduces some major and minor updates to core APIs such as Servlet 4.0 and Context and Dependency Injection 2.0. Learn what's new in Java EE 8 in my new book Java EE 8: Only What's New.

The JSON-P Object Model

The javax.json package provides the object model API for processing JSON data. It includes classes that model the JSON structure and factories for JSON readers and writers.

The Object model represents the elements that form the JSON data structure as objects. For example, a JSON array is represented by the javax.json.JsonArray class, and in turn, this class implements the List interface.

A JSON object is represented by the javax.json.JsonObject class, which implements the Map interface.

The javax.json.Json class includes various factory methods that create JsonGenerator, JsonParser, and JsonReader instances, among others.

The following code snippet creates a JsonObject instance from a JSON document and then retrieves the data from its properties.

1: private String json = "{\"id\": 123456, \"title\": \"Fun with JSON-Processing\", \"published\": true}";

2: JsonReader jsonReader = Json.createReader(new StringReader(json));
3: JsonObject jsonObject = jsonReader.readObject();
4: jsonReader.close();
5: jsonObject.getInt("id")
6: jsonObject.getString("title")
7: jsonObject.getBoolean("published")

Line 1 is the JSON document I want to process. I create an instance of a StringReader object and pass it the JSON document, which I pass to the JsonReader via the createReader() static method.

I read the JSON document into a JsonObject instance on line 3 and close the reader on line 4.

Now that I have a JsonObject, I can read the values of the JSON properties by passing the property name to the getString() method.

The code for this example is stored in the GitHub repository that accompanies this post.

The JSON-P Streaming Model

The javax.json.streaming package provides the Streaming model API that parses and generates JSON data. It includes factories for creating parsers and generators.

It is implemented quite differently and at a lower level. At its heart, there are two principle factories that generate and parse JSON data. They are the JsonGeneratorFactory and the JsonParserFactory. These factories are orientated toward writing to and reading from streams of data.

The writing of JSON data is done by chaining methods that add data to the buffer and then flushing it to the output stream by calling the flush or close methods.

JSON data is parsed in a streaming manner and is designed to be the most efficient way to read JSON data. Parsers are created from InputStream or Reader input sources.

The following code snippet creates a JSONObject instance by constructing it using builder methods on the JsonObjectBuilder. Then, it retrieves the data from the JsonObject.

1: JsonObject jsonObject = Json.createObjectBuilder()
        .add("id", 123456)
        .add("title", "Fun with JSON-Processing")
        .add("published", true)
        .build();

2: jsonObject.getInt("id")
3: jsonObject.getString("title")
4: jsonObject.getBoolean("published")

On line 1, the JsonObject is constructed. As you can see, it calls the static createObjectBuilder() method from the Json class, and I call the add method for as many properties as I want my JsonObject to have. In this case, I want three properties: id, title, and published. The final method is the build() method that constructs the JsonObject.

Lines 2-4 called the getter methods on the JsonObject built on line 1 and retrieves the properties values one by one, just as I did in the previous example.

The code for this example is, again, stored in the GitHub repository that accompanies this post.

Further Reading

I often post on Java EE technologies, so you might be interested in the following:

• Learn only what's new in Java EE 8
• Context and Dependency Injection (CDI)
• Enterprise Java Beans (EJB)
• JSP, JSP, and Expression Language
• RESTful web services