Pagina di rete e di database

Offri un'esperienza utente migliorata assicurandoti che la tua app possa essere utilizzata quando le connessioni di rete non sono affidabili o quando l'utente è offline. Un modo per farlo è eseguire la paginazione contemporaneamente dalla rete e da un database locale. In questo modo, l'app gestisce l'interfaccia utente da una cache del database locale ed effettua richieste alla rete solo quando non sono presenti altri dati nel database.

Questa guida presuppone che tu abbia familiarità con la libreria di persistenza Room e con l'utilizzo di base della libreria Paging.

Coordinare i caricamenti dei dati

La libreria Paging fornisce il RemoteMediator componente per questo caso d'uso. RemoteMediator funge da indicatore della libreria Paging quando l'app ha esaurito i dati memorizzati nella cache. Puoi utilizzare questo indicatore per caricare dati aggiuntivi dalla rete e memorizzarli nel database locale, dove un PagingSource può caricarli e fornirli all'interfaccia utente per la visualizzazione.

Quando sono necessari dati aggiuntivi, la libreria Paging chiama il load() metodo dall' implementazione RemoteMediator. Si tratta di una funzione di sospensione, quindi è sicuro eseguire operazioni a lunga esecuzione. In genere, questa funzione recupera i nuovi dati da un'origine di rete e li salva nello spazio di archiviazione locale.

Questa procedura funziona con i nuovi dati, ma nel tempo i dati archiviati nel database richiedono l'invalidazione, ad esempio quando l'utente attiva manualmente un aggiornamento. Questa operazione è rappresentata dalla LoadType proprietà passata al metodo load(). LoadType indica a RemoteMediator se deve aggiornare i dati esistenti o recuperare dati aggiuntivi da aggiungere o anteporre all'elenco esistente.

In questo modo, RemoteMediator garantisce che l'app carichi i dati che gli utenti vogliono visualizzare nell'ordine appropriato.

Ciclo di vita della paginazione

Quando la paginazione viene eseguita direttamente dalla rete, il PagingSource carica i dati e restituisce un LoadResult oggetto. L'PagingSource implementazione viene passata a Pager tramite il pagingSourceFactory parametro.

Quando l'interfaccia utente richiede nuovi dati, il Pager chiama il load() metodo dal PagingSource e restituisce uno stream di PagingData oggetti che incapsulano i nuovi dati. In genere, ogni oggetto PagingData viene memorizzato nella cache in ViewModel prima di essere inviato all'interfaccia utente per la visualizzazione.

RemoteMediator modifica questo flusso di dati. Un PagingSource carica ancora i dati, ma quando i dati paginati vengono esauriti, la libreria Paging attiva RemoteMediator per caricare nuovi dati dall'origine di rete. RemoteMediator memorizza i nuovi dati nel database locale, quindi una cache in memoria in ViewModel non è necessaria. Infine, PagingSource si invalida e Pager crea una nuova istanza per caricare i dati aggiornati dal database.

Utilizzo di base

Supponiamo che tu voglia che la tua app carichi pagine di elementi User da un'origine dati di rete con chiave elemento in una cache locale archiviata in un database Room.

Un'implementazione di RemoteMediator consente di caricare i dati paginati dalla rete nel database, ma non carica i dati direttamente nell'interfaccia utente. L'app utilizza invece il database come origine di riferimento. In altre parole, l'app visualizza solo i dati memorizzati nella cache del database. Un'implementazione di PagingSource (ad esempio, una generata da Room) gestisce il caricamento dei dati memorizzati nella cache dal database all'interfaccia utente.

Creare entità Room

Il primo passaggio consiste nell'utilizzare la libreria di persistenza Room per definire un database che contenga una cache locale di dati paginati dall'origine dati di rete. Inizia con un' implementazione di RoomDatabase come descritto in Salvare i dati in un database locale utilizzando Room.

