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 बिल्ट-इन java.time के समान आधुनिक API प्रदान करता है, लेकिन 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 आपको Android 4.0+ (API 14+) वाले उपकरणों पर OS अपडेट की प्रतीक्षा किए बिना आधुनिक दिनांक/समय API का उपयोग करने की अनुमति देता है।

Android परियोजना में ThreeTenABP जोड़ना

यह दो चरणों में किया जाता है: build.gradle (एप-स्तर) में निर्भरता जोड़ना और Application क्लास में आरंभ करना। महत्वपूर्ण: ThreeTenABP को कम से कम 21 का compileSdk और कम से कम 4.0 का Gradle संस्करण चाहिए।

निर्भरता निर्भरता अनुभाग में जोड़ी जाती है: 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 vs 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 पुरानी परियोजनाओं के लिए सबसे अच्छा विकल्प बना हुआ है जो AGP को 4.0+ में अपडेट नहीं कर सकतीं, या जहां APK का आकार महत्वपूर्ण है। ThreeTenABP सेटअप में भी आसान है — बस एक निर्भरता और एक पंक्ति का आरंभ। Stack Overflow (2024) के अनुसार, लगभग 30% परियोजनाएं minSdk < 26 के साथ अभी भी desugaring के बजाय ThreeTenABP का उपयोग करती हैं।

उपयोग उदाहरण

पहला उदाहरण ThreeTenABP का उपयोग करके दिनांकों के साथ काम करने का प्रदर्शन करता है। API java.time के समान है, लेकिन इम्पोर्ट org.threeten.bp से आते हैं। यह आपको ऐसा कोड लिखने की अनुमति देता है जो स्थानांतरण के बाद केवल इम्पोर्ट बदलने की आवश्यकता है।

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 पर स्विच कर सकते हैं। स्थानांतरण प्रक्रिया में कई चरण शामिल हैं और पूर्ण परीक्षण की आवश्यकता है।

पहला चरण इम्पोर्ट बदलना है। org.threeten.bp से इम्पोर्ट को 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) हटाएं