Ağ ve veritabanından sayfa (Görüntülemeler)

Kavramlar ve Jetpack Compose uygulaması

Uygulamanızın, ağ bağlantıları güvenilir olmadığında veya kullanıcı çevrimdışıyken kullanılabilmesini sağlayarak daha iyi bir kullanıcı deneyimi sunun. Bunu yapmanın bir yolu, aynı anda hem ağdan hem de yerel bir veritabanından sayfalama yapmaktır. Bu sayede uygulamanız, kullanıcı arayüzünü yerel bir veritabanı önbelleğinden yönetir ve yalnızca veritabanında başka veri kalmadığında ağa istek gönderir.

Bu kılavuzda, Room kalıcılık kitaplığı ve Paging kitaplığının temel kullanımı hakkında bilgi sahibi olduğunuz varsayılmaktadır.

Veri yüklemelerini koordine etme

Paging kitaplığı, bu kullanım alanı için RemoteMediator bileşenini sağlar. RemoteMediator, uygulamada önbelleğe alınmış veri kalmadığında Paging kitaplığından gelen bir sinyal görevi görür. Ağdan ek veri yüklemek ve bu verileri yerel veritabanında depolamak için bu sinyali kullanabilirsiniz. PagingSource, bu verileri yükleyip kullanıcı arayüzüne sunarak görüntülenmesini sağlayabilir.

Ek veri gerektiğinde Paging kitaplığı, RemoteMediator uygulamasından load() yöntemini çağırır. Bu, askıya alma işlevi olduğundan uzun süreli işleri gerçekleştirmek güvenlidir. Bu işlev genellikle yeni verileri bir ağ kaynağından getirir ve yerel depolama alanına kaydeder.

Bu işlem yeni verilerle çalışır ancak zaman içinde veritabanında depolanan verilerin geçersiz kılınması gerekir (ör. kullanıcı manuel olarak yenileme işlemini tetiklediğinde). Bu, load() yöntemine iletilen LoadType özelliğiyle temsil edilir. LoadType, mevcut verileri yenilemesi mi yoksa mevcut listenin başına veya sonuna eklenmesi gereken ek verileri mi getirmesi gerektiğini RemoteMediator öğesine bildirir.

Bu sayede RemoteMediator, uygulamanızın kullanıcıların görmek istediği verileri uygun sırada yüklemesini sağlar.

Sayfalandırma yaşam döngüsü

Şekil 1. PagingSource ve PagingData ile Sayfalandırma'nın yaşam döngüsünün diyagramı.

Doğrudan ağdan sayfalama yaparken PagingSource, verileri yükler ve bir LoadResult nesnesi döndürür. PagingSource uygulaması, pagingSourceFactory parametresi aracılığıyla Pager öğesine iletilir.

Kullanıcı arayüzü yeni veriler gerektirdiğinde Pager, PagingSource sınıfından load() yöntemini çağırır ve yeni verileri kapsayan bir PagingData nesnesi akışı döndürür. Her PagingData nesnesi, kullanıcı arayüzüne gönderilmeden önce genellikle ViewModel içinde önbelleğe alınır.

Şekil 2. PagingSource ve RemoteMediator ile Paging'in yaşam döngüsünün diyagramı.

RemoteMediator bu veri akışını değiştirir. PagingSource, verileri yüklemeye devam eder ancak sayfalara ayrılmış veriler tükendiğinde Paging kitaplığı, ağ kaynağından yeni veriler yüklemek için RemoteMediator öğesini tetikler. RemoteMediator, yeni verileri yerel veritabanında depolar. Bu nedenle, ViewModel içinde RAM önbelleği kullanılmasına gerek yoktur. Son olarak PagingSource kendini geçersiz kılar ve Pager, veritabanından yeni verileri yüklemek için yeni bir örnek oluşturur.

Temel kullanım

Uygulamanızın, öğe anahtarlı bir ağ veri kaynağından User öğe içeren sayfaları Room veritabanında depolanan yerel bir önbelleğe yüklemesini istediğinizi varsayalım.

