Gson Streaming APIs to read and write JSON With examples

In this guide, we will learn how to use Gson streaming APIs to read and write JSON files. This is especially useful when we are working with large JSON files. In order to save memory consumption, we can use Gson APIs to read and write such files without loading complete JSON file into the memory.

Gson provides JsonReader and JsonWriter classes for JSON streaming.

Gson’s Streaming API

• JsonWriter – Efficiently writes JSON data as a stream.
• JsonReader – Seamlessly reads JSON data as a stream.

Setting up Google Gson in pom.xml file

Here’s how you can add the Gson dependency to your pom.xml file for Maven:

<dependencies>
    <dependency>
        <groupId>com.google.code.gson</groupId>
        <artifactId>gson</artifactId>
        <version>2.8.8</version>
    </dependency>
</dependencies>

This will add Gson as a dependency to your Maven project. Make sure to replace the version number (2.8.8 in this example) with the latest version available at the time. You can find the latest version on Maven Central Repository: https://search.maven.org/artifact/com.google.code.gson/gson.

Program to write JSON String using JsonWriter

package com.example.json.stream;

import com.google.gson.stream.JsonWriter;

import java.io.FileWriter;
import java.io.IOException;

public class JsonStreamWriter {

    public static void main(String[] args) {

        try (JsonWriter writer = 
new JsonWriter(new FileWriter("user.json"))) {

            writer.setIndent("  ");

            writer.beginObject();
            writer.name("name").value("Chaitanya Singh");
            writer.name("age").value(37);

            writer.name("messages");
            writer.beginArray();
            writer.value("Hello");
            writer.value("World");
            writer.endArray();

            writer.endObject();

        } catch (IOException e) {
            throw new RuntimeException(e);
        }

    }
}

Output:

Contents of user.json file:

{
  "name": "Chaitanya Singh",
  "age": 37,
  "messages": [
    "Hello",
    "World"
  ]
}

Program to write JSON Array using JsonWriter

package com.example.json.stream;

import com.google.gson.stream.JsonWriter;
import java.io.FileWriter;
import java.io.IOException;

public class JsonStreamWriter {

    public static void main(String[] args) {

        try (JsonWriter jsonWriter = new JsonWriter(new FileWriter("users.json"))) {

            jsonWriter.setIndent("  "); // Enable pretty printing

            jsonWriter.beginArray(); // Begin JSON array

            // First user object
            jsonWriter.beginObject(); // Begin JSON object
            jsonWriter.name("name").value("Chaitanya Singh");
            jsonWriter.name("age").value(37);
            jsonWriter.name("hobbies").beginArray(); // Begin hobbies array
            jsonWriter.value("coding");
            jsonWriter.value("travelling");
            jsonWriter.value("reading");
            jsonWriter.endArray(); // End hobbies array
            jsonWriter.endObject(); // End JSON object

            // Second user object
            jsonWriter.beginObject(); // Begin JSON object
            jsonWriter.name("name").value("Rahul Singh");
            jsonWriter.name("age").value(34);
            jsonWriter.name("hobbies").beginArray(); // Begin hobbies array
            jsonWriter.value("cooking");
            jsonWriter.value("photography");
            jsonWriter.value("gardening");
            jsonWriter.endArray(); // End hobbies array
            jsonWriter.endObject(); // End JSON object

            jsonWriter.endArray(); // End JSON array

        } catch (IOException e) {
            throw new RuntimeException("Error writing JSON file", e);
        }
    }
}

Explanation:

In this code:

• We create a new JsonWriter object that writes to a file named “users.json”.
• We enable pretty printing using jsonWriter.setIndent(" ") for better readability.
• We start writing a JSON array using beginArray().
• For each user, we begin a JSON object using beginObject() and write its properties using name() and value().
• We begin an array for hobbies using beginArray() and write individual hobby values using value().
• We close the hobbies array and the user object using endArray() and endObject() respectively.
• After writing all user objects, we close the JSON array using endArray().
• Any IOExceptions are caught and handled appropriately.

Output:

[
  {
    "name": "Chaitanya Singh",
    "age": 37,
    "hobbies": [
      "coding",
      "travelling",
      "reading"
    ]
  },
  {
    "name": "Rahul Singh",
    "age": 34,
    "hobbies": [
      "cooking",
      "photography",
      "gardening"
    ]
  }
]

Program to read JSON String using JsonReader

Let’s say we want to read the following user.json file using JsonReader:

{
  "name": "Chaitanya Singh",
  "age": 37,
  "hobbies": ["coding", "travelling", "reading"]
}

The program to read the above json file:

package com.example.json.stream;

