Memigrasikan dari GCMNetworkManager ke WorkManager

Dokumen ini menjelaskan cara memigrasikan aplikasi agar menggunakan library klien WorkManager untuk melakukan operasi latar belakang, bukan library GCMNetworkManager. Cara yang lebih disukai agar aplikasi dapat menjadwalkan tugas latar belakang adalah menggunakan WorkManager. Dengan menyertakan library GCM WorkManager juga, Anda dapat mengaktifkan WorkManager untuk menggunakan GCM guna menjadwalkan tugas saat berjalan di perangkat Android yang menjalankan API level 22 atau yang lebih lama.

Bermigrasi ke WorkManager

Jika saat ini aplikasi Anda menggunakan GCMNetworkManager untuk melakukan operasi latar belakang, ikuti langkah-langkah ini untuk bermigrasi ke WorkManager.

Pada langkah ini, kami asumsikan Anda memulai dengan kode GCMNetworkManager berikut, yang menentukan dan menjadwalkan tugas:

 val myTask = OneoffTask.Builder()     // setService() says what class does the work     .setService(MyUploadService::class.java)     // Don't run the task unless device is charging     .setRequiresCharging(true)     // Run the task between 5 & 15 minutes from now     .setExecutionWindow(5 * DateUtil.MINUTE_IN_SECONDS,             15 * DateUtil.MINUTE_IN_SECONDS)     // Define a unique tag for the task     .setTag("test-upload")     // ...finally, build the task and assign its value to myTask     .build() GcmNetworkManager.getInstance(this).schedule(myTask)

 // In GcmNetworkManager, this call defines the task and its // runtime constraints: OneoffTask myTask = new OneoffTask.Builder()     // setService() says what class does the work     .setService(MyUploadService.class)     // Don't run the task unless device is charging     .setRequiresCharging(true)     // Run the task between 5 & 15 minutes from now     .setExecutionWindow(         5 * DateUtil.MINUTE_IN_SECONDS,         15 * DateUtil.MINUTE_IN_SECONDS)     // Define a unique tag for the task     .setTag("test-upload")     // ...finally, build the task and assign its value to myTask     .build(); GcmNetworkManager.getInstance(this).schedule(myTask);

