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 !!
Comments