صفحه از شبکه و پایگاه داده (بازدیدها)

مفاهیم و پیاده‌سازی Jetpack Compose

با اطمینان از اینکه برنامه‌تان می‌تواند هنگام غیرقابل‌اعتماد بودن اتصال‌های شبکه یا زمانی که کاربر آفلاین است استفاده شود، تجربه کاربری بهبودیافته‌ای ارائه دهید. یک راه برای انجام این کار، صفحه‌بندی هم‌زمان از شبکه و از پایگاه داده محلی است. به‌این‌ترتیب، برنامه‌تان میانای کاربر را از حافظه نهان پایگاه داده محلی هدایت می‌کند و فقط زمانی درخواست‌ها را به شبکه ارسال می‌کند که دیگر داده‌ای در پایگاه داده وجود نداشته باشد.

این راهنما فرض می‌کند که شما با کتابخانه پایداری Room و استفاده پایه از کتابخانه صفحه‌بندی آشنا هستید.

بارگیری داده‌های مختصات

کتابخانه «صفحه‌بندی» مؤلفه RemoteMediator را برای این مورد استفاده ارائه می‌دهد. RemoteMediator به‌عنوان سیگنالی از کتابخانه «صفحه‌بندی» عمل می‌کند وقتی برنامه داده‌های ذخیره‌شده در حافظه نهان را تمام کرده است. می‌توانید از این سیگنال برای بار کردن داده‌های اضافی از شبکه و ذخیره آن در پایگاه داده محلی استفاده کنید، جایی که PagingSource می‌تواند آن را بار کند و برای نمایش به میانای کاربر ارائه دهد.

وقتی داده‌های بیشتری لازم باشد، کتابخانه «صفحه‌بندی» روش load() را از پیاده‌سازی RemoteMediator فراخوانی می‌کند. این یک تابع تعلیق است، بنابراین انجام کارهای طولانی‌مدت با آن ایمن است. این تابع معمولاً داده‌های جدید را از منبع شبکه واکشی می‌کند و آن را در فضای ذخیره‌سازی محلی ذخیره می‌کند.

این فرایند با داده‌های جدید کار می‌کند، اما با گذشت زمان داده‌های ذخیره‌شده در پایگاه داده نیاز به باطل‌سازی دارند، مثلاً زمانی که کاربر به‌صورت دستی بازآوری را راه‌اندازی می‌کند. این با ویژگی LoadType که به روش load() منتقل شده است نشان داده می‌شود. LoadType به RemoteMediator اطلاع می‌دهد که آیا باید داده‌های موجود را بازآوری کند یا داده‌های بیشتری را واکشی کند که باید به فهرست موجود اضافه یا پیش‌افزوده شود.

به‌این‌ترتیب، RemoteMediator تضمین می‌کند که برنامه‌تان داده‌هایی را که کاربران می‌خواهند ببینند به ترتیب مناسب بار می‌کند.

چرخه حیات صفحه‌بندی

شکل ۱. نمودار چرخه حیات «صفحه‌بندی» با PagingSource و PagingData.

هنگام صفحه‌بندی مستقیم از شبکه، PagingSource داده‌ها را بار می‌کند و یک شیء LoadResult برمی‌گرداند. پیاده‌سازی PagingSource ازطریق پارامتر pagingSourceFactory به Pager منتقل می‌شود.

As new data is required by the UI, the Pager calls the load() method from the PagingSource and returns a stream of PagingData objects that encapsulate the new data. هر شیء PagingData معمولاً در ViewModel ذخیره موقت می‌شود و سپس برای نمایش به میانای کاربر ارسال می‌شود.

شکل ۲. نمودار چرخه حیات «صفحه‌بندی» با PagingSource و RemoteMediator.

‫RemoteMediator این جریان داده را تغییر می‌دهد. PagingSource همچنان داده‌ها را بار می‌کند؛ اما وقتی داده‌های صفحه‌بندی‌شده تمام می‌شود، کتابخانه «صفحه‌بندی» RemoteMediator را فعال می‌کند تا داده‌های جدید را از منبع شبکه بار کند. RemoteMediator داده‌های جدید را در پایگاه داده محلی ذخیره می‌کند، بنابراین حافظه نهان درون‌حافظه‌ای در ViewModel غیرضروری است. درنهایت، PagingSource خودش را باطل می‌کند و Pager نمونه جدیدی برای بار کردن داده‌های تازه از پایگاه داده ایجاد می‌کند.

استفاده پایه

فرض کنید می‌خواهید برنامه‌تان صفحه‌هایی از User مورد را از منبع داده شبکه کلید-موردی در حافظه نهان محلی ذخیره‌شده در پایگاه داده Room بار کند.