RemoteMediator, ağdaki verileri veritabanına yükler ve PagingSource, veritabanındaki verileri yükler. Sayfa gezgini, sayfalı verileri yüklemek için hem RemoteMediator hem de PagingSource'u kullanır.
Şekil 3. Katmanlı veri kaynağı kullanan bir Paging uygulamasının diyagramı.

RemoteMediator uygulaması, sayfalı verilerin ağdan veritabanına yüklenmesine yardımcı olur ancak verileri doğrudan kullanıcı arayüzüne yüklemez. Bunun yerine uygulama, veritabanını tek doğru kaynak olarak kullanır. Başka bir deyişle, uygulama yalnızca veritabanında önbelleğe alınmış verileri gösterir. PagingSource uygulaması (ör. Room tarafından oluşturulan bir uygulama), önbelleğe alınmış verilerin veritabanından kullanıcı arayüzüne yüklenmesini sağlar.

Oda varlıkları oluşturma

İlk adım, ağ veri kaynağından gelen sayfalanmış verilerin yerel önbelleğini tutan bir veritabanı tanımlamak için Room kalıcılık kitaplığını kullanmaktır. Room'u kullanarak yerel bir veritabanına veri kaydetme başlıklı makalede açıklandığı gibi RoomDatabase uygulayarak başlayın.

Ardından, Room varlıklarını kullanarak veri tanımlama bölümünde açıklandığı gibi, liste öğeleri tablosunu temsil edecek bir Room varlığı tanımlayın. Birincil anahtar olarak bir id alanı ve liste öğelerinizin içerdiği diğer bilgiler için alanlar ekleyin.

Java

@Entity(tableName = "users")
public class User {
  public String id;
  public String label;
}

Java

@Entity(tableName = "users")
public class User {
  public String id;
  public String label;
}

Ayrıca, Room DAO'larını kullanarak verilere erişme bölümünde açıklandığı gibi bu Room varlığı için bir veri erişimi nesnesi (DAO) tanımlamanız gerekir. Liste öğesi varlığı için DAO, aşağıdaki yöntemleri içermelidir:

  • Tabloya bir öğe listesi ekleyen insertAll() yöntemi.
  • Sorgu dizesini parametre olarak alan ve sonuç listesi için bir PagingSource nesnesi döndüren yöntem. Bu sayede Pager nesnesi, bu tabloyu sayfalandırılmış verilerin kaynağı olarak kullanabilir.
  • Tablodaki tüm verileri silen bir clearAll() yöntemi.

Java

@Dao
interface UserDao {
  @Insert(onConflict = OnConflictStrategy.REPLACE)
  void insertAll(List<User> users);

  @Query("SELECT * FROM users WHERE mLabel LIKE :query")
  PagingSource<Integer, User> pagingSource(String query);

  @Query("DELETE FROM users")
  int clearAll();
}

Java

@Dao
interface UserDao {
  @Insert(onConflict = OnConflictStrategy.REPLACE)
  void insertAll(List<User> users);

  @Query("SELECT * FROM users WHERE mLabel LIKE :query")
  PagingSource<Integer, User> pagingSource(String query);

  @Query("DELETE FROM users")
  int clearAll();
}

RemoteMediator uygulama

RemoteMediator, Pager'da veri kalmadığında veya mevcut veriler geçersiz kılındığında ağdan daha fazla veri yüklemek için kullanılır. Yükleme davranışını tanımlamak için geçersiz kılmanız gereken bir load() yöntemi içerir.

Tipik bir RemoteMediator uygulaması aşağıdaki parametreleri içerir:

  • query: Arka uç hizmetinden hangi verilerin alınacağını tanımlayan bir sorgu dizesi.
  • database: Yerel önbellek görevi gören Room veritabanı.
  • networkService: Arka uç hizmeti için bir API örneği.

RemoteMediator<Key, Value> uygulaması oluşturun. Key türü ve Value türü, aynı ağ veri kaynağına göre bir PagingSource tanımladığınızda olacağı gibi aynı olmalıdır. Tür parametrelerini seçme hakkında daha fazla bilgi için Anahtar ve değer türlerini seçme bölümüne bakın.

Java

