Mettre à jour un travail déjà mis en file d'attente

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 Worker pendant qu'il calcule une charge utile à envoyer au serveur, le nouveau Worker doit recommencer et recalculer la charge utile potentiellement coûteuse.
  • Planification : si vous annulez un PeriodicWorkRequest et que vous souhaitez que le nouveau PeriodicWorkRequest s'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 :

  1. 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 getWorkInfo ou en conservant manuellement l'ID de la requête WorkRequest initiale pour une récupération ultérieure avec la propriété publique WorkRequest.id, avant de la mettre en file d'attente.
  2. Créer une requête de travail : créez une requête WorkRequest et utilisez WorkRequest.Builder.setID() pour définir son ID de sorte qu'il corresponde à celui de la requête WorkRequest existante.
  3. Définir des contraintes : utilisez WorkRequest.Builder.setConstraints() pour transmettre les nouvelles contraintes à WorkManager.
  4. 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 :

  1. WorkInfo : appelez WorkManager.getWorkInfoById() pour récupérer une instance de WorkInfo correspondant à votre WorkRequest.
  2. getGeneration : appelez getGeneration() sur l'instance de WorkInfo. La valeur Int renvoyée correspond à la génération de WorkRequest.
    • Notez qu'il n'existe pas de champ ni de propriété de génération, mais uniquement la méthode WorkInfo.getGeneration().

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