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
Workerenquanto ele estiver computando um payload para enviar ao servidor, o novoWorkerprecisará recomeçar e recalcular o payload potencialmente caro. - Programação: se você cancelar um
PeriodicWorkRequeste quiser que o novoPeriodicWorkRequestseja 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:
- 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
getWorkInfoou mantendo manualmente o ID da WorkRequest inicial para recuperação posterior com a propriedade públicaWorkRequest.id, antes de colocá-lo na fila. - Criar uma nova WorkRequest: crie uma nova
WorkRequeste useWorkRequest.Builder.setID()para definir o ID dela de modo que corresponda ao daWorkRequestatual. - Definir restrições: use
WorkRequest.Builder.setConstraints()para transmitir as novas restrições do WorkManager. - 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:
- WorkInfo: chame
WorkManager.getWorkInfoById()para recuperar uma instância deWorkInfocorrespondente ao seuWorkRequest.- É possível chamar um dos vários métodos que retornam um
WorkInfo. Para mais informações, consulte a referência do WorkManager.
- É possível chamar um dos vários métodos que retornam um
- getGeneration: chame
getGeneration()na instância deWorkInfo. OIntretornado corresponde à geração doWorkRequest.- Não há um campo ou propriedade de geração, apenas o método
WorkInfo.getGeneration().
- Não há um campo ou propriedade de geração, apenas o método
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().