GCMNetworkManager'dan WorkManager'a taşıma

Bu dokümanda, arka plan işlemlerini gerçekleştirmek için GCMNetworkManager kitaplığı yerine WorkManager istemci kitaplığını kullanmak üzere uygulamaların nasıl taşınacağı açıklanmaktadır. Bir uygulamanın arka plan işlerini programlaması için tercih edilen yol WorkManager kullanmaktır. WorkManager GCM kitaplığını da ekleyerek, WorkManager'ın, API düzeyi 22 veya altını çalıştıran Android cihazlarda çalışırken görevleri planlamak için GCM'yi kullanmasını sağlayabilirsiniz.

WorkManager'a taşı

Uygulamanız şu anda arka plan işlemlerini gerçekleştirmek için GCMNetworkManager'ı kullanıyorsa, WorkManager'a geçiş için aşağıdaki adımları uygulayın.

Aşağıdaki adımlar için, görevinizi tanımlayan ve planlayan aşağıdaki GCMNetworkManager koduyla başladığınızı varsayıyoruz:

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

Bu örnekte, gerçek yükleme işleminin MyUploadService tarafından tanımlandığını varsayıyoruz:

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

WorkManager kitaplıklarını dahil et

WorkManager sınıflarını kullanmak için, derleme bağımlılıklarınıza WorkManager kitaplığını eklemeniz gerekir. Ayrıca, uygulamanız JobScheduler'ı desteklemeyen cihazlarda (yani API düzeyi 22 veya altını çalıştıran cihazlarda) çalışırken WorkManager'ın, iş planlaması için GCM'yi kullanmasını sağlayan WorkManager GCM kitaplığını eklemeniz gerekir. Kitaplık eklemeyle ilgili tüm ayrıntılar için WorkManager'ı kullanmaya başlama bölümüne bakın.

Manifest dosyanızı değiştirme

GCMNetworkManager'ı uyguladığınızda, GcmNetworkManager referans belgelerinde açıklandığı gibi uygulama manifestinize bir GcmTaskService örneği eklediniz. GcmTaskService, gelen göreve bakar ve görev işleyiciye yetki verir. WorkManager, Çalışanınıza görev yetkisini yönetir. Böylece artık bunu yapan bir sınıfa ihtiyacınız yoktur. Manifest'ten GcmTaskService öğenizi kaldırmanız yeterlidir.

Çalışanı tanımlayın

GCMNetworkManager uygulamanız, tam olarak hangi işin yapılması gerektiğini belirten bir OneoffTask veya RecurringTask tanımlar. Bunu İş taleplerinizi tanımlama bölümünde belirtildiği gibi Worker olarak yeniden yazmanız gerekiyor.

Örnek GCMNetworkManager kodu, bir myTask görevi tanımlar. WorkManager eşdeğeri şöyle görünür:

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

GCM görevi ile Worker arasında birkaç fark vardır:

  • GCM, parametreleri göreve geçirmek için bir TaskParams nesnesi kullanır. WorkManager, Göreviniz için giriş/çıkış tanımlama başlıklı WorkManager dokümanlarında açıklandığı gibi WorkRequest üzerinde belirtebileceğiniz giriş verilerini kullanır. Her iki durumda da, görevin ihtiyaç duyduğu kalıcı parametreleri belirten anahtar/değer çiftlerini aktarabilirsiniz.
  • GcmTaskService, GcmNetworkManager.RESULT_SUCCESS gibi işaretler döndürerek başarı veya başarısızlık sinyalini verir. WorkManager Worker, ListenableWorker.Result.success() gibi bir ListenableWorker.Result yöntemi kullanarak ve bu yöntemin döndürülen değerini döndürerek sonuçlarını bildirir.
  • Daha önce belirttiğimiz gibi, kısıtlamaları veya etiketleri Worker tanımlarken ayarlamazsınız; bunu bir sonraki adımda, yani WorkRequest oluşturduğunuzda ayarlarsınız.

İş isteğini programlama

Worker tanımlanması, ne yapmanız gerektiğini belirtir. İşin ne zaman yapılması gerektiğini belirtmek için WorkRequest öğesini tanımlamanız gerekir:

  1. Bir OneTimeWorkRequest veya PeriodicWorkRequest oluşturun ve görevin ne zaman çalıştırılması gerektiğini belirten istediğiniz kısıtlamaları ve işinizi tanımlayan etiketleri ayarlayın.
  2. Görevin yürütülmek üzere sıraya alınması için isteği WorkManager.enqueue()'e iletin.

