Atualizar um trabalho que já está na fila

O WorkManager permite atualizar um WorkRequest depois que ele já foi colocado na fila. Isso geralmente é necessário em apps maiores que mudam as restrições com frequência ou precisam atualizar os workers em tempo real. A partir da versão 2.8.0 do WorkManager, a API updateWork() é o meio de fazer isso.

O método updateWork() permite mudar determinados aspectos de um WorkRequest em tempo real, sem precisar cancelar e colocar um novo na fila manualmente. Isso simplifica muito o processo de desenvolvimento.

Evitar o cancelamento de trabalhos

Em geral, evite cancelar uma WorkRequest atual e colocar uma nova na fila. Isso pode fazer com que o app repita determinadas tarefas e exigir que você escreva uma quantidade significativa de código extra.

Considere os seguintes exemplos em que o cancelamento de uma WorkRequest pode causar dificuldades:

  • Solicitação de back-end: se você cancelar um Worker enquanto ele estiver computando um payload para enviar ao servidor, o novo Worker precisará recomeçar e recalcular o payload potencialmente caro.
  • Programação: se você cancelar um PeriodicWorkRequest e quiser que o novo PeriodicWorkRequest seja executado na mesma programação, será necessário calcular um ajuste de tempo para garantir que o novo horário de execução esteja alinhado com a solicitação de trabalho anterior.

A API updateWork() permite atualizar as restrições e outros parâmetros de uma solicitação de trabalho sem o trabalho de cancelar e colocar uma nova solicitação na fila.

Quando cancelar um trabalho

Há casos em que você deve cancelar diretamente um WorkRequest em vez de chamar updateWork(). Isso é o que você precisa fazer quando quer mudar a natureza fundamental do trabalho que foi colocado na fila.

Quando atualizar o trabalho

Imagine um app de fotos que faz um backup diário das fotos do usuário. Ele colocou um PeriodicWorkRequest na fila para fazer isso. O WorkRequest tem restrições que exigem que o dispositivo esteja carregando e conectado ao Wi-Fi.

No entanto, o usuário só carrega o dispositivo por 20 minutos por dia usando um carregador rápido. Nesse caso, o app pode atualizar o WorkRequest para flexibilizar a restrição de carregamento, de modo que ainda possa fazer upload das fotos, mesmo que o dispositivo não esteja totalmente carregado.

Nessa situação, use o método updateWork() para atualizar as restrições da solicitação de trabalho.

Como atualizar o trabalho

O método updateWork() oferece uma maneira simples de atualizar um WorkRequest existente, sem precisar cancelar e colocar um novo na fila.

Para usar o trabalho de atualização em fila, siga estas etapas:

  1. Acessar o ID do trabalho em fila: acesse o ID da WorkRequest que você quer atualizar. É possível recuperar esse ID com qualquer uma das APIs getWorkInfo ou mantendo manualmente o ID da WorkRequest inicial para recuperação posterior com a propriedade pública WorkRequest.id, antes de colocá-lo na fila.
  2. Criar uma nova WorkRequest: crie uma nova WorkRequest e use WorkRequest.Builder.setID() para definir o ID dela de modo que corresponda ao da WorkRequest atual.
  3. Definir restrições: use WorkRequest.Builder.setConstraints() para transmitir as novas restrições do WorkManager.
  4. Chame updateWork: transmita a nova WorkRequest para updateWork().

Exemplo de atualização de trabalho

Confira um exemplo de snippet de código em Kotlin que demonstra como usar o método updateWork() para mudar as restrições de bateria de um WorkRequest usado para fazer upload de fotos:

suspend fun updatePhotoUploadWork() {
    // Get instance of WorkManager.
    val workManager = WorkManager.getInstance(context)

    // Retrieve the work request ID. In this example, the work being updated is unique
    // work so we can retrieve the ID using the unique work name.
    val photoUploadWorkInfoList = workManager.getWorkInfosForUniqueWork(
        PHOTO_UPLOAD_WORK_NAME
    ).await()

    val existingWorkRequestId = photoUploadWorkInfoList.firstOrNull()?.id ?: return

    // Update the constraints of the WorkRequest to not require a charging device.
    val newConstraints = Constraints.Builder()
        // Add other constraints as required here.
        .setRequiresCharging(false)
        .build()

    // Create new WorkRequest from existing Worker, new constraints, and the id of the old WorkRequest.
    val updatedWorkRequest: WorkRequest =
        OneTimeWorkRequestBuilder<MyWorker>()
            .setConstraints(newConstraints)
            .setId(existingWorkRequestId)
            .build()

    // Pass the new WorkRequest to updateWork().
    workManager.updateWork(updatedWorkRequest)
}

Processar o resultado

updateWork() retorna um ListenableFuture<UpdateResult>. O UpdateResult fornecido pode ter um dos vários valores que descrevem se o WorkManager conseguiu ou não aplicar as mudanças. Ele também indica quando foi possível aplicar a mudança.

Para mais informações, consulte as referências de updateWork() e UpdateResult.

Acompanhar o trabalho com gerações

Sempre que você atualiza um WorkRequest, a geração dele aumenta em um. Isso permite que você acompanhe exatamente qual WorkRequest está na fila. As gerações oferecem mais controle ao observar, rastrear e testar solicitações de trabalho.

Para receber a geração de um WorkRequest, siga estas etapas:

  1. WorkInfo: chame WorkManager.getWorkInfoById() para recuperar uma instância de WorkInfo correspondente ao seu WorkRequest.
    • É possível chamar um dos vários métodos que retornam um WorkInfo. Para mais informações, consulte a referência do WorkManager.
  2. getGeneration: chame getGeneration() na instância de WorkInfo. O Int retornado corresponde à geração do WorkRequest.
    • Não há um campo ou propriedade de geração, apenas o método WorkInfo.getGeneration().

Exemplo de geração de faixa

Veja a seguir um exemplo de implementação do fluxo de trabalho descrito acima para recuperar a geração de um WorkRequest.

// Get instance of WorkManager.
val workManager = WorkManager.getInstance(context)

// Retrieve WorkInfo instance.
val workInfo = workManager.getWorkInfoById(oldWorkRequestId)

// Call getGeneration to retrieve the generation.
val generation = workInfo.getGeneration()

Políticas para atualizar o trabalho

Anteriormente, a solução recomendada para atualizar o trabalho periódico era colocar um PeriodicWorkRequest na fila com a política ExistingPeriodicWorkPolicy.REPLACE. Se houvesse um PeriodicWorkRequest pendente com o mesmo id exclusivo, a nova solicitação de trabalho o cancelaria e excluiria. Esta política foi descontinuada em favor do fluxo de trabalho que usa o ExistingPeriodicWorkPolicy.UPDATE.

Por exemplo, ao usar enqueueUniquePeriodicWork com um PeriodicWorkRequest, é possível inicializar o novo PeriodicWorkRequest com a política ExistingPeriodicWorkPolicy.UPDATE. Se houver um PeriodicWorkRequest pendente com o mesmo nome exclusivo, o WorkManager o atualizará para a nova especificação. Seguindo esse fluxo de trabalho, não é necessário usar updateWork().