ThreeTenABP: mi ez, java.time könyvtár Androidhoz

Mi az a ThreeTenABP?

ThreeTenABP (ThreeTen Android Backport) — Jake Wharton által létrehozott könyvtár a Java 8 dátum/idő API használatára régebbi Android verziókon. Ez egy adapter a ThreeTen-Backport projekthez, amely a java.time-ot (JSR-310) portolja Java 7-re és Android API < 26-ra.

A fő probléma, amit a könyvtár megold: az Android 8-as verzióig (API 26) nem tartalmazta a java.time-ot a standard csomagban. A fejlesztők kényszerültek java.util.Date/Calendar használatára vagy Joda-Time hozzáadására. A ThreeTenABP ugyanazt a modern API-t nyújtja, mint a beépített java.time, de az org.threeten.bp csomagon keresztül.

A GitHub repozitórium (2023) szerint a könyvtár optimalizált Androidra: a tzdata adatok (IANA Time Zone Database) az assets mappában tárolódnak és AssetManageren keresztül töltődnek be, nem classpath-en keresztül, mint asztali gépen. Ez csökkenti az APK méretét és gyorsítja a betöltést.

Utolsó stabil verzió — 1.4.0 (2021. augusztus). A könyvtár támogatási módban van, mivel a desugaring széles körű elterjedésével csökken az iránta való igény, de továbbra is releváns a minimális API < 26 projektek számára.

Miért van szükség java.time backportra?

A java.time megjelenése (Java 8, 2014) előtt a fejlesztők java.util.Date és java.util.Calendar osztályokat használtak. Ezek az osztályok komoly hiányosságokkal rendelkeznek: a Date módosítható, a Calendar nem intuitív konstansokat használ (Calendar.JANUARY = 0), mindkét osztály nem thread-safe és hajlamos a hibára az időzónákkal való munka során.

A Joda-Time volt a de facto standard Java 8 előtt, de alkotója, Stephen Colebourne a java.time-ot tervezte meg hivatalos helyettesítőként, a Joda-Time tapasztalataira építve és annak hiányosságait figyelembe véve. A java.time csomag részévé vált a JDK 8-nak, de az Android csak API 26-tól kapta meg.

ThreeTen-Backport — a java.time portolása Java 7-re, amelyet ugyanaz a szerző (Stephen Colebourne) készített. Tartalmazza az összes fő osztályt: LocalDate, LocalTime, LocalDateTime, ZonedDateTime, Instant, Duration, Period, DateTimeFormatter. A ThreeTenABP ezt a portot adaptálja Androidra, hozzáadva az inicializálást AssetsManageren keresztül és optimalizálást mobil eszközökhöz.

Így a ThreeTenABP lehetővé teszi a modern dátum/idő API használatát Android 4.0+ (API 14+) eszközökön anélkül, hogy meg kellene várni az operációs rendszer frissítését.

ThreeTenABP csatlakoztatása Android projektben

A csatlakoztatás két lépésben történik: függőség hozzáadása a build.gradle-ben (app-level) és inicializálás az Application osztályban. Fontos: A ThreeTenABP compileSdk-t legalább 21 és Gradle verziót legalább 4.0 követel meg.

A függőség a dependencies szekcióban kerül hozzáadásra: implementation „com.jakewharton.threetenabp:threetenabp:1.4.0”. Az 1.4.0 kiadás óta a könyvtár nem frissült, mert stabil és lefedi az összes szükséges esetet.

A hivatalos dokumentáció szerint a könyvtár tartalmazza a tzdata-t az assets mappában. Ha az alkalmazásnak már van assets mappája más fájlokkal, a ThreeTenABP helyesen együtt működik velük. A tzdata mérete körülbelül 200 KB tömörített formában.

// build.gradle (alkalmazás szint)
android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
}

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

ThreeTenABP inicializálása

Mielőtt bármely osztályt használná az org.threeten.bp-ből, inicializálni kell a könyvtárat. Az inicializálás egyszer történik az Application.onCreate()-ban az AndroidThreeTen.init(this) meghívásával.

Az inicializálás betölti a tzdata adatokat az assets-ből és beállítja a rendszerórát. Az init() meghívása nélkül a now() metódusok IllegalStateException kivételt dobnak azzal az üzenettel, hogy a könyvtár nincs inicializálva.

Tesztekhez használható az AndroidThreeTen.init(applicationContext, zoneId) — túlterhelés az időzóna explicit megadásával. Ez hasznos a tesztek kiszámítható viselkedéséhez. Ha csak alap inicializálásra van szükség tzdata nélkül — használja a AndroidThreeTen.initWithoutFiles(context) függvényt.

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

// Használat inicializálás után
val today = LocalDate.now()
val now = LocalDateTime.now()

Milyen osztályok érhetők el?

A ThreeTenABP biztosítja az összes fő java.time osztályt, de az org.threeten.bp csomagban. Az API gyakorlatilag azonos az eredeti java.time-val, ami megkönnyíti a migrációt API 26+-ra való áttéréskor.

Fő osztályok:

• LocalDate — dátum idő és időzóna nélkül
• LocalTime — idő dátum és időzóna nélkül
• LocalDateTime — dátum és idő időzóna nélkül
• ZonedDateTime — dátum és idő időzónával
• OffsetDateTime — dátum és idő rögzített eltolással
• OffsetTime — idő rögzített eltolással
• Instant — időpillanat UTC-ben
• Duration — time-based időtartam
• Period — date-based periódus
• DateTimeFormatter — formázás és elemzés
• ZoneId / ZoneOffset — időzónák

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

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

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

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

// build.gradle — ThreeTenABP cseréje desugaringre
android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
    }
}

dependencies {
    // Távolítás: implementation „com.jakewharton.threetenabp:threetenabp:1.4.0”
    // Hozzáadás:
    "coreLibraryDesugaring"("com.android.tools:desugar_jdk_libs:2.1.4")
}

// AndroidThreeTen.init(this) eltávolítása az Application-ből