Gson @Since – Field Versioning Support

As the applications change over time, the model classes also change with them. Sometimes these changes may be breaking e.g. adding/removing fields etc.

All such changes can be marked with @Since annotation to keep track of model class so that the application integration with other systems does not break – when these system talk using deserialized JSON data.

1. Gson @Since Annotation

In Gson, multiple versions of the same object can be maintained by using @Since annotation. This annotation can be used on Classes, Fields and, in a future release, Methods. It takes single parameter – ignoreVersionsAfter.

When we configure the Gson instance with a version number 'M.N' then all class fields marked with version greater than M.N will be ignored.

For example, if we configure Gson with version number '1.2' then all fields versioned with a number greater (e.g. 1.3, 1.4 …) will be ignored.

@Since(1.2)
private String email;

2. Gson Version Support

Let’s create and run an example to understand more about how the versioning support work in Gson.

2.1. Fields with Version Numbers

In the below Employee class, we have versioned three fields i.e. firstName, lastName and email.

public class Employee
{
	private Integer id;

	@Since(1.0)
    private String firstName;

    @Since(1.1)
    private String lastName;

    @Since(1.2)
    private String email;
}

2.2. Create Gson instance for Specified Version

To create Gson instance which will honor the @Since annotation, use GsonBuilder.setVersion() method.

Gson gson = new GsonBuilder()
			.setVersion(1.1)
			.create();

3. Demo

The @Since annotation affects the serialization and deserialization both, so use it very carefully.

3.1. Serialization with Version Support

Let us serialize above Employee object with version number 1.1.

Employee employeeObj = new Employee(1, "Lokesh", "Gupta", "howtogoinjava@gmail.com");

Gson gson = new GsonBuilder()
		.setVersion(1.1)
		.setPrettyPrinting()
		.create();

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

Observe the output. Field with a version number greater than 1.1 i.e. 1.2 is ignored. Other fields have gone through just fine.

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

3.2. Deserialization with Version Support

Let us deserialize a JSON string to Employee object with version number 1.1.

String json = "{'id': 1001, "
				+ "'firstName': 'Lokesh',"
				+ "'lastName': 'Gupta',"
				+ "'email': 'howtodoinjava@gmail.com'}";

Gson gson = new GsonBuilder()
		.setVersion(1.1)
		.setPrettyPrinting()
		.create();

Employee employeeObj = gson.fromJson(json, Employee.class);

System.out.println(employeeObj);

Observe the output. Even though the JSON string has email field, it did not got deserialized.

Employee [id=1001, firstName=Lokesh, lastName=Gupta, email=null]

Drop me your questions related to Gson version support using @Since annotation.

Happy Learning !!