Gson — یہ کیا ہے، Java اور Kotlin کے لیے JSON لائبریری

Gson کیا ہے

Gson Google کی تیار کردہ ایک Java لائبریری ہے جو آبجیکٹ کو JSON نمائندگی میں اور واپس تبدیل کرنے کے لیے ہے۔ یہ کلاس کے ڈھانچے کا تجزیہ کرنے کے لیے ریفلیکشن استعمال کرتی ہے، جو پہلے سے ترتیب کے بغیر کام کرنے کی اجازت دیتی ہے۔ Gson صوابدیدی Java آبجیکٹ، کلیکشن، اری، جنیرکس اور نیسٹڈ کلاس کو سپورٹ کرتی ہے۔ لائبریری کو بنیادی استعمال کے لیے تشریحات کی ضرورت نہیں ہے، لیکن باریک ٹیوننگ کے لیے فراہم کرتی ہے۔ ریفلیکشن کا بنیادی نقصان ابتدا کے دوران کارکردگی میں کمی اور کمپائل وقت پر اصلاح کی عدم صلاحیت ہے، جو Android ایپلیکیشن کے کولڈ اسٹارٹ پر سینکڑوں ماڈلز کو ڈی سیریلائز کرتے وقت خاص طور پر نمایاں ہے۔ اس کے باوجود، Gson اپنی استحکام اور وسیع دستاویزات کی بدولت زیادہ تر منصوبوں کے لیے ایک قابل اعتماد انتخاب بنی ہوئی ہے۔

تاریخ اور ایکو سسٹم میں مقام

Gson کو Google نے 2008 میں جاری کیا تھا اور یہ جلد ہی Android ایپلیکیشنز میں JSON کے لیے حقیقی معیار بن گیا۔ Moshi اور kotlinx.serialization کے آنے سے پہلے، Gson Kotlin منصوبوں کے لیے واحد مقبول انتخاب تھا۔ انضمام میں آسانی — build.gradle میں ایک انحصار شامل کرنا — اور لازمی تشریحات کی عدم موجودگی نے Gson کو ہر سطح کے ڈویلپرز میں مقبول بنا دیا۔

// build.gradle میں Gson شامل کرنا
dependencies {
    implementation 'com.google.code.gson:gson:2.10.1'
}

// بنیادی استعمال
data class User(
    val id: Int,
    val name: String,
    val email: String
)

val gson = Gson()
val user = User(1, "John", "john@test.com")
val json = gson.toJson(user)
println(json) // {"id":1,"name":"John","email":"john@test.com"}

بنیادی سیریلائزیشن کے علاوہ، Gson رویہ ترتیب دینے کے لیے GsonBuilder فراہم کرتی ہے: تاریخ فارمیٹنگ، HTML سے بچنا غیر فعال کرنا، کلید کی صورت اور حسب ضرورت مثالیں۔ GsonBuilder ان اقسام کے لیے حسب ضرورت JsonSerializer اور JsonDeserializer رجسٹر کرنے کی بھی اجازت دیتی ہے جنہیں لائبریری خود بخود نہیں سنبھال سکتی۔ ترتیب میں لچک GsonBuilder کو جدید Android ڈویلپمنٹ میں مخصوص منصوبہ کی ضروریات کے مطابق لائبریری کو ڈھالتے وقت ایک ناگزیر اور مفید ٹول بناتی ہے۔

بنیادی کارروائیاں toJson اور fromJson

toJson ریفلیکشن کے ذریعے فیلڈز کا تجزیہ کرکے Java آبجیکٹ کو JSON سٹرنگ میں تبدیل کرتا ہے۔ پہلے سے طے شدہ طور پر، Gson transient اور static کے علاوہ تمام فیلڈز شامل کرتا ہے۔ یہ طریقہ کسی بھی قسم کی حمایت کرتا ہے: پریمیٹو، آبجیکٹ، کلیکشن اور اری۔ fromJson الٹ کارروائی انجام دیتا ہے، JSON سٹرنگ اور ہدف آبجیکٹ کلاس قبول کرتا ہے، اور بھرے ہوئے فیلڈز کے ساتھ ایک مثال واپس کرتا ہے۔

آبجیکٹ کو JSON میں تبدیل کرنا

سیریلائزیشن کے دوران، Gson نیسٹڈ فیلڈز سمیت تمام آبجیکٹ فیلڈز کو بار بار گھومتا ہے۔ دائرہ کار حوالہ جات StackOverflowError کا باعث بنتے ہیں، لہذا انہیں @Expose تشریح یا حسب ضرورت اڈاپٹر کے ذریعے خارج کرنا ضروری ہے۔ کلیکشن کے لیے، Gson عنصر کی اقسام کو محفوظ رکھتا ہے، لیکن جنیرکس کے ساتھ فہرست کو ڈی سیریلائز کرتے وقت قسم کی معلومات کو محفوظ رکھنے کے لیے TypeToken کی ضرورت ہوتی ہے۔