‫RemoteMediator داده‌ها را از شبکه در پایگاه داده بار می‌کند و
    PagingSource داده‌ها را از پایگاه داده بار می‌کند. ‫Pager از هر دو
    RemoteMediator و PagingSource برای بار کردن داده‌های صفحه‌بندی‌شده استفاده می‌کند.
شکل ۳. نمودار پیاده‌سازی «صفحه‌بندی» که از منبع داده لایه‌ای استفاده می‌کند.

پیاده‌سازی RemoteMediator به بار کردن داده‌های صفحه‌بندی‌شده از شبکه در پایگاه داده کمک می‌کند، اما داده‌ها را مستقیماً در میانای کاربر بار نمی‌کند. درعوض، برنامه از پایگاه داده به‌عنوان منبع حقیقت استفاده می‌کند. به‌عبارت دیگر، برنامه فقط داده‌هایی را نمایش می‌دهد که در پایگاه داده ذخیره شده است. پیاده‌سازی PagingSource (برای مثال، پیاده‌سازی‌ای که Room تولید کرده است) بار کردن داده‌های ذخیره‌شده در حافظه نهان از پایگاه داده به میانای کاربر را مدیریت می‌کند.

ایجاد کردن نهادهای «اتاق»

اولین قدم استفاده از کتابخانه پایداری Room برای تعریف پایگاه داده‌ای است که حافظه پنهان محلی داده‌های صفحه‌بندی‌شده را از منبع داده شبکه نگه می‌دارد. با پیاده‌سازی RoomDatabase شروع کنید، همان‌طور که در ذخیره داده‌ها در پایگاه داده محلی بااستفاده از Room شرح داده شده است.

سپس، یک موجودیت Room تعریف کنید تا جدول موارد فهرست را همان‌طور که در تعریف داده‌ها بااستفاده از موجودیت‌های Room توضیح داده شده است نشان دهد. به آن یک فیلد id به‌عنوان کلید اصلی بدهید، و همچنین فیلدهایی برای هر اطلاعات دیگری که موارد فهرست شما حاوی آن است.

جاوا

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

جاوا

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

همچنین باید یک شیء دسترسی داده (DAO) برای این موجودیت Room تعریف کنید، همان‌طور که در دسترسی به داده‌ها بااستفاده از Room DAOs شرح داده شده است. DAO برای موجودیت مورد فهرست باید شامل روش‌های زیر باشد:

  • روش insertAll() که فهرستی از موارد را در جدول درج می‌کند.
  • روشی که رشته پُرسمان را به‌عنوان پارامتر می‌گیرد و شیء PagingSource را برای فهرست نتایج برمی‌گرداند. به‌این‌ترتیب، شیء Pager می‌تواند از این جدول به‌عنوان منبع داده صفحه‌بندی‌شده استفاده کند.
  • روش clearAll() که همه داده‌های جدول را حذف می‌کند.

جاوا

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

جاوا

@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

نقش اصلی RemoteMediator بار کردن داده‌های بیشتر از شبکه است، وقتی که Pager داده‌هایش تمام می‌شود یا داده‌های موجود نامعتبر می‌شود. این کلاس شامل روش load() است که باید آن را لغو کنید تا رفتار بارگیری را تعریف کنید.

یک پیاده‌سازی معمول RemoteMediator شامل پارامترهای زیر است:

  • ‫query: رشته پُرسمانی که مشخص می‌کند کدام داده‌ها از سرویس پس‌نهایی بازیابی شود.
  • ‫database: پایگاه داده Room که به‌عنوان حافظه نهان محلی عمل می‌کند.
  • networkService: نمونه میانای برنامه‌سازی کاربردی برای سرویس پس‌نهایی.

پیاده‌سازی RemoteMediator<Key, Value> ایجاد کنید. نوع Key و نوع Value باید همانند زمانی باشد که PagingSource را در مقابل همان منبع داده شبکه تعریف می‌کنید. برای اطلاعات بیشتر درباره انتخاب پارامترهای نوع، به انتخاب انواع کلید و مقدار مراجعه کنید.

جاوا

@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
  ) {
    ...
  }
}

جاوا

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() مسئول به‌روزرسانی مجموعه داده پشتیبان و باطل کردن PagingSource است. برخی‌از کتابخانه‌هایی که از صفحه‌بندی پشتیبانی می‌کنند (مانند Room) به‌طور خودکار باطل کردن اشیاء PagingSource را که پیاده‌سازی می‌کنند مدیریت خواهند کرد.

