Migracja z GCMNetworkManager do WorkManager

Ten dokument wyjaśnia, jak przenieść aplikacje, aby korzystały z biblioteki klienta WorkManager wykonywać operacje w tle, a nie korzystać z biblioteki GCMNetworkManager. Preferowanym sposobem planowania zadań w tle przez aplikację jest użycie WorkManagera. Według m.in. bibliotekę GCM, możesz włączyć w GCM do planowania zadań na urządzeniach z Androidem i interfejsem API na poziomie 22. lub niższy.

Migracja do WorkManagera

Jeśli Twoja aplikacja obecnie używa GCMNetworkManager do wykonywania operacji w tle, Wykonaj te czynności, aby przejść na platformę WorkManager.

W kolejnych krokach zakładamy, że zaczynasz od Kod GCMNetworkManager, który definiuje i planuje zadanie:

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

W tym przykładzie zakładamy, że MyUploadService definiuje rzeczywistą operację przesyłania:

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

Dołącz biblioteki WorkManagera

Aby używać klas WorkManager, musisz dodać bibliotekę WorkManager do swojej biblioteki zależności kompilacji. Musisz też dodać bibliotekę WorkManager GCM, umożliwia WorkManagerowi używanie GCM do planowania zadań, gdy aplikacja jest uruchomiona urządzenia, które nie obsługują funkcji JobScheduler (czyli urządzenia z interfejsem API na poziomie 22) lub niższy). Szczegółowe informacje o dodawaniu bibliotek znajdziesz w artykule Pierwsze kroki z WorkManager.

Modyfikowanie pliku manifestu

Podczas implementacji GCMNetworkManager dodano instancję GcmTaskService do pliku manifestu aplikacji, zgodnie z opisem w dokumencie GcmNetworkManager. dokumentacji referencyjnej. GcmTaskService sprawdza przychodzące zadanie i przekazuje je do zadania . WorkManager zarządza przekazywaniem zadań do instancji roboczej, więc nie możesz już potrzebują klasy, która to robi; po prostu usuń urządzenie GcmTaskService z pliku manifestu.

Uwaga: możliwe, że do GcmTaskService zostały dodane funkcje logiczne, które pozwalają wykonać pewne zadania przed wysyłanie zadania do modułu obsługi, W takim przypadku musisz dokonać refaktoryzacji i przeniesienia tę logikę do zdefiniowanej przez Ciebie klasy Worker w następnej sekcji.

Zdefiniuj instancję roboczą

Twoja implementacja GCMNetworkManager definiuje OneoffTask lub RecurringTask, który określa, co trzeba zrobić. Musisz to przepisać jako Worker, jak opisano w sekcji Definiowanie własnej pracy .

Uwaga: w usłudze GCMNetworkManager zadanie określa zarówno to, co chcesz zrobić, oraz kiedy ma być uruchamiane zadanie. W bibliotece WorkManager możesz używać 2 różnych klas definiujących te elementy. Worker określa zadanie, które chcesz wykonać realizować; podczas tworzenia WorkRequest, z ograniczeniami dotyczącymi czasu uruchamiania zadania.

Przykładowy plik GCMNetworkManager kod określa zadanie myTask. Odpowiednik w środowisku WorkManager wygląda tak:

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

Występuje kilka różnic między zadaniem GCM a Worker:

• GCM przekazuje parametry do zadania za pomocą obiektu TaskParams. Funkcja WorkManager używa danych wejściowych, które możesz określić w obiekcie WorkRequest, np. opisane w dokumentacji WorkManager dotyczącej definiowania wejścia/wyjścia dla Twoim zadaniem. W obu przypadkach możesz przekazywać pary klucz/wartość, określając dowolne parametry wymagane przez zadanie.
• GcmTaskService sygnalizuje sukces lub niepowodzenie, zwracając flagi takie jak GcmNetworkManager.RESULT_SUCCESS Aplikacja WorkManager Worker sygnalizuje swoje wyniki za pomocą ListenableWorker.Result. , np. ListenableWorker.Result.success(), i zwraca wartość zwracaną tej metody.
• Jak już wspomnieliśmy, nie określasz ograniczeń ani tagów przy definiowaniu Worker; zrobisz to w następnym kroku, podczas tworzenia WorkRequest

Planowanie zlecenia roboczego

Zdefiniowanie elementu Worker określa, co należy zrobić. Aby określić, kiedy utwór należy określić WorkRequest:

1. Tworzenie OneTimeWorkRequest lub PeriodicWorkRequest, oraz ustaw odpowiednie ograniczenia określające, kiedy zadanie ma być uruchamiane, a także znaczniki identyfikujące Twoją pracę.
2. Przekaż prośbę do WorkManager.enqueue() umieścić zadanie w kolejce do wykonania.

Na przykład w poprzedniej sekcji pokazaliśmy, jak przekonwertować OneoffTask równoważnej wartości Worker. W przypadku reguły Worker nie uwzględniono jednak ograniczenia wykonania obiektu OneoffTask oraz tag. Zamiast tego ustawimy parametr i identyfikatora zadania podczas tworzenia obiektu WorkRequest. Określimy też aby zadanie nie zostało uruchomione bez połączenia sieciowego. Nie potrzebujesz bezpośrednio zażądać połączenia sieciowego za pomocą GCMNetworkManager, ponieważ GCMNetworkManager domyślnie wymaga połączenia sieciowego, ale WorkManager wymaga nie wymagają połączenia sieciowego, chyba że dodasz to ograniczenie. Gdy zdefiniujesz usługę WorkRequest, umieścimy ją w kolejce w WorkManageru.

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

