WorkManager vous permet de mettre à jour un WorkRequest après l'avoir mis en file d'attente. Cela est souvent nécessaire dans les applications plus volumineuses qui modifient fréquemment les contraintes ou qui doivent mettre à jour leurs nœuds de calcul à la volée. Depuis la version 2.8.0 de WorkManager, l'API updateWork() permet d'effectuer cette opération.
La méthode updateWork() vous permet de modifier certains aspects d'un WorkRequest à la volée, sans avoir à annuler manuellement l'ancien et à en mettre un nouveau en file d'attente. Cela simplifie considérablement le processus de développement.
Éviter d'annuler des tâches
En règle générale, vous devez éviter d'annuler une requête WorkRequest existante et d'en ajouter une nouvelle à la file d'attente. Cela peut entraîner la répétition de certaines tâches par l'application et vous obliger à écrire une quantité importante de code supplémentaire.
Voici quelques exemples de situations dans lesquelles l'annulation d'une WorkRequest peut poser problème :
- Requête de backend : si vous annulez un
Workerpendant qu'il calcule une charge utile à envoyer au serveur, le nouveauWorkerdoit recommencer et recalculer la charge utile potentiellement coûteuse. - Planification : si vous annulez un
PeriodicWorkRequestet que vous souhaitez que le nouveauPeriodicWorkRequests'exécute selon la même planification, vous devez calculer un décalage temporel pour vous assurer que la nouvelle heure d'exécution est alignée sur la requête de travail précédente.
L'API updateWork() vous permet de mettre à jour les contraintes et d'autres paramètres d'une demande de travail sans avoir à annuler et à mettre en file d'attente une nouvelle demande.
Quand annuler une tâche
Dans certains cas, vous devez annuler directement un WorkRequest plutôt que d'appeler updateWork(). C'est ce que vous devez faire lorsque vous souhaitez modifier la nature fondamentale du travail que vous avez mis en file d'attente.
Quand mettre à jour des tâches
Imaginez une application photo qui effectue une sauvegarde quotidienne des photos de l'utilisateur. Il a mis en file d'attente un PeriodicWorkRequest pour ce faire. Le WorkRequest comporte des contraintes qui exigent que l'appareil soit en charge et connecté au Wi-Fi.
Cependant, l'utilisateur ne recharge son appareil que pendant 20 minutes par jour à l'aide d'un chargeur rapide. Dans ce cas, l'application peut mettre à jour le WorkRequest pour assouplir la contrainte de recharge, afin de pouvoir importer les photos même si l'appareil n'est pas complètement chargé.
Dans ce cas, vous pouvez utiliser la méthode updateWork() pour mettre à jour les contraintes de la demande de travail.
Mettre à jour le travail
La méthode updateWork() permet de mettre à jour facilement un WorkRequest existant, sans avoir à l'annuler et à en ajouter un nouveau à la file d'attente.
Pour utiliser la mise à jour du travail mis en file d'attente, procédez comme suit :
- Obtenir l'ID existant d'une tâche mise en file d'attente : obtenez l'ID de la WorkRequest que vous souhaitez mettre à jour. Vous pouvez récupérer cet ID avec l'une des API
getWorkInfoou en conservant manuellement l'ID de la requête WorkRequest initiale pour une récupération ultérieure avec la propriété publiqueWorkRequest.id, avant de la mettre en file d'attente. - Créer une requête de travail : créez une requête
WorkRequestet utilisezWorkRequest.Builder.setID()pour définir son ID de sorte qu'il corresponde à celui de la requêteWorkRequestexistante. - Définir des contraintes : utilisez
WorkRequest.Builder.setConstraints()pour transmettre les nouvelles contraintes à WorkManager. - Appeler updateWork : transmettez la nouvelle WorkRequest à
updateWork().
Mettre à jour un exemple de travail
Voici un exemple d'extrait de code en Kotlin qui montre comment utiliser la méthode updateWork() pour modifier les contraintes de batterie d'un WorkRequest utilisé pour importer des photos :
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)
}
Gérer le résultat
updateWork() renvoie un élément ListenableFuture<UpdateResult>. La valeur UpdateResult peut être l'une des nombreuses valeurs qui indiquent si WorkManager a pu appliquer vos modifications ou non. Il indique également quand il a pu appliquer la modification.
Pour en savoir plus, consultez la documentation de référence sur updateWork() et UpdateResult.
Suivre le travail avec les générations
Chaque fois que vous mettez à jour un WorkRequest, sa génération est incrémentée de un. Cela vous permet de suivre exactement quel WorkRequest est actuellement mis en file d'attente.
Les générations vous offrent plus de contrôle lorsque vous observez, tracez et testez des requêtes de travail.
Pour obtenir la génération d'un WorkRequest, procédez comme suit :
- WorkInfo : appelez
WorkManager.getWorkInfoById()pour récupérer une instance deWorkInfocorrespondant à votreWorkRequest.- Vous pouvez appeler l'une des méthodes qui renvoient un
WorkInfo. Pour en savoir plus, consultez la documentation de référence sur WorkManager.
- Vous pouvez appeler l'une des méthodes qui renvoient un
- getGeneration : appelez
getGeneration()sur l'instance deWorkInfo. La valeurIntrenvoyée correspond à la génération deWorkRequest.- Notez qu'il n'existe pas de champ ni de propriété de génération, mais uniquement la méthode
WorkInfo.getGeneration().
- Notez qu'il n'existe pas de champ ni de propriété de génération, mais uniquement la méthode
Exemple de génération de piste
Voici un exemple d'implémentation du workflow décrit ci-dessus pour récupérer la génération d'un 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()
Règles de mise à jour du travail
Auparavant, la solution recommandée pour mettre à jour une tâche périodique consistait à mettre en file d'attente un PeriodicWorkRequest avec la règle ExistingPeriodicWorkPolicy.REPLACE.
S'il y avait une PeriodicWorkRequest en attente avec le même id unique, la nouvelle requête de travail l'annulerait et la supprimerait. Cette règle est désormais obsolète et remplacée par le workflow utilisant ExistingPeriodicWorkPolicy.UPDATE.
Par exemple, lorsque vous utilisez enqueueUniquePeriodicWork avec un PeriodicWorkRequest, vous pouvez initialiser le nouveau PeriodicWorkRequest avec la règle ExistingPeriodicWorkPolicy.UPDATE. S'il existe un PeriodicWorkRequest en attente portant le même nom unique, WorkManager le met à jour avec la nouvelle spécification. En suivant ce workflow, il n'est pas nécessaire d'utiliser updateWork().