GSON

Gson is an open-source Java library developed by Google that converts Java Objects into their JSON representation and vice versa.

Gson mainly build for Java, other jvm languages may not work properly. It

• Provide simple toJson() and fromJson() methods to convert Java objects to JSON and vice-versa

• Allow pre-existing unmodifiable objects to be converted to and from JSON

• Extensive support of Java Generics and Allow custom representations for objects

Dependency

<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>${version}</version>
</dependency>

Some points to consider

• We can use private fields, they will be serialized.

• All fields in the current class (and from all super classes) are included by default.

• If a field is marked transient, (by default) it is ignored and not included in the JSON serialization or deserialization.

• This implementation handles nulls correctly.

  • While serializing, a null field is omitted from the output.

  • While deserializing, a missing entry in JSON results in setting the corresponding field in the object to its default value: null for object types, zero for numeric types, and false for booleans.

• If a field is synthetic, it is ignored and not included in JSON serialization or deserialization.

• Fields corresponding to the outer classes in inner classes are ignored and not included in serialization or deserialization.

• Anonymous and local classes are excluded. They will be serialized as JSON null and when deserialized their JSON value is ignored and null is returned. Convert the classes to static nested classes to enable serialization and deserialization for them.

• We cannot serialize objects with circular references, since that will result in infinite recursion.

Serialization and De-serialization

First we need to create Gson object by using the class Gson, then we can use methods like fromJson & toJson to do objects and json conversion.

TypeToken

TypeToken is a class in Gson that helps capture and preserve generic type information.

TypeToken is essential when working with generic types in Gson, and understanding its proper usage helps in handling complex JSON structures effectively.

TypeToken instances should be created carefully and reused when possible for better performance.

For more details go to TypeToken section

Examples

Primitives

// Serialization
Gson gson = new Gson();
gson.toJson(1);            // ==> 1
gson.toJson("abcd");       // ==> "abcd"
gson.toJson(new Long(10)); // ==> 10
int[] values = { 1 };
gson.toJson(values);       // ==> [1]

// Deserialization
int i = gson.fromJson("1", int.class);

Integer intObj = gson.fromJson("1", Integer.class);

Long longObj = gson.fromJson("1", Long.class);

Boolean boolObj = gson.fromJson("false", Boolean.class);

String str = gson.fromJson("\"abc\"", String.class);

String[] strArray = gson.fromJson("[\"abc\"]", String[].class);

Arrays Example

Gson gson = new Gson();
int[] ints = {1, 2, 3, 4, 5};
String[] strings = {"abc", "def", "ghi"};

// Serialization
gson.toJson(ints);     // ==> [1,2,3,4,5]

gson.toJson(strings);  // ==> ["abc", "def", "ghi"]

// Deserialization
int[] ints2 = gson.fromJson("[1,2,3,4,5]", int[].class);
// ==> ints2 will be same as ints

Collections Example

for the collections, we will be needing type tokens for conversion.

Gson gson = new Gson();
Collection<Integer> ints = Arrays.asList(1,2,3,4,5);

// Serialization
String json = gson.toJson(ints);  // ==> [1,2,3,4,5]

// Deserialization
TypeToken<Collection<Integer>> collectionType = new TypeToken<Collection<Integer>>(){};

Collection<Integer> ints2 = gson.fromJson(json, collectionType);
// ==> ints2 is same as ints

String json = "[\"Alice\", \"Bob\", \"Charlie\"]";

// Use TypeToken to define the type
Type listType = new TypeToken<List<String>>() {}.getType();

// Deserialize JSON to List<String>
List<String> names = gson.fromJson(json, listType);
System.out.println("Names: " + names);

// Serialize List<String> back to JSON
String jsonString = gson.toJson(names, listType);

Maps Examples

Gson by default serializes any java.util.Map implementation as a JSON object. Because JSON objects only support strings as member names, Gson converts the Map keys to strings by calling toString() on them, and using "null" for null keys:

Gson gson = new Gson();

Map<String, String> stringMap = new LinkedHashMap<>();
stringMap.put("key", "value");
stringMap.put(null, "null-entry");

// Serialization
String json = gson.toJson(stringMap); // ==> {"key":"value","null":"null-entry"}

Map<Integer, Integer> intMap = new LinkedHashMap<>();
intMap.put(2, 4);
intMap.put(3, 6);

// Serialization
String json = gson.toJson(intMap); // ==> {"2":4,"3":6}

for deserialization a TypeToken has to be used to tell Gson what types the Map keys and values have:

