Gson

Google Gson

Developer(s)	Google
Initial release	May 22, 2008 (2008-05-22)
Stable release	2.11.0  / 20 May 2024 (20 May 2024)
Repository	github.com/google/gson
Written in	Java
Operating system	Cross-platform
License	Apache License 2.0
Website	github.com/google/gson

Gson (also known as Google Gson) is an open-source Java library to serialize and deserialize Java objects to (and from) JSON.

History

The Gson library was originally developed for internal purposes of Google, and Version 1.0 was later released on May 22, 2008 under the terms of Apache License 2.0. The latest version, 2.11.0, was released on 20 May 2024.

Usage

Gson uses reflection, so it does not require classes being serialized or de-serialized to be modified. By default, it just needs the class to have defined a default no-args constructor (which can be worked around, see Features).

The following example demonstrates the most basic usage of Gson when serializing a sample object:

package example;

public class Car {
    public String manufacturer;
    public String model;
    public double capacity;
    public boolean accident;

    public Car() {
    }

    public Car(String manufacturer, String model, double capacity, boolean accident) {
        this.manufacturer = manufacturer;
        this.model = model;
        this.capacity = capacity;
        this.accident = accident;
    }

    @Override
    public String toString() {
        return ("Manufacturer: " + manufacturer + ", " + "Model: " + model + ", " + "Capacity: " + capacity + ", " + "Accident: " + accident);
    }
}

package example;

public class Person {
    public String name;
    public String surname;
    public Car[] cars;
    public int phone;
    public transient int age;

    public Person() {
    }

    public Person(String name, String surname, int phone, int age, Car[] cars) {
        this.name = name;
        this.surname = surname;
        this.cars = cars;
        this.phone = phone;
        this.age = age;
    }

    @Override
    public String toString() {
        StringBuilder sb = new StringBuilder();
        sb.append("Name: ").append(name).append(" ").append(surname).append("\n");
        sb.append("Phone: ").append(phone).append("\n");
        sb.append("Age: ").append(age).append("\n");
        int i = 0;
        for (Car car : cars) {
            i++;
            sb.append("Car ").append(i).append(": ").append(car).append("\n");
        }
        return sb.toString();
    }
}

After calling the code of the following Main class:

package main;

import example.Car;
import example.Person;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

public class Main {
    public static void main(String[] args) {
        // Enable pretty printing for demonstration purposes
        // Can also directly create instance with `new Gson()`; this will produce compact JSON
        Gson gson = new GsonBuilder().setPrettyPrinting().create();
        Car audi = new Car("Audi", "A4", 1.8, false);
        Car skoda = new Car("Škoda", "Octavia", 2.0, true);
        Car[] cars = {audi, skoda};
        Person johnDoe = new Person("John", "Doe", 2025550191, 35, cars);
        System.out.println(gson.toJson(johnDoe));
    }
}

You will get this JSON output:

{
  "name": "John",
  "surname": "Doe",
  "cars": [
    {
      "manufacturer": "Audi",
      "model": "A4",
      "capacity": 1.8,
      "accident": false
    },
    {
      "manufacturer": "Škoda",
      "model": "Octavia",
      "capacity": 2.0,
      "accident": true
    }
  ],
  "phone": 2025550191
}

Since the Person's field "age" is marked as transient, it is not included in the output.

To deserialize the output produced by the last example, you can execute the following code:

package main;

import example.Person;
import com.google.gson.Gson;

public class Main {
    public static void main(String[] args) {
        Gson gson = new Gson();
        String json = "{\"name\":\"John\",\"surname\":\"Doe\",\"cars\":[{\"manufacturer\":\"Audi\",\"model\":\"A4\"," +
                "\"capacity\":1.8,\"accident\":false},{\"manufacturer\":\"Škoda\",\"model\":\"Octavia\",\"capacity\"" +
                ":2.0,\"accident\":true}],\"phone\":2025550191}";
        Person johnDoe = gson.fromJson(json, Person.class);
        System.out.println(johnDoe.toString());
    }
}

And the following output will be generated:

Name: John Doe
Phone: 2025550191
Age: 0
Car 1: Manufacturer: Audi, Model: A4, Capacity: 1.8, Accident: false
Car 2: Manufacturer: Škoda, Model: Octavia, Capacity: 2.0, Accident: true

For the above example the following shows how Gson can be used with the Java Platform Module System:

module GsonExample {
    requires com.google.gson;
    // Open package declared in the example above to allow Gson to use reflection on classes
    // inside the package (and also access non-public fields)
    opens example to com.google.gson;
}

See Gson's usage guide on their GitHub repository for more extensive examples.

Features

• Gson can handle collections, generic types and nested classes (including inner classes, this can not be done by default though)
• When deserializing, Gson navigates the type tree of the object being deserialized. This results in ignoring extra fields present in the JSON input.
• User can write a custom serializer and/or deserializer so that they can control the whole process and even (de)serialize instances of classes for which the source code is not accessible.
• User can write an InstanceCreator which allows them to deserialize instances of classes without a defined no-args constructor.
• Gson is highly customizable, you can specify:

• Compact/pretty printing (whether you want compact or readable output)
• How to handle null object fields – by default they are not present in the output
• Rules of what fields are intended to be excluded from (de)serialization
• How to convert Java field names

External links

• Gson on GitHub
• Gson tutorial with examples