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

The @Until 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 @Until annotation is used for the fields of the class and it accepts a float as argument. The argument represents the version number upto which the field (annotated with @Until) should be serialized.

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 @Until annotation

User1.java

1  import com.google.gson.annotations.Until;
2  
3  public class User1 {
4   private String firstName;
5   private String lastName;
6   @Until(1.1) 
7   private String emailAddress;
8   @Until(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 @Until annotation for two fields “emailAddress” and “password” with version number as 1.1. Refer line 6 and 8.

So if the current version number is 0.5, the two fields will be serialized.

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

If the current version number is 1.1, the two fields will not be serialized because the two fields (emailAddress and password) were meant to be serialized if the current version number is less or equal to 1.0.

The same thing applies for deserialization process.

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 GsonDemo10 {
5   public static void main(String[] args) {
6       User1 user = new User1();
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 User1 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”,”emailAddress”:”emailAddress”,”password”:”password”}
Using version 1.0
{“firstName”:”firstName”,”lastName”:”lastName”,”emailAddress”:”emailAddress”,”password”:”password”}
Using version 1.1
{“firstName”:”firstName”,”lastName”:”lastName”}