صفحة من الشبكة وقاعدة البيانات (طرق العرض)

المفاهيم وتنفيذ Jetpack Compose

يمكنك تقديم تجربة مستخدم محسّنة من خلال التأكّد من إمكانية استخدام تطبيقك عندما تكون اتصالات الشبكة غير موثوقة أو عندما يكون المستخدم غير متصل بالإنترنت. ويمكنك إجراء ذلك من خلال تقسيم الصفحات من الشبكة ومن قاعدة بيانات محلية في الوقت نفسه. بهذه الطريقة، يعرض تطبيقك واجهة المستخدم من ذاكرة تخزين مؤقت لقاعدة بيانات محلية ولا يرسل طلبات إلى الشبكة إلا في حال عدم توفّر المزيد من البيانات في قاعدة البيانات.

يفترض هذا الدليل أنّك على دراية بمكتبة Room لاستدامة البيانات والاستخدام الأساسي لمكتبة Paging.

تنسيق عمليات تحميل البيانات

توفّر مكتبة Paging المكوّن RemoteMediator لحالة الاستخدام هذه. يعمل RemoteMediator كإشارة من مكتبة Paging عند نفاد البيانات المخزّنة مؤقتًا في التطبيق. يمكنك استخدام هذه الإشارة لتحميل بيانات إضافية من الشبكة وتخزينها في قاعدة البيانات المحلية، حيث يمكن لـ PagingSource تحميلها وتقديمها إلى واجهة المستخدم لعرضها.

عند الحاجة إلى بيانات إضافية، تستدعي مكتبة Paging الطريقة load() من تنفيذ RemoteMediator. هذه دالة تعليق، لذا من الآمن تنفيذ عمل طويل الأمد. تجلب هذه الدالة عادةً البيانات الجديدة من مصدر شبكة وتحفظها في مساحة التخزين المحلية.

تعمل هذه العملية مع البيانات الجديدة، ولكن بمرور الوقت تتطلب البيانات المخزّنة في قاعدة البيانات إبطالاً، مثلاً عندما يشغّل المستخدم عملية إعادة تحميل يدويًا. ويتم تمثيل ذلك من خلال السمة LoadType التي يتم تمريرها إلى الإجراء load(). يُعلم LoadType RemoteMediator ما إذا كان يحتاج إلى إعادة تحميل البيانات الحالية أو جلب بيانات إضافية يجب إلحاقها أو إضافتها إلى القائمة الحالية.

بهذه الطريقة، يضمن RemoteMediator أن يحمّل تطبيقك البيانات التي يريد المستخدمون رؤيتها بالترتيب المناسب.

دورة حياة التقسيم إلى صفحات

الشكل 1: مخطّط بياني لمراحل نشاط Paging باستخدام PagingSource وPagingData

عند التنقّل بين الصفحات مباشرةً من الشبكة، تحمّل PagingSource البيانات وتعرض عنصر LoadResult. يتم تمرير تنفيذ PagingSource إلى Pager من خلال المَعلمة pagingSourceFactory.

عندما تطلب واجهة المستخدم بيانات جديدة، يستدعي Pager طريقة load() من PagingSource ويعرض سلسلة من كائنات PagingData التي تغلّف البيانات الجديدة. يتم عادةً تخزين كل عنصر من عناصر PagingData مؤقتًا في ViewModel قبل إرساله إلى واجهة المستخدم لعرضه.

الشكل 2. رسم بياني لدورة حياة "تقسيم الصفحات" باستخدام PagingSource و RemoteMediator

يغيّر RemoteMediator تدفق البيانات هذا. يستمر PagingSource في تحميل البيانات، ولكن عند استنفاد البيانات المقسّمة إلى صفحات، تشغّل مكتبة Paging RemoteMediator لتحميل بيانات جديدة من مصدر الشبكة. يخزّن RemoteMediator البيانات الجديدة في قاعدة البيانات المحلية، لذا لا حاجة إلى ذاكرة تخزين مؤقت في الذاكرة في ViewModel. أخيرًا، يتم إبطال PagingSource، وينشئ Pager مثيلاً جديدًا لتحميل البيانات الجديدة من قاعدة البيانات.