// نیسٹڈ آبجیکٹ کے ساتھ data class
data class Address(
    val city: String,
    val street: String
)

data class Employee(
    val id: Int,
    val name: String,
    val address: Address
)

val gson = Gson()
val employee = Employee(1, "Alice",
    Address("New York", "5th Ave"))

// JSON میں سیریلائزیشن
val json = gson.toJson(employee)

// JSON سے ڈی سیریلائزیشن
val jsonString = """
{"id":2,"name":"Bob","address":{"city":"London","street":"Baker St"}}
"""
val parsed = gson.fromJson(jsonString, Employee::class.java)

تشریحات اور ترتیب

Gson سیریلائزیشن کے عمل کو منظم کرنے کے لیے تشریحات کا ایک سیٹ فراہم کرتی ہے۔ @SerializedName JSON کلید کا نام بتاتا ہے جو فیلڈ کے نام سے مختلف ہوتا ہے۔ @Expose کنٹرول کرتا ہے کہ آیا فیلڈ سیریلائزیشن میں شامل ہے: GsonBuilder.excludeFieldsWithoutExposeAnnotation() کے ذریعے بنایا گیا Gson صرف @Expose والے فیلڈز پر کارروائی کرے گا۔ @Since اور @Until فیلڈ ورژننگ کو کنٹرول کرتے ہیں۔

@SerializedName اور @Expose

@SerializedName تشریح ناموں کی عدم مطابقت کا مسئلہ حل کرتی ہے: سرور snake_case استعمال کر سکتا ہے جبکہ کوڈ camelCase استعمال کرتا ہے۔ تشریح پسماندہ مطابقت کے لیے ایک قیمت اور اختیاری متبادل قبول کرتی ہے۔ @Expose حساس فیلڈز (پاس ورڈ، ٹوکن) کو @Expose(serialize = false) کے طور پر نشان زد کرکے سیریلائزیشن سے چھپانے کی اجازت دیتی ہے۔ شامل کرنے اور خارج کرنے کے علاوہ، @Expose کو GsonBuilder.excludeFieldsWithoutExposeAnnotation کے ساتھ ملا کر فیلڈز کی سفید فہرست بنائی جا سکتی ہے، جو بہت سے فیلڈز والے آبجیکٹ کو سیریلائز کرتے وقت حملے کی سطح کو کنٹرول کرنے میں مدد کرتی ہے۔

// Gson تشریحات کے ساتھ ماڈل
data class UserResponse(
    @SerializedName("user_id")
    val userId: Int,

    @SerializedName("full_name",
        alternate = [Alternative("name")])
    val fullName: String,

    @Expose(serialize = false)
    val password: String
)

// @Expose فلٹرنگ کے ساتھ Gson
val gson = GsonBuilder()
    .excludeFieldsWithoutExposeAnnotation()
    .setPrettyPrinting()
    .create()

val user = UserResponse(1, "John", "secret123")
println(gson.toJson(user))
// {"user_id":1,"full_name":"John"} — پاس ورڈ خارج کر دیا گیا

جنیرکس کے ساتھ کام کرنا

جنیرکس کا مسئلہ Java اور Kotlin میں کمپائل وقت پر قسم مٹانا ہے۔ جب Gson List<User> کو ڈی سیریلائز کرتا ہے، تو وہ عنصر کی قسم نہیں جانتا اور List<Map<String, Any>> واپس کرتا ہے۔ قسم کی معلومات محفوظ رکھنے کے لیے، Gson TypeToken فراہم کرتی ہے — ایک تجریدی کلاس جو گمنام کلاس کے ذریعے قسم پیرامیٹر کو حاصل کرتی ہے۔ TypeToken کے بغیر، ڈویلپر کو دستی طور پر ہر عنصر کو Map سے ہدف کی قسم میں تبدیل کرنا ہوگا، جس سے بوجھل کوڈ اور کارکردگی میں کمی آتی ہے۔

فہرستوں کے لیے TypeToken

TypeToken قسم مٹانے کے مسئلے کو حل کرتا ہے۔ ڈویلپر مطلوبہ قسم پیرامیٹر کے ساتھ TypeToken کا ایک گمنام ذیلی طبقہ بناتا ہے، اور Gson درست ڈی سیریلائزیشن کے لیے کلاس دستخط سے معلومات استعمال کرتا ہے۔ TypeToken Map، Set اور کسی بھی دوسری پیرامیٹرائزڈ قسم کے ساتھ بھی کام کرتا ہے، بشمول نیسٹڈ جنیرکس۔ خاص طور پر، Map<String, List<User>> کے لیے، مکمل نیسٹڈ قسم کے دستخط کے ساتھ TypeToken درکار ہے، ورنہ Gson List<User> کے بجائے اقدار کو List<Map<String, Any>> کے طور پر ڈی سیریلائز کرتا ہے۔