Poi, definisci un'entità Room per rappresentare una tabella di elementi dell'elenco come descritto in Definire i dati utilizzando le entità Room. Assegna un campo id come chiave primaria, nonché campi per qualsiasi altra informazione contenuta negli elementi dell'elenco.

@Entity(tableName = "users")
data class User(val id: String, val label: String)

Devi anche definire un oggetto di accesso ai dati (DAO) per questa entità Room come descritto in Accedere ai dati utilizzando i DAO Room. Il DAO per l'entità dell'elemento dell'elenco deve includere i seguenti metodi:

• Un metodo insertAll() che inserisce un elenco di elementi nella tabella.
• Un metodo che accetta la stringa di query come parametro e restituisce un oggetto PagingSource per l'elenco dei risultati. In questo modo, un oggetto Pager può utilizzare questa tabella come origine di dati paginati.
• Un metodo clearAll() che elimina tutti i dati della tabella.

@Dao
interface UserDao {
  @Insert(onConflict = OnConflictStrategy.REPLACE)
  suspend fun insertAll(users: List<User>)

  @Query("SELECT * FROM users WHERE label LIKE :query")
  fun pagingSource(query: String): PagingSource<Int, User>

  @Query("DELETE FROM users")
  suspend fun clearAll()
}

Implementare un RemoteMediator

Il ruolo principale di RemoteMediator è caricare altri dati dalla rete quando Pager esaurisce i dati o i dati esistenti vengono invalidati. Include un metodo load() che devi sostituire per definire il comportamento di caricamento.

Una tipica implementazione di RemoteMediator include i seguenti parametri:

• query: una stringa di query che definisce i dati da recuperare dal servizio di backend.
• database: il database Room che funge da cache locale.
• networkService: un'istanza API per il servizio di backend.

Crea un'implementazione di RemoteMediator<Key, Value>. I tipi Key e Value devono essere gli stessi di quelli che utilizzeresti se stessi definendo un PagingSource rispetto alla stessa origine dati di rete. Per ulteriori informazioni sulla selezione dei parametri di tipo, consulta Selezionare i tipi di chiave e valore types.

@OptIn(ExperimentalPagingApi::class)
class ExampleRemoteMediator(
  private val query: String,
  private val database: RoomDb,
  private val networkService: ExampleBackendService
) : RemoteMediator<Int, User>() {
  val userDao = database.userDao()

  override suspend fun load(
    loadType: LoadType,
    state: PagingState<Int, User>
  ): MediatorResult {
    // ...
  }
}

Il metodo load() è responsabile dell'aggiornamento del set di dati di supporto e dell'invalidazione di PagingSource. Alcune librerie che supportano la paginazione (come Room) gestiscono automaticamente l'invalidazione degli oggetti PagingSource che implementano.

Il metodo load() accetta due parametri:

• PagingState, che contiene informazioni sulle pagine caricate finora, sull'indice a cui è stato eseguito l'accesso più di recente e sull'oggetto PagingConfig utilizzato per inizializzare lo stream di paginazione.
• LoadType, che indica il tipo di caricamento: REFRESH, APPEND o PREPEND.