الاستخدام الأساسي

لنفترض أنّك تريد أن يحمّل تطبيقك صفحات من عناصر User من مصدر بيانات شبكة مستند إلى مفتاح العناصر إلى ذاكرة تخزين مؤقت محلية مخزّنة في قاعدة بيانات Room.

يحمّل RemoteMediator البيانات من الشبكة إلى قاعدة البيانات،
    ويحمّل PagingSource البيانات من قاعدة البيانات. يستخدم Pager كلاً من
    RemoteMediator وPagingSource لتحميل البيانات المقسّمة إلى صفحات.
الشكل 3: مخطّط بياني لتنفيذ Paging يستخدم مصدر بيانات متعدّد الطبقات

يساعد تنفيذ RemoteMediator في تحميل البيانات المُقسَّمة إلى صفحات من الشبكة إلى قاعدة البيانات، ولكنّه لا يحمّل البيانات مباشرةً إلى واجهة المستخدم. بدلاً من ذلك، يستخدم التطبيق قاعدة البيانات كمصدر للمعلومات. بعبارة أخرى، يعرض التطبيق فقط البيانات التي تم تخزينها مؤقتًا في قاعدة البيانات. يتولّى تنفيذ PagingSource (على سبيل المثال، تنفيذ تم إنشاؤه بواسطة Room) تحميل البيانات المخزّنة مؤقتًا من قاعدة البيانات إلى واجهة المستخدم.

إنشاء كيانات الغرف

الخطوة الأولى هي استخدام مكتبة Room لاستدامة البيانات لتحديد قاعدة بيانات تحتوي على ذاكرة تخزين مؤقت محلية للبيانات المُقسَّمة إلى صفحات من مصدر بيانات الشبكة. ابدأ بتنفيذ RoomDatabase كما هو موضّح في مقالة حفظ البيانات في قاعدة بيانات محلية باستخدام Room.

بعد ذلك، حدِّد كيان Room لتمثيل جدول من عناصر القائمة كما هو موضّح في تحديد البيانات باستخدام كيانات Room. امنحه حقل id كمفتاح أساسي، بالإضافة إلى حقول لأي معلومات أخرى تحتوي عليها عناصر القائمة.

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

يجب أيضًا تحديد كائن الوصول إلى البيانات (DAO) لكيان Room هذا كما هو موضّح في الوصول إلى البيانات باستخدام كائنات الوصول إلى البيانات في Room. يجب أن يتضمن DAO لكيان عنصر القائمة الطرق التالية:

  • طريقة insertAll() تُدرج قائمة بالعناصر في الجدول.
  • هي طريقة تأخذ سلسلة طلب البحث كمَعلمة وتعرض عنصر PagingSource لقائمة النتائج. بهذه الطريقة، يمكن لكائن Pager استخدام هذا الجدول كمصدر للبيانات المقسّمة إلى صفحات.
  • طريقة 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();
}

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

يتمثّل الدور الرئيسي لـ RemoteMediator في تحميل المزيد من البيانات من الشبكة عندما تنفد البيانات من Pager أو يتم إبطال البيانات الحالية. وتتضمّن طريقة load() يجب إلغاؤها لتحديد سلوك التحميل.

يتضمّن التنفيذ المعتاد لـ RemoteMediator المَعلمات التالية:

  • ‫query: سلسلة طلب تحدّد البيانات التي سيتم استردادها من خدمة الخلفية
  • ‫database: قاعدة بيانات Room التي تعمل كذاكرة تخزين مؤقت محلية
  • ‫networkService: مثيل واجهة برمجة تطبيقات لخدمة الخلفية