@UseExperimental(markerClass = ExperimentalPagingApi.class)
class ExampleRemoteMediator extends RxRemoteMediator<Integer, User> {
  private String query;
  private ExampleBackendService networkService;
  private RoomDb database;
  private UserDao userDao;

  ExampleRemoteMediator(
    String query,
    ExampleBackendService networkService, RoomDb database
  ) {
    query = query;
    networkService = networkService;
    database = database;
    userDao = database.userDao();
  }

  @NotNull
  @Override
  public Single<MediatorResult> loadSingle(
    @NotNull LoadType loadType,
    @NotNull PagingState<Integer, User> state
  ) {
    ...
  }
}

Java

class ExampleRemoteMediator extends ListenableFutureRemoteMediator<Integer, User> {
  private String query;
  private ExampleBackendService networkService;
  private RoomDb database;
  private UserDao userDao;
  private Executor bgExecutor;

  ExampleRemoteMediator(
    String query,
    ExampleBackendService networkService,
    RoomDb database,
    Executor bgExecutor
  ) {
    this.query = query;
    this.networkService = networkService;
    this.database = database;
    this.userDao = database.userDao();
    this.bgExecutor = bgExecutor;
  }

  @NotNull
  @Override
  public ListenableFuture<MediatorResult> loadFuture(
    @NotNull LoadType loadType,
    @NotNull PagingState<Integer, User> state
  ) {
    ...
  }
}

load() yöntemi, destekleyici veri kümesini güncellemekten ve PagingSource değerini geçersiz kılmaktan sorumludur. Sayfalandırmayı destekleyen bazı kitaplıklar (ör. Room), uyguladıkları PagingSource nesnelerini geçersiz kılma işlemini otomatik olarak gerçekleştirir.

load() yöntemi iki parametre alır:

  • Şimdiye kadar yüklenen sayfalar, en son erişilen dizin ve sayfalama akışını ilk kullanıma hazırlamak için kullandığınız PagingConfig nesnesi hakkında bilgiler içeren PagingState.
  • LoadType, yükün türünü belirtir: REFRESH, APPEND veya PREPEND.

load() yönteminin döndürdüğü değer bir MediatorResult nesnesidir. MediatorResult, MediatorResult.Error (hata açıklamasını içerir) veya MediatorResult.Success (yüklenecek daha fazla veri olup olmadığını belirten bir sinyal içerir) olabilir.

load() yöntemi aşağıdaki adımları gerçekleştirmelidir:

  1. Yükleme türüne ve şimdiye kadar yüklenen verilere bağlı olarak ağdan hangi sayfanın yükleneceğini belirleyin.
  2. Ağ isteğini tetikleyin.
  3. Yükleme işleminin sonucuna göre işlem yapın:
    • Yükleme başarılı olursa ve alınan öğe listesi boş değilse liste öğelerini veritabanında depolayın ve MediatorResult.Success(endOfPaginationReached = false) değerini döndürün. Veriler depolandıktan sonra, Paging kitaplığını yeni veriler hakkında bilgilendirmek için veri kaynağını geçersiz kılın.
    • Yükleme başarılı olursa ve alınan öğe listesi boşsa veya son sayfa diziniyse MediatorResult.Success(endOfPaginationReached = true) değerini döndürün. Veriler depolandıktan sonra, Paging kitaplığını yeni veriler hakkında bilgilendirmek için veri kaynağını geçersiz kılın.
    • İstek hataya neden olursa MediatorResult.Error döndürülür.

Java

@NotNull
@Override
public Single<MediatorResult> loadSingle(
  @NotNull LoadType loadType,
  @NotNull PagingState<Integer, User> state
) {
  // 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.
  String loadKey = null;
  switch (loadType) {
    case REFRESH:
      break;
    case PREPEND:
      // 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.
      return Single.just(new MediatorResult.Success(true));
    case APPEND:
      User 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 Single.just(new MediatorResult.Success(true));
      }

      loadKey = lastItem.getId();
      break;
  }

  return networkService.searchUsers(query, loadKey)
    .subscribeOn(Schedulers.io())
    .map((Function<SearchUserResponse, MediatorResult>) response -> {
      database.runInTransaction(() -> {
        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.getUsers());
      });

      return new MediatorResult.Success(response.getNextKey() == null);
    })
    .onErrorResumeNext(e -> {
      if (e instanceof IOException || e instanceof HttpException) {
        return Single.just(new MediatorResult.Error(e));
      }

      return Single.error(e);
    });
}