import com.google.gson.stream.JsonReader;
import java.io.FileReader;
import java.io.IOException;

public class JsonReaderExample {

    public static void main(String[] args) {

        try (JsonReader jsonReader = new JsonReader(new FileReader("user.json"))) {

            // Begin reading the JSON object
            jsonReader.beginObject();

            // Iterate through each element of the JSON object
            while (jsonReader.hasNext()) {

                // Read the name of the current element
                String name = jsonReader.nextName();

                // Check the name of the current element
                switch (name) {
                    case "name" -> {
                        // If element is "name", print the next string
                        System.out.println(jsonReader.nextString());
                    }
                    case "age" -> {
                        // If element is "age", print the next integer
                        System.out.println(jsonReader.nextInt());
                    }
                    case "hobbies" -> {
                        // If element is "hobbies", begin reading the array
                        jsonReader.beginArray();
                        while (jsonReader.hasNext()) {
                            // Print each string value in the array
                            System.out.println(jsonReader.nextString());
                        }
                        // End reading the array
                        jsonReader.endArray();
                    }
                    default -> {
                        // If the element is not recognized, skip it
                        jsonReader.skipValue();
                    }
                }
            }

            // End reading the JSON object
            jsonReader.endObject();

        } catch (IOException e) {
            throw new RuntimeException(e);
        }

    }
}

Output:

Chaitanya Singh
37
coding
travelling
reading

Program to read JSON Array using JsonReader

Lets say I want to read the content of following json file that contains an array:

users.json

[
  {
    "name": "Chaitanya Singh",
    "age": 37,
    "hobbies": [
      "coding",
      "travelling",
      "reading"
    ]
  },
  {
    "name": "Rahul Singh",
    "age": 34,
    "hobbies": [
      "cooking",
      "photography",
      "gardening"
    ]
  }
]

Program:

package com.example.json.stream;

import com.google.gson.stream.JsonReader;
import java.io.FileReader;
import java.io.IOException;

public class JsonReaderExample {

    public static void main(String[] args) {

        try (JsonReader jsonReader = new JsonReader(new FileReader("data.json"))) {

            // Begin reading the JSON array
            jsonReader.beginArray();

            // Loop through each element of the JSON array
            while (jsonReader.hasNext()) {

                // Begin reading a JSON object
                jsonReader.beginObject();

                // Loop through each property of the JSON object
                while (jsonReader.hasNext()) {

                    // Read the name of the current property
                    String propertyName = jsonReader.nextName();

                    // Check the name of the current property
                    switch (propertyName) {
                        case "name" -> System.out.println("Name: " + jsonReader.nextString());
                        case "age" -> System.out.println("Age: " + jsonReader.nextInt());
                        case "hobbies" -> {
                            System.out.println("Hobbies:");
                            // Begin reading the JSON array of hobbies
                            jsonReader.beginArray();
                            while (jsonReader.hasNext()) {
                                // Read and print each hobby
                                System.out.println("- " + jsonReader.nextString());
                            }
                            // End reading the JSON array of hobbies
                            jsonReader.endArray();
                        }
                        // Skip unknown properties
                        default -> jsonReader.skipValue(); 
                    }
                }

                // End reading the JSON object
                jsonReader.endObject();
            }

            // End reading the JSON array
            jsonReader.endArray();

        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

Conclusion

The Gson Streaming APIs provide efficient mechanisms for reading and writing JSON data in a streaming manner. These APIs are particularly useful for processing large JSON files, where loading the entire JSON into memory at once might not be feasible.

Key points about Gson Streaming APIs for reading and writing JSON:

1. Efficient Streaming: Gson provides JsonReader and JsonWriter classes for reading and writing JSON data as streams, allowing efficient processing of large datasets without loading the entire JSON into memory.
2. JsonReader: JsonReader allows sequential reading of JSON data from an input source. It provides methods to read individual JSON elements such as objects, arrays, strings, numbers, and boolean values.
3. JsonWriter: JsonWriter enables the incremental construction of JSON data by writing JSON elements directly to an output stream or writer. It supports writing JSON objects, arrays, strings, numbers, boolean values, and null values.
4. Streaming Processing: With Gson Streaming APIs, JSON data can be processed incrementally as it is being read or written, enabling efficient handling of large or nested JSON structures.
5. Flexible Handling: Gson Streaming APIs offer flexibility in handling JSON data by allowing developers to selectively read or write specific JSON elements based on their requirements.

In conclusion, Gson Streaming APIs provide a powerful and efficient way to work with JSON data by enabling streaming processing, which is particularly useful for handling large JSON datasets or scenarios where memory usage needs to be optimized.