WorkManager — mi ez, API és feladatütemezés

Hogyan működik a WorkManager?

A WorkManager architektúrája három alaposztály köré épül: Worker, WorkRequest és WorkManager. A Worker tartalmazza a feladat logikáját, a WorkRequest leírja a végrehajtási paramétereket, a WorkManager pedig kezeli a várakozási sort és az ütemezést. A könyvtár egy belső Room-adatbázist használ az összes feladat állapotának tárolására.

Worker és WorkRequest

Worker — egy absztrakt osztály egyetlen doWork metódussal, amelyet egy háttérszálon hívnak meg. A metódus ListenableWorker.Result-ot ad vissza — SUCCESS, FAILURE vagy RETRY. A WorkRequest összeköti a Worker-t a paraméterekkel: időtúllépés, címke, kezdeti késleltetés és korlátozások.

class SyncWorker(
    context: Context,
    params: WorkerParameters
) : Worker(context, params) {

    override fun doWork(): Result {
        return try {
            val api = RetrofitClient.api
            val response = api.syncData()
            Result.success()
        } catch (e: Exception) {
            Result.retry()
        }
    }
}

Ütemezés a WorkManager-en keresztül

WorkManager egységesen ütemezi a feladatokat az Android verziójától függetlenül. Az enqueue hívásakor a könyvtár elmenti a feladatot a Room-ba, kiértékeli az aktuális körülményeket, és kiválasztja az optimális indítási időt. A motorháztető alatt JobScheduler, AlarmManager vagy saját ütemező használható — a fejlesztőnek ezzel nem kell foglalkoznia.

val syncRequest = OneTimeWorkRequestBuilder<SyncWorker>()
    .setInitialDelay(15, TimeUnit.MINUTES)
    .addTag("sync")
    .build()

WorkManager.getInstance(context)
    .enqueue(syncRequest)

WorkRequest típusok

WorkManager két típusú végrehajtási kérést támogat: egyszeri és ismétlődő. A típus kiválasztása a forgatókönyvtől függ: a feladatot egyszer kell végrehajtani, vagy ismétlődően egy adott időközönként.

OneTimeWorkRequest

OneTimeWorkRequest olyan feladatokhoz készült, amelyeket egyszer kell végrehajtani. Ez lehet napló küldése, adatok szinkronizálása engedélyezés után, konfiguráció betöltése az első indításkor. A késleltetés a setInitialDelay segítségével, a korlátozások a setConstraints segítségével állíthatók be.

PeriodicWorkRequest

PeriodicWorkRequest ismétlődő feladatokhoz alkalmas, minimum 15 perces időközzel. A könyvtár garantálja, hogy a végrehajtások közötti időköz nem lesz rövidebb a megadottnál, de az eszköz korlátainak függvényében hosszabb lehet. 15 percnél gyakoribb feladatokhoz használjon Handlert vagy Timert egy Foreground Service-ben.

Korlátozások beállítása és feladatkötések

Korlátozások (constraints) a WorkManagerben lehetővé teszik a feladat indításának feltételeit: hálózati kapcsolat (NetworkType), akkumulátorszint (batteryNotLow), tárhely állapota (StorageNotLow) és tétlen mód (DeviceIdle). A feladat nem indul el, amíg az összes korlátozás nem teljesül.

val constraints = Constraints.Builder()
    .setRequiredNetworkType(NetworkType.CONNECTED)
    .setRequiresCharging(true)
    .setRequiresBatteryNotLow(true)
    .build()

val request = OneTimeWorkRequestBuilder<ImageUploadWorker>()
    .setConstraints(constraints)
    .build()

Kötések (chaining) lehetővé teszik a feladatok egymás utáni vagy párhuzamos végrehajtásának megszervezését. A beginWith elindít egy láncot, a then hozzáadja a következő Worker-t, amely az előző sikeres befejezése után fut le. Párhuzamos végrehajtáshoz használja a workManager.enqueue(listOf(request1, request2)) parancsot.

WorkManager.getInstance(context)
    .beginWith(compressWorker)
    .then(uploadWorker)
    .then(cleanupWorker)
    .enqueue()
    // compress -> upload -> cleanup egymás után

