WorkManager — o que é, API e agendamento de tarefas

Como funciona o WorkManager?

A arquitetura do WorkManager é construída em torno de três classes base: Worker, WorkRequest e WorkManager. O Worker contém a lógica da tarefa, o WorkRequest descreve os parâmetros de execução e o WorkManager gerencia a fila e o agendamento. A biblioteca usa um banco de dados Room interno para armazenar o estado de todas as tarefas.

Worker e WorkRequest

Worker é uma classe abstrata com um único método doWork que é chamado em uma thread em segundo plano. O método retorna ListenableWorker.Result — SUCCESS, FAILURE ou RETRY. O WorkRequest vincula o Worker com parâmetros: tempo limite, tag, atraso inicial e restrições.

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

Agendamento via WorkManager

WorkManager agenda tarefas de forma uniforme, independentemente da versão do Android. Ao chamar enqueue, a biblioteca salva a tarefa no Room, avalia as condições atuais e seleciona o momento ideal de execução. Internamente, pode usar JobScheduler, AlarmManager ou seu próprio agendador — o desenvolvedor não precisa se preocupar com isso.

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

WorkManager.getInstance(context)
    .enqueue(syncRequest)

Tipos de WorkRequest

WorkManager suporta dois tipos de solicitações de execução: únicas e periódicas. A escolha do tipo depende do cenário: a tarefa deve ser executada uma vez ou repetida em um intervalo determinado.

OneTimeWorkRequest

OneTimeWorkRequest é projetado para tarefas que devem ser executadas uma única vez. Pode ser o envio de um log, sincronização de dados após autorização, download de configuração no primeiro início. O atraso é definido via setInitialDelay e as restrições via setConstraints.

PeriodicWorkRequest

PeriodicWorkRequest é adequado para tarefas repetitivas com intervalo mínimo de 15 minutos. A biblioteca garante que o intervalo entre execuções não será menor que o especificado, mas pode ser maior devido a restrições do dispositivo. Para tarefas com frequência inferior a 15 minutos, use Handler ou Timer no Foreground Service.

Configuração de restrições e cadeias de tarefas

As restrições no WorkManager permitem definir condições sob as quais uma tarefa pode ser iniciada: conexão de rede (NetworkType), nível de bateria (batteryNotLow), estado do armazenamento (StorageNotLow) e modo ocioso (DeviceIdle). A tarefa não será iniciada até que todas as restrições sejam atendidas.

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

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

As cadeias permitem organizar a execução sequencial ou paralela de tarefas. beginWith inicia uma cadeia, em seguida, adiciona o próximo Worker que será executado após a conclusão bem-sucedida do anterior. Para execução paralela, use workManager.enqueue(listOf(request1, request2)).

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

Migração do JobScheduler para WorkManager

JobScheduler foi introduzido no Android 5 (API 21) como um serviço de sistema para agendar tarefas em segundo plano. O WorkManager veio para substituí-lo, oferecendo uma API multiplataforma com migração automática e capacidades adicionais: cadeias, garantia de execução, tags, observação de estado via LiveData.

Ao migrar do JobScheduler para WorkManager, você precisará converter JobService em Worker, substituir JobInfo por WorkRequest e Context.getSystemService pela API do WorkManager. O WorkManager lida automaticamente com problemas de compatibilidade e lida com o Modo Doze de forma mais correta do que uma implementação manual de JobScheduler. Passos da migração: 1) criar uma classe Worker, 2) construir um WorkRequest com as mesmas condições, 3) remover JobService e JobInfo do código e manifesto.

UniqueWork para tarefas únicas

WorkManager suporta o conceito de tarefas únicas através de ExistingWorkPolicy. Se uma tarefa com o nome especificado já existir, a política determina o comportamento: KEEP (não criar uma nova), REPLACE (substituir a existente), APPEND (adicionar ao final da cadeia) e APPEND_OR_REPLACE. UniqueWorkRequest é conveniente para tarefas que não devem ser duplicadas: sincronização de banco de dados, download de configuração, envio de lote de análises.

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

Gerenciamento de progresso e resultados intermediários

CoroutineWorker suporta o mecanismo setProgress, permitindo passar resultados intermediários de execução. Isso é útil para operações longas: download de arquivo grande, processamento em lote de imagens, migração de banco de dados. A UI pode se inscrever em atualizações via getWorkInfosByTagLiveData e exibir o progresso em tempo real. O método ForegroundInfo também está disponível para executar um Worker como Foreground Service com uma notificação se a tarefa deve ser visível ao usuário.

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 e OutputData para transferência de dados

WorkManager suporta transferência de dados entre Workers via InputData e OutputData. InputData é criado durante a construção do WorkRequest através de Data.Builder e é passado para o Worker através de inputData. Após a execução, o Worker cria OutputData via workDataOf ou Data.Builder e retorna junto com Result.success(outputData). O próximo Worker na cadeia recebe o outputData do anterior como seu inputData. Os dados são armazenados no formato chave-valor com suporte para tipos básicos: String, Int, Long, Boolean, Double. O tamanho máximo de Data é 10 KB.

Na prática, muitos projetos usam WorkManager como o único agendador de tarefas em segundo plano. O Google recomenda migrar todos os JobService existentes para WorkManager, especialmente em aplicativos que suportam Android 4.4 (API 19) e inferiores, onde o JobScheduler não está disponível e o WorkManager usa um mecanismo de fallback via AlarmManager e BroadcastReceiver. Para testes, o WorkManager fornece TestListenableWorkerBuilder e TestWorkerBuilder, que permitem testar Workers em testes JUnit sem um agendador real.