WorkManager è una libreria per la pianificazione e l'esecuzione di operazioni in background differibili in Android. È la sostituzione consigliata di Firebase JobDispatcher. La seguente guida ti illustrerà come eseguire la migrazione dell'implementazione di Firebase JobDispatcher a WorkManager.
Configurazione di Gradle
Per importare la libreria di WorkManager nel progetto Android, aggiungi le dipendenze elencate nella Guida introduttiva a WorkManager.
Da JobService ai worker
FirebaseJobDispatcher
utilizza una sottoclasse di
JobService
come punto di contatto per definire il lavoro da svolgere. È possibile che tu stia utilizzando JobService
direttamente o SimpleJobService
.
Un JobService
avrà un aspetto simile al seguente:
Kotlin
import com.firebase.jobdispatcher.JobParameters import com.firebase.jobdispatcher.JobService class MyJobService : JobService() { override fun onStartJob(job: JobParameters): Boolean { // Do some work here return false // Answers the question: "Is there still work going on?" } override fun onStopJob(job: JobParameters): Boolean { return false // Answers the question: "Should this job be retried?" } }
Java
import com.firebase.jobdispatcher.JobParameters; import com.firebase.jobdispatcher.JobService; public class MyJobService extends JobService { @Override public boolean onStartJob(JobParameters job) { // Do some work here return false; // Answers the question: "Is there still work going on?" } @Override public boolean onStopJob(JobParameters job) { return false; // Answers the question: "Should this job be retried?" } }
Se utilizzi SimpleJobService
, avrai eseguito l'override di onRunJob()
,
che restituisce un tipo @JobResult int
.
La differenza principale è che, quando utilizzi JobService
direttamente, onStartJob()
viene chiamato nel thread principale ed è responsabilità dell'app trasferire il lavoro a un thread in background. Se invece utilizzi SimpleJobService
, il servizio è responsabile dell'esecuzione del tuo lavoro su un thread in background.
WorkManager presenta concetti simili. L'unità di lavoro fondamentale in WorkManager è
una ListenableWorker
. Esistono
anche altri sottotipi utili di worker come
Worker
,
RxWorker
e CoroutineWorker
(quando
si utilizzano le coroutine Kotlin).
JobService è mappato a AscoltaableWorker
Se utilizzi JobService
direttamente, il worker a cui viene mappato è un
ListenableWorker
. Se utilizzi SimpleJobService
, devi usare
Worker
.
Utilizziamo l'esempio sopra (MyJobService
) e vediamo come possiamo convertirlo
in un ListenableWorker
.
Kotlin
import android.content.Context import androidx.work.ListenableWorker import androidx.work.ListenableWorker.Result import androidx.work.WorkerParameters import com.google.common.util.concurrent.ListenableFuture class MyWorker(appContext: Context, params: WorkerParameters) : ListenableWorker(appContext, params) { override fun startWork(): ListenableFuture<ListenableWorker.Result> { // Do your work here. TODO("Return a ListenableFuture<Result>") } override fun onStopped() { // Cleanup because you are being stopped. } }
Java
import android.content.Context; import androidx.work.ListenableWorker; import androidx.work.ListenableWorker.Result; import androidx.work.WorkerParameters; import com.google.common.util.concurrent.ListenableFuture; class MyWorker extends ListenableWorker { public MyWorker(@NonNull Context appContext, @NonNull WorkerParameters params) { super(appContext, params); } @Override public ListenableFuture<ListenableWorker.Result> startWork() { // Do your work here. Data input = getInputData(); // Return a ListenableFuture<> } @Override public void onStopped() { // Cleanup because you are being stopped. } }
L'unità di lavoro di base in WorkManager è ListenableWorker
. Proprio come
JobService.onStartJob()
, startWork()
viene chiamata nel thread principale. Qui
MyWorker
implementa ListenableWorker
e restituisce un'istanza di
ListenableFuture
,
che viene utilizzata per segnalare il completamento del lavoro in modo asincrono. Dovresti scegliere la tua strategia
di organizzazione in thread qui.
ListenableFuture
qui restituisce un tipo ListenableWorker.Result
che può essere Result.success()
, Result.success(Data outputData)
, Result.retry()
, Result.failure()
o Result.failure(Data outputData)
. Per
ulteriori informazioni, consulta la pagina di riferimento per
ListenableWorker.Result
.
onStopped()
viene chiamato per indicare che ListenableWorker
deve arrestarsi, perché i vincoli non vengono più soddisfatti (ad esempio perché la rete non è più disponibile) o perché è stato chiamato un metodo WorkManager.cancel…()
. onStopped()
può essere chiamato anche se il sistema operativo decide di arrestare il lavoro per qualche motivo.
SimpleJobService viene mappato a un worker
Quando utilizzi SimpleJobService
, il worker riportato sopra avrà il seguente aspetto:
Kotlin
import android.content.Context; import androidx.work.Data; import androidx.work.ListenableWorker.Result; import androidx.work.Worker; import androidx.work.WorkerParameters; class MyWorker(context: Context, params: WorkerParameters) : Worker(context, params) { override fun doWork(): Result { TODO("Return a Result") } override fun onStopped() { super.onStopped() TODO("Cleanup, because you are being stopped") } }
Java
import android.content.Context; import androidx.work.Data; import androidx.work.ListenableWorker.Result; import androidx.work.Worker; import androidx.work.WorkerParameters; class MyWorker extends Worker { public MyWorker(@NonNull Context appContext, @NonNull WorkerParameters params) { super(appContext, params); } @Override public Result doWork() { // Do your work here. Data input = getInputData(); // Return a ListenableWorker.Result Data outputData = new Data.Builder() .putString(“Key”, “value”) .build(); return Result.success(outputData); } @Override public void onStopped() { // Cleanup because you are being stopped. } }
Qui doWork()
restituisce un'istanza di ListenableWorker.Result
per segnalare il completamento
del lavoro in modo sincrono. È simile a SimpleJobService
, che pianifica
i job in un thread in background.
JobBuilder viene mappato a WorkRequest
FirebaseJobBuilder utilizza Job.Builder
per rappresentare i metadati Job
. Per ricoprire questo ruolo, WorkManager
utilizza WorkRequest
.
WorkManager ha due tipi di WorkRequest
:
OneTimeWorkRequest
e
PeriodicWorkRequest
.
Se attualmente utilizzi Job.Builder.setRecurring(true)
, devi
creare un nuovo PeriodicWorkRequest
. In caso contrario, devi utilizzare un
OneTimeWorkRequest
.
Vediamo come potrebbe essere la pianificazione di un Job
complesso con FirebaseJobDispatcher
:
Kotlin
val input: Bundle = Bundle().apply { putString("some_key", "some_value") } val job = dispatcher.newJobBuilder() // the JobService that will be called .setService(MyService::class.java) // uniquely identifies the job .setTag("my-unique-tag") // one-off job .setRecurring(false) // don't persist past a device reboot .setLifetime(Lifetime.UNTIL_NEXT_BOOT) // start between 0 and 60 seconds from now .setTrigger(Trigger.executionWindow(0, 60)) // don't overwrite an existing job with the same tag .setReplaceCurrent(false) // retry with exponential backoff .setRetryStrategy(RetryStrategy.DEFAULT_EXPONENTIAL) .setConstraints( // only run on an unmetered network Constraint.ON_UNMETERED_NETWORK, // // only run when the device is charging Constraint.DEVICE_CHARGING ) .setExtras(input) .build() dispatcher.mustSchedule(job)
Java
Bundle input = new Bundle(); input.putString("some_key", "some_value"); Job myJob = dispatcher.newJobBuilder() // the JobService that will be called .setService(MyJobService.class) // uniquely identifies the job .setTag("my-unique-tag") // one-off job .setRecurring(false) // don't persist past a device reboot .setLifetime(Lifetime.UNTIL_NEXT_BOOT) // start between 0 and 60 seconds from now .setTrigger(Trigger.executionWindow(0, 60)) // don't overwrite an existing job with the same tag .setReplaceCurrent(false) // retry with exponential backoff .setRetryStrategy(RetryStrategy.DEFAULT_EXPONENTIAL) // constraints that need to be satisfied for the job to run .setConstraints( // only run on an unmetered network Constraint.ON_UNMETERED_NETWORK, // only run when the device is charging Constraint.DEVICE_CHARGING ) .setExtras(input) .build(); dispatcher.mustSchedule(myJob);
Per ottenere lo stesso risultato con WorkManager, devi:
- Dati di input della build che possono essere utilizzati come input per
Worker
. - Crea una
WorkRequest
con i dati di input e i vincoli simili a quelli definiti sopra perFirebaseJobDispatcher
. - Accoda
WorkRequest
.
Configurazione degli input per il worker
FirebaseJobDispatcher
utilizza Bundle
per inviare i dati di input al JobService
.
WorkManager utilizza invece Data
. Ciò diventa:
Kotlin
import androidx.work.workDataOf val data = workDataOf("some_key" to "some_val")
Java
import androidx.work.Data; Data input = new Data.Builder() .putString("some_key", "some_value") .build();
Impostazione dei vincoli per il worker
FirebaseJobDispatcher
utilizza
Job.Builder.setConstaints(...)
per configurare vincoli per i job. WorkManager utilizza invece Constraints
.
Kotlin
import androidx.work.* val constraints: Constraints = Constraints.Builder().apply { setRequiredNetworkType(NetworkType.CONNECTED) setRequiresCharging(true) }.build()
Java
import androidx.work.Constraints; import androidx.work.Constraints.Builder; import androidx.work.NetworkType; Constraints constraints = new Constraints.Builder() // The Worker needs Network connectivity .setRequiredNetworkType(NetworkType.CONNECTED) // Needs the device to be charging .setRequiresCharging(true) .build();
Creazione di WorkRequest (una tantum o periodica)
Per creare OneTimeWorkRequest
e PeriodicWorkRequest
devi usare
OneTimeWorkRequest.Builder
e PeriodicWorkRequest.Builder
.
Per creare un OneTimeWorkRequest
simile a quello sopra Job
, procedi nel seguente modo:
Kotlin
import androidx.work.* import java.util.concurrent.TimeUnit val constraints: Constraints = TODO("Define constraints as above") val request: Tell which work to execute OneTimeWorkRequestBuilder<MyWorker>() // Sets the input data for the ListenableWorker .setInputData(input) // If you want to delay the start of work by 60 seconds .setInitialDelay(60, TimeUnit.SECONDS) // Set a backoff criteria to be used when retry-ing .setBackoffCriteria(BackoffPolicy.EXPONENTIAL, 30000, TimeUnit.MILLISECONDS) // Set additional constraints .setConstraints(constraints) .build()
Java
import androidx.work.BackoffCriteria; import androidx.work.Constraints; import androidx.work.Constraints.Builder; import androidx.work.NetworkType; import androidx.work.OneTimeWorkRequest; import androidx.work.OneTimeWorkRequest.Builder; import androidx.work.Data; // Define constraints (as above) Constraints constraints = ... OneTimeWorkRequest request = // Tell which work to execute new OneTimeWorkRequest.Builder(MyWorker.class) // Sets the input data for the ListenableWorker .setInputData(inputData) // If you want to delay the start of work by 60 seconds .setInitialDelay(60, TimeUnit.SECONDS) // Set a backoff criteria to be used when retry-ing .setBackoffCriteria(BackoffCriteria.EXPONENTIAL, 30000, TimeUnit.MILLISECONDS) // Set additional constraints .setConstraints(constraints) .build();
La differenza principale qui è che i job di WorkManager vengono sempre resi persistenti su tutto il dispositivo e, in questo caso, viene riavviato automaticamente.
Se vuoi creare un PeriodicWorkRequest
, puoi procedere come segue:
Kotlin
val constraints: Constraints = TODO("Define constraints as above") val request: PeriodicWorkRequest = PeriodicWorkRequestBuilder<MyWorker>(15, TimeUnit.MINUTES) // Sets the input data for the ListenableWorker .setInputData(input) // Other setters .build()
Java
import androidx.work.BackoffCriteria; import androidx.work.Constraints; import androidx.work.Constraints.Builder; import androidx.work.NetworkType; import androidx.work.PeriodicWorkRequest; import androidx.work.PeriodicWorkRequest.Builder; import androidx.work.Data; // Define constraints (as above) Constraints constraints = ... PeriodicWorkRequest request = // Executes MyWorker every 15 minutes new PeriodicWorkRequest.Builder(MyWorker.class, 15, TimeUnit.MINUTES) // Sets the input data for the ListenableWorker .setInputData(input) . // other setters (as above) .build();
Programmazione del lavoro
Ora che hai definito Worker
e WorkRequest
, puoi
programmare il lavoro.
Ogni Job
definito con FirebaseJobDispatcher
aveva un tag
che è stato utilizzato per
identificare in modo univoco un Job
. Inoltre, ha permesso all'applicazione di indicare allo scheduler se questa istanza di Job
dovesse sostituire una copia esistente di Job
chiamando setReplaceCurrent
.
Kotlin
val job = dispatcher.newJobBuilder() // the JobService that will be called .setService(MyService::class.java) // uniquely identifies the job .setTag("my-unique-tag") // don't overwrite an existing job with the same tag .setRecurring(false) // Other setters... .build()
Java
Job myJob = dispatcher.newJobBuilder() // the JobService that will be called .setService(MyJobService.class) // uniquely identifies the job .setTag("my-unique-tag") // don't overwrite an existing job with the same tag .setReplaceCurrent(false) // other setters // ... dispatcher.mustSchedule(myJob);
Quando utilizzi WorkManager, puoi ottenere lo stesso risultato utilizzando
le API enqueueUniqueWork()
e enqueueUniquePeriodicWork()
(se utilizzi rispettivamente
OneTimeWorkRequest
e PeriodicWorkRequest
). Per ulteriori informazioni, consulta le pagine di riferimento per WorkManager.enqueueUniqueWork()
e WorkManager.enqueueUniquePeriodicWork()
.
Sarà simile a questo:
Kotlin
import androidx.work.* val request: "A WorkRequest") WorkManager.getInstance(myContext) .enqueueUniqueWork("my-unique-name", ExistingWorkPolicy.KEEP, request)
Java
import androidx.work.ExistingWorkPolicy; import androidx.work.OneTimeWorkRequest; import androidx.work.WorkManager; OneTimeWorkRequest workRequest = // a WorkRequest; WorkManager.getInstance(myContext) // Use ExistingWorkPolicy.REPLACE to cancel and delete any existing pending // (uncompleted) work with the same unique name. Then, insert the newly-specified // work. .enqueueUniqueWork("my-unique-name", ExistingWorkPolicy.KEEP, workRequest);
Annullamento lavoro
Con FirebaseJobDispatcher
puoi annullare il lavoro utilizzando:
Kotlin
dispatcher.cancel("my-unique-tag")
Java
dispatcher.cancel("my-unique-tag");
Quando usi WorkManager puoi usare:
Kotlin
import androidx.work.WorkManager WorkManager.getInstance(myContext).cancelUniqueWork("my-unique-name")
Java
import androidx.work.WorkManager; WorkManager.getInstance(myContext).cancelUniqueWork("my-unique-name");
Inizializzazione di WorkManager
In genere WorkManager si inizializza automaticamente utilizzando un ContentProvider
.
Se hai bisogno di un maggiore controllo sul funzionamento di WorkManager che organizza e pianifica il funzionamento, puoi personalizzare la configurazione e l'inizializzazione di WorkManager.