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 how the versioning support work in Gson.
2.1. How to write a versioned class using @Since annotation
In 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 with version support
To create Gson
instance which will honor the @Since annotation, use GsonBuilder.setVersion() method.
Gson gson = new GsonBuilder() .setVersion(1.1) .create();
3. Demo
@Since
annotation affects the serialization and deserialization both, so use it very carefully.
3.1. Serialization with version support
Lets serialize above Employee
object with version number
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));
{ "id": 1, "firstName": "Lokesh", "lastName": "Gupta" }
Observe the output. Field with version number greater than 1.1
i.e. 1.2
is ignored. Other fields gone through just fine.
3.2. Deserialization with version support
Lets deserialize a JSON string to Employee
object with version number
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);
Employee [id=1001, firstName=Lokesh, lastName=Gupta, email=null]
Observe the output. Even though the JSON string has email
field, it did not got deserialized.
Drop me your questions related to Gson version support using @Since annotation.
Happy Learning !!
Leave a Reply