Java

@NotNull
@Override
public ListenableFuture<MediatorResult> loadFuture(
  @NotNull LoadType loadType,
  @NotNull PagingState<Integer, User> state
) {
  // 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.
  String loadKey = null;
  switch (loadType) {
    case REFRESH:
      break;
    case PREPEND:
      // 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.
      return Futures.immediateFuture(new MediatorResult.Success(true));
    case APPEND:
      User 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 Futures.immediateFuture(new MediatorResult.Success(true));
      }

      loadKey = lastItem.getId();
      break;
  }

  ListenableFuture<MediatorResult> networkResult = Futures.transform(
    networkService.searchUsers(query, loadKey),
    response -> {
      database.runInTransaction(() -> {
        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.getUsers());
      });

      return new MediatorResult.Success(response.getNextKey() == null);
    }, bgExecutor);

  ListenableFuture<MediatorResult> ioCatchingNetworkResult =
    Futures.catching(
      networkResult,
      IOException.class,
      MediatorResult.Error::new,
      bgExecutor
    );

  return Futures.catching(
    ioCatchingNetworkResult,
    HttpException.class,
    MediatorResult.Error::new,
    bgExecutor
  );
}

initialize yöntemini tanımlayın

RemoteMediator uygulamaları, önbelleğe alınmış verilerin güncel olup olmadığını kontrol etmek ve uzaktan yenilemenin tetiklenip tetiklenmeyeceğine karar vermek için initialize() yöntemini de geçersiz kılabilir. Bu yöntem, herhangi bir yükleme işlemi gerçekleştirilmeden önce çalışır. Bu sayede, yerel veya uzak yüklemeleri tetiklemeden önce veritabanını değiştirebilirsiniz (ör. eski verileri temizlemek için).

initialize() eşzamansız bir işlev olduğundan, veritabanındaki mevcut verilerin alaka düzeyini belirlemek için veri yükleyebilirsiniz. En yaygın durum, önbelleğe alınan verilerin yalnızca belirli bir süre için geçerli olmasıdır. RemoteMediator, bu geçerlilik süresinin dolup dolmadığını kontrol edebilir. Süre dolmuşsa Paging kitaplığının verileri tamamen yenilemesi gerekir. initialize() uygulamaları, aşağıdaki gibi bir InitializeAction döndürmelidir:

  • Yerel verilerin tamamen yenilenmesi gereken durumlarda initialize(), InitializeAction.LAUNCH_INITIAL_REFRESH değerini döndürmelidir. Bu, RemoteMediator uygulamasının verileri tamamen yeniden yüklemek için uzaktan yenileme yapmasına neden olur. Uzak APPEND veya PREPEND yüklemeleri, devam etmeden önce REFRESH yüklemesinin başarılı olmasını bekler.
  • Yerel verilerin yenilenmesi gerekmediğinde initialize(), InitializeAction.SKIP_INITIAL_REFRESH değerini döndürmelidir. Bu, RemoteMediator uygulamasının uzaktan yenilemeyi atlamasına ve önbelleğe alınmış verileri yüklemesine neden olur.

Java

@NotNull
@Override
public Single<InitializeAction> initializeSingle() {
  long cacheTimeout = TimeUnit.MILLISECONDS.convert(1, TimeUnit.HOURS);
  return mUserDao.lastUpdatedSingle()
    .map(lastUpdatedMillis -> {
      if (System.currentTimeMillis() - lastUpdatedMillis <= cacheTimeout) {
        // Cached data is up-to-date, so there is no need to re-fetch
        // from the network.
        return 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.
        return InitializeAction.LAUNCH_INITIAL_REFRESH;
      }
    });
}

Java

