WorkManager — wat is het, API en taakplanning

Hoe werkt WorkManager?

De architectuur van WorkManager is gebouwd rond drie basisklassen: Worker, WorkRequest en WorkManager. Worker bevat de taaklogica, WorkRequest beschrijft de uitvoeringsparameters en WorkManager beheert de wachtrij en planning. De bibliotheek gebruikt een interne Room-database om de status van alle taken op te slaan.

Worker en WorkRequest

Worker — is een abstracte klasse met een enkele methode doWork, die in een achtergrondthread wordt aangeroepen. De methode retourneert ListenableWorker.Result — SUCCESS, FAILURE of RETRY. WorkRequest koppelt Worker aan parameters: timeout, tag, initiële vertraging en beperkingen.

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

Planning via WorkManager

WorkManager plant taken uniform, ongeacht de Android-versie. Bij het aanroepen van enqueue slaat de bibliotheek de taak op in Room, evalueert de huidige omstandigheden en kiest het optimale starttijdstip. Onder de motorkap kan JobScheduler, AlarmManager of een eigen planner worden gebruikt — de ontwikkelaar hoeft hier niet over na te denken.

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

WorkManager.getInstance(context)
    .enqueue(syncRequest)

Soorten WorkRequest

WorkManager ondersteunt twee soorten uitvoeringsverzoeken: eenmalig en periodiek. De keuze van het type hangt af van het scenario: moet de taak eenmalig worden uitgevoerd of herhaald met een bepaald interval.

OneTimeWorkRequest

OneTimeWorkRequest is bedoeld voor taken die eenmalig moeten worden uitgevoerd. Dit kan het verzenden van een log zijn, gegevenssynchronisatie na autorisatie, het laden van configuratie bij de eerste start. Vertraging wordt ingesteld via setInitialDelay en beperkingen via setConstraints.

PeriodicWorkRequest

PeriodicWorkRequest is geschikt voor terugkerende taken met een minimuminterval van 15 minuten. De bibliotheek garandeert dat het interval tussen uitvoeringen niet korter zal zijn dan opgegeven, maar kan langer zijn vanwege apparaatbeperkingen. Gebruik voor taken met een frequentie van minder dan 15 minuten Handler of Timer in een Foreground Service.

Beperkingen instellen en taakketens

Beperkingen (constraints) in WorkManager maken het mogelijk om voorwaarden in te stellen waaronder een taak kan worden gestart: netwerkverbinding (NetworkType), batterijniveau (batteryNotLow), opslagstatus (StorageNotLow) en inactiviteitsmodus (DeviceIdle). De taak wordt niet gestart totdat aan alle beperkingen is voldaan.

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

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

Ketens (chaining) maken het mogelijk om opeenvolgende of parallelle uitvoering van taken te organiseren. beginWith start een keten, then voegt de volgende Worker toe, die wordt uitgevoerd na succesvolle voltooiing van de vorige. Voor parallelle uitvoering wordt workManager.enqueue(listOf(request1, request2)) gebruikt.

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

Migratie van JobScheduler naar WorkManager

JobScheduler werd geïntroduceerd in Android 5 (API 21) als een systeemservice voor het plannen van achtergrondtaken. WorkManager kwam als vervanging met een cross-platform API, automatische migratie en extra mogelijkheden: ketens, uitvoeringsgarantie, tags, statusbewaking via LiveData.

Bij migratie van JobScheduler naar WorkManager moet JobService worden omgezet naar Worker, JobInfo vervangen door WorkRequest en Context.getSystemService door WorkManager API. WorkManager lost automatisch compatibiliteitsproblemen op en verwerkt Doze Mode correcter dan een handmatige JobScheduler-implementatie. Migratiestappen: 1) maak een Worker-klasse, 2) bouw een WorkRequest met dezelfde voorwaarden, 3) verwijder JobService en JobInfo uit de code en het manifest.

UniqueWork voor unieke taken

WorkManager ondersteunt het concept van unieke taken via ExistingWorkPolicy. Als een taak met de opgegeven naam al bestaat, bepaalt de policy het gedrag: KEEP (geen nieuwe aanmaken), REPLACE (bestaande vervangen), APPEND (toevoegen aan het einde van de keten) en APPEND_OR_REPLACE. UniqueWorkRequest is handig voor taken die niet mogen worden gedupliceerd: databasesynchronisatie, configuratieladen, het verzenden van een analytics-pakket.

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

Voortgang en tussentijdse resultaten verwerken

CoroutineWorker ondersteunt het setProgress-mechanisme waarmee tussentijdse resultaten van een taak kunnen worden doorgegeven. Dit is handig voor langdurige bewerkingen: het laden van een groot bestand, batchverwerking van afbeeldingen, databasemigratie. De UI kan zich abonneren op updates via getWorkInfosByTagLiveData en de voortgang in realtime weergeven. Ook beschikbaar is de ForegroundInfo-methode om Worker als Foreground Service met een melding te starten als de taak zichtbaar moet zijn voor de gebruiker.

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 en OutputData voor gegevensoverdracht

WorkManager ondersteunt gegevensoverdracht tussen Workers via InputData en OutputData. InputData wordt gemaakt bij het bouwen van WorkRequest via Data.Builder en doorgegeven aan Worker via inputData. Na uitvoering maakt Worker OutputData via workDataOf of Data.Builder en retourneert dit samen met Result.success(outputData). De volgende Worker in de keten ontvangt de outputData van de vorige als zijn inputData. Gegevens worden opgeslagen in sleutel-waarde-indeling met ondersteuning voor basistypen: String, Int, Long, Boolean, Double. De maximale grootte van Data is 10 KB.

In de praktijk gebruiken veel projecten WorkManager als enige planner voor achtergrondtaken. Google raadt aan om alle bestaande JobService te migreren naar WorkManager, vooral in apps die Android 4.4 (API 19) en lager ondersteunen, waar JobScheduler niet beschikbaar is en WorkManager een back-upmechanisme gebruikt via AlarmManager en BroadcastReceiver. Voor testen biedt WorkManager TestListenableWorkerBuilder en TestWorkerBuilder, waarmee Workers in JUnit-tests kunnen worden getest zonder een echte planner.