从 Firebase JobDispatcher 迁移到 WorkManager

WorkManager 是一个用于在 Android 中调度和执行可延迟后台工作的库。它是 Firebase JobDispatcher 的推荐替代方案。以下指南将引导您完成将 Firebase JobDispatcher 实现迁移到 WorkManager 的过程。

Gradle 设置

要将 WorkManager 库导入您的 Android 项目，请添加 WorkManager 入门中列出的依赖项。

从 JobService 到 Worker

FirebaseJobDispatcher 使用 JobService 的子类作为定义所需工作的入口点。您可能直接使用 JobService，也可能使用 SimpleJobService。

一个 JobService 大致如下所示

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?"
    }
}

如果您使用的是 SimpleJobService，您将重写 onRunJob()，它会返回一个 @JobResult int 类型。

主要区别在于，当您直接使用 JobService 时，onStartJob() 会在主线程上调用，并且应用有责任将工作分流到后台线程。另一方面，如果您使用的是 SimpleJobService，则该服务负责在后台线程上执行您的工作。

WorkManager 具有类似的概念。WorkManager 中工作的基本单元是 ListenableWorker。还有其他有用的 Worker 子类型，例如 Worker、RxWorker 和 CoroutineWorker（在使用 Kotlin 协程时）。

JobService 映射到 ListenableWorker

如果您直接使用 JobService，则它映射到的 Worker 是 ListenableWorker。如果您使用的是 SimpleJobService，则应改用 Worker。

让我们使用上面的示例（MyJobService），看看如何将其转换为 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.
  }
}

WorkManager 中工作的基本单元是 ListenableWorker。就像 JobService.onStartJob() 一样，startWork() 在主线程上调用。这里 MyWorker 实现了 ListenableWorker 并返回一个 ListenableFuture 实例，该实例用于异步通知工作完成。您应该在此处选择自己的线程策略。

这里的 ListenableFuture 最终会返回一个 ListenableWorker.Result 类型，它可以是 Result.success()、Result.success(Data outputData)、Result.retry()、Result.failure() 或 Result.failure(Data outputData) 之一。如需了解详情，请参阅 ListenableWorker.Result 的参考页面。

调用 onStopped() 表示 ListenableWorker 需要停止，这可能是因为不再满足约束条件（例如，网络不再可用），或者因为调用了 WorkManager.cancel…() 方法。如果操作系统因某种原因决定终止您的工作，也可能会调用 onStopped()。

SimpleJobService 映射到 Worker

使用 SimpleJobService 时，上面的 worker 将如下所示

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.
  }
}

这里 doWork() 返回一个 ListenableWorker.Result 实例，以同步通知工作完成。这与 SimpleJobService 类似，后者在后台线程上调度作业。

JobBuilder 映射到 WorkRequest

FirebaseJobBuilder 使用 Job.Builder 来表示 Job 元数据。WorkManager 使用 WorkRequest 来承担此角色。

WorkManager 有两种 WorkRequest 类型：OneTimeWorkRequest 和 PeriodicWorkRequest。

如果您当前正在使用 Job.Builder.setRecurring(true)，则应创建一个新的 PeriodicWorkRequest。否则，您应该使用 OneTimeWorkRequest。

让我们看看使用 FirebaseJobDispatcher 调度一个复杂 Job 的示例

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);

要使用 WorkManager 实现相同的功能，您需要

构建可作为 Worker 输入的输入数据。
使用输入数据和与 FirebaseJobDispatcher 上述定义类似的约束条件构建 WorkRequest。
将 WorkRequest 加入队列。

为 Worker 设置输入

FirebaseJobDispatcher 使用 Bundle 将输入数据发送到 JobService。WorkManager 改用 Data。因此，它变为

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

为 Worker 设置约束

FirebaseJobDispatcher 使用 Job.Builder.setConstaints(...) 来设置作业的约束。WorkManager 改用 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();

创建 WorkRequest（一次性或周期性）

要创建 OneTimeWorkRequest 和 PeriodicWorkRequest，您应该使用 OneTimeWorkRequest.Builder 和 PeriodicWorkRequest.Builder。

要创建一个与上述 Job 类似的 OneTimeWorkRequest，您应该执行以下操作

Kotlin

import androidx.work.*
import java.util.concurrent.TimeUnit

val constraints: Constraints = TODO("Define constraints as above")
val request: OneTimeWorkRequest =
     // 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();

这里的关键区别在于 WorkManager 的作业在设备重启后始终会自动持久化。

如果要创建 PeriodicWorkRequest，您可以这样做

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

调度工作

既然您已经定义了 Worker 和 WorkRequest，您就可以开始调度工作了。

使用 FirebaseJobDispatcher 定义的每个 Job 都有一个 tag，用于唯一标识一个 Job。它还提供了一种方式，让应用程序通过调用 setReplaceCurrent 来告知调度器此 Job 实例是否替换现有 Job 的副本。

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);

使用 WorkManager 时，您可以使用 enqueueUniqueWork() 和 enqueueUniquePeriodicWork() API 实现相同的结果（分别用于 OneTimeWorkRequest 和 PeriodicWorkRequest）。如需了解详情，请参阅 WorkManager.enqueueUniqueWork() 和 WorkManager.enqueueUniquePeriodicWork() 的参考页面。

示例如下所示

Kotlin

import androidx.work.*

val request: OneTimeWorkRequest = TODO("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);

取消工作

使用 FirebaseJobDispatcher，您可以使用以下方式取消工作

Kotlin

dispatcher.cancel("my-unique-tag")

Java

dispatcher.cancel("my-unique-tag");

使用 WorkManager 时，您可以使用

Kotlin

import androidx.work.WorkManager
WorkManager.getInstance(myContext).cancelUniqueWork("my-unique-name")

Java

import androidx.work.WorkManager;
WorkManager.getInstance(myContext).cancelUniqueWork("my-unique-name");

初始化 WorkManager

WorkManager 通常会通过使用 ContentProvider 来自行初始化。如果您需要更多地控制 WorkManager 组织和调度工作的方式，您可以自定义 WorkManager 配置和初始化。

从 Firebase JobDispatcher 迁移到 WorkManager 利用收藏集整理内容 根据您的偏好保存和分类内容。

Gradle 设置

从 JobService 到 Worker

Kotlin

Java

JobService 映射到 ListenableWorker

Kotlin

Java

SimpleJobService 映射到 Worker

Kotlin

Java

JobBuilder 映射到 WorkRequest

Kotlin

Java

为 Worker 设置输入

Kotlin

Java

为 Worker 设置约束

Kotlin

Java

创建 WorkRequest（一次性或周期性）

Kotlin

Java

Kotlin

Java

调度工作

Kotlin

Java

Kotlin

Java

取消工作

Kotlin

Java

Kotlin

Java

初始化 WorkManager

从 Firebase JobDispatcher 迁移到 WorkManager