WorkManager — ce este, API și planificarea sarcinilor

Cum funcționează WorkManager?

Arhitectura WorkManager este construită în jurul a trei clase de bază: Worker, WorkRequest și WorkManager. Worker conține logica sarcinii, WorkRequest descrie parametrii de execuție, iar WorkManager gestionează coada și planificarea. Biblioteca folosește o bază de date internă Room pentru stocarea stării tuturor sarcinilor.

Worker și WorkRequest

Worker este o clasă abstractă cu o singură metodă doWork, care este apelată într-un fir de fundal. Metoda returnează ListenableWorker.Result — SUCCESS, FAILURE sau RETRY. WorkRequest leagă Worker-ul de parametri: timeout, tag, întârziere inițială și constrângeri.

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

Planificarea execuției prin WorkManager

WorkManager planifică sarcinile uniform, indiferent de versiunea Android. La apelul enqueue, biblioteca salvează sarcina în Room, evaluează condițiile curente și alege timpul optim de pornire. Sub capotă poate fi folosit JobScheduler, AlarmManager sau propriul planificator — dezvoltatorul nu trebuie să se gândească la asta.

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

WorkManager.getInstance(context)
    .enqueue(syncRequest)

Tipuri de WorkRequest

WorkManager suportă două tipuri de cereri de execuție: unice și periodice. Alegerea tipului depinde de scenariu: sarcina trebuie executată o dată sau repetată la un interval dat.

OneTimeWorkRequest

OneTimeWorkRequest este destinat sarcinilor care trebuie executate o singură dată. Poate fi trimiterea unui log, sincronizarea datelor după autentificare, încărcarea configurației la prima lansare. Întârzierea se setează prin setInitialDelay, iar constrângerile prin setConstraints.

PeriodicWorkRequest

PeriodicWorkRequest este potrivit pentru sarcini repetitive cu un interval minim de 15 minute. Biblioteca garantează că intervalul între executări nu va fi mai mic decât cel specificat, dar poate fi mai mare din cauza limitărilor dispozitivului. Pentru sarcini cu frecvență mai mică de 15 minute, folosește Handler sau Timer în Foreground Service.

Configurarea constrângerilor și lanțuri de sarcini

Constrângerile (constraints) în WorkManager permit stabilirea condițiilor în care sarcina poate fi pornită: conexiune la rețea (NetworkType), nivelul bateriei (batteryNotLow), starea stocării (StorageNotLow) și modul de așteptare (DeviceIdle). Sarcina nu va porni până când toate constrângerile nu sunt îndeplinite.

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

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

Lanțurile (chaining) permit organizarea executării secvențiale sau paralele a sarcinilor. beginWith pornește lanțul, then adaugă următorul Worker, care se va executa după finalizarea cu succes a precedentului. Pentru executare paralelă se folosește workManager.enqueue(listOf(request1, request2)).

WorkManager.getInstance(context)
    .beginWith(compressWorker)
    .then(uploadWorker)
    .then(cleanupWorker)
    .enqueue()
    // compress → upload → cleanup secvențial

Migrarea de la JobScheduler la WorkManager

JobScheduler a fost introdus în Android 5 (API 21) ca serviciu de sistem pentru planificarea sarcinilor de fundal. WorkManager a venit ca înlocuitor, oferind o API cross-platform cu migrare automată și capabilități suplimentare: lanțuri, garanție de execuție, tag-uri, monitorizarea stării prin LiveData.

La migrarea de la JobScheduler la WorkManager, trebuie să transformi JobService într-un Worker, să înlocuiești JobInfo cu WorkRequest, iar Context.getSystemService cu API-ul WorkManager. WorkManager rezolvă automat problemele de compatibilitate și gestionează Doze Mode mai corect decât implementarea manuală a JobScheduler. Pașii migrării: 1) creează o clasă Worker, 2) construiește WorkRequest cu aceleași condiții, 3) șterge JobService și JobInfo din cod și manifest.

UniqueWork pentru sarcini unice

WorkManager suportă conceptul de sarcini unice prin ExistingWorkPolicy. Dacă o sarcină cu numele specificat există deja, politica determină comportamentul: KEEP (nu crea una nouă), REPLACE (înlocuiește-o pe cea existentă), APPEND (adaugă la sfârșitul lanțului) și APPEND_OR_REPLACE. UniqueWorkRequest este convenabil pentru sarcini care nu trebuie duplicate: sincronizarea bazei de date, încărcarea configurației, trimiterea pachetului de analitică.

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

Gestionarea progresului și a rezultatelor intermediare

CoroutineWorker suportă mecanismul setProgress, permițând transmiterea rezultatelor intermediare ale executării sarcinii. Acest lucru este util pentru operațiuni lungi: încărcarea unui fișier mare, procesarea loturilor de imagini, migrarea bazei de date. UI se poate abona la actualizări prin getWorkInfosByTagLiveData și poate afișa progresul în timp real. Este disponibilă și metoda ForegroundInfo pentru pornirea Worker-ului ca Foreground Service cu notificare, dacă sarcina trebuie să fie vizibilă utilizatorului.

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 și OutputData pentru transmiterea datelor

WorkManager suportă transmiterea datelor între Worker-i prin InputData și OutputData. InputData se creează în etapa de construire a WorkRequest-ului prin Data.Builder și se transmite Worker-ului prin inputData. După execuție, Worker-ul creează OutputData prin workDataOf sau Data.Builder și îl returnează împreună cu Result.success(outputData). Următorul Worker din lanț primește outputData-ul precedentului ca inputData propriu. Datele sunt stocate în format cheie-valoare cu suport pentru tipurile de bază: String, Int, Long, Boolean, Double. Dimensiunea maximă a Data este de 10 KB.

În practică, multe proiecte folosesc WorkManager ca unic planificator de sarcini de fundal. Google recomandă migrarea tuturor JobService-urilor existente la WorkManager, în special în aplicațiile care suportă Android 4.4 (API 19) și inferior, unde JobScheduler nu este disponibil, iar WorkManager folosește un mecanism de rezervă prin AlarmManager și BroadcastReceiver. Pentru testare, WorkManager oferă TestListenableWorkerBuilder și TestWorkerBuilder, care permit testarea Worker-ilor în teste JUnit fără un planificator real.