Il valore restituito del metodo load() è un MediatorResult oggetto. MediatorResult può essere MediatorResult.Error (che include la descrizione dell'errore) o MediatorResult.Success (che include un indicatore che indica se sono presenti altri dati da caricare).

Il metodo load() deve eseguire i seguenti passaggi:

1. Determina la pagina da caricare dalla rete in base al tipo di caricamento e ai dati caricati finora.
2. Attiva la richiesta di rete.
3. Esegui le azioni in base al risultato dell'operazione di caricamento:
   • Se il caricamento ha esito positivo e l'elenco di elementi ricevuto non è vuoto, memorizza gli elementi dell'elenco nel database e restituisci MediatorResult.Success(endOfPaginationReached = false). Dopo aver memorizzato i dati, invalida l'origine dati per notificare alla libreria Paging i nuovi dati.
   • Se il caricamento ha esito positivo e l'elenco di elementi ricevuto è vuoto o è l'indice dell'ultima pagina, restituisci MediatorResult.Success(endOfPaginationReached = true). Dopo aver memorizzato i dati, invalida l'origine dati per notificare alla libreria Paging i nuovi dati.
   • Se la richiesta causa un errore, restituisci MediatorResult.Error.

override suspend fun load(
  loadType: LoadType,
  state: PagingState<Int, User>
): MediatorResult {
  return try {
    // The network load method takes an optional after=<user.id>
    // parameter. For every page after the first, pass the last user
    // ID to let it continue from where it left off. For REFRESH,
    // pass null to load the first page.
    val loadKey = when (loadType) {
      LoadType.REFRESH -> null
      // In this example, you never need to prepend, since REFRESH
      // will always load the first page in the list. Immediately
      // return, reporting end of pagination.
      LoadType.PREPEND ->
        return MediatorResult.Success(endOfPaginationReached = true)
      LoadType.APPEND -> {
        val lastItem = state.lastItemOrNull()

        // You must explicitly check if the last item is null when
        // appending, since passing null to networkService is only
        // valid for initial load. If lastItem is null it means no
        // items were loaded after the initial REFRESH and there are
        // no more items to load.
        if (lastItem == null) {
          return MediatorResult.Success(
            endOfPaginationReached = true
          )
        }

        lastItem.id
      }
    }

    // Suspending network load via Retrofit. This doesn't need to be
    // wrapped in a withContext(Dispatcher.IO) { ... } block since
    // Retrofit's Coroutine CallAdapter dispatches on a worker
    // thread.
    val response = networkService.searchUsers(
      query = query, after = loadKey
    )

    database.withTransaction {
      if (loadType == LoadType.REFRESH) {
        userDao.deleteByQuery(query)
      }

      // Insert new users into database, which invalidates the
      // current PagingData, allowing Paging to present the updates
      // in the DB.
      userDao.insertAll(response.users)
    }

    MediatorResult.Success(
      endOfPaginationReached = response.nextKey == null
    )
  } catch (e: IOException) {
    MediatorResult.Error(e)
  } catch (e: HttpException) {
    MediatorResult.Error(e)
  }
}

Definire il metodo initialize

Le implementazioni di RemoteMediator possono anche sostituire il initialize() metodo per verificare se i dati memorizzati nella cache non sono aggiornati e decidere se attivare un aggiornamento remoto. Questo metodo viene eseguito prima di qualsiasi caricamento, quindi puoi manipolare il database (ad esempio, per cancellare i dati precedenti) prima di attivare qualsiasi caricamento locale o remoto.

Poiché initialize() è una funzione asincrona, puoi caricare i dati per determinare la pertinenza dei dati esistenti nel database. Il caso più comune è che i dati memorizzati nella cache siano validi solo per un determinato periodo di tempo. RemoteMediator può verificare se questo tempo di scadenza è trascorso, nel qual caso la libreria Paging deve aggiornare completamente i dati. Le implementazioni di initialize() devono restituire un InitializeAction come segue:

• Nei casi in cui i dati locali devono essere aggiornati completamente, initialize() deve restituire InitializeAction.LAUNCH_INITIAL_REFRESH. In questo modo, RemoteMediator esegue un aggiornamento remoto per ricaricare completamente i dati. Tutti i caricamenti APPEND o PREPEND remoti attendono il completamento del caricamento REFRESH prima di procedere.
• Nei casi in cui i dati locali non devono essere aggiornati, initialize() deve restituire InitializeAction.SKIP_INITIAL_REFRESH. In questo modo, RemoteMediator salta l'aggiornamento remoto e carica i dati memorizzati nella cache.

override suspend fun initialize(): InitializeAction {
  val cacheTimeout = TimeUnit.MILLISECONDS.convert(1, TimeUnit.HOURS)
  return if (System.currentTimeMillis() - db.lastUpdated() <= cacheTimeout)
  {
    // Cached data is up-to-date, so there is no need to re-fetch
    // from the network.
    InitializeAction.SKIP_INITIAL_REFRESH
  } else {
    // Need to refresh cached data from network; returning
    // LAUNCH_INITIAL_REFRESH here will also block RemoteMediator's
    // APPEND and PREPEND from running until REFRESH succeeds.
    InitializeAction.LAUNCH_INITIAL_REFRESH
  }
}

Creare un Pager

Infine, devi creare un'istanza di Pager per configurare lo stream di dati paginati. Questa operazione è simile alla creazione di un Pager da un'origine dati di rete semplice, ma ci sono due cose che devi fare in modo diverso:

• Anziché passare direttamente un costruttore PagingSource, devi fornire il metodo di query che restituisce un oggetto PagingSource dal DAO.
• Devi fornire un'istanza dell'implementazione di RemoteMediator come parametro remoteMediator.

val userDao = database.userDao()
val pager = Pager(
  config = PagingConfig(pageSize = 50)
  remoteMediator = ExampleRemoteMediator(query, database, networkService)
) {
  userDao.pagingSource(query)
}

Gestire le race condition

Una situazione che la tua app deve gestire durante il caricamento dei dati da più origini è il caso in cui i dati memorizzati nella cache locale non sono sincronizzati con l'origine dati remota.

Quando il metodo initialize() dell'implementazione di RemoteMediator restituisce LAUNCH_INITIAL_REFRESH, i dati non sono aggiornati e devono essere sostituiti con dati aggiornati. Tutte le richieste di caricamento PREPEND o APPEND sono costrette ad attendere il completamento del caricamento REFRESH remoto. Poiché le richieste PREPEND o APPEND sono state messe in coda prima della richiesta REFRESH, è possibile che PagingState passato a queste chiamate di caricamento non sia aggiornato al momento dell'esecuzione.

A seconda di come i dati vengono archiviati localmente, la tua app può ignorare le richieste ridondanti se le modifiche ai dati memorizzati nella cache causano l'invalidazione e il recupero di nuovi dati. Ad esempio, Room invalida le query su qualsiasi inserimento di dati. Ciò significa che i nuovi oggetti PagingSource con i dati aggiornati vengono forniti alle richieste di caricamento in attesa quando vengono inseriti nuovi dati nel database.

La risoluzione di questo problema di sincronizzazione dei dati è essenziale per garantire che gli utenti vedano i dati più pertinenti e aggiornati. La soluzione migliore dipende principalmente dal modo in cui l'origine dati di rete pagina i dati. In ogni caso, chiavi remote ti consentono di salvare informazioni sulla pagina più recente richiesta dal server. La tua app può utilizzare queste informazioni per identificare e richiedere la pagina di dati corretta da caricare successivamente.

Gestire le chiavi remote

Le chiavi remote sono chiavi che un'implementazione di RemoteMediator utilizza per indicare al servizio di backend quali dati caricare successivamente. Nel caso più semplice, ogni elemento di dati paginati include una chiave remota a cui puoi fare riferimento facilmente. Tuttavia, se le chiavi remote non corrispondono a singoli elementi, devi memorizzarle separatamente e gestirle nel metodo load().

Questa sezione descrive come raccogliere, archiviare e aggiornare le chiavi remote che non sono archiviate in singoli elementi.

Chiavi elemento

Questa sezione descrive come utilizzare le chiavi remote che corrispondono a singoli elementi. In genere, quando un'API utilizza le chiavi per i singoli elementi, l'ID dell'elemento viene passato come parametro di query. Il nome del parametro indica se il server deve rispondere con gli elementi prima o dopo l'ID fornito. Nell'esempio della classe del modello User, il campo id del server viene utilizzato come chiave remota quando si richiedono dati aggiuntivi.

Quando il metodo load() deve gestire le chiavi remote specifiche dell'elemento, queste chiavi sono in genere gli ID dei dati recuperati dal server. Le operazioni di aggiornamento non richiedono una chiave di caricamento, perché recuperano solo i dati più recenti. Allo stesso modo, le operazioni di anteposizione non devono recuperare dati aggiuntivi perché l'aggiornamento recupera sempre i dati più recenti dal server.

Tuttavia, le operazioni di aggiunta richiedono un ID. Per questo, devi caricare l'ultimo elemento dal database e utilizzare il relativo ID per caricare la pagina di dati successiva. Se non sono presenti elementi nel database, endOfPaginationReached viene impostato su true, a indicare che è necessario un aggiornamento dei dati.

@OptIn(ExperimentalPagingApi::class)
class ExampleRemoteMediator(
  private val query: String,
  private val database: RoomDb,
  private val networkService: ExampleBackendService
) : RemoteMediator<Int, User>() {
  val userDao = database.userDao()

  override suspend fun load(
    loadType: LoadType,
    state: PagingState<Int, User>
  ): MediatorResult {
    return try {
      // The network load method takes an optional String
      // parameter. For every page after the first, pass the String
      // token returned from the previous page to let it continue
      // from where it left off. For REFRESH, pass null to load the
      // first page.
      val loadKey = when (loadType) {
        LoadType.REFRESH -> null
        // In this example, you never need to prepend, since REFRESH
        // will always load the first page in the list. Immediately
        // return, reporting end of pagination.
        LoadType.PREPEND -> return MediatorResult.Success(
          endOfPaginationReached = true
        )
        // Get the last User object id for the next RemoteKey.
        LoadType.APPEND -> {
          val lastItem = state.lastItemOrNull()

          // You must explicitly check if the last item is null when
          // appending, since passing null to networkService is only
          // valid for initial load. If lastItem is null it means no
          // items were loaded after the initial REFRESH and there are
          // no more items to load.
          if (lastItem == null) {
            return MediatorResult.Success(
              endOfPaginationReached = true
            )
          }

          lastItem.id
        }
      }

      // Suspending network load via Retrofit. This doesn't need to
      // be wrapped in a withContext(Dispatcher.IO) { ... } block
      // since Retrofit's Coroutine CallAdapter dispatches on a
      // worker thread.
      val response = networkService.searchUsers(query, loadKey)

      // Store loaded data, and next key in transaction, so that
      // they're always consistent.
      database.withTransaction {
        if (loadType == LoadType.REFRESH) {
          userDao.deleteByQuery(query)
        }

        // Insert new users into database, which invalidates the
        // current PagingData, allowing Paging to present the updates
        // in the DB.
        userDao.insertAll(response.users)
      }

      // End of pagination has been reached if no users are returned from the
      // service
      MediatorResult.Success(
        endOfPaginationReached = response.users.isEmpty()
      )
    } catch (e: IOException) {
      MediatorResult.Error(e)
    } catch (e: HttpException) {
      MediatorResult.Error(e)
    }
  }
}

Chiavi pagina

Questa sezione descrive come utilizzare le chiavi remote che non corrispondono a singoli elementi.

Aggiungere la tabella delle chiavi remote

Quando le chiavi remote non sono associate direttamente agli elementi dell'elenco, è consigliabile memorizzarle in una tabella separata nel database locale. Definisci un'entità Room che rappresenta una tabella di chiavi remote:

@Entity(tableName = "remote_keys")
data class RemoteKey(val label: String, val nextKey: String?)

Devi anche definire un DAO per l'entità RemoteKey:

@Dao
interface RemoteKeyDao {
  @Insert(onConflict = OnConflictStrategy.REPLACE)
  suspend fun insertOrReplace(remoteKey: RemoteKey)

  @Query("SELECT * FROM remote_keys WHERE label = :query")
  suspend fun remoteKeyByQuery(query: String): RemoteKey

  @Query("DELETE FROM remote_keys WHERE label = :query")
  suspend fun deleteByQuery(query: String)
}

Caricare con le chiavi remote

Quando il metodo load() deve gestire le chiavi di pagina remote, devi definirlo in modo diverso rispetto all'utilizzo di base di RemoteMediator:

• Includi una proprietà aggiuntiva che contenga un riferimento al DAO per la tabella delle chiavi remote.
• Determina la chiave da caricare successivamente eseguendo una query sulla tabella delle chiavi remote anziché utilizzare PagingState.
• Inserisci o memorizza la chiave remota restituita dall'origine dati di rete oltre ai dati paginati stessi.

@OptIn(ExperimentalPagingApi::class)
class ExampleRemoteMediator(
  private val query: String,
  private val database: RoomDb,
  private val networkService: ExampleBackendService
) : RemoteMediator<Int, User>() {
  val userDao = database.userDao()
  val remoteKeyDao = database.remoteKeyDao()

  override suspend fun load(
    loadType: LoadType,
    state: PagingState<Int, User>
  ): MediatorResult {
    return try {
      // The network load method takes an optional String
      // parameter. For every page after the first, pass the String
      // token returned from the previous page to let it continue
      // from where it left off. For REFRESH, pass null to load the
      // first page.
      val loadKey = when (loadType) {
        LoadType.REFRESH -> null
        // In this example, you never need to prepend, since REFRESH
        // will always load the first page in the list. Immediately
        // return, reporting end of pagination.
        LoadType.PREPEND -> return MediatorResult.Success(
          endOfPaginationReached = true
        )
        // Query remoteKeyDao for the next RemoteKey.
        LoadType.APPEND -> {
          val remoteKey = database.withTransaction {
            remoteKeyDao.remoteKeyByQuery(query)
          }

          // You must explicitly check if the page key is null when
          // appending, since null is only valid for initial load.
          // If you receive null for APPEND, that means you have
          // reached the end of pagination and there are no more
          // items to load.
          if (remoteKey.nextKey == null) {
            return MediatorResult.Success(
              endOfPaginationReached = true
            )
          }

          remoteKey.nextKey
        }
      }

      // Suspending network load via Retrofit. This doesn't need to
      // be wrapped in a withContext(Dispatcher.IO) { ... } block
      // since Retrofit's Coroutine CallAdapter dispatches on a
      // worker thread.
      val response = networkService.searchUsers(query, loadKey)

      // Store loaded data, and next key in transaction, so that
      // they're always consistent.
      database.withTransaction {
        if (loadType == LoadType.REFRESH) {
          remoteKeyDao.deleteByQuery(query)
          userDao.deleteByQuery(query)
        }

        // Update RemoteKey for this query.
        remoteKeyDao.insertOrReplace(
          RemoteKey(query, response.nextKey)
        )

        // Insert new users into database, which invalidates the
        // current PagingData, allowing Paging to present the updates
        // in the DB.
        userDao.insertAll(response.users)
      }

      MediatorResult.Success(
        endOfPaginationReached = response.nextKey == null
      )
    } catch (e: IOException) {
      MediatorResult.Error(e)
    } catch (e: HttpException) {
      MediatorResult.Error(e)
    }
  }
}

Aggiornare in loco

Se la tua app deve supportare solo gli aggiornamenti di rete dall'inizio dell'elenco, come negli esempi precedenti, RemoteMediator non deve definire il comportamento di caricamento di anteposizione.

Tuttavia, se la tua app deve supportare il caricamento incrementale dalla rete nel database locale, devi fornire il supporto per la ripresa della paginazione a partire dall'ancoraggio, ovvero dalla posizione di scorrimento dell'utente. L'implementazione di Room gestisce questa operazione, ma se non utilizzi Room puoi farlo sostituendo PagingSource.getRefreshKey().PagingSource Per un esempio di implementazione di getRefreshKey(), consulta Definire the PagingSource.

La Figura 2 illustra la procedura di caricamento dei dati prima dal database locale e poi dalla rete una volta che il database non contiene più dati.

Risorse aggiuntive

Per saperne di più sulla libreria Paging, consulta le seguenti risorse aggiuntive:

Visualizzare i contenuti

• Paginare dalla rete e dal database (Visualizzazioni)