Gson gson = new Gson();
TypeToken<Map<String, String>> mapType = new TypeToken<Map<String, String>>(){};
String json = "{\"key\": \"value\"}";

// Deserialization
Map<String, String> stringMap = gson.fromJson(json, mapType);
// ==> stringMap is {key=value}

Another Example

String json = "[{\"Alice\": 25, \"Bob\": 30}, {\"Charlie\": 35, \"David\": 40}]";
Gson gson = new Gson();

// Use TypeToken to define the type
Type nestedType = new TypeToken<List<Map<String, Integer>>>() {}.getType();

// Deserialize JSON to List<Map<String, Integer>>
List<Map<String, Integer>> nestedList = gson.fromJson(json, nestedType);
System.out.println("Nested List: " + nestedList);

// Serialize List<Map<String, Integer>> back to JSON
String jsonString = gson.toJson(nestedList, nestedType);
System.out.println("JSON: " + jsonString);

If map keys are complex and toString method is not implemented, then this can lead to malformed encoded keys or can cause mismatch between serialization and deserialization of the keys. A workaround for this can be to use enableComplexMapKeySerialization() to make sure the TypeAdapter registered for the Map key type is used for deserialization and serialization.

class PersonName {
  String firstName;
  String lastName;

  PersonName(String firstName, String lastName) {
    this.firstName = firstName;
    this.lastName = lastName;
  }

}

Gson gson = new GsonBuilder().enableComplexMapKeySerialization().create();
Map<PersonName, Integer> complexMap = new LinkedHashMap<>();
complexMap.put(new PersonName("John", "Doe"), 30);
complexMap.put(new PersonName("Jane", "Doe"), 35);

// Serialization; 
String json = gson.toJson(complexMap);
// ==> [[{"firstName":"John","lastName":"Doe"},30],[{"firstName":"Jane","lastName":"Doe"},35]]

Map<String, String> stringMap = new LinkedHashMap<>();
stringMap.put("key", "value");
// Serialization; 
String json = gson.toJson(stringMap); // ==> {"key":"value"}

Raw Collection Example

    Gson gson = new Gson();
    Collection collection = new ArrayList();
    collection.add("hello");
    collection.add(5);
    collection.add(new Event("GREETINGS", "guest"));
    
    String json = gson.toJson(collection);
    System.out.println("Using Gson.toJson() on a raw collection: " + json);
    
    JsonArray array = JsonParser.parseString(json).getAsJsonArray();
    String message = gson.fromJson(array.get(0), String.class);
    int number = gson.fromJson(array.get(1), int.class);
    Event event = gson.fromJson(array.get(2), Event.class);
    
    System.out.printf("Using Gson.fromJson() to get: %s, %d, %s", message, number, event);

Objects Types-

class Person {
    String name;
    int age;
    boolean isDeveloper;
}

Gson gson = new Gson();
// Serialization
String json = gson.toJson(person);

// --output 
{"name":"Alice","age":25,"isDeveloper":true}

String json = "{\"name\":\"Alice\",\"age\":25,\"isDeveloper\":true}";

// deSerialization
Person person = gson.fromJson(json, Person.class);

If Object is in with collections -

import com.google.gson.Gson;
import com.google.gson.reflect.TypeToken;
import java.lang.reflect.Type;
import java.util.List;

public class Main {
    public static void main(String[] args) {
        String json = "[{\"name\": \"Alice\", \"age\": 25}, {\"name\": \"Bob\", \"age\": 30}]";
        Gson gson = new Gson();

        // Use TypeToken to define the type
        Type listType = new TypeToken<List<Person>>() {}.getType();

        // Deserialize JSON to List<Person>
        List<Person> people = gson.fromJson(json, listType);
        for (Person person : people) {
            System.out.println(person.name + " is " + person.age + " years old.");
        }

        // Serialize List<Person> back to JSON
        String jsonString = gson.toJson(people, listType);
        System.out.println("JSON: " + jsonString);
    }
}

Nested Structure with Multiple Types

public class Department {
    private String name;
    private Employee manager;
    private List<Employee> employees;
    private Map<String, Project> projects;
    private Set<String> locations;
    
    // Constructor, getters, setters
}

public class Project {
    private String name;
    private Date startDate;
    private List<Employee> team;
    private Map<String, Object> metadata;
    
    // Constructor, getters, setters
}

