In this post under Gson, I will explain with an example how to use @Since annotation.

The @Since annotation is used in combination with “GsonBuilder.setVersion” method. The annotation has no effect if it is not used along with “GsonBuilder.setVersion” method.

The @Since annotation is used for the fields of the class and it accepts a float as argument. The argument represents the version number from which the field (annotated with @Since) should be serialized.

The same thing applies for deserialization process.

The current version number is set using “GsonBuilder.setVersion” method.

This annotation is useful to manage versioning of your JSON classes for a web-service.

Below is a class whose fields are annotated with @Since annotation

User2.java

1  import com.google.gson.annotations.Since;
2  
3  public class User2 {
4   private String firstName;
5   private String lastName;
6   @Since(1.0) 
7   private String emailAddress;
8   @Since(1.1) 
9   private String password;
10  
11  public String getFirstName() {
12      return firstName;
13  }
14  public void setFirstName(String firstName) {
15      this.firstName = firstName;
16  }
17  public String getLastName() {
18      return lastName;
19  }
20  public void setLastName(String lastName) {
21      this.lastName = lastName;
22  }
23  public String getEmailAddress() {
24      return emailAddress;
25  }
26  public void setEmailAddress(String emailAddress) {
27      this.emailAddress = emailAddress;
28  }
29  public String getPassword() {
30      return password;
31  }
32  public void setPassword(String password) {
33      this.password = password;
34  }
35 }

In the above java class, I used @Since annotation for field “emailAddress” with version 1.0 and “password” with version number as 1.1. Refer line 6 and 8.

So if the current version number is 0.5, both the fields are not serialized because “emailAddress” is meant to be serialized when the current version number is greater than or equal to 1.0 and “password” is meant to be serialized when the current version number is greater than or equal to 1.1.

If the current version number is 1.0, the field “emailAddress” will be serialized but not the field “password”.

If the current version number is 1.1, the two fields will be serialized.

Below is the Main class which shows how to set the current version number

Main class

1  import com.google.gson.Gson;
2  import com.google.gson.GsonBuilder;
3  
4  public class GsonDemo11 {
5   public static void main(String[] args) {
6       User2 user = new User2();
7       user.setFirstName("firstName");
8       user.setLastName("lastName");
9       user.setPassword("password");
10      user.setEmailAddress("emailAddress");
11      
12      System.out.println("Using version 0.5");
13      GsonBuilder gsonBuilder = new GsonBuilder();
14      Gson gson = gsonBuilder.setVersion(0.5).create();
15      String result = gson.toJson(user);
16      System.out.println(result);
17      
18      System.out.println("Using version 1.0");
19      gsonBuilder = new GsonBuilder();
20      gson = gsonBuilder.setVersion(1.0).create();
21      result = gson.toJson(user);
22      System.out.println(result);
23      
24      System.out.println("Using version 1.1");
25      gsonBuilder = new GsonBuilder();
26      gson = gsonBuilder.setVersion(1.1).create();
27      result = gson.toJson(user);
28      System.out.println(result);
29  }
30 }

In the above code we created an instance of User2 class.

At line 14, we created a Gson instance using GsonBuilder with version number of 0.5.

At line 20, we created a Gson instance using GsonBuilder with version number of 1.0.

At line 26, we created a Gson instance using GsonBuilder with version number of 1.1.

Below is the output

Output

Using version 0.5
{“firstName”:”firstName”,”lastName”:”lastName”}
Using version 1.0
{“firstName”:”firstName”,”lastName”:”lastName”,”emailAddress”:”emailAddress”}
Using version 1.1
{“firstName”:”firstName”,”lastName”:”lastName”,”emailAddress”:”emailAddress”,”password”:”password”}