ThreeTenABP: یہ کیا ہے، Android کے لیے java.time لائبریری

ThreeTenABP کیا ہے؟

ThreeTenABP (ThreeTen Android Backport) Jake Wharton کی بنائی ہوئی ایک لائبریری ہے جو پرانے Android ورژنز پر Java 8 کی تاریخ/وقت API استعمال کرنے کی اجازت دیتی ہے۔ یہ ThreeTen-Backport پروجیکٹ کے لیے ایک اڈاپٹر ہے، جو java.time (JSR-310) کو Java 7 اور Android API < 26 پر پورٹ کرتا ہے۔

لائبریری جس اہم مسئلے کو حل کرتی ہے: Android ورژن 8 (API 26) سے پہلے java.time معیاری تقسیم میں شامل نہیں تھا۔ ڈویلپرز java.util.Date/Calendar استعمال کرنے یا Joda-Time شامل کرنے پر مجبور تھے۔ ThreeTenABP وہی جدید API فراہم کرتا ہے جو بلٹ ان java.time میں ہے، لیکن org.threeten.bp پیکیج کے ذریعے۔

GitHub ذخیرہ (2023) کے مطابق، لائبریری Android کے لیے بہتر بنائی گئی ہے: tzdata (IANA Time Zone Database) assets میں محفوظ ہے اور ڈیسک ٹاپ کی طرح classpath کے بجائے AssetManager کے ذریعے لوڈ ہوتی ہے۔ اس سے APK کا سائز کم ہوتا ہے اور لوڈنگ تیز ہوتی ہے۔

تازہ ترین مستحکم ورژن 1.4.0 (اگست 2021) ہے۔ لائبریری دیکھ بھال کے موڈ میں ہے، کیونکہ desugaring کے وسیع پیمانے پر اپنانے کے ساتھ اس کی ضرورت کم ہو رہی ہے، لیکن یہ کم از کم API < 26 والے پروجیکٹس کے لیے متعلقہ ہے۔

java.time backport کیوں ضروری ہے؟

Java 8 (2014) میں java.time متعارف ہونے سے پہلے، ڈویلپرز java.util.Date اور java.util.Calendar استعمال کرتے تھے۔ ان کلاسز میں سنگین خامیاں ہیں: Date قابل تبدیلی ہے، Calendar غیر وجدانی مستقل استعمال کرتا ہے (Calendar.JANUARY = 0)، دونوں کلاسیں تھریڈ سیف نہیں ہیں اور ٹائم زون کے ساتھ کام کرتے وقت غلطیوں کا شکار ہیں۔

Joda-Time Java 8 سے پہلے حقیقی معیار تھا، لیکن اس کے تخلیق کار Stephen Colebourne نے Joda-Time کے تجربے اور اس کی خامیوں کو دور کرتے ہوئے java.time کو سرکاری متبادل کے طور پر ڈیزائن کیا۔ java.time پیکیج JDK 8 میں شامل تھا، لیکن Android کو یہ API 26 تک نہیں ملا۔

ThreeTen-Backport java.time کا Java 7 پر ایک پورٹ ہے، جو اسی مصنف (Stephen Colebourne) نے بنایا ہے۔ اس میں تمام اہم کلاسیں شامل ہیں: LocalDate، LocalTime، LocalDateTime، ZonedDateTime، Instant، Duration، Period، DateTimeFormatter۔ ThreeTenABP اس پورٹ کو Android کے لیے ڈھالتا ہے، AssetsManager کے ذریعے ابتدا اور موبائل آلات کے لیے اصلاح شامل کرتا ہے۔

اس طرح، ThreeTenABP آپ کو OS اپ ڈیٹ کا انتظار کیے بغیر Android 4.0+ (API 14+) والے آلات پر جدید تاریخ/وقت API استعمال کرنے کی اجازت دیتا ہے۔

Android پروجیکٹ میں ThreeTenABP شامل کرنا

شامل کرنا دو مراحل میں کیا جاتا ہے: build.gradle (ایپ لیول) میں انحصار شامل کرنا اور Application کلاس میں ابتدا کرنا۔ اہم: ThreeTenABP کو کم از کم 21 کا compileSdk اور کم از کم 4.0 کا Gradle ورژن درکار ہے۔

انحصار dependencies سیکشن میں شامل کیا جاتا ہے: implementation "com.jakewharton.threetenabp:threetenabp:1.4.0"۔ 1.4.0 کی ریلیز کے بعد سے، لائبریری اپ ڈیٹ نہیں ہوئی ہے، کیونکہ یہ مستحکم ہے اور تمام ضروری معاملات کا احاطہ کرتی ہے۔