// Usage Example
public class ComplexStructureExample {
    public static void main(String[] args) {
        Gson gson = new GsonBuilder()
            .setPrettyPrinting()
            .setDateFormat("yyyy-MM-dd")
            .create();
        
        // Create complex structure
        Department dept = new Department();
        dept.setName("Engineering");
        dept.setManager(new Employee("John Manager", new Address("456 Boss St", "Boston", "USA", 12345)));
        dept.setEmployees(Arrays.asList(
            new Employee("Dev1", new Address("123 Dev St", "Boston", "USA", 12345)),
            new Employee("Dev2", new Address("124 Dev St", "Boston", "USA", 12345))
        ));
        
        Map<String, Project> projects = new HashMap<>();
        Project project = new Project();
        project.setName("Project X");
        project.setStartDate(new Date());
        project.setTeam(Arrays.asList(new Employee("Dev1"), new Employee("Dev2")));
        
        Map<String, Object> metadata = new HashMap<>();
        metadata.put("priority", 1);
        metadata.put("tags", Arrays.asList("urgent", "innovative"));
        project.setMetadata(metadata);
        
        projects.put("PRJ-1", project);
        dept.setProjects(projects);
        
        dept.setLocations(new HashSet<>(Arrays.asList("Boston", "New York", "San Francisco")));
        
        // Serialize
        String jsonDept = gson.toJson(dept);
        
        // Deserialize
        Department parsedDept = gson.fromJson(jsonDept, Department.class);
    }
}

Generic Types

When you call toJson(obj), Gson calls obj.getClass() to get information on the fields to serialize. Similarly, you can typically pass MyClass.class object in the fromJson(json, MyClass.class) method. This works fine if the object is a non-generic type.

However, if the object is of a generic type, then the Generic type information is lost because of Java Type Erasure. To make it work properly we need to use TypeToken

class Foo<T> {
  T value;
}
Gson gson = new Gson();
Foo<Bar> foo = new Foo<Bar>();

Type fooType = new TypeToken<Foo<Bar>>() {}.getType();
gson.toJson(foo, fooType);

gson.fromJson(json, fooType);

fooType actually defines an anonymous local inner class containing a method getType() that returns the fully parameterized type.

{
  "status": "success",
  "data": [
    {"name": "Alice", "age": 25},
    {"name": "Bob", "age": 30}
  ]
}

class ApiResponse<T> {
    String status;
    T data;
}

class Person {
    String name;
    int age;
}

import com.google.gson.Gson;
import com.google.gson.reflect.TypeToken;
import java.lang.reflect.Type;
import java.util.List;

public class Main {
    public static void main(String[] args) {
        String json = "{\"status\": \"success\", \"data\": [{\"name\": \"Alice\", \"age\": 25}, {\"name\": \"Bob\", \"age\": 30}]}";
        Gson gson = new Gson();

        // Define the TypeToken for ApiResponse<List<Person>>
        Type responseType = new TypeToken<ApiResponse<List<Person>>>() {}.getType();

        // Deserialize JSON to ApiResponse<List<Person>>
        ApiResponse<List<Person>> response = gson.fromJson(json, responseType);
        System.out.println("Status: " + response.status);
        for (Person person : response.data) {
            System.out.println(person.name + " is " + person.age + " years old.");
        }

        // Serialize ApiResponse<List<Person>> back to JSON
        String jsonString = gson.toJson(response, responseType);
        System.out.println("JSON: " + jsonString);
    }
}

Custom Serialization and Deserialization

Sometimes the default representation is not what you want. This is often the case when dealing with library classes (DateTime, etc.). Gson allows you to register your own custom serializers and deserializers. This is done by defining two parts:

• JSON Serializers: Need to define custom serialization for an object

• JSON Deserializers: Needed to define custom deserialization for a type

• Instance Creators: Not needed if no-args constructor is available or a deserializer is registered

GsonBuilder gson = new GsonBuilder();
gson.registerTypeAdapter(MyType2.class, new MyTypeAdapter());
gson.registerTypeAdapter(MyType.class, new MySerializer());
gson.registerTypeAdapter(MyType.class, new MyDeserializer());
gson.registerTypeAdapter(MyType.class, new MyInstanceCreator());

Custom Type Adapters

class DateAdapter implements JsonSerializer<Date>, JsonDeserializer<Date> {
    private final SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");

    @Override
    public JsonElement serialize(Date date, Type type, JsonSerializationContext context) {
        return new JsonPrimitive(dateFormat.format(date));
    }

