Migrazione da GCMNetworkManager a WorkManager

Questo documento spiega come eseguire la migrazione delle app per utilizzare la libreria client di WorkManager per eseguire operazioni in background al posto della libreria GCMNetworkManager. La il modo migliore per un'app di pianificare i job in background è utilizzare WorkManager. Di inclusa la libreria GCM di WorkManager, puoi consentire a WorkManager di utilizzare GCM per pianificare le attività quando vengono eseguite su dispositivi Android con livello API 22 o inferiore.

Esegui la migrazione a WorkManager

Se al momento la tua app utilizza GCMNetworkManager per eseguire operazioni in background, segui questi passaggi per eseguire la migrazione a WorkManager.

Per i passaggi successivi, supponiamo che tu stia iniziando con quanto segue: Codice GCMNetworkManager, che definisce e pianifica l'attività:

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

In questo esempio, supponiamo che MyUploadService definisca l'operazione di caricamento effettiva:

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

Includi le librerie di WorkManager

Per utilizzare i corsi WorkManager, devi aggiungere la libreria WorkManager al tuo e creare dipendenze. Devi aggiungere anche la libreria GCM di WorkManager, consente a WorkManager di utilizzare GCM per la pianificazione dei job quando l'app è in esecuzione Dispositivi che non supportano JobScheduler (ovvero dispositivi con livello API 22) o inferiore). Per informazioni dettagliate sull'aggiunta delle librerie, consulta la guida introduttiva all'utilizzo di WorkManager.

Modificare il manifest

Quando hai implementato GCMNetworkManager, hai aggiunto un'istanza di GcmTaskService al file manifest dell'app, come descritto in GcmNetworkManager documentazione di riferimento. GcmTaskService esamina l'attività in arrivo e la delega all'attività . WorkManager gestisce la delega delle attività per il tuo worker, così una classe che lo faccia; devi solo rimuovere GcmTaskService dal del file manifest.

Nota: potresti aver aggiunto una logica a GcmTaskService in precedenza per eseguire alcune operazioni dell'attività al gestore. In questo caso, occorre eseguire il refactoring e questa logica nella classe Worker che definisci nella prossima sezione.

Definisci il worker

L'implementazione di GCMNetworkManager definisce un valore OneoffTask o RecurringTask, che specifica solo il lavoro da svolgere. Devi riscriverlo come Worker, come documentato in Definizione del lavoro richieste di assistenza.

Nota: in GCMNetworkManager, l'attività definisce sia il lavoro che vuoi svolgere, sia quando deve essere eseguita l'attività. Con la libreria WorkManager, utilizzi due diversi per definire questi elementi. La Worker definisce l'attività da eseguire eseguire; quando crei WorkRequest, devi specificare qualsiasi valore e vincoli su quando deve essere eseguito il job.

Il file GCMNetworkManager di esempio codice definisce un'attività myTask. L'equivalente di WorkManager ha il seguente aspetto:

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

Esistono alcune differenze tra l'attività in GCM e l'Worker:

• GCM utilizza un oggetto TaskParams per passare parametri all'attività. La WorkManager utilizza dati di input, che puoi specificare su WorkRequest, come descritto nella documentazione WorkManager in merito alla definizione di input/output per dell'attività. In entrambi i casi, puoi passare coppie chiave/valore che specifichino i parametri richiesti dall'attività.
• L'elemento GcmTaskService segnala l'esito positivo o negativo grazie alla restituzione di flag come GcmNetworkManager.RESULT_SUCCESS. Un Worker di WorkManager indica i propri risultati utilizzando un ListenableWorker.Result come ListenableWorker.Result.success(), e restituendo il valore restituito da quel metodo.
• Come abbiamo detto prima, quando definisci i vincoli o i tag non devi Worker; dovrai eseguire questa operazione nel passaggio successivo, quando crei WorkRequest.

Programma la richiesta di lavoro

La definizione di un Worker specifica cosa devi fare. Per specificare quando il lavoro devi definire WorkRequest:

1. Crea una OneTimeWorkRequest o PeriodicWorkRequest, e impostare i vincoli desiderati per specificare quando eseguire l'attività, nonché eventuali tag per identificare il tuo lavoro.
2. Passa la richiesta a WorkManager.enqueue() in coda per l'esecuzione.

Ad esempio, la sezione precedente ha mostrato come convertire un OneoffTask a un Worker equivalente. Tuttavia, Worker non ha incluso i vincoli di esecuzione e il tag dell'oggetto OneoffTask. Impostiamo invece vincoli e ID attività quando creiamo WorkRequest. Specifica inoltre che l'attività non deve essere eseguita in assenza di una connessione di rete. Non è necessario richiedere esplicitamente una connessione di rete con GCMNetworkManager, dato che Per impostazione predefinita, GCMNetworkManager richiede una connessione di rete, al contrario di WorkManager non richiedono una connessione di rete, a meno che tu non aggiunga appositamente questo vincolo. Una volta definito il WorkRequest, lo accodaamo con 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);