Migráció JobScheduler-ről WorkManager-re

JobScheduler az Android 5-ben (API 21) került bevezetésre rendszerszolgáltatásként a háttérfeladatok ütemezésére. A WorkManager váltotta fel, keresztplatformos API-val, automatikus migrációval és további képességekkel: láncok, végrehajtási garancia, címkék, állapotfigyelés LiveData-n keresztül.

A JobScheduler-ről WorkManager-re való migráció során a JobService-t Worker-re kell alakítani, a JobInfo-t WorkRequest-re cserélni, a Context.getSystemService-t pedig WorkManager API-ra. A WorkManager automatikusan megoldja a kompatibilitási problémákat, és helyesebben kezeli a Doze Mode-ot, mint a JobScheduler kézi implementációja. Migrációs lépések: 1) hozzon létre egy Worker osztályt, 2) építsen fel egy WorkRequest-ot ugyanazokkal a feltételekkel, 3) távolítsa el a JobService-t és a JobInfo-t a kódból és a manifestből.

UniqueWork egyedi feladatokhoz

A WorkManager támogatja az egyedi feladatok koncepcióját az ExistingWorkPolicy segítségével. Ha egy adott nevű feladat már létezik, a szabályzat határozza meg a viselkedést: KEEP (ne hozzon létre újat), REPLACE (cserélje le a meglévőt), APPEND (adja hozzá a lánc végéhez) és APPEND_OR_REPLACE. A UniqueWorkRequest olyan feladatokhoz praktikus, amelyek nem duplikálódhatnak: adatbázis-szinkronizálás, konfiguráció betöltése, analitikai csomag küldése.

WorkManager.getInstance(context)
    .enqueueUniqueWork(
        "sync_data",
        ExistingWorkPolicy.KEEP,
        syncRequest
    )

Előrehaladás és köztes eredmények kezelése

A CoroutineWorker támogatja a setProgress mechanizmust, amely lehetővé teszi a feladat köztes eredményeinek átadását. Ez hosszú műveleteknél hasznos: nagy fájl betöltése, képek kötegelt feldolgozása, adatbázis migráció. Az UI feliratkozhat a frissítésekre a getWorkInfosByTagLiveData segítségével, és valós időben megjelenítheti az előrehaladást. Elérhető a ForegroundInfo metódus is a Worker Foreground Service-ként történő elindításához értesítéssel, ha a feladatnak láthatónak kell lennie a felhasználó számára.

class ProgressWorker(
    context: Context,
    params: WorkerParameters
) : CoroutineWorker(context, params) {

    override suspend fun doWork(): Result {
        val total = 100
        for (i in 1..total) {
            setProgress(
                workDataOf("progress" to i)
            )
        }
        return Result.success()
    }
}

InputData és OutputData adatátvitelhez

A WorkManager támogatja az adatátvitelt a Worker-ek között InputData és OutputData segítségével. Az InputData a WorkRequest felépítése során jön létre a Data.Builder segítségével, és az inputData-n keresztül kerül a Worker-be. A végrehajtás után a Worker OutputData-t hoz létre a workDataOf vagy a Data.Builder segítségével, és a Result.success(outputData) értékkel együtt adja vissza. A lánc következő Worker-e az előző outputData-ját kapja meg inputData-ként. Az adatok kulcs-érték formátumban tárolódnak, alapvető típusok támogatásával: String, Int, Long, Boolean, Double. A Data maximális mérete 10 KB.

A gyakorlatban sok projekt WorkManager-t használ egyetlen háttérfeladat-ütemezőként. A Google azt ajánlja, hogy az összes meglévő JobService-t migrálják WorkManager-re, különösen azokban az alkalmazásokban, amelyek Android 4.4-et (API 19) és alacsonyabb verziókat támogatnak, ahol a JobScheduler nem érhető el, és a WorkManager tartalék mechanizmust használ az AlarmManager és BroadcastReceiver segítségével. Teszteléshez a WorkManager TestListenableWorkerBuilder-t és TestWorkerBuilder-t biztosít, amelyek lehetővé teszik a Worker-ek JUnit tesztekben történő tesztelését valódi ütemező nélkül.