Gson

Google Gson

Developer(s)	Google
Initial release	May 22, 2008;15 years ago (2008-05-22)
Stable release	2.10.1 [1]   / 6 January 2023;15 months ago (6 January 2023)
Repository	github.com/google/gson
Written in	Java
Operating system	Cross-platform
License	Apache License 2.0
Website	github.com/google/gson

• Free and open-source software portal
• Computer programming portal

Gson, or Google Gson, is an open-source Java library that serializes Java objects to JSON (and deserializes them back to Java).

History

The Gson library was originally developed for internal purposes at Google, with Version 1.0 released on May 22, 2008, under the terms of the Apache License 2.0. The latest version, 2.10.1, was released on January 6, 2023.

Usage

Gson utilizes reflection, meaning that classes do not have to be modified to be serialized or deserialized. By default, a class only needs a defined default (no-args) constructor; however, this requirement can be circumvented (see Features).

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

packageexample;publicclassCar{publicStringmanufacturer;publicStringmodel;publicdoublecapacity;publicbooleanaccident;publicCar(){}publicCar(Stringmanufacturer,Stringmodel,doublecapacity,booleanaccident){this.manufacturer=manufacturer;this.model=model;this.capacity=capacity;this.accident=accident;}@OverridepublicStringtoString(){return("Manufacturer: "+manufacturer+", "+"Model: "+model+", "+"Capacity: "+capacity+", "+"Accident: "+accident);}}

packageexample;publicclassPerson{publicStringname;publicStringsurname;publicCar[]cars;publicintphone;publictransientintage;publicPerson(){}publicPerson(Stringname,Stringsurname,intphone,intage,Car[]cars){this.name=name;this.surname=surname;this.cars=cars;this.phone=phone;this.age=age;}@OverridepublicStringtoString(){StringBuildersb=newStringBuilder();sb.append("Name: ").append(name).append(" ").append(surname).append("\n");sb.append("Phone: ").append(phone).append("\n");sb.append("Age: ").append(age).append("\n");inti=0;for(Carcar:cars){i++;sb.append("Car ").append(i).append(": ").append(car).append("\n");}returnsb.toString();}}

packagemain;importexample.Car;importexample.Person;importcom.google.gson.Gson;importcom.google.gson.GsonBuilder;publicclassMain{publicstaticvoidmain(String[]args){// Enable pretty printing for demonstration purposes// Can also directly create instance with `new Gson()`; this will produce compact JSONGsongson=newGsonBuilder().setPrettyPrinting().create();Caraudi=newCar("Audi","A4",1.8,false);Carskoda=newCar("Škoda","Octavia",2.0,true);Car[]cars={audi,skoda};PersonjohnDoe=newPerson("John","Doe",2025550191,35,cars);System.out.println(gson.toJson(johnDoe));}}

Calling the code of the above Main class will result in the following 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.

packagemain;importexample.Person;importcom.google.gson.Gson;publicclassMain{publicstaticvoidmain(String[]args){Gsongson=newGson();Stringjson="{\"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}";PersonjohnDoe=gson.fromJson(json,Person.class);System.out.println(johnDoe.toString());}}

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

Name: John DoePhone: [phone]Age: 0Car 1: Manufacturer: Audi, Model: A4, Capacity: 1.8, Accident: falseCar 2: Manufacturer: Škoda, Model: Octavia, Capacity: 2.0, Accident: true

This shows how Gson can be used with the Java Platform Module System for the example above:

moduleGsonExample{requirescom.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)opensexampletocom.google.gson;}

For more extensive examples, see Gson's usage guide on their GitHub repository.

Features

• Gson can handle collections, generic types, and nested classes (including inner classes, which cannot be done by default).
• When deserializing, Gson navigates the type tree of the object being deserialized, which means that it ignores extra fields present in the JSON input.
• The user can:
  • write a custom serializer and/or deserializer so that they can control the whole process, and even deserialize instances of classes for which the source code is inaccessible.
  • write an InstanceCreator, which allows them to deserialize instances of classes without a defined no-args constructor.
• Gson is highly customizable, as 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
• Excluding fields - rules of what fields are intended to be excluded from deserialization
• How to convert Java field names

References

1. "Release 2.10.1". 6 January 2023. Retrieved 12 January 2023.

^[1]

^[2]

External links

• Gson on GitHub
• Gson tutorial with examples Archived 2020-10-31 at the Wayback Machine

Further reading

1. More info on com.google.gson package (from javadoc.io)
2. More info on Gson class (from javadoc.io)

1. Jenkov, Jakob. "GSON - Gson". tutorials.jenkov.com. Retrieved 2023-12-28.
2. Gson, Google, 2023-12-28, retrieved 2023-12-28