أنشئ عملية تنفيذ RemoteMediator<Key, Value>. يجب أن يكون نوع Key ونوع Value متطابقَين مع ما سيكون عليه الحال إذا كنت تحدّد PagingSource مقابل مصدر بيانات الشبكة نفسه. لمزيد من المعلومات حول اختيار مَعلمات النوع، يُرجى الاطّلاع على اختيار أنواع المفاتيح والقيم.

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() مسؤولة عن تعديل مجموعة البيانات الداعمة وإبطال 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). بعد تخزين البيانات، يجب إبطال مصدر البيانات لإعلام مكتبة Paging بالبيانات الجديدة.
    • إذا تم التحميل بنجاح وكانت قائمة العناصر المستلَمة فارغة أو كانت آخر فهرس للصفحة، يتم عرض MediatorResult.Success(endOfPaginationReached = true). بعد تخزين البيانات، يجب إبطال مصدر البيانات لإعلام مكتبة Paging بالبيانات الجديدة.
    • إذا تسبّب الطلب في حدوث خطأ، يتم عرض MediatorResult.Error.

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

تحديد إجراء الإعداد

يمكن أيضًا لعمليات تنفيذ RemoteMediator إلغاء طريقة initialize() للتحقّق مما إذا كانت البيانات المخزّنة مؤقتًا قديمة وتحديد ما إذا كان يجب بدء إعادة تحميل عن بُعد. يتم تشغيل هذه الطريقة قبل إجراء أي تحميل، لذا يمكنك التعامل مع قاعدة البيانات (على سبيل المثال، لمحو البيانات القديمة) قبل بدء أي عمليات تحميل محلية أو عن بُعد.

بما أنّ initialize() هي دالة غير متزامنة، يمكنك تحميل البيانات لتحديد مدى صلة البيانات الحالية في قاعدة البيانات بالموضوع. الحالة الأكثر شيوعًا هي أنّ البيانات المخزّنة مؤقتًا تكون صالحة لفترة زمنية معيّنة فقط. يمكن لـ RemoteMediator التحقّق مما إذا كان وقت انتهاء الصلاحية هذا قد انقضى، وفي هذه الحالة تحتاج مكتبة Paging إلى إعادة تحميل البيانات بالكامل. يجب أن تعرض عمليات تنفيذ initialize() قيمة InitializeAction على النحو التالي:

  • في الحالات التي يجب فيها إعادة تحميل البيانات المحلية بالكامل، يجب أن تعرض initialize() القيمة InitializeAction.LAUNCH_INITIAL_REFRESH. يؤدي ذلك إلى إجراء RemoteMediator عملية إعادة تحميل عن بُعد لإعادة تحميل البيانات بالكامل. تنتظر أي عمليات تحميل عن بُعد لـ APPEND أو PREPEND نجاح عملية تحميل REFRESH قبل المتابعة.
  • في الحالات التي لا تحتاج فيها البيانات المحلية إلى إعادة تحميل، يجب أن تعرض initialize() القيمة InitializeAction.SKIP_INITIAL_REFRESH. يؤدي ذلك إلى تخطّي RemoteMediator لعملية إعادة التحميل عن بُعد وتحميل البيانات المخزّنة مؤقتًا.

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

إنشاء عنصر تنقّل بين الصفحات

أخيرًا، عليك إنشاء مثيل Pager لإعداد مصدر البيانات المقسّمة على صفحات. يشبه ذلك إنشاء Pager من مصدر بيانات شبكة بسيط، ولكن هناك أمران يجب تنفيذهما بشكل مختلف:

  • بدلاً من تمرير دالة الإنشاء PagingSource مباشرةً، يجب تقديم طريقة طلب البحث التي تعرض عنصر PagingSource من DAO.
  • يجب تقديم مثيل لتنفيذ RemoteMediator كمَعلمة remoteMediator.

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

إدارة المفاتيح عن بُعد