Nota: con GCMNetworkManager, ogni attività deve avere un tag univoco. L'analoga Il costrutto WorkManager è l'ID WorkRequest. Questo ID viene impostato automaticamente da WorkManager al momento della creazione della richiesta. puoi ottenere l'ID chiamando WorkRequest.getId() Responsabile del lavoro permette anche di definire i tag per i job, ma questi sono diversi tag GCMNetworkManager perché non devono essere univoci; potresti avere diverse attività WorkManager simili in coda contemporaneamente e tutte utilizzano lo stesso tag.

Nota: GCMNetworkManager richiede di definire una finestra di esecuzione, ma Questa operazione non è richiesta in WorkManager. WorkManager esegue il job non appena possibile dopo aver soddisfatto i vincoli. In questo esempio, supponiamo che di impostare un orario specifico per l'esecuzione del job.

Mappature API

Questa sezione descrive la mappatura di alcune funzionalità e vincoli di GCMNetworkManager agli equivalenti di WorkManager.

Mappature dei vincoli

GCMNetworkManager consente di impostare una serie di vincoli su quando l'attività deve vengono eseguiti tutti i test delle unità. Nella maggior parte dei casi, esiste un vincolo di WorkManager chiaramente equivalente. Questo che elenca gli equivalenti.

Imposta i vincoli per le attività di GCMNetworkManager richiamando il metodo appropriato in l'oggetto Builder dell'attività. Ad esempio, puoi impostare un requisito di rete chiamata al numero Task.Builder.setRequiredNetwork().

In WorkManager, crei un Oggetto Constraints.Builder e chiama i metodi di quell'oggetto per impostare vincoli (ad esempio, Constraints.Builder.setRequiredNetworkType()), e usare Builder per creare un oggetto Vincoli da collegare al richiesta di lavoro. Per ulteriori informazioni, consulta la sezione Definizione del lavoro richieste.

Nota: GCMNetworkManager consente di specificare una finestra di esecuzione specifica per l'attività. Non esiste una funzionalità equivalente in WorkManager. Per lavorare in un momento preciso, ti consigliamo di utilizzare altre opzioni, AlarmManager

.

Vincolo GCMNetworkManager	Equivalente WorkManager	Note
setPersisted()	(non obbligatorio)	Tutti i job WorkManager vengono resi persistenti tra i riavvii del dispositivo
setRequiredNetwork()	setRequiredNetworkType()	Per impostazione predefinita, GCMNetworkManager richiede l'accesso alla rete. WorkManager non richiede l'accesso alla rete per impostazione predefinita. Se il job richiede l'accesso alla rete, devi usare setRequiredNetworkType(CONNECTED) o impostare un tipo di rete più specifico.
setRequiresCharging()

Altre mappature

Oltre ai vincoli, ci sono altre impostazioni che puoi applicare a GCMNetworkManager attività di machine learning. In questa sezione viene elencato il modo corrispondente per applicare queste impostazioni a un Job WorkManager.

Tag

Tutte le attività GCMNetworkManager devono avere una stringa tag, che viene impostata richiamando il metodo Builder setTag() . I job WorkManager sono identificati in modo univoco da un ID, che generate automaticamente da WorkManager; puoi ottenerlo chiamando WorkRequest.getId() Nella Inoltre, le richieste di lavoro possono facoltativamente avere uno o più tag. Per impostare un tag per il tuo job WorkManager, richiama WorkRequest.Builder.addTag() , prima di utilizzare quel Builder per creare WorkRequest.

In GCMNetworkManager puoi chiamare setUpdateCurrent() per specificare se l'attività deve sostituire qualsiasi attività esistente con lo stesso tag. L'approccio equivalente a WorkManager consiste nell'accodare l'attività chiamando enqueueUniqueWork() o enqueueUniquePeriodicWork(); Se utilizzi questi metodi, assegni al job un nome univoco e specifichi anche come WorkManager dovrebbe gestire la richiesta se esiste già un job in attesa con quel job nome. Per ulteriori informazioni, consulta la sezione Gestione Google Workspace.

Parametri attività

Puoi passare i parametri a un job GCMNetworkManager richiamando Task.Builder.setExtras() e passando un valore Bundle contenente i parametri. WorkManager ti consente di passare un oggetto Data al job WorkManager, contenente i parametri come chiave/valore in coppia. Per maggiori dettagli, vedi Assegna i dati di input.