วิธีใช้ @Until annotation ด้วย Gson library ใน Java

คำอธิบายประกอบ @Until ใช้ร่วมกับเมธอด setVersion() ของคลาส GsonBuilder คล้ายกับ @Since แต่ทำงานในทางตรงข้าม Annotation นี้วางได้ที่ฟิลด์ใน Java class และรับค่า float เป็น argument แทน version number ที่ฟิลด์นั้น หยุดถูก serialize (serialize จนถึง version นั้น) @Until สามารถจัดการ versioning ของ JSON classes ใน web-services ได้

Syntax

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

ตัวอย่างการใช้งาน

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("Using version 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("Using version 1.0");
        gsonBuilder = new GsonBuilder();
        gson = gsonBuilder.setPrettyPrinting().setVersion(1.0).create();
        jsonString = gson.toJson(emp);
        System.out.println(jsonString);
        
        System.out.println("Using version 1.1");
        gsonBuilder = new GsonBuilder();
        gson = gsonBuilder.setPrettyPrinting().setVersion(1.1).create();
        jsonString = gson.toJson(emp);
        System.out.println(jsonString);
    }
}

// Employee class
class Employee {
    private String empName;
    private int empId;
    
    @Until(1.1)
    private String empTech;
    
    @Until(1.1)
    private String empAddress;
    
    // getters และ setters...
}

ผลลัพธ์ (Output)

Using version 0.5
{
  "empName": "Adithya",
  "empId": 115,
  "empTech": "Python",
  "empAddress": "Pune"
}

Using version 1.0
{
  "empName": "Adithya",
  "empId": 115,
  "empTech": "Python",
  "empAddress": "Pune"
}

Using version 1.1
{
  "empName": "Adithya",
  "empId": 115
}

คำอธิบาย

@Until ทำงานตรงข้ามกับ @Since: ฟิลด์ที่มี @Until(1.1) จะถูก serialize เมื่อ version < 1.1 แต่เมื่อ version >= 1.1 ฟิลด์นั้นจะหายไปจาก JSON output

การรวมใช้ @Since และ @Until

สามารถใช้ทั้งคู่ร่วมกันได้ เพื่อกำหนดช่วง version ที่ฟิลด์ active:

@Since(1.0)
@Until(2.0)
private String deprecatedField; // ใช้ได้เฉพาะ version 1.0 - 1.9

กรณีการใช้งาน (Use Cases)

• Deprecation - ลบฟิลด์เก่าออกเมื่อ version เพิ่มขึ้น
• API Evolution - จัดการฟิลด์ที่ deprecated
• Compliance - หยุดส่งข้อมูลที่ไม่ควรส่งใน version ใหม่

สรุป

@Until annotation เป็นคู่ของ @Since ใช้สำหรับ "ปิด" ฟิลด์เมื่อ version ถึงจุดที่กำหนด ร่วมกันช่วยจัดการ API versioning และ schema evolution ได้ครบถ้วน