WorkManager — co to je, API a plánování úkolů

Jak funguje WorkManager?

Architektura WorkManageru je postavena kolem tří základních tříd: Worker, WorkRequest a WorkManager. Worker obsahuje logiku úlohy, WorkRequest popisuje parametry provedení a WorkManager spravuje frontu a plánování. Knihovna používá interní databázi Room pro ukládání stavu všech úloh.

Worker a WorkRequest

Worker — je abstraktní třída s jedinou metodou doWork, která je volána na vlákně na pozadí. Metoda vrací ListenableWorker.Result — SUCCESS, FAILURE nebo RETRY. WorkRequest propojuje Worker s parametry: časový limit, značka, počáteční zpoždění a omezení.

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

Plánování prostřednictvím WorkManageru

WorkManager plánuje úlohy jednotně bez ohledu na verzi Androidu. Při volání enqueue knihovna uloží úlohu do Room, vyhodnotí aktuální podmínky a vybere optimální čas spuštění. Pod kapotou může být použit JobScheduler, AlarmManager nebo vlastní plánovač — vývojář o tom nemusí přemýšlet.

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

WorkManager.getInstance(context)
    .enqueue(syncRequest)

Typy WorkRequest

WorkManager podporuje dva typy požadavků na provedení: jednorázové a periodické. Výběr typu závisí na scénáři: úloha má být provedena jednou nebo opakovaně v daném intervalu.

OneTimeWorkRequest

OneTimeWorkRequest je určen pro úlohy, které mají být provedeny jednou. Může to být odeslání logu, synchronizace dat po autorizaci, načtení konfigurace při prvním spuštění. Zpoždění se nastavuje pomocí setInitialDelay a omezení pomocí setConstraints.

PeriodicWorkRequest

PeriodicWorkRequest je vhodný pro opakující se úlohy s minimálním intervalem 15 minut. Knihovna garantuje, že interval mezi spuštěními nebude kratší než uvedený, ale může být delší kvůli omezením zařízení. Pro úlohy s frekvencí kratší než 15 minut použijte Handler nebo Timer ve Foreground Service.

Nastavení omezení a řetězce úloh

Omezení (constraints) ve WorkManageru umožňují nastavit podmínky, za kterých může být úloha spuštěna: připojení k síti (NetworkType), úroveň baterie (batteryNotLow), stav úložiště (StorageNotLow) a režim nečinnosti (DeviceIdle). Úloha se nespustí, dokud nejsou splněna všechna omezení.

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

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

Řetězce (chaining) umožňují organizovat sekvenční nebo paralelní provádění úloh. beginWith spouští řetězec, then přidává další Worker, který se provede po úspěšném dokončení předchozího. Pro paralelní provádění použijte workManager.enqueue(listOf(request1, request2)).

WorkManager.getInstance(context)
    .beginWith(compressWorker)
    .then(uploadWorker)
    .then(cleanupWorker)
    .enqueue()
    // compress -> upload -> cleanup postupně

Migrace z JobScheduler na WorkManager

JobScheduler byl zaveden v Androidu 5 (API 21) jako systémová služba pro plánování úloh na pozadí. WorkManager přišel jako náhrada s multiplatformním API, automatickou migrací a dalšími možnostmi: řetězce, záruka provedení, značky, sledování stavu pomocí LiveData.

Při migraci z JobScheduler na WorkManager bude třeba převést JobService na Worker, nahradit JobInfo za WorkRequest a Context.getSystemService za API WorkManageru. WorkManager automaticky řeší problémy s kompatibilitou a zpracovává Doze Mode správněji než ruční implementace JobScheduleru. Kroky migrace: 1) vytvořte třídu Worker, 2) sestavte WorkRequest se stejnými podmínkami, 3) odstraňte JobService a JobInfo z kódu a manifestu.

UniqueWork pro jedinečné úlohy

WorkManager podporuje koncept jedinečných úloh prostřednictvím ExistingWorkPolicy. Pokud úloha se zadaným názvem již existuje, politika určuje chování: KEEP (nevytvářet novou), REPLACE (nahradit stávající), APPEND (přidat na konec řetězce) a APPEND_OR_REPLACE. UniqueWorkRequest je vhodný pro úlohy, které by se neměly duplikovat: synchronizace databáze, načítání konfigurace, odesílání balíčku analytiky.

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

Zpracování průběhu a průběžných výsledků

CoroutineWorker podporuje mechanismus setProgress, který umožňuje předávat průběžné výsledky úlohy. To je užitečné pro dlouhé operace: načítání velkého souboru, dávkové zpracování obrázků, migrace databáze. UI se může přihlásit k odběru aktualizací prostřednictvím getWorkInfosByTagLiveData a zobrazovat průběh v reálném čase. K dispozici je také metoda ForegroundInfo pro spuštění Workeru jako Foreground Service s oznámením, pokud má být úloha viditelná pro uživatele.

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 a OutputData pro přenos dat

WorkManager podporuje přenos dat mezi Workery prostřednictvím InputData a OutputData. InputData se vytváří při sestavování WorkRequest pomocí Data.Builder a předává se Workeru prostřednictvím inputData. Po provedení Worker vytvoří OutputData pomocí workDataOf nebo Data.Builder a vrátí ji spolu s Result.success(outputData). Další Worker v řetězci obdrží outputData předchozího jako svůj inputData. Data jsou uložena ve formátu klíč-hodnota s podporou základních typů: String, Int, Long, Boolean, Double. Maximální velikost Data je 10 KB.

V praxi mnoho projektů používá WorkManager jako jediný plánovač úloh na pozadí. Google doporučuje migrovat všechny stávající JobService na WorkManager, zejména v aplikacích podporujících Android 4.4 (API 19) a nižší, kde JobScheduler není k dispozici a WorkManager používá záložní mechanismus prostřednictvím AlarmManager a BroadcastReceiver. Pro testování poskytuje WorkManager TestListenableWorkerBuilder a TestWorkerBuilder, které umožňují testování Workerů v JUnit testech bez skutečného plánovače.