Java API for JSON Processing: An Introduction to JSON
JSON (JavaScript Object Notation) is a lightweight, text-based, language-independent data exchange format that is easy for humans and machines to read and write. JSON can represent two structured types: objects and arrays. An object is an unordered collection of zero or more name/value pairs. An array is an ordered sequence of zero or more values. The values can be strings, numbers, booleans, null, and these two structured types.
Listing 1 is an example from Wikipedia that shows the JSON representation of an object that describes a person. The object has string values for first name and last name, a number value for age, an object value representing the person’s address, and an array value of phone number objects.
Listing 1. Example of JSON representation of an object
JSON is often used in Ajax applications, configurations, databases, and RESTful web services. All popular websites offer JSON as the data exchange format with their RESTful web services.
JSON Processing
The Java API for JSON Processing (JSR 353) provides portable APIs to parse, generate, transform, and query JSON using object model and streaming APIs.
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 streaming API provides a way to parse and generate 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 JSON processing. 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
The object model API is similar to the Document Object Model (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. Table 1 lists the main classes and interfaces in the object model API.
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.
- JsonObjectBuilder
- JsonArrayBuilder
- JsonValue
- JsonObject
- JsonArray
- JsonString
- JsonNumber
JsonObject , JsonArray , JsonString , and JsonNumber are subtypes of JsonValue . These are constants defined in the API for null, true, and false JSON values.
The object model API uses builder patterns to create these object models from scratch. Application code can use the interface JsonObjectBuilder to create models that represent JSON objects. The resulting model is of type JsonObject . Application code can use the interface JsonArrayBuilder to create models that represent JSON arrays. The resulting model is of type JsonArray .
These object models can also be created from an input source (such as InputStream or Reader ) using the interface JsonReader . Similarly, these object models can be written to an output source (such as OutputStream or Writer ) using the class JsonWriter .
For example, let’s write code to search Facebook’s public posts using the object model API. The Facebook API gives the search results in the JSON format shown in Listing 2:
< "data" : [ < "from" : < "name" : "xxx", . >, "message" : "yyy", . >, < "from" : < "name" : "ppp", . >, "message" : "qqq", . >, . ], . > Listing 2. JSON representation of searching Facebook public posts
We can use the object model API to get names and their public posts about the term java. In the Listing 3, lines 1 through 3 lines create JsonReader ; line 5 creates JsonObject for the results; line 7 loops over each result; and lines 8 through 11 get the name of the person who posted, get the public post, and prints them. Note that the JsonReader and other objects in this API can be used in the try -with-resources statement (which is also called automatic resource management [ARM]).
URL url = new URL("https://graph.facebook.com/search?q=java&type=post"); try (InputStream is = url.openStream(); JsonReader rdr = Json.createReader(is)) < JsonObject obj = rdr.readObject(); JsonArray results = obj.getJsonArray("data"); for (JsonObject result : results.getValuesAs(JsonObject.class)) < System.out.print(result.getJsonObject("from").getString("name")); System.out.print(": "); System.out.println(result.getString("message", "")); System.out.println("-----------"); >> Listing 3. Processing Facebook posts using the object model API
The Streaming API
The streaming API is similar to the Streaming API for XML (StAX) 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 output source. Table 2 lists the main classes and interfaces in the streaming API.
| Class or Interface | Description |
|---|---|
| Json | Contains static methods to create JSON parsers, generators, and their factory objects. |
| JsonParser | Represents an event-based parser that can read JSON data from a stream. |
| JsonGenerator | Writes JSON data to a stream one value at a time |
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.
JsonGenerator provides methods to write JSON data to a stream. The generator can be used to write name/value pairs in JSON objects and values in JSON arrays.
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.
Let’s use the streaming API to do the same thing that was done with the object model API, that is, to search Facebook’s public posts about java. In Listing 4, lines 1 through 3 create a streaming parser, lines 4 through 5 get the next event, line 6 looks for the KEY_NAME event, lines 8 through 11 read names and print them, and lines 14 through 16 read the public posts and print them. The use of streaming API provides an efficient way to access names and their public posts when compared to the same task using the object model API.
URL url = new URL("https://graph.facebook.com/search?q=java&type=post"); try (InputStream is = url.openStream(); JsonParser parser = Json.createParser(is)) < while (parser.hasNext()) < Event e = parser.next(); if (e == Event.KEY_NAME) < switch (parser.getString()) < case "name": parser.next(); System.out.print(parser.getString()); System.out.print(": "); break; case "message": parser.next(); System.out.println(parser.getString()); System.out.println("---------"); break; >> > > Listing 4. Processing Facebook posts using the streaming API
Conclusion
The Java API for JSON Processing provides the following capabilities:
- Parsing input streams into immutable objects or event streams
- Writing event streams or immutable objects to output streams
- Programmatically navigating immutable objects
- Programmatically building immutable objects with builders
The API becomes a base for building data binding, transformation, querying, or other manipulation APIs. JAX-RS 2.0 provides native integration for the Java API for JSON Processing.
See Also
About the Author
Jitendra Kotamraju, a principal member of the technical staff at Oracle, is the JSON Processing specification lead and one of the key engineers behind GlassFish. Before leading the JSON Processing project, he was in charge of both the specification and implementation of JAX-WS 2.2.