Add documentation

Change-Id: I1d5cf1f6d49d5964b7cd5d702ccd7a24db3f79a8

Author: samtstern

firestore/README.md

@@ -12,9 +12,13 @@ Before using this library, you should be familiar with the following topics:
 1. [Data model](#data-model)
 1. [Querying](#querying)
 1. [Populating a RecyclerView](#using-firebaseui-to-populate-a-recyclerview)
-   1. [Using the adapter](#using-the-firestorerecycleradapter)
-   1. [Adapter lifecyle](#firestorerecycleradapter-lifecycle)
-   1. [Events](#data-and-error-events)
+   1. [Choosing an adapter](#choosing-an-adapter)
+   1. [Using the FirestoreRecyclerAdapter](#using-the-firestorerecycleradapter)
+       1. [Adapter lifecyle](#firestorerecycleradapter-lifecycle)
+       1. [Events](#data-and-error-events)
+   1. [Using the FirestoreRecyclerAdapter](#using-the-firestorepagingadapter)
+       1. [Adapter lifecyle](#firestorepagingadapter-lifecycle)
+       1. [Events](#paging-events)
 
 ## Data model
 
@@ -109,6 +113,18 @@ updates with the `EventListener` on the `Query`.
 
 Fear not, FirebaseUI does all of this for you automatically!
 
+
+### Choosing an adapter
+
+FirebaseUI offers two types of RecyclerView adapters for Cloud Firestore:
+
+  * `FirestoreRecyclerAdapter` - bind a `Query` to a `RecyclerView` and respond to all real-time
+    events included items being added, removed, moved, or changed. Best used with small result sets
+    since all results are loaded at once.
+  * `FirestorePagingAdapter` - bind a `Query` to a `RecyclerView` by loading data in pages. Best
+    used with large, static data sets. Real-time events are not respected by this adapter, so it
+    will not detect new/removed items or changes to items already loaded.
+
 ### Using the `FirestoreRecyclerAdapter`
 
 The `FirestoreRecyclerAdapter` binds a `Query` to a `RecyclerView`. When documents are added,
@@ -164,9 +180,9 @@ FirestoreRecyclerAdapter adapter = new FirestoreRecyclerAdapter<Chat, ChatHolder
 Finally attach the adapter to your `RecyclerView` with the `RecyclerView#setAdapter()`.
 Don't forget to also set a `LayoutManager`!
 
-### `FirestoreRecyclerAdapter` lifecycle
+#### `FirestoreRecyclerAdapter` lifecycle
 
-#### Start/stop listening
+##### Start/stop listening
 
 The `FirestoreRecyclerAdapter` uses a snapshot listener to monitor changes to the Firestore query.
 To begin listening for data, call the `startListening()` method. You may want to call this
@@ -192,15 +208,15 @@ protected void onStop() {
 }
 ```
 
-#### Automatic listening
+##### Automatic listening
 
 If you don't want to manually start/stop listening you can use
 [Android Architecture Components][arch-components] to automatically manage the lifecycle of the
 `FirestoreRecyclerAdapter`. Pass a `LifecycleOwner` to
 `FirestoreRecyclerOptions.Builder#setLifecycleOwner(...)` and FirebaseUI will automatically
 start and stop listening in `onStart()` and `onStop()`.
 
-### Data and error events
+#### Data and error events
 
 When using the `FirestoreRecyclerAdapter` you may want to perform some action every time data
 changes or when there is an error. To do this, override the `onDataChanged()` and `onError()`
@@ -227,7 +243,155 @@ FirestoreRecyclerAdapter adapter = new FirestoreRecyclerAdapter<Chat, ChatHolder
 ```
 
 
+### Using the `FirestorePagingAdapter`
+
+The `FirestorePagingAdapter` binds a `Query` to a `RecyclerView` by loading documents in pages.
+This results in a time and memory efficient binding, however it gives up the real-time events
+afforted by the `FirestoreRecyclerAdaoter`.
+
+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:
+
+```groovy
+implementation 'android.arch.paging:runtime:1.0.0-beta1'
+```
+
+First, configure the adapter by building `FirestorePagingOptions`. Since the paging adapter
+is not appropriate for a chat application (it would not detect new messages), we will consider
+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
+Query baseQuery = mItemsCollection.orderBy("value", Query.Direction.ASCENDING);
+
+// This configuration comes from the Paging Support Library
+// https://developer.android.com/reference/android/arch/paging/PagedList.Config.html
+PagedList.Config config = new PagedList.Config.Builder()
+        .setEnablePlaceholders(false)
+        .setPrefetchDistance(10)
+        .setPageSize(20)
+        .build();
+
+// The options for the adapter combine the paging configuration with query information
+// and application-specific options for lifecycle, etc.
+FirestorePagingOptions<Item> options = new FirestorePagingOptions.Builder<Item>()
+        .setLifecycleOwner(this)
+        .setQuery(baseQuery, config, Item.class)
+        .build();
+```
+
+If you need to customize how your model class is parsed, you can use a custom `SnapshotParser`:
+
+```java
+...setQuery(..., new SnapshotParser<Item>() {
+    @NonNull
+    @Override
+    public Item parseSnapshot(@NonNull DocumentSnapshot snapshot) {
+        return ...;
+    }
+});
+```
+
+Next create the `FirestorePagingAdapter` object. You should already have a `ViewHolder` subclass
+for displaying each item. In this case we will use a custom `ItemViewHolder` class:
+
+```java
+FirestorePagingAdapter<Item, ItemViewHolder> adapter =
+        new FirestorePagingAdapter<Item, ItemViewHolder>(options) {
+            @NonNull
+            @Override
+            public ItemViewHolder onCreateViewHolder(@NonNull ViewGroup parent, int viewType) {
+                // Create the ItemViewHolder
+                // ,,,
+            }
+
+            @Override
+            protected void onBindViewHolder(@NonNull ItemViewHolder holder,
+                                            int position,
+                                            @NonNull Item model) {
+                // Bind the item to the view holder
+                // ...
+            }
+        };
+```
+
+Finally attach the adapter to your `RecyclerView` with the `RecyclerView#setAdapter()`.
+Don't forget to also set a `LayoutManager`!
+
+#### `FirestorePagingAdapter` lifecycle
+
+##### Start/stop listening
+
+The `FirestorePagingAdapter` listens for scrolling events and loads additional pages from the
+database only when needed.
+
+To begin populating data, call the `startListening()` method. You may want to call this
+in your `onStart()` method. Make sure you have finished any authentication necessary to read the
+data before calling `startListening()` or your query will fail.
+
+```java
+@Override
+protected void onStart() {
+    super.onStart();
+    adapter.startListening();
+}
+```
+
+Similarly, the `stopListening()` call removes the snapshot listener and all data in the adapter.
+Call this method when the containing Activity or Fragment stops:
+
+```java
+@Override
+protected void onStop() {
+    super.onStop();
+    adapter.stopListening();
+}
+```
+
+##### Automatic listening
+
+If you don't want to manually start/stop listening you can use
+[Android Architecture Components][arch-components] to automatically manage the lifecycle of the
+`FirestorePagingAdapter`. Pass a `LifecycleOwner` to
+`FirestorePagingOptions.Builder#setLifecycleOwner(...)` and FirebaseUI will automatically
+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:
+
+```java
+FirestorePagingAdapter<Item, ItemViewHolder> adapter =
+        new FirestorePagingAdapter<Item, ItemViewHolder>(options) {
+
+            // ...
+
+            @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
+                        // ...
+                    case LOADED:
+                        // 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.
+                        // ...
+                }
+            }
+        };
+```
+
 [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/android/support/v7/widget/RecyclerView.html
 [arch-components]: https://developer.android.com/topic/libraries/architecture/index.html
+[paging-support]: https://developer.android.com/topic/libraries/architecture/paging.html

firestore/src/androidTest/java/com/firebase/ui/firestore/FirestoreDataSourceTest.java

@@ -10,7 +10,6 @@
 import com.firebase.ui.firestore.paging.PageKey;
 import com.google.android.gms.tasks.Tasks;
 import com.google.firebase.firestore.DocumentSnapshot;
-import com.google.firebase.firestore.FirebaseFirestore;
 import com.google.firebase.firestore.Query;
 import com.google.firebase.firestore.QuerySnapshot;
 
@@ -21,6 +20,7 @@
 import org.mockito.MockitoAnnotations;
 
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.List;
 import java.util.concurrent.CountDownLatch;
 
@@ -33,9 +33,6 @@
 @RunWith(AndroidJUnit4.class)
 public class FirestoreDataSourceTest {
 
-    private static final String TAG = "DataSourceTest";
-
-    private FirebaseFirestore mFirestore;
     private FirestoreDataSource mDataSource;
 
     @Mock Query mMockQuery;
@@ -65,7 +62,7 @@ public void testLoadInitial_success() throws Exception {
 
         // Should go from LOADING_INITIAL --> LOADED
         observer.await();
-        observer.assertResults(LoadingState.LOADING_INITIAL, LoadingState.LOADED);
+        observer.assertResults(Arrays.asList(LoadingState.LOADING_INITIAL, LoadingState.LOADED));
     }
 
     @Test
@@ -82,7 +79,7 @@ public void testLoadInitial_failure() throws Exception {
 
         // Should go from LOADING_INITIAL --> ERROR
         observer.await();
-        observer.assertResults(LoadingState.LOADING_INITIAL, LoadingState.ERROR);
+        observer.assertResults(Arrays.asList(LoadingState.LOADING_INITIAL, LoadingState.ERROR));
     }
 
     @Test
@@ -100,7 +97,7 @@ public void testLoadAfter_success() throws Exception {
 
         // Should go from LOADING_MORE --> LOADED
         observer.await();
-        observer.assertResults(LoadingState.LOADING_MORE, LoadingState.LOADED);
+        observer.assertResults(Arrays.asList(LoadingState.LOADING_MORE, LoadingState.LOADED));
     }
 
     @Test
@@ -118,7 +115,7 @@ public void testLoadAfter_failure() throws Exception {
 
         // Should go from LOADING_MORE --> ERROR
         observer.await();
-        observer.assertResults(LoadingState.LOADING_MORE, LoadingState.ERROR);
+        observer.assertResults(Arrays.asList(LoadingState.LOADING_MORE, LoadingState.ERROR));
     }
 
     @Test
@@ -136,7 +133,7 @@ public void testLoadAfter_retry() throws Exception {
 
         // Should go from LOADING_MORE --> ERROR
         observer1.await();
-        observer1.assertResults(LoadingState.LOADING_MORE, LoadingState.ERROR);
+        observer1.assertResults(Arrays.asList(LoadingState.LOADING_MORE, LoadingState.ERROR));
 
         // Create a new observer
         TestObserver<LoadingState> observer2 = new TestObserver<>(3);
@@ -148,7 +145,8 @@ public void testLoadAfter_retry() throws Exception {
 
         // Should go from ERROR --> LOADING_MORE --> SUCCESS
         observer2.await();
-        observer2.assertResults(LoadingState.ERROR, LoadingState.LOADING_MORE, LoadingState.LOADED);
+        observer2.assertResults(
+                Arrays.asList(LoadingState.ERROR, LoadingState.LOADING_MORE, LoadingState.LOADED));
     }
 
     private void initMockQuery() {
@@ -194,11 +192,11 @@ public void await() throws InterruptedException {
             mLatch.await();
         }
 
-        public void assertResults(T... results) {
-            assertEquals(results.length, mResults.size());
+        public void assertResults(List<T> expected) {
+            assertEquals(expected.size(), mResults.size());
 
             for (int i = 0; i < mResults.size(); i++) {
-                assertEquals(mResults.get(i), results[i]);
+                assertEquals(mResults.get(i), expected.get(i));
             }
         }
 

firestore/src/main/java/com/firebase/ui/firestore/paging/FirestorePagingAdapter.java

@@ -58,6 +58,9 @@ public void onChanged(@Nullable PagedList<DocumentSnapshot> snapshots) {
                 }
             };
 
+    /**
+     * Construct a new FirestorePagingAdapter from the given {@link FirestorePagingOptions}.
+     */
     public FirestorePagingAdapter(@NonNull FirestorePagingOptions<T> options) {
         super(options.getDiffCallback());
 
@@ -101,12 +104,18 @@ public void retry() {
         source.retry();
     }
 
+    /**
+     * Start listening to paging / scrolling events and populating adapter data.
+     */
     @OnLifecycleEvent(Lifecycle.Event.ON_START)
     public void startListening() {
         mSnapshots.observeForever(mDataObserver);
         mLoadingState.observeForever(mStateObserver);
     }
 
+    /**
+     * Unsubscribe from paging / scrolling events, no more data will be populated.
+     */
     @OnLifecycleEvent(Lifecycle.Event.ON_STOP)
     public void stopListening() {
         mSnapshots.removeObserver(mDataObserver);
@@ -119,8 +128,18 @@ public void onBindViewHolder(@NonNull VH holder, int position) {
         onBindViewHolder(holder, position, mParser.parseSnapshot(snapshot));
     }
 
+    /**
+     * @param model the model object containing the data that should be used to populate the view.
+     * @see #onBindViewHolder(RecyclerView.ViewHolder, int)
+     */
     protected abstract void onBindViewHolder(@NonNull VH holder, int position, @NonNull T model);
 
+    /**
+     * Called whenever the loading state of the adapter changes.
+     *
+     * When the state is {@link LoadingState#ERROR} the adapter will stop loading any data unless
+     * {@link #retry()} is called.
+     */
     protected void onLoadingStateChanged(@NonNull LoadingState state) {
         // For overriding
     }