Gson – Quick Guide

Gson (by Google) is a Java library that can be used to convert a Java object into JSON string. Also, it can used to convert the JSON string into equivalent java object.

There are some other java libraries also capable of doing this conversion, but Gson stands among very few which does not require any pre-annotated java classes OR sourcecode of java classes in any way.

Gson also support the old java classes which had not support of generics in them for type information. It just work with these legacy classes smoothly.

In this gson tutorial, I am giving few examples of very common tasks you can perform with Gson.

Table of Contents

1. Prerequisites and dependency
2. Create Gson object
3. Convert Java objects to JSON format
4. Convert JSON to Java Objects
5. Writing an Instance Creator
6. Custom Serialization and De-serialization
7. Pretty Printing for JSON Output Format
8. Versioning Support
9. More Gson Tutorials

1. Prerequisites and dependency

1.1. POJO Class

Before coming to examples, let’s have a POJO class which we will use in given examples.

public class Employee
{
   private Integer id;
   private String firstName;
   private String lastName;
   private List<String> roles;
   
   public Employee(){      
   }
   
   public Employee(Integer id, String firstName, String lastName, Date birthDate){
      this.id = id;
      this.firstName = firstName;
      this.lastName = lastName;
   }
   
   //Getters and setters
   
   @Override
   public String toString()
   {
      return "Employee [id=" + id + ", firstName=" + firstName + ", " +
            "lastName=" + lastName + ", roles=" + roles + "]";
   }
}

1.2. Maven dependency

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

In gradle, use below dependency.

compile group: 'com.google.code.gson', name: 'gson', version: '2.8.5'

2. Create Gson object

Gson object can be created in two ways. First way gives you a quick Gson object ready for faster coding, while second way uses GsonBuilder to build a more sophisticated Gson object.

//1. Default constructor
Gson gson = new Gson();

//2. Using GsonBuilder
Gson gson = new GsonBuilder()
			 .disableHtmlEscaping()
			 .setFieldNamingPolicy(FieldNamingPolicy.UPPER_CAMEL_CASE)
			 .setPrettyPrinting()
			 .serializeNulls()
			 .create();

When using GsonBuilder, there are plenty of other useful options you can provide to Gson object. Go ahead and check them out.

3. Gson toJson() – Convert Java object to JSON String

To convert object to json, use toJson() method.

Employee employee = new Employee();
employee.setId(1);
employee.setFirstName("Lokesh");
employee.setLastName("Gupta");
employee.setRoles(Arrays.asList("ADMIN", "MANAGER"));

Gson gson = new Gson();

System.out.println(gson.toJson(employee));

Program Output.

{"id":1,"firstName":"Lokesh","lastName":"Gupta","roles":["ADMIN","MANAGER"]}

4. 3. Gson fromJson() – Convert JSON string to Object

To parse json to object, use fromJson() method.

Gson gson = new Gson();

System.out.println(
	gson.fromJson("{'id':1,'firstName':'Lokesh','lastName':'Gupta','roles':['ADMIN','MANAGER']}", 
	Employee.class));

Program Output.

Employee [id=1, firstName=Lokesh, lastName=Gupta, roles=[ADMIN, MANAGER]]

5. Gson InstanceCreator – when no-args constructor is not present in given object

In most of the cases, Gson library is smart enough to create instances even if any class does not provide default no-args constructor. But, if you found any problem using a class having no-args constructor, you can use InstanceCreator support. You need to register the InstanceCreator of a java class type with Gson first before using it.

For example, Department does not have any default constructor.

public class Department
{
   public Department(String deptName)
   {
      this.deptName = deptName;
   }

   private String deptName;

   public String getDeptName()
   {
      return deptName;
   }

   public void setDeptName(String deptName)
   {
      this.deptName = deptName;
   }
   
   @Override
   public String toString()
   {
      return "Department [deptName="+deptName+"]";
   }
}

And our Employee class has reference of Department as:

public class Employee
{
   private Integer id;
   private String firstName;
   private String lastName;
   private List<String> roles;
   private Department department; //Department reference
   
   //Other setters and getters
}

To use Department class correctly, we need to register an InstanceCreator for Department as below:

class DepartmentInstanceCreator implements InstanceCreator<Department> {
   public Department createInstance(Type type)
   {
      return new Department("None");
   }
}

Now use the above InstanceCreator as below.

GsonBuilder gsonBuilder = new GsonBuilder();

gsonBuilder.registerTypeAdapter(Department.class, new DepartmentInstanceCreator());

Gson gson = gsonBuilder.create();

System.out.println(
            gson.fromJson("{'id':1,'firstName':'Lokesh','lastName':'Gupta',
            'roles':['ADMIN','MANAGER'],'department':{'deptName':'Finance'}}", 
            Employee.class));

Program Output.

Employee [id=1, firstName=Lokesh, lastName=Gupta, roles=[ADMIN, MANAGER], department=Department [deptName=Finance]]

6. Gson custom serialization and deserialization

Many times, we need to write/read the JSON values which are not default representation of java object. In that case, we need to write custom serializer and deserializer of that java type.

In our example, I am writing serializer and deserializer for java.util.Date class, which will help writing the Date format in “dd/MM/yyyy” format.

6.1. Gson custom serializer

import java.lang.reflect.Type;
import java.text.SimpleDateFormat;
import java.util.Date;

import com.google.gson.JsonElement;
import com.google.gson.JsonPrimitive;
import com.google.gson.JsonSerializationContext;
import com.google.gson.JsonSerializer;