روش load() دو پارامتر را می‌گیرد:

  • PagingState، که حاوی اطلاعاتی درباره صفحه‌های بارشده تا این لحظه، نمایه‌ای که اخیراً به آن دسترسی پیدا شده، و شیء PagingConfig است که برای مقداردهی اولیه جاری‌سازی صفحه‌بندی استفاده کرده‌اید.
  • LoadType، که نشان‌دهنده نوع بار است: REFRESH، APPEND، یا PREPEND.

مقدار برگشتی روش load() یک شیء MediatorResult است. MediatorResult می‌تواند MediatorResult.Error (که شامل شرح خطا است) یا MediatorResult.Success (که شامل سیگنالی است که نشان می‌دهد آیا داده‌های بیشتری برای بار کردن وجود دارد یا نه) باشد.

روش load() باید مراحل زیر را انجام دهد:

  1. بسته به نوع بار کردن و داده‌هایی که تاکنون بار شده است، تعیین کنید کدام صفحه از شبکه بار شود.
  2. درخواست شبکه را راه‌اندازی کنید.
  3. بسته به نتیجه عملیات بارگیری، کنش‌هایی را انجام دهید:
    • اگر بارگیری موفقیت‌آمیز باشد و فهرست موارد دریافتی خالی نباشد، موارد فهرست را در پایگاه داده ذخیره کنید و MediatorResult.Success(endOfPaginationReached = false) را برگردانید. پس‌از ذخیره شدن داده‌ها، منبع داده را باطل کنید تا کتابخانه «صفحه‌بندی» از داده‌های جدید مطلع شود.
    • اگر بارگیری موفقیت‌آمیز باشد و فهرست دریافتی موارد خالی باشد یا نمایه صفحه آخر باشد، MediatorResult.Success(endOfPaginationReached = true) را برگردانید. After the data is stored, invalidate the data source to notify the Paging library of the new data.
    • اگر درخواست باعث ایجاد خطا شد، MediatorResult.Error را برگردانید.

جاوا

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

جاوا

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

تعریف روش مقداردهی اولیه

پیاده‌سازی‌های RemoteMediator همچنین می‌توانند روش initialize() را لغو کنند تا بررسی کنند که آیا داده‌های ذخیره‌شده در حافظه نهان قدیمی هستند یا نه و تصمیم بگیرند که آیا بازآوری از راه دور را راه‌اندازی کنند یا نه. این روش قبل‌از انجام هرگونه بارگیری اجرا می‌شود، بنابراین می‌توانید قبل‌از راه‌اندازی هرگونه بارگیری محلی یا ازراه‌دور، پایگاه داده را دستکاری کنید (برای مثال، برای پاک کردن داده‌های قدیمی).

چون initialize() تابع ناهمگام است، می‌توانید داده‌ها را بار کنید تا ارتباط داده‌های موجود در پایگاه داده را تعیین کنید. رایج‌ترین مورد این است که داده‌های ذخیره‌شده در حافظه نهان فقط برای مدت زمان خاصی معتبر هستند. RemoteMediator می‌تواند بررسی کند که آیا این زمان انقضا گذشته است یا نه، که در این صورت کتابخانه «صفحه‌بندی» باید داده‌ها را کاملاً بازآوری کند. پیاده‌سازی‌های initialize() باید InitializeAction را به‌صورت زیر برگرداند:

  • در مواردی که داده‌های محلی باید کاملاً بازآوری شود، initialize() باید InitializeAction.LAUNCH_INITIAL_REFRESH را برگرداند. این کار باعث می‌شود RemoteMediator بازآوری ازراه‌دور انجام دهد تا داده‌ها را به‌طور کامل بارگیری مجدد کند. هرگونه بارگیری APPEND یا PREPEND ازراه‌دور منتظر می‌ماند تا بارگیری REFRESH با موفقیت انجام شود و سپس ادامه می‌دهد.
  • در مواردی که داده‌های محلی نیازی به بازآوری ندارند، initialize() باید InitializeAction.SKIP_INITIAL_REFRESH را برگرداند. این کار باعث می‌شود RemoteMediator از بازآوری از راه دور صرف‌نظر کند و داده‌های ذخیره‌شده در حافظه نهان را بار کند.

جاوا

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

جاوا

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

ایجاد کردن «ورق‌زن»

