Gson

From Wikipedia, the free encyclopedia
Jump to navigation Jump to search
Google Gson
Developer(s) Google
Initial release May 22, 2008 (2008-05-22)
Stable release
2.8.5 / 21 May 2018; 5 months ago (2018-05-21)
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[edit]

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.8.5, was released on May 21, 2018.

Version history[edit]

  • May 21, 2018: Version 2.8.5
  • May 01, 2018: Version 2.8.4
  • April 27, 2018: Version 2.8.3
  • Sept 19, 2017: Version 2.8.2
  • May 30, 2017: Version 2.8.1
  • October 27, 2016: Version 2.8.0
  • June 14, 2016: Version 2.7
  • February 26, 2016: Version 2.6.2
  • February 11, 2016: Version 2.6.1
  • February 11, 2016: Version 2.6
  • Nov 24, 2015: Version 2.5
  • Oct 4, 2015: Version 2.4
  • Nov 20, 2014: Version 2.3.1
  • Aug 11, 2014: Version 2.3
  • May 13, 2013: Version 2.2.4
  • April 12, 2013: Version 2.2.3
  • July 2, 2012: Version 2.2.2
  • May 5, 2012: Version 2.2.1
  • May 5, 2012: Version 2.2
  • December 31, 2011: Version 2.1
  • November 13, 2011: Version 2.0
  • April 13, 2011: Version 1.7.1
  • April 12, 2011: Version 1.7
  • November 24, 2010: Version 1.6
  • August 19, 2010: Version 1.5
  • October 9, 2009: Version 1.4
  • April 1, 2009: Version 1.3
  • January 12, 2009: Version 1.3 Beta
  • August 29, 2008: Version 1.2
  • July 18, 2008: Version 1.1.1
  • July 1, 2008: Version 1.1
  • June 17, 2008: Version 1.0.1
  • May 22, 2008: Version 1.0

Usage[edit]

Gson uses reflection so it does not require additional modifications to classes of (de)serialized objects. In fact it just needs the class to have defined default no-args constructor (not entirely true, see Features).

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

module GsonExample {
    requires gson;
    requires java.sql; // Required by gson
    exports Person;
    exports Car;
}
package Car;

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 Person;

import Car.Car;

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 item : cars) {
            i++;
            sb.append("Car ").append(i).append(": ").append(item).append("\n");
        }
        return sb.toString();
    }
}

After calling

package Main;

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

public class Main {
    public static void main(String[] args) {
        Gson gson = new Gson();
        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 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 output produced by last example, you can execute the following code:

package Main;

import Person.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

Features[edit]

  • Gson can handle collections, generic types and nested classes (including inner classes, this can not be done by default though)
  • When deserializing, Gson is navigating 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[edit]