@NotNull
@Override
public ListenableFuture<InitializeAction> initializeFuture() {
  long cacheTimeout = TimeUnit.MILLISECONDS.convert(1, TimeUnit.HOURS);
  return Futures.transform(
    mUserDao.lastUpdated(),
    lastUpdatedMillis -> {
      if (System.currentTimeMillis() - lastUpdatedMillis <= cacheTimeout) {
        // Cached data is up-to-date, so there is no need to re-fetch
        // from the network.
        return 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.
        return InitializeAction.LAUNCH_INITIAL_REFRESH;
      }
    },
    mBgExecutor);
}

Sayfa gezgini oluşturma

Son olarak, sayfalı veri akışını ayarlamak için bir Pager örneği oluşturmanız gerekir. Bu işlem, basit bir ağ veri kaynağından Pager oluşturmaya benzer ancak farklı yapmanız gereken iki şey vardır:

  • Doğrudan bir PagingSource oluşturucu iletmek yerine DAO'dan bir PagingSource nesnesi döndüren sorgu yöntemini sağlamanız gerekir.
  • remoteMediator parametresi olarak RemoteMediator uygulamanızın bir örneğini sağlamanız gerekir.

Java

UserDao userDao = database.userDao();
Pager<Integer, User> pager = Pager(
  new PagingConfig(/* pageSize = */ 20),
  null, // initialKey,
  new ExampleRemoteMediator(query, database, networkService)
  () -> userDao.pagingSource(query));

Java

UserDao userDao = database.userDao();
Pager<Integer, User> pager = Pager(
  new PagingConfig(/* pageSize = */ 20),
  null, // initialKey
  new ExampleRemoteMediator(query, database, networkService, bgExecutor),
  () -> userDao.pagingSource(query));

Uzaktan anahtarları yönetme

Uzak anahtarlar, bir RemoteMediator uygulamasının arka uç hizmetine bir sonraki adımda hangi verileri yükleyeceğini bildirmek için kullandığı anahtarlardır. En basit durumda, sayfalanmış verilerin her öğesi kolayca referans verebileceğiniz bir uzak anahtar içerir. Ancak uzak anahtarlar tek tek öğelere karşılık gelmiyorsa bunları ayrı olarak depolamanız ve load() yönteminizde yönetmeniz gerekir.

Bu bölümde, ayrı öğelerde depolanmayan uzak anahtarların nasıl toplanacağı, depolanacağı ve güncelleneceği açıklanmaktadır.

Öğe anahtarları

Bu bölümde, her bir öğeye karşılık gelen uzak anahtarlarla nasıl çalışılacağı açıklanmaktadır. Genellikle bir API, tek tek öğeleri anahtar olarak kullandığında öğe kimliği sorgu parametresi olarak iletilir. Parametre adı, sunucunun sağlanan kimlikten önceki mi yoksa sonraki mi öğelerle yanıt vermesi gerektiğini belirtir. User model sınıfı örneğinde, sunucudan gelen id alanı, ek veri istenirken uzak anahtar olarak kullanılır.

load() yönteminizin öğeye özel uzak anahtarları yönetmesi gerektiğinde bu anahtarlar genellikle sunucudan getirilen verilerin kimlikleridir. Yenileme işlemleri, yalnızca en son verileri aldığından yükleme anahtarı gerektirmez. Benzer şekilde, yenileme işlemi her zaman sunucudan en yeni verileri çektiği için başa ekleme işlemlerinin ek veri getirmesi gerekmez.

Ancak ekleme işlemleri için kimlik gerekir. Bunun için veritabanından son öğeyi yüklemeniz ve bir sonraki veri sayfasını yüklemek için bu öğenin kimliğini kullanmanız gerekir. Veritabanında öğe yoksa endOfPaginationReached, true olarak ayarlanır. Bu, verilerin yenilenmesi gerektiğini gösterir.

Java