public class DateSerializer implements JsonSerializer<Date>
{
   private static final SimpleDateFormat dateFormat = new SimpleDateFormat("dd/MM/yyyy");
   public JsonElement serialize(Date date, Type typeOfSrc, JsonSerializationContext context)
   {
      return new JsonPrimitive(dateFormat.format(date));
   }
}

6.2. Gson custom deserializer

import java.lang.reflect.Type;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Date;

import com.google.gson.JsonDeserializationContext;
import com.google.gson.JsonDeserializer;
import com.google.gson.JsonElement;

public class DateDeserializer implements JsonDeserializer<Date>
{
   private static final SimpleDateFormat dateFormat = new SimpleDateFormat("dd/MM/yyyy");
   public Date deserialize(JsonElement dateStr, Type typeOfSrc, JsonDeserializationContext context)
   {
      try
      {
         return dateFormat.parse(dateStr.getAsString());
      } 
      catch (ParseException e)
      {
         e.printStackTrace();
      }
      return null;
   }
}

6.3. Register custom serializer and deserializer

Now you can register these serializer and deserializer with GsonBuilder as below:

GsonBuilder gsonBuilder = new GsonBuilder();
gsonBuilder.registerTypeAdapter(Date.class, new DateSerializer());
gsonBuilder.registerTypeAdapter(Date.class, new DateDeserializer());

6.4. Gson custom serializer and deserializer example

Complete example of serializer and deserializer is as below.

Employee employee = new Employee();
employee.setId(1);
employee.setFirstName("Lokesh");
employee.setLastName("Gupta");
employee.setRoles(Arrays.asList("ADMIN", "MANAGER"));
employee.setBirthDate(new Date());

GsonBuilder gsonBuilder = new GsonBuilder();
gsonBuilder.registerTypeAdapter(Date.class, new DateSerializer());
gsonBuilder.registerTypeAdapter(Date.class, new DateDeserializer());
Gson gson = gsonBuilder.create();

//Convert to JSON
System.out.println(gson.toJson(employee));

//Convert to java objects
System.out.println(gson.fromJson("{'id':1,'firstName':'Lokesh','lastName':'Gupta',
                                 'roles':['ADMIN','MANAGER'],'birthDate':'17/06/2014'}"
							           , Employee.class));
							

Program Output.

{"id":1,"firstName":"Lokesh","lastName":"Gupta","roles":["ADMIN","MANAGER"],"birthDate":"17/06/2014"}

Employee [id=1, firstName=Lokesh, lastName=Gupta, roles=[ADMIN, MANAGER], birthDate=Tue Jun 17 00:00:00 IST 2014]	

7. Gson setPrettyPrinting() – pretty print JSON output

The default JSON output that is provide by Gson is a compact JSON format. This means that there will not be any white-space in the output JSON structure. To generate a more readable and pretty looking JSON use setPrettyPrinting() in GsonBuilder.

Gson gson = new GsonBuilder().setPrettyPrinting().create();
String jsonOutput = gson.toJson(employee);

Program Output.

{
  "id": 1,
  "firstName": "Lokesh",
  "lastName": "Gupta",
  "roles": [
    "ADMIN",
    "MANAGER"
  ],
  "birthDate": "17/06/2014"
}

8. Gson setVersion() – versioning support

This is excellent feature you can use, if the class file you are working has been modified in different versions and fields has been annotated with @Since. All you need to do is to use setVersion() method of GsonBuilder.

GsonBuilder gsonBuilder = new GsonBuilder();

gsonBuilder.registerTypeAdapter(Date.class, new DateSerializer());
gsonBuilder.registerTypeAdapter(Date.class, new DateDeserializer());

//Specify the version like this
gsonBuilder.setVersion(1.0);

Gson gson = gsonBuilder.create();

8.1. Fields added in various versions in Employee.java

public class Employee
{
   @Since(1.0)
   private Integer id;
   private String firstName;
   private String lastName;
   
   @Since(1.1)
   private List<String> roles;
   
   @Since(1.2)
   private Date birthDate;
   
   //Setters and Getters
}

Gson @Since example

//Using version 1.0 fields
gsonBuilder.setVersion(1.0);

Output:
{"id":1,"firstName":"Lokesh","lastName":"Gupta"}

/////////////////////////////////////////////////////////////

//Using version 1.1 fields
gsonBuilder.setVersion(1.1);

Output:
{"id":1,"firstName":"Lokesh","lastName":"Gupta","roles":["ADMIN","MANAGER"]}

/////////////////////////////////////////////////////////////

//Using version 1.2 fields
gsonBuilder.setVersion(1.2);

Output:
{"id":1,"firstName":"Lokesh","lastName":"Gupta","roles":["ADMIN","MANAGER"],"birthDate":"17/06/2014"}

9. More Gson Tutorials

1. Gson – GsonBuilder Tutorial
2. Gson – Serialize and deserialize JSON
3. Gson – Serialize and deserialize Map
4. Gson – Serialize and deserialize Set
5. Gson – Serialize and deserialize array
6. Gson – @SerializedName annotation example
7. Gson – Jersey + Gson Example

That’s all for this very useful java gson library to convert java objects from /to JSON. Drop a comment is you have any query or feedback.

Happy Learning !!

Reference

GSON User Guide

Further Reading:

Gson – Pretty Print JSON Gson – Serialize NULL values Gson @SerializedName