Uwaga: w usłudze GCMNetworkManager każde zadanie musi mieć unikalny tag. Analogiczne Konstrukcja WorkManager to identyfikator WorkRequest. Ten identyfikator jest ustawiany automatycznie przez WorkManagera po utworzeniu żądania; można uzyskać identyfikator, dzwoniąc WorkRequest.getId() Menedżer roboczy umożliwia także definiowanie tagów dla zadań, ale różnią się one od tagów Tagi GCMNetworkManager, bo nie muszą być unikalne. możesz mieć kilka Umieszczone w kolejce są podobne zadania WorkManagera jednocześnie i korzystają z tego samego tagu.

Uwaga: GCMNetworkManager wymaga zdefiniowania okna wykonania, ale WorkManager nie wymaga tego. Zamiast tego WorkManager uruchamia zadanie, gdy tylko jest możliwa po spełnieniu ograniczeń. W tym przykładzie zakładamy, że nie musisz musisz ustawić konkretny czas uruchomienia zadania.

Mapowania interfejsów API

W tej sekcji opisujemy, jak mapowane są niektóre funkcje i ograniczenia GCMNetworkManager na ich odpowiedniki z WorkManagera.

Mapowania ograniczeń

GCMNetworkManager pozwala ustawić różne ograniczenia dotyczące sytuacji, w których zadanie powinno bieganie. W większości przypadków istnieje wyraźne równoważne ograniczenie WorkManager. Ten zawiera ich listę.

Ustaw ograniczenia dotyczące zadań GCMNetworkManager, wywołując odpowiednią metodę w obiekt konstruktora zadania; Możesz na przykład określić wymagania dotyczące sieci, Wywołuję: Task.Builder.setRequiredNetwork().

W usłudze WorkManager tworzysz Constraints.Builder i wywołuje metody tego obiektu, aby ustawić ograniczenia (na przykład Constraints.Builder.setRequiredNetworkType()), a następnie za pomocą konstruktora utwórz obiekt Constraints, który będzie można dołączyć do w ramach pracy. Więcej informacji znajdziesz w artykule Definiowanie własnej pracy .

Uwaga: GCMNetworkManager umożliwia określenie konkretnego okna wykonywania Twoim zadaniem. W usłudze WorkManager nie ma odpowiednika funkcji. W razie potrzeby w określonym czasie, zalecamy użycie innych opcji, AlarmManager.

Ograniczenie GCMNetworkManager	Odpowiednik w usłudze WorkManager	Uwagi
setPersisted()	(niewymagane)	Wszystkie zadania WorkManager są zachowywane po ponownym uruchomieniu urządzenia
setRequiredNetwork()	setRequiredNetworkType()	Domyślnie GCMNetworkManager wymaga dostępu do sieci. WorkManager domyślnie nie wymaga dostępu do sieci. Jeśli Twoje zadanie wymaga dostępu do sieci, musisz użyć sieci setRequiredNetworkType(CONNECTED) lub ustawić bardziej szczegółowy typ sieci.
setRequiresCharging()

Inne mapowania

Oprócz ograniczeń w usłudze GCMNetworkManager możesz stosować też inne ustawienia. zadania. W tej sekcji znajdziesz informacje o sposobie stosowania tych ustawień do Zadanie WorkManager.

Tagi

Wszystkie zadania usługi GCMNetworkManager muszą zawierać ciąg tagu ustawiany przez wywołanie metody Budowniczy setTag() . Zadania WorkManager są jednoznacznie identyfikowane przez identyfikator, który jest: generowane automatycznie przez WorkManagera; można go uzyskać, dzwoniąc WorkRequest.getId() W żądania służbowe mogą opcjonalnie mieć jeden lub więcej tagów. Aby ustawić tag dla zadanie WorkManager, wywołaj funkcję WorkRequest.Builder.addTag() przed użyciem tego konstruktora do utworzenia WorkRequest.

W GCMNetworkManager możesz wywoływać setUpdateCurrent() , aby określić, czy zadanie ma zastąpić istniejące zadanie tym samym tagiem. Odpowiednikiem w usłudze WorkManager jest umieszczenie zadania w kolejce przez wywołanie enqueueUniqueWork() lub enqueueUniquePeriodicWork(); jeśli korzystasz z tych metod, nadajesz zadaniu unikalną nazwę, a także określasz, jak WorkManager powinien obsłużyć żądanie, jeśli istnieje już oczekujące zadanie z tym imię i nazwisko. Więcej informacji znajdziesz w sekcji Obsługa unikalnych użytkowników w pracy.

Parametry zadania

Parametry możesz przekazać do zadania GCMNetworkManager, wywołując Task.Builder.setExtras() i przekazywanie Bundle z parametrami. WorkManager pozwala przekazać obiekt Data do zadania WorkManager, który zawiera parametry jako para klucz-wartość pary. Więcej informacji: Przypisz dane wejściowe.