// فہرست ڈی سیریلائزیشن کے لیے TypeToken
data class Product(
    val id: Int,
    val title: String,
    val price: Double
)

val jsonArray = """
[
    {"id":1,"title":"Phone","price":599.0},
    {"id":2,"title":"Laptop","price":1299.0}
]
"""

val gson = Gson()
val listType = object : TypeToken<List<Product>>() {}
val products: List<Product> =
    gson.fromJson(jsonArray, listType.type)

// حسب ضرورت ڈی سیریلائزر
class LocalDateAdapter :
    JsonDeserializer<LocalDate> {

    override fun deserialize(
        json: JsonElement,
        typeOfT: java.lang.reflect.Type,
        context: JsonDeserializationContext
    ): LocalDate {
        return LocalDate.parse(json.asString)
    }
}

حسب ضرورت سیریلائزیشن منطق کے لیے، Gson JsonSerializer اور JsonDeserializer انٹرفیس سپورٹ کرتی ہے۔ یہ GsonBuilder.registerTypeAdapter() کے ذریعے رجسٹر ہوتے ہیں اور ان اقسام کو سنبھالنے کی اجازت دیتے ہیں جنہیں لائبریری خود بخود سیریلائز نہیں کر سکتی: Java 8 تاریخیں، غیر معیاری اقدار کے ساتھ Enum، یا سورس کوڈ تک رسائی کے بغیر تیسرے فریق کی کلاس۔ اڈاپٹر نافذ کرتے وقت، کارکردگی کی نگرانی کرنا ضروری ہے: حسب ضرورت اڈاپٹر کے اندر ریفلیکشن کو کال کرنا دستی کنٹرول کے فوائد کو ختم کر دیتا ہے، لہذا براہ راست طریقہ اور فیلڈ کالز کو ترجیح دی جاتی ہے۔ Gson ایکو سسٹم میں gson-extras ماڈیول بھی موجود ہے، جو عام اقسام جیسے UUID، Optional اور Joda-Time تاریخ پہیوں کے لیے اڈاپٹر فراہم کرتا ہے۔

GsonBuilder کے ذریعے ترتیب

GsonBuilder سیریلائزیشن کو باریک ٹیون کرنے کے لیے درجنوں طریقے فراہم کرتا ہے۔ setPrettyPrinting پڑھنے کی اہلیت کے لیے آؤٹ پٹ JSON میں انڈینٹیشن اور لائن بریک شامل کرتا ہے۔ disableHtmlEscaping سٹرنگز میں HTML کریکٹر سے بچنے کو غیر فعال کرتا ہے۔ setDateFormat تاریخ کی شکل بتاتا ہے، جو غیر معیاری وقت کی نمائندگی استعمال کرنے والے سرورز کے ساتھ کام کرتے وقت اہم ہے۔ setLenient نرم پارسنگ موڈ کو فعال کرتا ہے، جو کچھ JSON فارمیٹنگ کی غلطیوں کو نظر انداز کرتا ہے۔ addDeserializationExclusionStrategy حسب ضرورت حکمت عملیوں کی بنیاد پر پروگرامی طور پر فیلڈز کو ڈی سیریلائزیشن سے خارج کرنے کی اجازت دیتا ہے۔ ڈیبگنگ کے لیے، لاگنگ کے ساتھ مل کر setPrettyPrinting مفید ہے — یہ JSON جوابات کو لاگز میں پڑھنے کے قابل بناتا ہے اور مماثلت تلاش کرنا آسان بناتا ہے۔

GsonBuilder کی ایک اہم خصوصیت @Since اور @Until تشریحات کے ذریعے فیلڈ ورژننگ کا انتظام ہے۔ ڈویلپر setVersion کے ذریعے آبجیکٹ ورژن بتاتا ہے، اور Gson خود بخود ان کے ورژن تشریح کی بنیاد پر فیلڈز کو شامل یا خارج کرتا ہے۔ یہ API ارتقاء کے دوران مفید ہے جب ایک ہی ماڈل سرور پروٹوکول کے مختلف ورژن کے لیے استعمال ہوتا ہے۔ GsonBuilder خاندان کی اقسام کی عالمی ہینڈلنگ کے لیے TypeAdapterFactory اور پیچیدہ Map کلیدوں کے ساتھ درست کام کے لیے complexMapKeySerialization رجسٹر کرنے کی بھی حمایت کرتا ہے۔