درنهایت، باید یک نمونه Pager ایجاد کنید تا جریان داده‌های صفحه‌بندی‌شده را راه‌اندازی کنید. این کار شبیه به ایجاد Pager از منبع داده شبکه ساده است، اما دو کار را باید به‌طور متفاوت انجام دهید:

  • به‌جای ارسال مستقیم سازنده PagingSource، باید روش پُرسمانی را ارائه دهید که شیء PagingSource را از DAO برمی‌گرداند.
  • باید نمونه‌ای از پیاده‌سازی RemoteMediator خود را به‌عنوان پارامتر remoteMediator ارائه دهید.

جاوا

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

جاوا

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

مدیریت کلیدهای ازراه‌دور

کلیدهای راه دور کلیدهایی هستند که پیاده‌سازی RemoteMediator از آن‌ها استفاده می‌کند تا به سرویس پس‌نما بگوید کدام داده‌ها را در مرحله بعد بار کند. در ساده‌ترین حالت، هر مورد از داده‌های صفحه‌بندی‌شده شامل یک کلید ازراه‌دور است که به‌راحتی می‌توانید به آن ارجاع دهید. بااین‌حال، اگر کلیدهای راه دور با موارد جداگانه مطابقت نداشته باشند، باید آن‌ها را جداگانه ذخیره کنید و در روش load() خود مدیریت کنید.

این بخش نحوه جمع‌آوری، ذخیره، و به‌روزرسانی کلیدهای راه دور را که در موارد تکی ذخیره نشده‌اند شرح می‌دهد.

کلیدهای مورد

این بخش نحوه کار با کلیدهای راه دور را که با موارد تکی مطابقت دارند شرح می‌دهد. معمولاً وقتی یک میانای برنامه‌سازی کاربردی (API) براساس موارد تکی عمل می‌کند، شناسه مورد به‌عنوان پارامتر پُرسمان ارسال می‌شود. نام پارامتر نشان می‌دهد که آیا سرور باید با موارد قبل یا بعداز شناسه ارائه‌شده پاسخ دهد. در مثال کلاس مدل User، فیلد id از سرور به‌عنوان کلید راه دور هنگام درخواست داده‌های اضافی استفاده می‌شود.

وقتی روش load() شما نیاز به مدیریت کلیدهای ازراه‌دور مختص مورد دارد، این کلیدها معمولاً شناسه‌های داده‌های واکشی‌شده از سرور هستند. عملیات بازآوری به کلید بارگیری نیاز ندارد، زیرا فقط جدیدترین داده‌ها را بازیابی می‌کند. به‌طور مشابه، عملیات پیش‌افزودن نیازی به واکشی داده‌های اضافی ندارد زیرا بازآوری همیشه جدیدترین داده‌ها را از سرور می‌کشد.

بااین‌حال، عملیات الحاق به شناسه نیاز دارد. این کار مستلزم آن است که آخرین مورد را از پایگاه داده بار کنید و از شناسه آن برای بار کردن صفحه بعدی داده‌ها استفاده کنید. اگر هیچ موردی در پایگاه داده وجود نداشته باشد، endOfPaginationReached روی true تنظیم می‌شود که نشان می‌دهد بازآوری داده‌ها لازم است.

جاوا

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

جاوا

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

کلیدهای صفحه

این بخش نحوه کار با کلیدهای راه دور را که با موارد تکی مطابقت ندارند شرح می‌دهد.

افزودن جدول کلید ازراه‌دور

وقتی کلیدهای راه دور مستقیماً با موارد فهرست مرتبط نیستند، بهتر است آن‌ها را در جدول جداگانه‌ای در پایگاه داده محلی ذخیره کنید. نهاد Room را که نشان‌دهنده جدولی از کلیدهای ازراه‌دور است تعریف کنید:

جاوا

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

جاوا

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

همچنین باید DAO را برای نهاد RemoteKey تعریف کنید:

جاوا

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

جاوا

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

بار کردن با کلیدهای ازراه‌دور

وقتی روش load() شما نیاز به مدیریت کلیدهای صفحه ازراه‌دور دارد، باید آن را به‌شکل متفاوتی نسبت‌به استفاده پایه از RemoteMediator تعریف کنید:

  • ویژگی دیگری را اضافه کنید که حاوی ارجاعی به DAO برای جدول کلید راه دور شما باشد.
  • تعیین اینکه کدام کلید بعدی بار شود با پرسمان از جدول کلید راه دور به‌جای استفاده از PagingState.
  • کلید راه دور برگردانده‌شده از منبع داده شبکه را علاوه‌بر خود داده‌های صفحه‌بندی‌شده درج یا ذخیره کنید.

جاوا

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

جاوا

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

منابع بیشتر

برای کسب اطلاعات بیشتر درباره کتابخانه Paging، منابع اضافی زیر را ببینید:

نمونه‌ها