ThreeTenABP: ano ito, library ng java.time para sa Android

Ano ang ThreeTenABP?

ThreeTenABP (ThreeTen Android Backport) — library na ginawa ni Jake Wharton para gamitin ang Java 8 date/time API sa mga lumang bersyon ng Android. Ito ay adapter para sa proyektong ThreeTen-Backport, na nagpo-port ng java.time (JSR-310) sa Java 7 at Android API < 26.

Ang pangunahing problema na nilulutas ng library: Ang Android hanggang bersyon 8 (API 26) ay hindi kasama ang java.time sa standard na package. Ang mga developer ay napilitang gumamit ng java.util.Date/Calendar o magdagdag ng Joda-Time. Ang ThreeTenABP ay nagbibigay ng parehong modernong API tulad ng built-in java.time, ngunit sa pamamagitan ng package na org.threeten.bp.

Ayon sa GitHub repository (2023), ang library ay optimisado para sa Android: ang data ng tzdata (IANA Time Zone Database) ay nakaimbak sa assets at nilo-load sa pamamagitan ng AssetManager, hindi sa pamamagitan ng classpath tulad sa desktop. Binabawasan nito ang laki ng APK at pinapabilis ang pag-load.

Huling stable na bersyon — 1.4.0 (Agosto 2021). Ang library ay nasa mode ng suporta, dahil sa malawakang pagkalat ng desugaring bumababa ang pangangailangan dito, ngunit nananatiling mahalaga para sa mga project na may minimum na API < 26.

Bakit kailangan ang backport ng java.time?

Bago dumating ang java.time sa Java 8 (2014), ang mga developer ay gumagamit ng java.util.Date at java.util.Calendar. Ang mga klaseng ito ay may malubhang pagkukulang: ang Date ay mutable, ang Calendar ay gumagamit ng hindi intuitive na constants (Calendar.JANUARY = 0), ang parehong klase ay hindi thread-safe at madaling magkaroon ng error kapag nagtatrabaho sa mga timezone.

Ang Joda-Time ay ang de facto standard bago ang Java 8, ngunit ang gumawa nito na si Stephen Colebourne ay nagdisenyo ng java.time bilang opisyal na kapalit, batay sa karanasan ng Joda-Time at isinasaalang-alang ang mga pagkukulang nito. Ang package na java.time ay naging bahagi ng JDK 8, ngunit hindi ito nakuha ng Android hanggang API 26.

ThreeTen-Backport — port ng java.time sa Java 7, na ginawa ng parehong may-akda (Stephen Colebourne). Kasama nito ang lahat ng pangunahing klase: LocalDate, LocalTime, LocalDateTime, ZonedDateTime, Instant, Duration, Period, DateTimeFormatter. Iniakma ng ThreeTenABP ang port na ito para sa Android, na nagdaragdag ng initialisasyon sa pamamagitan ng AssetsManager at optimisasyon para sa mga mobile device.

Kaya, pinapayagan ng ThreeTenABP ang paggamit ng modernong API ng petsa/oras sa mga device na may Android 4.0+ (API 14+) nang hindi naghihintay ng update sa OS.

Pagkonekta ng ThreeTenABP sa Android project

Ang pagkonekta ay ginagawa sa dalawang hakbang: pagdaragdag ng dependency sa build.gradle (app-level) at initialisasyon sa Application class. Mahalaga: Ang ThreeTenABP ay nangangailangan ng compileSdk na hindi bababa sa 21 at Gradle na bersyon na hindi bababa sa 4.0.

Ang dependency ay idinaragdag sa seksyong dependencies: implementation “com.jakewharton.threetenabp:threetenabp:1.4.0”. Mula noong release 1.4.0, hindi na na-update ang library dahil stable ito at sumasaklaw sa lahat ng kinakailangang kaso.

Ayon sa opisyal na dokumentasyon, kasama sa library ang tzdata sa assets. Kung ang app ay mayroon nang folder ng assets na may iba pang mga file, ang ThreeTenABP ay maaaring makisama nang tama sa kanila. Ang laki ng tzdata ay mga 200 KB sa naka-compress na anyo.

// build.gradle (antas ng app)
android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
}

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

Initialisasyon ng ThreeTenABP

Bago gamitin ang anumang klase mula sa org.threeten.bp, kailangang i-initialisa ang library. Ang initialisasyon ay ginagawa nang isang beses sa Application.onCreate() sa pamamagitan ng pagtawag sa AndroidThreeTen.init(this).

Ang initialisasyon ay naglo-load ng tzdata mula sa assets at nagko-configure ng system clock. Kung walang tawag sa init(), ang mga method na now() ay magtapon ng IllegalStateException na may mensahe na hindi na-initialisa ang library.

Para sa mga test, maaaring gamitin ang AndroidThreeTen.init(applicationContext, zoneId) — overload na may eksplisitong pagtukoy ng timezone. Ito ay kapaki-pakinabang para sa predictable na behavior ng mga test. Kung kailangan lang ng basic na initialisasyon na walang tzdata — gamitin ang AndroidThreeTen.initWithoutFiles(context).

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

// Paggamit pagkatapos ng initialisasyon
val today = LocalDate.now()
val now = LocalDateTime.now()