@NotNull
@Override
public Single>MediatorResult< loadSingle(
  @NotNull LoadType loadType,
  @NotNull PagingState>Integer, User< state
) {
  // 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.
  Single>String< remoteKeySingle = null;
  switch (loadType) {
    case REFRESH:
      // Initial load should use null as the page key, so you can return null
      // directly.
      remoteKeySingle = Single.just(null);
      break;
    case PREPEND:
      // 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.
      return Single.just(new MediatorResult.Success(true));
    case APPEND:
      User 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 Single.just(new MediatorResult.Success(true));
      }
      remoteKeySingle = Single.just(lastItem.getId());
      break;
  }

  return remoteKeySingle
    .subscribeOn(Schedulers.io())
    .flatMap((Function<String, Single<MediatorResult>>) remoteKey -> {
      return networkService.searchUsers(query, remoteKey)
        .map(response -> {
          database.runInTransaction(() -> {
            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.getUsers());
          });

          return new MediatorResult.Success(response.getUsers().isEmpty());
        });
    })
    .onErrorResumeNext(e -> {
      if (e instanceof IOException || e instanceof HttpException) {
        return Single.just(new MediatorResult.Error(e));
      }

      return Single.error(e);
    });
}

Java

@NotNull
@Override
public ListenableFuture<MediatorResult> loadFuture(
  @NotNull LoadType loadType,
  @NotNull PagingState<Integer, User> state
) {
  // 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.
  ResolvableFuture<String> remoteKeyFuture = ResolvableFuture.create();
  switch (loadType) {
    case REFRESH:
      remoteKeyFuture.set(null);
      break;
    case PREPEND:
      // 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.
      return Futures.immediateFuture(new MediatorResult.Success(true));
    case APPEND:
      User 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 Futures.immediateFuture(new MediatorResult.Success(true));
      }

      remoteKeyFuture.set(lastItem.getId());
      break;
  }

  return Futures.transformAsync(remoteKeyFuture, remoteKey -> {

    ListenableFuture<MediatorResult> networkResult = Futures.transform(
      networkService.searchUsers(query, remoteKey),
      response -> {
        database.runInTransaction(() -> {
        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.getUsers());
      });

      return new MediatorResult.Success(response.getUsers().isEmpty());
    }, bgExecutor);

    ListenableFuture<MediatorResult> ioCatchingNetworkResult =
      Futures.catching(
        networkResult,
        IOException.class,
        MediatorResult.Error::new,
        bgExecutor
      );

    return Futures.catching(
      ioCatchingNetworkResult,
      HttpException.class,
      MediatorResult.Error::new,
      bgExecutor
    );
  }, bgExecutor);
}

Sayfa anahtarları

Bu bölümde, ayrı öğelere karşılık gelmeyen uzak anahtarlarla nasıl çalışılacağı açıklanmaktadır.

Uzak anahtar tablosu ekleme

Uzak anahtarlar liste öğeleriyle doğrudan ilişkili olmadığında bunları yerel veritabanında ayrı bir tabloda depolamak en iyisidir. Uzak anahtarlar tablosunu temsil eden bir Room varlığı tanımlayın:

Java

@Entity(tableName = "remote_keys")
public class RemoteKey {
  public String label;
  public String nextKey;
}

Java

@Entity(tableName = "remote_keys")
public class RemoteKey {
  public String label;
  public String nextKey;
}

RemoteKey varlığı için bir DAO da tanımlamanız gerekir:

Java

@Dao
interface RemoteKeyDao {
  @Insert(onConflict = OnConflictStrategy.REPLACE)
  void insertOrReplace(RemoteKey remoteKey);

  @Query("SELECT * FROM remote_keys WHERE label = :query")
  Single<RemoteKey> remoteKeyByQuerySingle(String query);

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

Java

@Dao
interface RemoteKeyDao {
  @Insert(onConflict = OnConflictStrategy.REPLACE)
  void insertOrReplace(RemoteKey remoteKey);

  @Query("SELECT * FROM remote_keys WHERE label = :query")
  ListenableFuture<RemoteKey> remoteKeyByQueryFuture(String query);

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

Uzaktan anahtarlarla yükleme

load() yönteminizin uzak sayfa anahtarlarını yönetmesi gerektiğinde, RemoteMediator yönteminin temel kullanımına kıyasla aşağıdaki şekillerde farklı tanımlamanız gerekir:

