【Java】Gsonの@UntilアノテーションでJSONのバージョン管理を行う方法

@Untilアノテーションは、GsonBuilderクラスのsetVersion()メソッドと組み合わせて使用します。このアノテーションはJavaクラスのフィールドに付与でき、float型の値を引数として受け取ります。この引数はバージョン番号を表し、指定したバージョン未満の場合にのみ、そのフィールドがJSONとしてシリアライズされます。つまり、バージョンが上がると自動的に対象フィールドが出力から除外されるため、WebサービスなどでAPIの互換性を保ちながらJSONクラスのバージョン管理を行う際に非常に便利です。

@Untilアノテーションの構文

@Documented
@Retention(value=RUNTIME)
@Target(value={FIELD,TYPE})
public @interface Until

• @Documented: Javadocにアノテーション情報が反映されます。
• @Retention(RUNTIME): 実行時までアノテーション情報が保持され、Gsonがリフレクションで参照できるようになります。
• @Target({FIELD, TYPE}): フィールドおよび型に対して適用できます。

サンプルコード

次の例では、EmployeeクラスのempTechとempAddressフィールドに@Until(1.1)を付与し、バージョン0.5・1.0・1.1の3パターンでJSONを出力しています。

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

public class GsonUntilAnnotationTest {
    public static void main(String[] args) {
        Employee emp = new Employee();
        emp.setEmployeeName("Adithya");
        emp.setEmployeeId(115);
        emp.setEmployeeTechnology("Python");
        emp.setEmploeeAddress("Pune");

        System.out.println("バージョン0.5を使用");
        GsonBuilder gsonBuilder = new GsonBuilder();
        Gson gson = gsonBuilder.setPrettyPrinting().setVersion(0.5).create();
        String jsonString = gson.toJson(emp);
        System.out.println(jsonString);

        System.out.println("バージョン1.0を使用");
        gsonBuilder = new GsonBuilder();
        gson = gsonBuilder.setPrettyPrinting().setVersion(1.0).create();
        jsonString = gson.toJson(emp);
        System.out.println(jsonString);

        System.out.println("バージョン1.1を使用");
        gsonBuilder = new GsonBuilder();
        gson = gsonBuilder.setPrettyPrinting().setVersion(1.1).create();
        jsonString = gson.toJson(emp);
        System.out.println(jsonString);
    }
}

// Employeeクラス
class Employee {
    private String empName;
    private int empId;

    @Until(1.1)
    private String empTech;

    @Until(1.1)
    private String empAddress;

    public String getEmployeeName() {
        return empName;
    }
    public void setEmployeeName(String empName) {
        this.empName = empName;
    }
    public int getEmployeeId() {
        return empId;
    }
    public void setEmployeeId(int empId) {
        this.empId = empId;
    }
    public String getEmployeeTechnology() {
        return empTech;
    }
    public void setEmployeeTechnology(String empTech) {
        this.empTech = empTech;
    }
    public String getEmploeeAddress() {
        return empAddress;
    }
    public void setEmploeeAddress(String empAddress) {
        this.empAddress = empAddress;
    }
}

実行結果

バージョン0.5を使用
{
    "empName": "Adithya",
    "empId": 115,
    "empTech": "Python",
    "empAddress": "Pune"
}
バージョン1.0を使用
{
    "empName": "Adithya",
    "empId": 115,
    "empTech": "Python",
    "empAddress": "Pune"
}
バージョン1.1を使用
{
    "empName": "Adithya",
    "empId": 115
}

動作のポイント

• バージョン0.5および1.0の場合: @Until(1.1)が付与されたempTechとempAddressも含めて、すべてのフィールドが出力されます。
• バージョン1.1の場合: @Until(1.1)が付与されたフィールドは出力から除外され、empNameとempIdのみがシリアライズされます。

なお、逆に「特定のバージョン以降でフィールドを新たに追加したい」場合は、@Sinceアノテーションを使用します。@Sinceと@Untilを組み合わせることで、フィールド単位のきめ細かなバージョン管理が可能になります。