Anong mga klase ang available?

Ang ThreeTenABP ay nagbibigay ng lahat ng pangunahing klase ng java.time, ngunit sa package na org.threeten.bp. Halos magkapareho ang API sa orihinal na java.time, na nagpapadali ng migrasyon kapag lumipat sa API 26+.

Mga pangunahing klase:

• LocalDate — petsa na walang oras at timezone
• LocalTime — oras na walang petsa at timezone
• LocalDateTime — petsa at oras na walang timezone
• ZonedDateTime — petsa at oras na may timezone
• OffsetDateTime — petsa at oras na may fixed offset
• OffsetTime — oras na may fixed offset
• Instant — sandali ng oras sa UTC
• Duration — time-based na tagal
• Period — date-based na panahon
• DateTimeFormatter — pag-format at pag-parse
• ZoneId / ZoneOffset — mga timezone

Ang mga auxiliary class ay sinusuportahan din: Clock, DayOfWeek, Month, Year, YearMonth, MonthDay. Ang mga timezone ay kasama ng library (IANA tzdata). Ang bersyon ng tzdata sa ThreeTenABP 1.4.0 ay tumutugma sa 2021a.

ThreeTenABP vs desugaring

Simula sa Android Gradle Plugin 4.0 (2020) at desugar_jdk_libs, nakuha ng mga developer ang kakayahang gumamit ng java.time sa lahat ng bersyon ng Android sa pamamagitan ng coreLibraryDesugaring. Binabago ng desugaring ang bytecode upang ang mga tawag sa java.time ay gumana sa lumang API nang walang karagdagang library.

Mga bentahe ng desugaring: ginagamit ang orihinal na java.time package (hindi org.threeten.bp), hindi kailangan ng initialisasyon, buong integrasyon sa Android Studio. Mga disadvantages: nangangailangan ng AGP 4.0+, nagdaragdag ng oras ng build, maaaring tumaas ang laki ng APK ng 2-3 MB.

Ang ThreeTenABP ay nananatiling pinakamahusay na pagpipilian para sa mga legacy project na hindi maaaring i-update ang AGP sa 4.0+, o kung saan kritikal ang laki ng APK. Mas simple din ang ThreeTenABP sa pag-setup — isang dependency at isang linya ng initialisasyon ay sapat na. Ayon sa Stack Overflow (2024), mga 30% ng mga project na may minSdk < 26 ay gumagamit pa rin ng ThreeTenABP sa halip na desugaring.

Mga halimbawa ng paggamit

Unang halimbawa — pagtatrabaho sa mga petsa sa pamamagitan ng ThreeTenABP. Ang API ay magkapareho sa java.time, ngunit ang mga import ay nagmumula sa org.threeten.bp. Ito ay nagpapahintulot sa pagsulat ng code na pagkatapos ng migrasyon ay nangangailangan lamang ng pagpapalit ng mga import.

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)
}

Pangalawang halimbawa — pag-format ng petsa. Ang DateTimeFormatter mula sa org.threeten.bp ay gumagana tulad ng sa 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)
}

Pangatlong halimbawa — pagtatrabaho sa ZonedDateTime at conversion sa pagitan ng mga timezone sa ThreeTenABP.

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

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

Migrasyon mula ThreeTenABP patungong built-in java.time

Kapag itinaas ang minSdk sa 26, maaaring iwanan ang ThreeTenABP at lumipat sa built-in java.time. Ang proseso ng migrasyon ay may kasamang ilang hakbang at nangangailangan ng maingat na pagsubok.

Unang hakbang — pagpapalit ng mga import. Ang mga import ng org.threeten.bp ay pinapalitan ng java.time. Sa karamihan ng mga kaso, magkatugma ang mga pangalan ng klase: LocalDate → java.time.LocalDate, ZonedDateTime → java.time.ZonedDateTime. Ang exception ay DateTimeFormatter — sa ThreeTenABP ito ay nasa org.threeten.bp.format, sa java.time — nasa java.time.format.

Pangalawang hakbang — pag-alis ng initialisasyon. Ang linya na AndroidThreeTen.init(this) ay hindi na kailangan, dahil ang java.time ay naka-built na sa Android SDK. Alisin ang tawag mula sa Application.onCreate() at ang dependency mula sa build.gradle.

Pangatlong hakbang — pagpapalit ng dependency sa desugaring, kung mananatili ang minSdk sa ibaba 26. Idagdag ang isCoreLibraryDesugaringEnabled = true sa compileOptions at ang dependency na desugar_jdk_libs. Ito ay titiyak na gagana ang java.time sa lumang API nang walang ThreeTenABP. Ayon sa Google I/O (2023), ang desugaring ay ang mas gustong paraan para sa mga bagong project.

// build.gradle — palitan ang ThreeTenABP ng desugaring
android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
    }
}

dependencies {
    // Tanggalin: implementation “com.jakewharton.threetenabp:threetenabp:1.4.0”
    // Idagdag:
    "coreLibraryDesugaring"("com.android.tools:desugar_jdk_libs:2.1.4")
}

// Tanggalin ang AndroidThreeTen.init(this) mula sa Application