سرکاری دستاویزات کے مطابق، لائبریری assets میں tzdata شامل کرتی ہے۔ اگر ایپ میں پہلے سے دوسری فائلوں کے ساتھ assets فولڈر موجود ہے، تو ThreeTenABP ان کے ساتھ صحیح طور پر موجود رہتا ہے۔ tzdata کا سائز کمپریسڈ ہونے پر تقریباً 200 KB ہے۔

// build.gradle (ایپ لیول)
android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
}

dependencies {
    implementation "com.jakewharton.threetenabp:threetenabp:1.4.0"
}

ThreeTenABP کی ابتدا

org.threeten.bp سے کسی بھی کلاس کو استعمال کرنے سے پہلے، لائبریری کو ابتداء کرنا ضروری ہے۔ ابتدا Application.onCreate() میں AndroidThreeTen.init(this) کال کر کے ایک بار کی جاتی ہے۔

ابتداء assets سے tzdata ڈیٹا لوڈ کرتی ہے اور سسٹم کلاک ترتیب دیتی ہے۔ init() کال کیے بغیر، now() میتھڈز IllegalStateException پھینکیں گی جس میں پیغام ہوگا کہ لائبریری ابتدا نہیں ہوئی۔

ٹیسٹ کے لیے، آپ AndroidThreeTen.init(applicationContext, zoneId) استعمال کر سکتے ہیں — واضح ٹائم زون وضاحت کے ساتھ ایک اوورلوڈ۔ یہ ٹیسٹ میں پیش قیاسی رویے کے لیے مفید ہے۔ اگر tzdata کے بغیر صرف بنیادی ابتدا کی ضرورت ہو تو AndroidThreeTen.initWithoutFiles(context) استعمال کریں۔

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        AndroidThreeTen.init(this)
    }
}

// ابتداء کے بعد استعمال
val today = LocalDate.now()
val now = LocalDateTime.now()

کون سی کلاسیں دستیاب ہیں؟

ThreeTenABP java.time کی تمام اہم کلاسیں org.threeten.bp پیکیج میں فراہم کرتا ہے۔ API اصل java.time سے تقریباً ایک جیسی ہے، جو API 26+ میں منتقلی کو آسان بناتی ہے۔

اہم کلاسیں:

• LocalDate — وقت اور ٹائم زون کے بغیر تاریخ
• LocalTime — تاریخ اور ٹائم زون کے بغیر وقت
• LocalDateTime — ٹائم زون کے بغیر تاریخ اور وقت
• ZonedDateTime — ٹائم زون کے ساتھ تاریخ اور وقت
• OffsetDateTime — مقررہ آفسیٹ کے ساتھ تاریخ اور وقت
• OffsetTime — مقررہ آفسیٹ کے ساتھ وقت
• Instant — UTC میں وقت کا لمحہ
• Duration — وقت پر مبنی مدت
• Period — تاریخ پر مبنی مدت
• DateTimeFormatter — فارمیٹنگ اور پارسنگ
• ZoneId / ZoneOffset — ٹائم زونز

معاون کلاسیں بھی سپورٹ ہیں: Clock، DayOfWeek، Month، Year، YearMonth، MonthDay۔ ٹائم زونز لائبریری کے ساتھ شامل ہیں (IANA tzdata)۔ ThreeTenABP 1.4.0 میں tzdata ورژن 2021a کے مطابق ہے۔

ThreeTenABP بمقابلہ desugaring

Android Gradle Plugin 4.0 (2020) اور desugar_jdk_libs سے شروع کرتے ہوئے، ڈویلپرز کو coreLibraryDesugaring کے ذریعے Android کے تمام ورژنز پر java.time استعمال کرنے کی صلاحیت ملی۔ Desugaring بائٹ کوڈ کو تبدیل کرتا ہے تاکہ java.time کالز اضافی لائبریریوں کے بغیر پرانی API پر کام کریں۔

Desugaring کے فوائد: اصل java.time پیکیج استعمال کرتا ہے (org.threeten.bp نہیں)، کسی ابتدا کی ضرورت نہیں، Android Studio کے ساتھ مکمل انضمام۔ نقصانات: AGP 4.0+ درکار ہے، بلڈ ٹائم بڑھاتا ہے، APK سائز 2-3 MB بڑھ سکتا ہے۔

