refactor(firestore): migrate pagination to Paging 3 (#1915)

Author: thatfiredev

app/src/main/java/com/firebase/uidemo/database/firestore/FirestorePagingActivity.java

@@ -12,7 +12,6 @@
 
 import com.firebase.ui.firestore.paging.FirestorePagingAdapter;
 import com.firebase.ui.firestore.paging.FirestorePagingOptions;
-import com.firebase.ui.firestore.paging.LoadingState;
 import com.firebase.uidemo.R;
 import com.firebase.uidemo.databinding.ActivityFirestorePagingBinding;
 import com.google.android.gms.tasks.OnCompleteListener;
@@ -27,10 +26,14 @@
 import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
 import androidx.appcompat.app.AppCompatActivity;
-import androidx.paging.PagedList;
+import androidx.paging.CombinedLoadStates;
+import androidx.paging.LoadState;
+import androidx.paging.PagingConfig;
 import androidx.recyclerview.widget.LinearLayoutManager;
 import androidx.recyclerview.widget.RecyclerView;
 import androidx.swiperefreshlayout.widget.SwipeRefreshLayout;
+import kotlin.Unit;
+import kotlin.jvm.functions.Function1;
 
 public class FirestorePagingActivity extends AppCompatActivity {
 
@@ -56,11 +59,7 @@ protected void onCreate(@Nullable Bundle savedInstanceState) {
     private void setUpAdapter() {
         Query baseQuery = mItemsCollection.orderBy("value", Query.Direction.ASCENDING);
 
-        PagedList.Config config = new PagedList.Config.Builder()
-                .setEnablePlaceholders(false)
-                .setPrefetchDistance(10)
-                .setPageSize(20)
-                .build();
+        PagingConfig config = new PagingConfig(20, 10, false);
 
         FirestorePagingOptions<Item> options = new FirestorePagingOptions.Builder<Item>()
                 .setLifecycleOwner(this)
@@ -84,34 +83,42 @@ protected void onBindViewHolder(@NonNull ItemViewHolder holder,
                                                     @NonNull Item model) {
                         holder.bind(model);
                     }
+                };
+        adapter.addLoadStateListener(new Function1<CombinedLoadStates, Unit>() {
+            @Override
+            public Unit invoke(CombinedLoadStates states) {
+                LoadState refresh = states.getRefresh();
+                LoadState append = states.getAppend();
 
-                    @Override
-                    protected void onLoadingStateChanged(@NonNull LoadingState state) {
-                        switch (state) {
-                            case LOADING_INITIAL:
-                            case LOADING_MORE:
-                                mBinding.swipeRefreshLayout.setRefreshing(true);
-                                break;
-                            case LOADED:
-                                mBinding.swipeRefreshLayout.setRefreshing(false);
-                                break;
-                            case FINISHED:
-                                mBinding.swipeRefreshLayout.setRefreshing(false);
-                                showToast("Reached end of data set.");
-                                break;
-                            case ERROR:
-                                showToast("An error occurred.");
-                                retry();
-                                break;
-                        }
+                if (refresh instanceof LoadState.Error || append instanceof LoadState.Error) {
+                    showToast("An error occurred.");
+                    adapter.retry();
+                }
+
+                if (append instanceof LoadState.Loading) {
+                    mBinding.swipeRefreshLayout.setRefreshing(true);
+                }
+
+                if (append instanceof LoadState.NotLoading) {
+                    LoadState.NotLoading notLoading = (LoadState.NotLoading) append;
+                    if (notLoading.getEndOfPaginationReached()) {
+                        // This indicates that the user has scrolled
+                        // until the end of the data set.
+                        mBinding.swipeRefreshLayout.setRefreshing(false);
+                        showToast("Reached end of data set.");
+                        return null;
                     }
 
-                    @Override
-                    protected void onError(@NonNull Exception e) {
+                    if (refresh instanceof LoadState.NotLoading) {
+                        // This indicates the most recent load
+                        // has finished.
                         mBinding.swipeRefreshLayout.setRefreshing(false);
-                        Log.e(TAG, e.getMessage(), e);
+                        return null;
                     }
-                };
+                }
+                return null;
+            }
+        });
 
         mBinding.pagingRecycler.setLayoutManager(new LinearLayoutManager(this));
         mBinding.pagingRecycler.setAdapter(adapter);

buildSrc/src/main/kotlin/Config.kt

@@ -37,7 +37,8 @@ object Config {
             const val lifecycleViewModel = "androidx.lifecycle:lifecycle-viewmodel:2.2.0"
             const val legacySupportv4 = "androidx.legacy:legacy-support-v4:1.0.0"
             const val multidex = "androidx.multidex:multidex:2.0.1"
-            const val paging = "androidx.paging:paging-runtime:2.1.2"
+            const val paging = "androidx.paging:paging-runtime:3.0.0"
+            const val pagingRxJava = "androidx.paging:paging-rxjava3:3.0.0"
             const val recyclerView = "androidx.recyclerview:recyclerview:1.1.0"
 
             const val design = "com.google.android.material:material:1.2.1"

firestore/README.md

@@ -249,11 +249,11 @@ The `FirestorePagingAdapter` binds a `Query` to a `RecyclerView` by loading docu
 This results in a time and memory efficient binding, however it gives up the real-time events
 afforded by the `FirestoreRecyclerAdapter`.
 
-The `FirestorePagingAdapter` is built on top of the [Android Paging Support Library][paging-support].
-Before using the adapter in your application, you must add a dependency on the support library:
+The `FirestorePagingAdapter` is built on top of the [Android Paging 3 Library][paging-support].
+Before using the adapter in your application, you must add a dependency on that library:
 
 ```groovy
-implementation 'androidx.paging:paging-runtime:2.x.x'
+implementation 'androidx.paging:paging-runtime:3.x.x'
 ```
 
 First, configure the adapter by building `FirestorePagingOptions`. Since the paging adapter
@@ -262,16 +262,13 @@ an adapter that loads a generic `Item`:
 
 ```java
 // The "base query" is a query with no startAt/endAt/limit clauses that the adapter can use
-// to form smaller queries for each page.  It should only include where() and orderBy() clauses
+// to form smaller queries for each page. It should only include where() and orderBy() clauses
 Query baseQuery = mItemsCollection.orderBy("value", Query.Direction.ASCENDING);
 
-// This configuration comes from the Paging Support Library
-// https://developer.android.com/reference/androidx/paging/PagedList.Config
-PagedList.Config config = new PagedList.Config.Builder()
-        .setEnablePlaceholders(false)
-        .setPrefetchDistance(10)
-        .setPageSize(20)
-        .build();
+// This configuration comes from the Paging 3 Library
+// https://developer.android.com/reference/kotlin/androidx/paging/PagingConfig
+PagingConfig config = new PagingConfig(/* page size */ 20, /* prefetchDistance */ 10,
+    /* enablePlaceHolders */ false);
 
 // The options for the adapter combine the paging configuration with query information
 // and application-specific options for lifecycle, etc.
@@ -362,38 +359,103 @@ start and stop listening in `onStart()` and `onStop()`.
 #### Paging events
 
 When using the `FirestorePagingAdapter`, you may want to perform some action every time data
-changes or when there is an error. To do this, override the `onLoadingStateChanged()`
-method of the adapter:
+changes or when there is an error. To do this:
 
-```java
-FirestorePagingAdapter<Item, ItemViewHolder> adapter =
-        new FirestorePagingAdapter<Item, ItemViewHolder>(options) {
+##### In Java
 
-            // ...
+Use the `addLoadStateListener` method from the adapter:
 
+```java
+adapter.addLoadStateListener(new Function1<CombinedLoadStates, Unit>() {
             @Override
-            protected void onLoadingStateChanged(@NonNull LoadingState state) {
-                switch (state) {
-                    case LOADING_INITIAL:
-                        // The initial load has begun
-                        // ...
-                    case LOADING_MORE:
-                        // The adapter has started to load an additional page
+            public Unit invoke(CombinedLoadStates states) {
+                LoadState refresh = states.getRefresh();
+                LoadState append = states.getAppend();
+
+                if (refresh instanceof LoadState.Error || append instanceof LoadState.Error) {
+                    // The previous load (either initial or additional) failed. Call
+                    // the retry() method in order to retry the load operation.
+                    // ...
+                }
+
+                if (refresh instanceof LoadState.Loading) {
+                    // The initial Load has begun
+                    // ...
+                }
+
+                if (append instanceof LoadState.Loading) {
+                    // The adapter has started to load an additional page
+                    // ...
+                }
+
+                if (append instanceof LoadState.NotLoading) {
+                    LoadState.NotLoading notLoading = (LoadState.NotLoading) append;
+                    if (notLoading.getEndOfPaginationReached()) {
+                        // The adapter has finished loading all of the data set
                         // ...
-                    case LOADED:
+                        return null;
+                    }
+
+                    if (refresh instanceof LoadState.NotLoading) {
                         // The previous load (either initial or additional) completed
                         // ...
-                    case ERROR:
-                        // The previous load (either initial or additional) failed. Call
-                        // the retry() method in order to retry the load operation.
-                        // ...
+                        return null;
+                    }
                 }
+                return null;
             }
-        };
+        });
+```
+
+#### In Kotlin
+
+Use the `loadStateFlow` exposed by the adapter, in a Coroutine Scope:
+
+```kotlin
+// Activities can use lifecycleScope directly, but Fragments should instead use
+// viewLifecycleOwner.lifecycleScope.
+lifecycleScope.launch {
+    pagingAdapter.loadStateFlow.collectLatest { loadStates ->
+        when (loadStates.refresh) {
+            is LoadState.Error -> {
+                // The initial load failed. Call the retry() method
+                // in order to retry the load operation.
+                // ...
+            }
+            is LoadState.Loading -> {
+                // The initial Load has begun
+                // ...
+            }
+        }
+
+        when (loadStates.append) {
+            is LoadState.Error -> {
+                // The additional load failed. Call the retry() method
+                // in order to retry the load operation.
+                // ...
+            }
+            is LoadState.Loading -> {
+                // The adapter has started to load an additional page
+                // ...
+            }
+            is LoadState.NotLoading -> {
+                if (loadStates.append.endOfPaginationReached) {
+                    // The adapter has finished loading all of the data set
+                    // ...
+                }
+                if (loadStates.refresh is LoadState.NotLoading) {
+                    // The previous load (either initial or additional) completed
+                    // ...
+                }
+            }
+        }
+  }
+}
+
 ```
 
 [firestore-docs]: https://firebase.google.com/docs/firestore/
 [firestore-custom-objects]: https://firebase.google.com/docs/firestore/manage-data/add-data#custom_objects
 [recyclerview]: https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView
 [arch-components]: https://developer.android.com/topic/libraries/architecture/index.html
-[paging-support]: https://developer.android.com/topic/libraries/architecture/paging.html
+[paging-support]: https://developer.android.com/topic/libraries/architecture/paging/v3-overview

firestore/build.gradle.kts

@@ -42,6 +42,11 @@ android {
             consumerProguardFiles("proguard-rules.pro")
         }
     }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_1_8
+        targetCompatibility = JavaVersion.VERSION_1_8
+    }
 }
 
 dependencies {
@@ -53,6 +58,7 @@ dependencies {
     api(Config.Libs.Androidx.recyclerView)
 
     compileOnly(Config.Libs.Androidx.paging)
+    api(Config.Libs.Androidx.pagingRxJava)
     annotationProcessor(Config.Libs.Androidx.lifecycleCompiler)
 
     lintChecks(project(":lint"))