Java Gson versioning support using @Since annotation

Tags: JSON gson Gson toJson Gson Since Gson versioning GsonBuilder setVersion

In this Java Gson tutorial we learn how to @Since annotation to support versioning during serialization or deserialize JSON with Gson library.

How to add Gson to the Java project

To use the Gson library in the Gradle build project, add the following dependency into the build.gradle file.

implementation group: 'com.google.code.gson', name: 'gson', version: '2.8.7'

To use the Gson library in the Maven build project, add the following dependency into the pom.xml file.

<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.8.7</version>
</dependency>

Or you can download the Gson jar file from Maven Central at gson-2.8.7.jar

To have more information about the Gson library you can visit the project repository at github.com/google/gson

What is @Since annotation?

The @Since annotation of Gson library to indicate the version number since a member or a type has been present. This annotation is useful to manage versioning of your Json classes for a web-service.

How Gson library support versioning using @Since annotation

For example we have the User class as below.

User.java 

import com.google.gson.annotations.Since;

public class User {
    @Since(1.0)
    private String userIdentity;

    @Since(1.3)
    private String userName;

    @Since(2.0)
    private String fullName;

    public String getUserIdentity() {
        return userIdentity;
    }

    public void setUserIdentity(String userIdentity) {
        this.userIdentity = userIdentity;
    }

    public String getUserName() {
        return userName;
    }

    public void setUserName(String userName) {
        this.userName = userName;
    }

    public String getFullName() {
        return fullName;
    }

    public void setFullName(String fullName) {
        this.fullName = fullName;
    }
}

You can see the User class above we have @Since(1.0), @Since(1.3) and @Since(2.0) annotation to indicate which version these fields were introduced.

In the following Java programs to show you how to generate JSON String from a User object for different versions using the GsonBuilder.setVersion() method to configure versioning for Gson objects.

VersioningExample1.java 

import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

public class VersioningExample1 {
    public static void main(String... args) {
        User user = new User();
        user.setUserIdentity("SimpleSolution");
        user.setUserName("SimpleSolution");
        user.setFullName("Simple Solution");

        GsonBuilder gsonBuilder = new GsonBuilder();
        Gson gson = gsonBuilder
                .setVersion(1.0)
                .create();
        String jsonString = gson.toJson(user);

        System.out.println("Output JSON: ");
        System.out.println(jsonString);
    }
}
The output is: 
Output JSON: 
{"userIdentity":"SimpleSolution"}

VersioningExample2.java 

import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

public class VersioningExample2 {
    public static void main(String... args) {
        User user = new User();
        user.setUserIdentity("SimpleSolution");
        user.setUserName("SimpleSolution");
        user.setFullName("Simple Solution");

        GsonBuilder gsonBuilder = new GsonBuilder();
        Gson gson = gsonBuilder
                .setVersion(1.5)
                .create();
        String jsonString = gson.toJson(user);

        System.out.println("Output JSON: ");
        System.out.println(jsonString);
    }
}
The output is: 
Output JSON: 
{"userIdentity":"SimpleSolution","userName":"SimpleSolution"}

VersioningExample3.java 

import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

public class VersioningExample3 {
    public static void main(String... args) {
        User user = new User();
        user.setUserIdentity("SimpleSolution");
        user.setUserName("SimpleSolution");
        user.setFullName("Simple Solution");

        GsonBuilder gsonBuilder = new GsonBuilder();
        Gson gson = gsonBuilder
                .setVersion(2.0)
                .create();
        String jsonString = gson.toJson(user);

        System.out.println("Output JSON: ");
        System.out.println(jsonString);
    }
}
The output is: 
Output JSON: 
{"userIdentity":"SimpleSolution","userName":"SimpleSolution","fullName":"Simple Solution"}

Happy Coding 😊