Pada contoh ini, kami asumsikan MyUploadService mendefinisikan operasi upload yang sesungguhnya:

 class MyUploadService : GcmTaskService() {     fun onRunTask(params: TaskParams): Int {         // Do some upload work         return GcmNetworkManager.RESULT_SUCCESS     } }

 class MyUploadService extends GcmTaskService {     @Override     public int onRunTask(TaskParams params) {         // Do some upload work         return GcmNetworkManager.RESULT_SUCCESS;     } }

Menyertakan library WorkManager

Untuk menggunakan class WorkManager, Anda perlu menambahkan library WorkManager ke dependensi build. Anda juga perlu menambahkan library GCM WorkManager, yang memungkinkan WorkManager menggunakan GCM untuk penjadwalan tugas saat aplikasi Anda berjalan pada perangkat yang tidak mendukung JobScheduler (yaitu, perangkat yang menjalankan API level 22 atau yang lebih lama). Untuk mengetahui detail lengkap tentang menambahkan library, lihat Mulai Menggunakan WorkManager.

Mengubah manifes Anda

Setelah menerapkan GCMNetworkManager, Anda menambahkan instance GcmTaskService ke manifes aplikasi, seperti yang dijelaskan dalam dokumentasi referensi GcmNetworkManager. GcmTaskService melihat tugas yang masuk dan mendelegasikannya ke pengendali tugas. WorkManager mengelola delegasi tugas untuk Worker, sehingga Anda tidak lagi membutuhkan class yang melakukan hal ini; cukup hapus GcmTaskService dari manifes.

Menentukan Worker

Penerapan GCMNetworkManager Anda menentukan OneoffTask atau RecurringTask, yang menetapkan pekerjaan apa yang harus dilakukan. Anda perlu menulis ulang kode tersebut sebagai Worker, seperti yang didokumentasikan dalam Menentukan permintaan pekerjaan Anda.

Contoh kode GCMNetworkManager mendefinisikan tugas myTask. WorkManager yang setara terlihat seperti ini:

 class UploadWorker(context: Context, params: WorkerParameters)                         : Worker(context, params) {     override fun doWork() : Result {         // Do the upload operation ...         myUploadOperation()          // Indicate whether the task finished successfully with the Result         return Result.success()     } }

 public class UploadWorker extends Worker {      public UploadWorker(         @NonNull Context context,         @NonNull WorkerParameters params) {         super(context, params);     }      @Override     public Result doWork() {       // Do the upload operation ...        myUploadOperation()        // Indicate whether the task finished successfully with the Result       return Result.success()     } }

Ada beberapa perbedaan antara tugas GCM dan Worker:

• GCM menggunakan objek TaskParams untuk meneruskan parameter ke tugas. WorkManager menggunakan data input, yang dapat Anda tentukan pada WorkRequest, seperti yang dijelaskan dalam dokumentasi WorkManager untuk Menentukan input/output untuk tugas Anda. Pada kedua kasus ini, Anda dapat meneruskan key-value pair yang mencantumkan parameter yang dapat dipertahankan apa pun yang diperlukan tugas.
• GcmTaskService menandakan berhasil atau tidaknya dengan menampilkan flag seperti GcmNetworkManager.RESULT_SUCCESS. Worker WorkManager menandai hasilnya menggunakan metode ListenableWorker.Result seperti ListenableWorker.Result.success(), dan menampilkan nilai pengembalian metode tersebut.
• Seperti yang telah disebutkan, jangan menetapkan batasan atau tag saat menentukan Worker; sebagai gantinya, lakukan hal ini pada langkah berikutnya saat membuat WorkRequest.

Menjadwalkan permintaan pekerjaan

Mendefinisikan Worker akan menentukan apa yang perlu Anda lakukan. Untuk menentukan kapan pekerjaan harus dilakukan, Anda harus mendefinisikan WorkRequest:

1. Buat OneTimeWorkRequest atau PeriodicWorkRequest, dan tetapkan batasan yang diinginkan yang menentukan kapan tugas harus dijalankan, serta tag untuk mengidentifikasi pekerjaan.
2. Teruskan permintaan ke WorkManager.enqueue() agar tugas diantrekan untuk dieksekusi.

Misalnya, bagian sebelumnya menunjukkan cara mengonversi OneoffTask menjadi Worker yang setara. Namun, Worker tersebut tidak menyertakan tag dan batasan eksekusi objek OneoffTask. Sebagai gantinya, kami tetapkan batasan dan ID tugas saat membuat WorkRequest. Kami juga akan tentukan bahwa tugas tidak boleh berjalan kecuali ada koneksi jaringan. Anda tidak perlu secara eksplisit meminta koneksi jaringan pada GCMNetworkManager, karena GCMNetworkManager perlu koneksi jaringan secara default, tetapi WorkManager tidak perlu koneksi jaringan kecuali Anda secara khusus menambahkan batasan tersebut. Setelah mendefinisikan WorkRequest, kami akan mengantrekannya dengan WorkManager.

 val uploadConstraints = Constraints.Builder()     .setRequiredNetworkType(NetworkType.CONNECTED)     .setRequiresCharging(true).build()  val uploadTask = OneTimeWorkRequestBuilder<UploadWorker>()     .setConstraints(uploadConstraints)     .build() WorkManager.getInstance().enqueue(uploadTask)

 Constraints uploadConstraints = new Constraints.Builder()     .setRequiredNetworkType(NetworkType.CONNECTED)     .setRequiresCharging(true)     .build();  OneTimeWorkRequest uploadTask =         new OneTimeWorkRequest.Builder(UploadWorker.class)   .setConstraints(uploadConstraints)   .build(); WorkManager.getInstance().enqueue(uploadTask);

Pemetaan API

Bagian ini menjelaskan cara beberapa batasan dan fitur GCMNetworkManager dipetakan ke WorkManager yang setara.

Pemetaan batasan

GCMNetworkManager memungkinkan Anda menetapkan sejumlah batasan pada saat tugas Anda harus dijalankan. Biasanya, ada batasan WorkManager setara yang jelas. Bagian ini mencantumkan kesetaraan tersebut.

Tetapkan batasan pada tugas GCMNetworkManager dengan memanggil metode yang sesuai pada objek Builder tugas; misalnya, Anda dapat menetapkan persyaratan jaringan dengan memanggil Task.Builder.setRequiredNetwork().

Di WorkManager, Anda membuat objek Constraints.Builder dan memanggil metode objek tersebut untuk menetapkan batasan misalnya, Constraints.Builder.setRequiredNetworkType()), lalu menggunakan Builder untuk membuat objek Constraints yang dapat ditambahkan ke permintaan pekerjaan. Untuk informasi selengkapnya, lihat Menentukan permintaan pekerjaan Anda.

Pemetaan lainnya

Selain batasan, ada setelan lain yang dapat Anda terapkan ke tugas GCMNetworkManager. Bagian ini mencantumkan cara yang sesuai untuk menerapkan setelan tersebut ke tugas WorkManager.

Tag

Semua tugas GCMNetworkManager harus memiliki string tag, yang Anda tetapkan dengan memanggil metode setTag() Builder. Tugas WorkManager diidentifikasi secara unik oleh ID, yang otomatis dibuat oleh WorkManager; Anda dapat memperoleh ID tersebut dengan memanggil WorkRequest.getId(). Selain itu, permintaan pekerjaan dapat secara opsional memiliki satu atau beberapa tag. Untuk menetapkan tag bagi tugas WorkManager, panggil metode WorkRequest.Builder.addTag() sebelum menggunakan Builder tersebut untuk membuat WorkRequest.

Di GCMNetworkManager, Anda dapat memanggil setUpdateCurrent() untuk menentukan apakah tugas harus mengganti tugas yang ada dengan tag yang sama. Pendekatan WorkManager yang setara adalah mengantrekan tugas dengan memanggil enqueueUniqueWork() atau enqueueUniquePeriodicWork(); jika menggunakan metode ini, berikan nama unik untuk tugas, dan juga tentukan cara WorkManager menangani permintaan jika sudah ada tugas yang tertunda dengan nama tersebut. Untuk informasi selengkapnya, lihat Menangani pekerjaan unik.

Parameter tugas

Anda dapat meneruskan parameter ke tugas GCMNetworkManager dengan memanggil Task.Builder.setExtras() dan meneruskan Bundle yang berisi parameter. WorkManager memungkinkan Anda meneruskan objek Data ke tugas WorkManager, yang berisi parameter sebagai key-value pair. Untuk mengetahui detailnya, lihat Menetapkan data input.