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:

Kotlin

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)

Java

// 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:

Kotlin

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

Java

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.

Catatan: Anda mungkin telah menambahkan logika ke GcmTaskService untuk melakukan beberapa pekerjaan sebelum mengirim tugas ke pengendali. Pada kasus ini, Anda perlu memfaktorkan ulang dan memindahkan logika tersebut ke dalam class Worker yang Anda tentukan di bagian berikutnya.

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.

Catatan: Di GCMNetworkManager, tugas mendefinisikan pekerjaan yang ingin dilakukan, dan kapan tugas harus dijalankan. Dengan library WorkManager, Anda menggunakan dua class berbeda untuk mendefinisikan elemen ini. Worker mendefinisikan tugas yang ingin Anda lakukan, saat membuat WorkRequest, tentukan batasan kapan tugas akan dijalankan.

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

Kotlin

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

Java

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.

Kotlin

val uploadConstraints = Constraints.Builder()
    .setRequiredNetworkType(NetworkType.CONNECTED)
    .setRequiresCharging(true).build()

val uploadTask = OneTimeWorkRequestBuilder<UploadWorker>()
    .setConstraints(uploadConstraints)
    .build()
WorkManager.getInstance().enqueue(uploadTask)

Java

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

Catatan: Dengan GCMNetworkManager, setiap tugas harus memiliki tag unik. Konstruksi WorkManager semacam ini adalah ID WorkRequest. ID ini ditetapkan secara otomatis oleh WorkManager saat permintaan dibuat; Anda mendapatkan ID dengan memanggil WorkRequest.getId(). WorkManager juga memungkinkan Anda menentukan tag untuk tugas, tetapi sifatnya berbeda dengan tag GCMNetworkManager karena tag ini tidak harus unik; Anda mungkin memiliki beberapa tugas WorkManager serupa, semuanya diantrekan sekaligus, dan semuanya menggunakan tag yang sama.

Catatan: GCMNetworkManager mengharuskan Anda menentukan jendela eksekusi, tetapi WorkManager tidak perlu ini. Sebaliknya, WorkManager akan menjalankan tugas secepatnya setelah batasan terpenuhi. Dalam contoh ini, kami asumsikan Anda sebenarnya tidak perlu menetapkan waktu tertentu agar tugas dapat dijalankan.

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.

Catatan: GCMNetworkManager memungkinkan Anda menentukan jendela eksekusi tertentu untuk tugas. Tidak ada fungsi yang setara di WorkManager. Jika perlu melakukan pekerjaan pada waktu yang tepat, sebaiknya gunakan opsi lain, seperti AlarmManager.

Batasan GCMNetworkManager	WorkManager yang setara	Notes
setPersisted()	(tidak wajib)	Semua tugas WorkManager dipertahankan saat reboot perangkat
setRequiredNetwork()	setRequiredNetworkType()	Secara default, GCMNetworkManager perlu akses jaringan. Sedangkan, WorkManager tidak perlu akses jaringan. Jika tugas Anda perlu akses jaringan, Anda harus menggunakan setRequiredNetworkType(CONNECTED), atau tentukan beberapa jenis jaringan yang lebih spesifik.
setRequiresCharging()

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.