Örneğin, önceki bölümde bir OneoffTask öğesinin eşdeğer Worker değerine nasıl dönüştürüleceği gösteriliyordu. Ancak bu Worker, OneoffTask nesnesinin yürütme kısıtlamalarını ve etiketini içermiyordu. Bunun yerine, WorkRequest oluştururken kısıtlamaları ve görev kimliğini belirleriz. Ayrıca, ağ bağlantısı olmadığı sürece görevin çalışmaması gerektiğini de belirteceğiz. GCMNetworkManager için varsayılan olarak ağ bağlantısı gerektiğinden, ancak WorkManager bu kısıtlamayı özel olarak eklemediğiniz sürece ağ bağlantısı gerektirmez. Bu nedenle, GCMNetworkManager ile açık bir şekilde ağ bağlantısı istemenize gerek yoktur. WorkRequest tanımlandıktan sonra WorkManager ile sıraya alınır.

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

API eşlemeleri

Bu bölümde, bazı GCMNetworkManager özellik ve kısıtlamalarının WorkManager eşdeğerleriyle nasıl eşlendiği açıklanmaktadır.

Kısıtlama eşlemeleri

GCMNetworkManager, görevinizin ne zaman çalışması gerektiğiyle ilgili bir dizi kısıtlama ayarlamanıza olanak tanır. Çoğu durumda net bir eşdeğer WorkManager kısıtlaması vardır. Bu bölümde bu eşdeğerleri listelenmektedir.

Görevin Builder nesnesinde uygun yöntemi çağırarak GCMNetworkManager görevlerinde kısıtlamalar belirleyin. Örneğin, Task.Builder.setRequiredNetwork() çağrısı yaparak bir ağ gereksinimi ayarlayabilirsiniz.

WorkManager'da bir Constraints.Builder nesnesi oluşturur ve kısıtlamalar belirlemek için bu nesnenin yöntemlerini çağırır (örneğin, Constraints.Builder.setRequiredNetworkType())), ardından Oluşturucu'yu kullanarak iş isteğine ekleyebileceğiniz bir Kısıtlamalar nesnesi oluşturabilirsiniz. Daha fazla bilgi için İş taleplerinizi tanımlama bölümüne bakın.

GCMNetworkManager kısıtlaması WorkManager eşdeğeri Notlar
setPersisted() (zorunlu değil) Tüm WorkManager işleri, cihaz yeniden başlatmalarında devam eder
setRequiredNetwork() setRequiredNetworkType() GCMNetworkManager varsayılan olarak ağ erişimi gerektirir. WorkManager varsayılan olarak ağ erişimi gerektirmez. İşiniz için ağ erişimi gerekiyorsa setRequiredNetworkType(CONNECTED) kullanmanız veya daha spesifik bir ağ türü ayarlamanız gerekir.
setRequiresCharging()

Diğer eşlemeler

Kısıtlamaların yanı sıra, GCMNetworkManager görevlerine uygulayabileceğiniz başka ayarlar da vardır. Bu bölümde, bu ayarları bir WorkManager işine uygulamanın ilgili yolu açıklanmaktadır.

Etiketler

Tüm GCMNetworkManager görevleri, Oluşturucu'nun setTag() yöntemini çağırarak ayarladığınız bir etiket dizesine sahip olmalıdır. WorkManager işleri, WorkManager tarafından otomatik olarak oluşturulan bir kimlikle benzersiz şekilde tanımlanır. Bu kimliği WorkRequest.getId() çağrısı yaparak alabilirsiniz. Buna ek olarak, iş istekleri isteğe bağlı olarak bir veya daha fazla etikete sahip olabilir. WorkManager işiniz için etiket ayarlamak isterseniz, WorkRequest öğesini oluşturmak için bu Oluşturucu'yu kullanmadan önce WorkRequest.Builder.addTag() yöntemini çağırın.

GCMNetworkManager'da, görevin mevcut herhangi bir görevi aynı etiketle değiştirip değiştirmeyeceğini belirtmek için setUpdateCurrent() çağırabilirsiniz. Eşdeğer WorkManager yaklaşımı, enqueueUniqueWork() veya enqueueUniquePeriodicWork() yöntemini çağırarak görevi sıraya koymaktır. Bu yöntemleri kullanırsanız işe benzersiz bir ad verir ve WorkManager'ın bu ada sahip bekleyen bir iş varsa isteği nasıl işlemesi gerektiğini belirtirsiniz. Daha fazla bilgi için Benzersiz işleri işleme bölümüne bakın.

Görev parametreleri

Task.Builder.setExtras() yöntemini çağırıp parametreleri içeren bir Bundle ileterek parametreleri GCMNetworkManager işine aktarabilirsiniz. WorkManager, parametreleri anahtar/değer çiftleri olarak içeren bir Data nesnesini WorkManager işine iletmenizi sağlar. Ayrıntılar için Giriş verilerini atama bölümüne bakın.