ThreeTenABP ان legacy پروجیکٹس کے لیے بہترین انتخاب ہے جو AGP کو 4.0+ اپ ڈیٹ نہیں کر سکتے، یا جہاں APK سائز اہم ہے۔ ThreeTenABP سیٹ اپ کرنا بھی آسان ہے — صرف ایک انحصار اور ابتدا کی ایک لائن۔ Stack Overflow (2024) کے مطابق، minSdk < 26 والے تقریباً 30% پروجیکٹس اب بھی desugaring کے بجائے ThreeTenABP استعمال کرتے ہیں۔

استعمال کی مثالیں

پہلی مثال ThreeTenABP استعمال کرتے ہوئے تاریخوں کے ساتھ کام دکھاتی ہے۔ API java.time جیسی ہے، لیکن imports org.threeten.bp سے آتے ہیں۔ یہ آپ کو ایسا کوڈ لکھنے کی اجازت دیتا ہے جسے منتقلی کے بعد صرف imports تبدیل کرنے کی ضرورت ہو۔

import org.threeten.bp.LocalDate
import org.threeten.bp.LocalTime
import org.threeten.bp.Duration

fun isWeekend(date: LocalDate): Boolean {
    val dayOfWeek = date.getDayOfWeek()
    return dayOfWeek == DayOfWeek.SATURDAY ||
           dayOfWeek == DayOfWeek.SUNDAY
}

fun timeBetween(
    start: LocalTime, end: LocalTime
): Duration {
    return Duration.between(start, end)
}

دوسری مثال تاریخ فارمیٹنگ دکھاتی ہے۔ org.threeten.bp سے DateTimeFormatter java.time کی طرح کام کرتا ہے۔

import org.threeten.bp.LocalDateTime
import org.threeten.bp.format.DateTimeFormatter

fun formatTimestamp(dateTime: LocalDateTime): String {
    val formatter = DateTimeFormatter.ofPattern("dd.MM.yyyy HH:mm")
    return dateTime.format(formatter)
}

تیسری مثال ThreeTenABP میں ZonedDateTime کے ساتھ کام اور ٹائم زونز کے درمیان تبدیلی دکھاتی ہے۔

import org.threeten.bp.ZonedDateTime
import org.threeten.bp.ZoneId

fun convertTimeZone(
    time: ZonedDateTime,
    targetZone: ZoneId
): ZonedDateTime {
    return time.withZoneSameInstant(targetZone)
}

ThreeTenABP سے بلٹ ان java.time میں منتقلی

minSdk کو 26 تک بڑھانے پر، آپ ThreeTenABP کو ہٹا کر بلٹ ان java.time پر جا سکتے ہیں۔ منتقلی کے عمل میں کئی مراحل شامل ہیں اور مکمل جانچ کی ضرورت ہے۔

پہلا مرحلہ imports کو تبدیل کرنا ہے۔ org.threeten.bp سے imports کو java.time میں تبدیل کیا جاتا ہے۔ زیادہ تر معاملات میں، کلاس کے نام مماثل ہیں: LocalDate → java.time.LocalDate، ZonedDateTime → java.time.ZonedDateTime۔ استثنا DateTimeFormatter ہے — ThreeTenABP میں یہ org.threeten.bp.format میں ہے، java.time میں یہ java.time.format میں ہے۔

دوسرا مرحلہ ابتدا کو ہٹانا ہے۔ لائن AndroidThreeTen.init(this) کی مزید ضرورت نہیں، کیونکہ java.time Android SDK میں بلٹ ان ہے۔ Application.onCreate() سے کال اور build.gradle سے انحصار ہٹا دیں۔

تیسرا مرحلہ انحصار کو desugaring سے تبدیل کرنا ہے، اگر minSdk 26 سے نیچے رہتا ہے۔ compileOptions میں isCoreLibraryDesugaringEnabled = true اور desugar_jdk_libs انحصار شامل کریں۔ یہ ThreeTenABP کے بغیر پرانی API پر java.time کے کام کو یقینی بنائے گا۔ Google I/O (2023) کے مطابق، desugaring نئے پروجیکٹس کے لیے ترجیحی طریقہ ہے۔

// build.gradle — ThreeTenABP کو desugaring سے تبدیل کریں
android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
    }
}

dependencies {
    // ہٹائیں: implementation "com.jakewharton.threetenabp:threetenabp:1.4.0"
    // شامل کریں:
    "coreLibraryDesugaring"("com.android.tools:desugar_jdk_libs:2.1.4")
}

// Application سے AndroidThreeTen.init(this) ہٹائیں