    @Override
    public Date deserialize(JsonElement json, Type type, JsonDeserializationContext context) throws JsonParseException {
        try {
            return dateFormat.parse(json.getAsString());
        } catch (ParseException e) {
            throw new JsonParseException(e);
        }
    }
}

// Register the adapter
Gson gson = new GsonBuilder()
.registerTypeAdapter(Date.class, new DateAdapter()).create();

Check custom Joda datetime Serializer and deserializer with Gson

Instance Creator

Typically, Instance Creators are needed when you are dealing with a library class that does NOT define a no-argument constructor.

Basic instance creator-

private class MoneyInstanceCreator implements InstanceCreator<Money> {
  public Money createInstance(Type type) {
    return new Money("1000000", CurrencyCode.USD);
  }
}

Instance Creator with parameterized type

public class Id<T> {
  private final Class<T> classOfId;
  private final long value;
  public Id(Class<T> classOfId, long value) {
    this.classOfId = classOfId;
    this.value = value;
  }
}

class IdInstanceCreator implements InstanceCreator<Id<?>> {
  public Id<?> createInstance(Type type) {
    Type[] typeParameters = ((ParameterizedType)type).getActualTypeArguments();
    Type idType = typeParameters[0]; // Id has only one parameterized type T
    return new Id((Class)idType, 0L);
  }
}

Pretty Printing for JSON Output Format

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

Null Object Support

By default null object fields are ignored. To serialize them -

Gson gson = new GsonBuilder().serializeNulls().create();

public class Foo {
  private final String s;
  private final int i;

  public Foo() {
    this(null, 5);
  }

  public Foo(String s, int i) {
    this.s = s;
    this.i = i;
  }
}

Gson gson = new GsonBuilder().serializeNulls().create();
Foo foo = new Foo();
String json = gson.toJson(foo);
System.out.println(json);

json = gson.toJson(null);
System.out.println(json);


{"s":null,"i":5}
null

Excluding Fields From Serialization and Deserialization

By default, if you mark a field as transient, it will be excluded. As well, if a field is marked as static then by default it will be excluded.

We can control this by using modifiers-

Gson gson = new GsonBuilder()
    .excludeFieldsWithModifiers(Modifier.STATIC, Modifier.TRANSIENT, Modifier.VOLATILE)
    .create();

User Defined Exclusion Strategies

The following example shows how to exclude fields marked with a specific @Foo annotation and excludes top-level types (or declared field type) of class String.

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD})
public @interface Foo {
  // Field tag only annotation
}

public class SampleObjectForTest {
  @Foo private final int annotatedField;
  private final String stringField;
  private final long longField;

}

// custom exclusion strategy
public class MyExclusionStrategy implements ExclusionStrategy {
  private final Class<?> typeToSkip;

  private MyExclusionStrategy(Class<?> typeToSkip) {
    this.typeToSkip = typeToSkip;
  }

  public boolean shouldSkipClass(Class<?> clazz) {
    return (clazz == typeToSkip);
  }

  public boolean shouldSkipField(FieldAttributes f) {
    return f.getAnnotation(Foo.class) != null;
  }
}

public static void main(String[] args) {
  Gson gson = new GsonBuilder()
      .setExclusionStrategies(new MyExclusionStrategy(String.class))
      .serializeNulls()
      .create();
      
  SampleObjectForTest src = new SampleObjectForTest();
  String json = gson.toJson(src);
  System.out.println(json);
}

The output is:

{"longField":1234}

JSON Field Naming Support

For defining custom name we can use @SerializedName annotation and can configure FieldNamingPolicy to serilization of fields

private class SomeObject {
  @SerializedName("custom_naming") private final String someField;
  private final String someOtherField;

  public SomeObject(String a, String b) {
    this.someField = a;
    this.someOtherField = b;
  }
}

SomeObject someObject = new SomeObject("first", "second");

Gson gson = new GsonBuilder().setFieldNamingPolicy(FieldNamingPolicy.UPPER_CAMEL_CASE).create();

String jsonRepresentation = gson.toJson(someObject);
System.out.println(jsonRepresentation);

//-- output
{"custom_naming":"first","SomeOtherField":"second"}

Best Practices -

1. Use Pretty Printing for Debug

2. Handle Null Values Appropriately

3. Reuse Gson Instances

@Configuration
public class GsonConfig {
    @Bean
    public Gson gson() {
        return new GsonBuilder()
            .setDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSZ")
            .setFieldNamingPolicy(FieldNamingPolicy.LOWER_CASE_WITH_UNDERSCORES)
            .create();
    }
}

Inspired from - gson user guide