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.
Top 5 JSON Libraries in Java that every Developer Should Know
The usage of JSON is quite straightforward; it’s commonly used to read data from a web server and display the results on the web page. Over time, JSON has replaced XML as it’s considered a lightweight format for exchanging and storing data through the web. If you are a Java developer and eager to produce or decipher JSON data, then you shouldn’t worry as there are many open source libraries that can help you create and parse JSON files in Java.
You might come across a number of JSON libraries existing in Java, but it isn’t worth comprehending all of them. Learning only a single JSON library would be enough for a developer. However, we are here to discuss the top 5 JSON libraries that every developer should be aware of. Without learning about JSON libraries, a Java developer would always fall short of the competition. The usefulness and effectiveness of JSON libraries cannot be ignored; therefore, let’s move towards the top 5 JSON libraries in Java without any further delay.
Useful JSON Libraries in Java
Each of the JSON libraries we are going to discuss below has its own perks. You should deeply investigate each JSON library before making a decision to choose any of them.
1. Jackson
Among all JSON libraries, Jackson comes on the top due to its rich features and consistency. Jackson is a multi-purpose Java library to process the JSON data, and it’s considered best for the developers who are hunting down a combination of lightweight, fast, correct, and ergonomic traits. The JSON format data can be processed with Jackson in three methods, which include:
- Tree model: its function is to represent a mutable tree-view of a JSON document.
- Streaming API: a function to read and write JSON format data into individual events.
- Data Binding: Convert JSON to POJO and vice versa.
In case your requirement is to serialize a Java object to JSON string, then Jackson wouldn’t be the right library you should go for due to the drawback of size. On the other hand, if you are finding a JSON library that’s jam-packed with multiple features, then Jackson is the perfect option.
2. GSON
GSON or google-gson is the second open-source Java library on this list. Just like Jackson, GSON is also a powerful JSON library that can help you in numerous ways. The top features of the JSON library are as follows:
- GSON comes with the extensive support of Java Generics.
- This library supports autocratically complex objects.
- The unmodifiable objects can be converted to and from JSON through GSON.
- GSON library permits the custom representation for objects.
- It ignores the extra fields available in the JSON input.
The best thing about the GSON library is its capability to convert Java Objects into their JSON representation and vice versa without imposing a requirement of entering Java annotations in the classes.
3. Json-simple
As the name suggests, json-simple is the simplest JSON library in addition to being lightweight. One of the best things about this JSON library is that it relies on no external dependency. The binary and source are both compatible with JDK 1.2 in the JSON-simple. This open-source library can be used to decode and encode JSON text effortlessly. The flexibility of JSON-simple makes it an easy-to-use lightweight library that can be consumed by reusing List and Map interfaces from JDK.
Json-simple is probably the best match library for the people who are searching for a simple, lightweight Java library that is compatible with streams and allows reading and writing JSON format data. Besides this, another reason that can urge you to go for this library is its support for Java IO readers and writers.
4. Flexjson
Another lightweight JSON library, Flexjson, is best to serialize Java objects into JSON format and the other way around. While transforming to or from JSON format, Flexjson allows both deep and shallow copies of objects. Flexjson allows its users to control the extent to which an object can be serialized. This process makes it effortless and easier for the users to extract the required information.
You should opt for Flexjson if you are aware that the data you are going to use is of a small amount. Flexjson is a reliable library to meet your requirements of reading and storing to and from JSON format data just like GSON.
5. JSON-Lib
Last but not least on our list of top 5 JSON libraries is JSON-Lib. This Java library possesses the capability to transform Java arrays, beans, maps, XML, and collections, to JSON and vice versa. The JSON-lib library is basically based on the work of Douglas Crockford. In the case of using, storing, and reading large amounts of JSON format data, JSON-lib is a recommended option along with the Jackson.
Final Words
That’s all about the top 5 JSON libraries in Java that every developer should know. The popularity of a JSON library shouldn’t be a convincing factor while choosing one in Java. You should conduct an in-depth analysis of what output you need and then look into the top 5 JSON libraries discussed to make a perfect decision.
But at the end whichever tool you choose, you will need a set of JSON Online Tools that can provide you a complete coding environment for testing, viewing, parsing and converting the code.