المفاتيح البعيدة هي مفاتيح تستخدمها عملية تنفيذ RemoteMediator لإعلام خدمة الخلفية بالبيانات التي يجب تحميلها بعد ذلك. في أبسط الحالات، يتضمّن كل عنصر من البيانات المقسّمة إلى صفحات مفتاحًا عن بُعد يمكنك الرجوع إليه بسهولة. ومع ذلك، إذا كانت المفاتيح البعيدة لا تتوافق مع العناصر الفردية، يجب تخزينها بشكل منفصل وإدارتها في طريقة load().

يوضّح هذا القسم كيفية جمع المفاتيح البعيدة وتخزينها وتعديلها، وهي المفاتيح التي لا يتم تخزينها في عناصر فردية.

مفاتيح العناصر

يوضّح هذا القسم كيفية التعامل مع المفاتيح البعيدة التي تتوافق مع عناصر فردية. عادةً، عندما تستخدم واجهة برمجة التطبيقات عناصر فردية، يتم تمرير معرّف العنصر كمَعلمة طلب بحث. يشير اسم المَعلمة إلى ما إذا كان يجب أن يستجيب الخادم بالعناصر قبل المعرّف المقدَّم أو بعده. في مثال فئة نموذج User، يتم استخدام حقل id من الخادم كمفتاح عن بُعد عند طلب بيانات إضافية.

عندما تحتاج طريقة load() إلى إدارة مفاتيح عن بُعد خاصة بالعناصر، تكون هذه المفاتيح عادةً معرّفات البيانات التي تم جلبها من الخادم. لا تحتاج عمليات إعادة التحميل إلى مفتاح تحميل، لأنّها تسترد أحدث البيانات فقط. وبالمثل، لا تحتاج عمليات الإضافة إلى بداية القائمة إلى جلب أي بيانات إضافية لأنّ عملية إعادة التحميل تسحب دائمًا أحدث البيانات من الخادم.

ومع ذلك، تتطلّب عمليات الإلحاق معرّفًا. يتطلب ذلك تحميل العنصر الأخير من قاعدة البيانات واستخدام معرّفه لتحميل الصفحة التالية من البيانات. إذا لم تكن هناك عناصر في قاعدة البيانات، يتم ضبط endOfPaginationReached على "صحيح"، ما يشير إلى الحاجة إلى إعادة تحميل البيانات.

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

مفاتيح الصفحة

يوضّح هذا القسم كيفية التعامل مع المفاتيح البعيدة التي لا تتوافق مع عناصر فردية.

إضافة جدول مفاتيح خارجي

عندما لا تكون المفاتيح البعيدة مرتبطة مباشرةً بعناصر القائمة، من الأفضل تخزينها في جدول منفصل في قاعدة البيانات المحلية. حدِّد كيان Room يمثّل جدولاً للمفاتيح البعيدة:

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

يجب أيضًا تحديد DAO لكيان RemoteKey:

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

التحميل باستخدام مفاتيح التحكّم عن بُعد

عندما تحتاج طريقة load() إلى إدارة مفاتيح الصفحات البعيدة، يجب تحديدها بشكل مختلف بالطرق التالية مقارنةً بالاستخدام الأساسي لـ RemoteMediator:

  • أضِف سمة إضافية تحتوي على مرجع إلى DAO لجدول المفاتيح البعيدة.
  • تحديد المفتاح التالي الذي سيتم تحميله من خلال الاستعلام عن جدول المفاتيح البعيدة بدلاً من استخدام PagingState
  • أدخِل المفتاح البعيد الذي تم عرضه من مصدر بيانات الشبكة أو خزِّنه بالإضافة إلى البيانات المقسّمة إلى صفحات نفسها.

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

مراجع إضافية

لمزيد من المعلومات حول مكتبة Paging، يُرجى الاطّلاع على المراجع الإضافية التالية:

نماذج