  • Uzak anahtar tablonuz için DAO'ya referans içeren ek bir özellik ekleyin.
  • PagingState kullanmak yerine uzak anahtar tablosunu sorgulayarak bir sonraki adımda hangi anahtarın yükleneceğini belirleyin.
  • Sayfalanmış verilerin yanı sıra ağ veri kaynağından döndürülen uzak anahtarı ekleyin veya depolayın.

Java

@NotNull
@Override
public Single<MediatorResult> loadSingle(
  @NotNull LoadType loadType,
  @NotNull PagingState<Integer, User> state
) {
  // 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.
  Single<RemoteKey> remoteKeySingle = null;
  switch (loadType) {
    case REFRESH:
      // Initial load should use null as the page key, so you can return null
      // directly.
      remoteKeySingle = Single.just(new RemoteKey(mQuery, null));
      break;
    case PREPEND:
      // 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.
      return Single.just(new MediatorResult.Success(true));
    case APPEND:
      // Query remoteKeyDao for the next RemoteKey.
      remoteKeySingle = mRemoteKeyDao.remoteKeyByQuerySingle(mQuery);
      break;
  }

  return remoteKeySingle
    .subscribeOn(Schedulers.io())
    .flatMap((Function<RemoteKey, Single<MediatorResult>>) remoteKey -> {
      // 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 (loadType != REFRESH && remoteKey.getNextKey() == null) {
        return Single.just(new MediatorResult.Success(true));
      }

      return networkService.searchUsers(query, remoteKey.getNextKey())
        .map(response -> {
          database.runInTransaction(() -> {
            if (loadType == LoadType.REFRESH) {
              userDao.deleteByQuery(query);
              remoteKeyDao.deleteByQuery(query);
            }

            // Update RemoteKey for this query.
            remoteKeyDao.insertOrReplace(new RemoteKey(query, response.getNextKey()));

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

          return new MediatorResult.Success(response.getNextKey() == null);
        });
    })
    .onErrorResumeNext(e -> {
      if (e instanceof IOException || e instanceof HttpException) {
        return Single.just(new MediatorResult.Error(e));
      }

      return Single.error(e);
    });
}

Java

@NotNull
@Override
public ListenableFuture<MediatorResult> loadFuture(
  @NotNull LoadType loadType,
  @NotNull PagingState<Integer, User> state
) {
  // 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.
  ResolvableFuture<RemoteKey> remoteKeyFuture = ResolvableFuture.create();
  switch (loadType) {
    case REFRESH:
      remoteKeyFuture.set(new RemoteKey(query, null));
      break;
    case PREPEND:
      // 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.
      return Futures.immediateFuture(new MediatorResult.Success(true));
    case APPEND:
      User 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 Futures.immediateFuture(new MediatorResult.Success(true));
      }

      // Query remoteKeyDao for the next RemoteKey.
      remoteKeyFuture.setFuture(
        remoteKeyDao.remoteKeyByQueryFuture(query));
      break;
  }

  return Futures.transformAsync(remoteKeyFuture, remoteKey -> {
    // 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 (loadType != LoadType.REFRESH && remoteKey.getNextKey() == null) {
      return Futures.immediateFuture(new MediatorResult.Success(true));
    }

    ListenableFuture<MediatorResult> networkResult = Futures.transform(
      networkService.searchUsers(query, remoteKey.getNextKey()),
      response -> {
        database.runInTransaction(() -> {
        if (loadType == LoadType.REFRESH) {
          userDao.deleteByQuery(query);
          remoteKeyDao.deleteByQuery(query);
        }

        // Update RemoteKey for this query.
        remoteKeyDao.insertOrReplace(new RemoteKey(query, response.getNextKey()));

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

      return new MediatorResult.Success(response.getNextKey() == null);
    }, bgExecutor);

    ListenableFuture<MediatorResult> ioCatchingNetworkResult =
      Futures.catching(
        networkResult,
        IOException.class,
        MediatorResult.Error::new,
        bgExecutor
      );

    return Futures.catching(
      ioCatchingNetworkResult,
      HttpException.class,
      MediatorResult.Error::new,
      bgExecutor
    );
  }, bgExecutor);
}

Ek kaynaklar

Paging kitaplığı hakkında daha fazla bilgi edinmek için aşağıdaki ek kaynaklara göz atın:

Örnekler