Source added

paging/app/build.gradle.kts

@@ -0,0 +1,16 @@
+plugins {
+  id("signal-sample-app")
+  alias(libs.plugins.compose.compiler)
+}
+
+android {
+  namespace = "org.signal.pagingtest"
+
+  defaultConfig {
+    applicationId = "org.signal.pagingtest"
+  }
+}
+
+dependencies {
+  implementation(project(":paging"))
+}

paging/app/src/main/AndroidManifest.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest
+    xmlns:android="http://schemas.android.com/apk/res/android">
+
+  <application
+      android:allowBackup="true"
+      android:icon="@mipmap/ic_launcher"
+      android:label="@string/app_name"
+      android:roundIcon="@mipmap/ic_launcher_round"
+      android:supportsRtl="true"
+      android:theme="@style/Theme.PagingTest">
+    <activity android:name=".MainActivity"
+        android:exported="true">
+      <intent-filter>
+        <action android:name="android.intent.action.MAIN" />
+
+        <category android:name="android.intent.category.LAUNCHER" />
+      </intent-filter>
+    </activity>
+  </application>
+
+</manifest>

paging/app/src/main/java/org/signal/pagingtest/EventListener.java

@@ -0,0 +1,5 @@
+package org.signal.pagingtest;
+
+interface EventListener {
+  void onItemClicked(String key);
+}

paging/app/src/main/java/org/signal/pagingtest/Item.java

@@ -0,0 +1,11 @@
+package org.signal.pagingtest;
+
+public final class Item {
+  final String key;
+  final long   timestamp;
+
+  public Item(String key, long timestamp) {
+    this.key       = key;
+    this.timestamp = timestamp;
+  }
+}

paging/app/src/main/java/org/signal/pagingtest/MainActivity.java

@@ -0,0 +1,191 @@
+package org.signal.pagingtest;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+import androidx.appcompat.app.AppCompatActivity;
+import androidx.lifecycle.ViewModelProvider;
+import androidx.recyclerview.widget.DiffUtil;
+import androidx.recyclerview.widget.LinearLayoutManager;
+import androidx.recyclerview.widget.RecyclerView;
+
+import android.os.Bundle;
+import android.view.LayoutInflater;
+import android.view.View;
+import android.view.ViewGroup;
+import android.widget.TextView;
+
+import org.signal.paging.PagingController;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+import java.util.Optional;
+
+public class MainActivity extends AppCompatActivity implements EventListener {
+
+  private MainViewModel viewModel;
+
+  @Override
+  protected void onCreate(Bundle savedInstanceState) {
+    super.onCreate(savedInstanceState);
+    setContentView(R.layout.activity_main);
+
+    MyAdapter           adapter       = new MyAdapter(this);
+    RecyclerView        list          = findViewById(R.id.list);
+    LinearLayoutManager layoutManager = new LinearLayoutManager(this);
+
+    list.setAdapter(adapter);
+    list.setLayoutManager(layoutManager);
+
+    viewModel = new ViewModelProvider(this, new ViewModelProvider.NewInstanceFactory()).get(MainViewModel.class);
+    adapter.setPagingController(viewModel.getPagingController());
+    viewModel.getList().observe(this, newList -> {
+      adapter.submitList(newList);
+    });
+
+    findViewById(R.id.invalidate_btn).setOnClickListener(v -> {
+      viewModel.getPagingController().onDataInvalidated();
+    });
+
+    findViewById(R.id.down250_btn).setOnClickListener(v -> {
+      int target = Math.min(adapter.getItemCount() - 1, layoutManager.findFirstVisibleItemPosition() + 250);
+      layoutManager.scrollToPosition(target);
+    });
+
+    findViewById(R.id.up250_btn).setOnClickListener(v -> {
+      int target = Math.max(0, layoutManager.findFirstVisibleItemPosition() - 250);
+      layoutManager.scrollToPosition(target);
+    });
+
+    findViewById(R.id.prepend_btn).setOnClickListener(v -> {
+      viewModel.prependItems();
+    });
+  }
+
+  @Override
+  public void onItemClicked(String key) {
+    viewModel.onItemClicked(key);
+  }
+
+  static class MyAdapter extends RecyclerView.Adapter<MyViewHolder> {
+
+    private final static int TYPE_NORMAL      = 1;
+    private final static int TYPE_PLACEHOLDER = -1;
+
+    private final EventListener listener;
+    private final List<Item>    data;
+
+    private PagingController<String> controller;
+
+    public MyAdapter(@NonNull EventListener listener) {
+      this.listener = listener;
+      this.data     = new ArrayList<>();
+
+      setHasStableIds(true);
+    }
+
+    @Override
+    public int getItemViewType(int position) {
+      return getItem(position) == null ? TYPE_PLACEHOLDER : TYPE_NORMAL;
+    }
+
+    @Override
+    public int getItemCount() {
+      return data.size();
+    }
+
+    @Override
+    public long getItemId(int position) {
+      Item item = getItem(position);
+      if (item != null) {
+        return item.key.hashCode();
+      } else {
+        return 0;
+      }
+    }
+
+    @Override
+    public @NonNull MyViewHolder onCreateViewHolder(@NonNull ViewGroup parent, int viewType) {
+      switch (viewType) {
+        case TYPE_NORMAL:
+        case TYPE_PLACEHOLDER:
+          return new MyViewHolder(LayoutInflater.from(parent.getContext()).inflate(R.layout.item, parent, false));
+        default:
+          throw new AssertionError();
+      }
+    }
+
+    @Override
+    public void onBindViewHolder(@NonNull MyViewHolder holder, int position) {
+      holder.bind(getItem(position), position, listener);
+    }
+
+    private Item getItem(int index) {
+      if (controller != null) {
+        controller.onDataNeededAroundIndex(index);
+      }
+      return data.get(index);
+    }
+
+    void setPagingController(PagingController<String> pagingController) {
+      this.controller = pagingController;
+    }
+
+    void submitList(List<Item> list) {
+      DiffUtil.DiffResult result = DiffUtil.calculateDiff(new DiffUtil.Callback() {
+        @Override
+        public int getOldListSize() {
+          return data.size();
+        }
+
+        @Override
+        public int getNewListSize() {
+          return list.size();
+        }
+
+        @Override
+        public boolean areItemsTheSame(int oldItemPosition, int newItemPosition) {
+          String oldKey = Optional.ofNullable(data.get(oldItemPosition)).map(item -> item.key).orElse(null);
+          String newKey = Optional.ofNullable(list.get(newItemPosition)).map(item -> item.key).orElse(null);
+
+          return Objects.equals(oldKey, newKey);
+        }
+
+        @Override
+        public boolean areContentsTheSame(int oldItemPosition, int newItemPosition) {
+          Long oldKey = Optional.ofNullable(data.get(oldItemPosition)).map(item -> item.timestamp).orElse(null);
+          Long newKey = Optional.ofNullable(list.get(newItemPosition)).map(item -> item.timestamp).orElse(null);
+
+          return Objects.equals(oldKey, newKey);
+        }
+      }, false);
+
+      result.dispatchUpdatesTo(this);
+
+      data.clear();
+      data.addAll(list);
+    }
+  }
+
+  static class MyViewHolder extends RecyclerView.ViewHolder {
+
+    TextView textView;
+
+    public MyViewHolder(@NonNull View itemView) {
+      super(itemView);
+      textView = itemView.findViewById(R.id.text);
+    }
+
+    void bind(@Nullable Item item, int position, @NonNull EventListener listener) {
+      if (item != null) {
+        textView.setText(position + " | " + item.key.substring(0, 13) + " | " + System.currentTimeMillis());
+        textView.setOnClickListener(v -> {
+          listener.onItemClicked(item.key);
+        });
+      } else {
+        textView.setText(position + " | PLACEHOLDER");
+        textView.setOnClickListener(null);
+      }
+    }
+  }
+}

paging/app/src/main/java/org/signal/pagingtest/MainDataSource.java

@@ -0,0 +1,70 @@
+package org.signal.pagingtest;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+
+import org.signal.paging.PagedDataSource;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.ListIterator;
+import java.util.UUID;
+
+class MainDataSource implements PagedDataSource<String, Item> {
+
+  private final List<Item> items = new ArrayList<>();
+
+  MainDataSource(int size) {
+    buildItems(size);
+  }
+
+  @Override
+  public int size() {
+    return items.size();
+  }
+
+  @Override
+  public @NonNull List<Item> load(int start, int length, int totalSize, @NonNull CancellationSignal cancellationSignal) {
+    try {
+      Thread.sleep(500);
+    } catch (InterruptedException e) {
+      e.printStackTrace();
+    }
+
+    return items.subList(start, start + length);
+  }
+
+  @Override
+  public @Nullable Item load(String key) {
+    return items.stream().filter(item -> item.key.equals(key)).findFirst().orElse(null);
+  }
+
+  @Override
+  public @NonNull String getKey(@NonNull Item item) {
+    return item.key;
+  }
+
+  public void updateItem(@NonNull String key) {
+    ListIterator<Item> iter = items.listIterator();
+    while (iter.hasNext()) {
+      if (iter.next().key.equals(key)) {
+        iter.set(new Item(key, System.currentTimeMillis()));
+        break;
+      }
+    }
+  }
+
+  public @NonNull String prepend() {
+    Item item = new Item(UUID.randomUUID().toString(), System.currentTimeMillis());
+    items.add(0, item);
+    return item.key;
+  }
+
+  private void buildItems(int size) {
+    items.clear();
+
+    for (int i = 0; i < size; i++) {
+      items.add(new Item(UUID.randomUUID().toString(), System.currentTimeMillis()));
+    }
+  }
+}

paging/app/src/main/java/org/signal/pagingtest/MainViewModel.java

@@ -0,0 +1,44 @@
+package org.signal.pagingtest;
+
+import androidx.annotation.NonNull;
+import androidx.lifecycle.LiveData;
+import androidx.lifecycle.ViewModel;
+
+import org.signal.paging.LivePagedData;
+import org.signal.paging.PagingController;
+import org.signal.paging.PagingConfig;
+import org.signal.paging.PagedData;
+
+import java.util.List;
+
+public class MainViewModel extends ViewModel {
+
+  private final LivePagedData<String, Item> pagedData;
+  private final MainDataSource              dataSource;
+
+  public MainViewModel() {
+    this.dataSource = new MainDataSource(1000);
+    this.pagedData = PagedData.createForLiveData(dataSource, new PagingConfig.Builder().setBufferPages(3)
+                                                                                       .setPageSize(25)
+                                                                                       .build());
+  }
+
+  public void onItemClicked(@NonNull String key) {
+    dataSource.updateItem(key);
+    pagedData.getController().onDataItemChanged(key);
+  }
+
+  public @NonNull LiveData<List<Item>> getList() {
+    return pagedData.getData();
+  }
+
+  public @NonNull PagingController<String> getPagingController() {
+    return pagedData.getController();
+  }
+
+  public void prependItems() {
+    String key = dataSource.prepend();
+    pagedData.getController().onDataItemInserted(key, 0);
+  }
+
+}

paging/app/src/main/res/drawable-v24/ic_launcher_foreground.xml

@@ -0,0 +1,31 @@
+<vector
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:aapt="http://schemas.android.com/aapt"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportWidth="108"
+    android:viewportHeight="108">
+  <path android:pathData="M31,63.928c0,0 6.4,-11 12.1,-13.1c7.2,-2.6 26,-1.4 26,-1.4l38.1,38.1L107,108.928l-32,-1L31,63.928z">
+    <aapt:attr name="android:fillColor">
+      <gradient
+          android:endX="85.84757"
+          android:endY="92.4963"
+          android:startX="42.9492"
+          android:startY="49.59793"
+          android:type="linear">
+        <item
+            android:color="#44000000"
+            android:offset="0.0" />
+        <item
+            android:color="#00000000"
+            android:offset="1.0" />
+      </gradient>
+    </aapt:attr>
+  </path>
+  <path
+      android:fillColor="#FFFFFF"
+      android:fillType="nonZero"
+      android:pathData="M65.3,45.828l3.8,-6.6c0.2,-0.4 0.1,-0.9 -0.3,-1.1c-0.4,-0.2 -0.9,-0.1 -1.1,0.3l-3.9,6.7c-6.3,-2.8 -13.4,-2.8 -19.7,0l-3.9,-6.7c-0.2,-0.4 -0.7,-0.5 -1.1,-0.3C38.8,38.328 38.7,38.828 38.9,39.228l3.8,6.6C36.2,49.428 31.7,56.028 31,63.928h46C76.3,56.028 71.8,49.428 65.3,45.828zM43.4,57.328c-0.8,0 -1.5,-0.5 -1.8,-1.2c-0.3,-0.7 -0.1,-1.5 0.4,-2.1c0.5,-0.5 1.4,-0.7 2.1,-0.4c0.7,0.3 1.2,1 1.2,1.8C45.3,56.528 44.5,57.328 43.4,57.328L43.4,57.328zM64.6,57.328c-0.8,0 -1.5,-0.5 -1.8,-1.2s-0.1,-1.5 0.4,-2.1c0.5,-0.5 1.4,-0.7 2.1,-0.4c0.7,0.3 1.2,1 1.2,1.8C66.5,56.528 65.6,57.328 64.6,57.328L64.6,57.328z"
+      android:strokeWidth="1"
+      android:strokeColor="#00000000" />
+</vector>

paging/app/src/main/res/drawable/ic_launcher_background.xml

@@ -0,0 +1,171 @@
+<?xml version="1.0" encoding="utf-8"?>
+<vector
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportWidth="108"
+    android:viewportHeight="108">
+  <path
+      android:fillColor="#3DDC84"
+      android:pathData="M0,0h108v108h-108z" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M9,0L9,108"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M19,0L19,108"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M29,0L29,108"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M39,0L39,108"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M49,0L49,108"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M59,0L59,108"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M69,0L69,108"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M79,0L79,108"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M89,0L89,108"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M99,0L99,108"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,9L108,9"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,19L108,19"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,29L108,29"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,39L108,39"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,49L108,49"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,59L108,59"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,69L108,69"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,79L108,79"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,89L108,89"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,99L108,99"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M19,29L89,29"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M19,39L89,39"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M19,49L89,49"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M19,59L89,59"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M19,69L89,69"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M19,79L89,79"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M29,19L29,89"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M39,19L39,89"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M49,19L49,89"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M59,19L59,89"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M69,19L69,89"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M79,19L79,89"
+      android:strokeWidth="0.8"
+      android:strokeColor="#33FFFFFF" />
+</vector>

paging/app/src/main/res/layout/activity_main.xml

@@ -0,0 +1,72 @@
+<?xml version="1.0" encoding="utf-8"?>
+<androidx.constraintlayout.widget.ConstraintLayout
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:app="http://schemas.android.com/apk/res-auto"
+    xmlns:tools="http://schemas.android.com/tools"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
+    tools:context=".MainActivity">
+
+  <HorizontalScrollView
+      android:id="@+id/buttons"
+      android:layout_width="match_parent"
+      android:layout_height="wrap_content"
+      android:background="@color/purple_200"
+      app:layout_constraintTop_toTopOf="parent"
+      app:layout_constraintStart_toStartOf="parent"
+      android:elevation="4dp">
+
+    <LinearLayout
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:orientation="horizontal"
+        android:padding="8dp">
+
+      <com.google.android.material.button.MaterialButton
+          android:id="@+id/invalidate_btn"
+          android:layout_width="wrap_content"
+          android:layout_height="wrap_content"
+          android:text="Invalidate" />
+
+      <Space
+          android:layout_width="8dp"
+          android:layout_height="wrap_content" />
+
+      <com.google.android.material.button.MaterialButton
+          android:id="@+id/down250_btn"
+          android:layout_width="wrap_content"
+          android:layout_height="wrap_content"
+          android:text="250 ↓" />
+
+      <Space
+          android:layout_width="8dp"
+          android:layout_height="wrap_content" />
+
+      <com.google.android.material.button.MaterialButton
+          android:id="@+id/up250_btn"
+          android:layout_width="wrap_content"
+          android:layout_height="wrap_content"
+          android:text="250 ↑" />
+
+      <Space
+          android:layout_width="8dp"
+          android:layout_height="wrap_content" />
+
+      <com.google.android.material.button.MaterialButton
+          android:id="@+id/prepend_btn"
+          android:layout_width="wrap_content"
+          android:layout_height="wrap_content"
+          android:text="Prepend" />
+
+    </LinearLayout>
+
+  </HorizontalScrollView>
+
+  <androidx.recyclerview.widget.RecyclerView
+      android:id="@+id/list"
+      android:layout_width="match_parent"
+      android:layout_height="0dp"
+      app:layout_constraintTop_toBottomOf="@id/buttons"
+      app:layout_constraintBottom_toBottomOf="parent"/>
+
+</androidx.constraintlayout.widget.ConstraintLayout>

paging/app/src/main/res/layout/item.xml

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="utf-8"?>
+<androidx.constraintlayout.widget.ConstraintLayout
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:app="http://schemas.android.com/apk/res-auto"
+    xmlns:tools="http://schemas.android.com/tools"
+    android:layout_width="match_parent"
+    android:layout_height="wrap_content"
+    android:padding="5dp"
+    android:clipToPadding="false"
+    android:clipChildren="false">
+
+  <com.google.android.material.card.MaterialCardView
+      android:layout_width="match_parent"
+      android:layout_height="wrap_content"
+      app:cardElevation="5dp"
+      app:cardCornerRadius="5dp"
+      app:layout_constraintTop_toTopOf="parent"
+      app:layout_constraintStart_toStartOf="parent">
+
+    <TextView
+        android:id="@+id/text"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:padding="8dp"
+        android:fontFamily="monospace"
+        tools:text="Spider-Man"/>
+
+  </com.google.android.material.card.MaterialCardView>
+
+</androidx.constraintlayout.widget.ConstraintLayout>

paging/app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon
+    xmlns:android="http://schemas.android.com/apk/res/android">
+  <background android:drawable="@drawable/ic_launcher_background" />
+  <foreground android:drawable="@drawable/ic_launcher_foreground" />
+</adaptive-icon>

paging/app/src/main/res/mipmap-anydpi-v26/ic_launcher_round.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon
+    xmlns:android="http://schemas.android.com/apk/res/android">
+  <background android:drawable="@drawable/ic_launcher_background" />
+  <foreground android:drawable="@drawable/ic_launcher_foreground" />
+</adaptive-icon>

paging/app/src/main/res/values-night/themes.xml

@@ -0,0 +1,16 @@
+<resources xmlns:tools="http://schemas.android.com/tools">
+  <!-- Base application theme. -->
+  <style name="Theme.PagingTest" parent="Theme.MaterialComponents.DayNight.DarkActionBar">
+    <!-- Primary brand color. -->
+    <item name="colorPrimary">@color/purple_200</item>
+    <item name="colorPrimaryVariant">@color/purple_700</item>
+    <item name="colorOnPrimary">@color/black</item>
+    <!-- Secondary brand color. -->
+    <item name="colorSecondary">@color/teal_200</item>
+    <item name="colorSecondaryVariant">@color/teal_200</item>
+    <item name="colorOnSecondary">@color/black</item>
+    <!-- Status bar color. -->
+    <item name="android:statusBarColor" tools:targetApi="l">?attr/colorPrimaryVariant</item>
+    <!-- Customize your theme here. -->
+  </style>
+</resources>

paging/app/src/main/res/values/colors.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+  <color name="purple_200">#FFBB86FC</color>
+  <color name="purple_500">#FF6200EE</color>
+  <color name="purple_700">#FF3700B3</color>
+  <color name="teal_200">#FF03DAC5</color>
+  <color name="teal_700">#FF018786</color>
+  <color name="black">#FF000000</color>
+  <color name="white">#FFFFFFFF</color>
+</resources>

paging/app/src/main/res/values/strings.xml

@@ -0,0 +1,3 @@
+<resources>
+  <string name="app_name">PagingTest</string>
+</resources>

paging/app/src/main/res/values/themes.xml

@@ -0,0 +1,16 @@
+<resources xmlns:tools="http://schemas.android.com/tools">
+  <!-- Base application theme. -->
+  <style name="Theme.PagingTest" parent="Theme.MaterialComponents.DayNight.DarkActionBar">
+    <!-- Primary brand color. -->
+    <item name="colorPrimary">@color/purple_500</item>
+    <item name="colorPrimaryVariant">@color/purple_700</item>
+    <item name="colorOnPrimary">@color/white</item>
+    <!-- Secondary brand color. -->
+    <item name="colorSecondary">@color/teal_200</item>
+    <item name="colorSecondaryVariant">@color/teal_700</item>
+    <item name="colorOnSecondary">@color/black</item>
+    <!-- Status bar color. -->
+    <item name="android:statusBarColor" tools:targetApi="l">?attr/colorPrimaryVariant</item>
+    <!-- Customize your theme here. -->
+  </style>
+</resources>

paging/lib/build.gradle.kts

@@ -0,0 +1,11 @@
+plugins {
+  id("signal-library")
+}
+
+android {
+  namespace = "org.signal.paging"
+}
+
+dependencies {
+  implementation(project(":core-util"))
+}

paging/lib/src/main/AndroidManifest.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest
+    xmlns:android="http://schemas.android.com/apk/res/android">
+
+</manifest>

paging/lib/src/main/java/org/signal/paging/BufferedPagingController.java

@@ -0,0 +1,83 @@
+package org.signal.paging;
+
+import androidx.annotation.NonNull;
+
+import java.util.concurrent.Executor;
+import java.util.concurrent.Executors;
+
+/**
+ * We have a bit of a threading problem -- we want our controller to have a fixed size so that it
+ * can keep track of which ranges of requests are in flight, but it needs to make a blocking call
+ * to find out the size of the dataset first!
+ *
+ * So what this controller does is use a serial executor so that it can buffer calls to a secondary
+ * controller. The first task on the executor creates the first controller, so all future calls to
+ * {@link #onDataNeededAroundIndex(int)} are guaranteed to have an active controller.
+ *
+ * It's also worth noting that this controller has lifecycle that matches the {@link PagedData} that
+ * contains it. When invalidations come in, this class will just swap out the active controller with
+ * a new one.
+ */
+class BufferedPagingController<Key, Data> implements PagingController<Key> {
+
+  private final PagedDataSource<Key, Data>  dataSource;
+  private final PagingConfig                config;
+  private final DataStream<Data>            dataStream;
+  private final Executor                    serializationExecutor;
+
+  private PagingController<Key> activeController;
+  private int                   lastRequestedIndex;
+
+  BufferedPagingController(@NonNull PagedDataSource<Key, Data> dataSource,
+                           @NonNull PagingConfig config,
+                           @NonNull DataStream<Data> dataStream)
+  {
+    this.dataSource            = dataSource;
+    this.config                = config;
+    this.dataStream            = dataStream;
+    this.serializationExecutor = Executors.newSingleThreadExecutor();
+
+    this.activeController   = null;
+    this.lastRequestedIndex = config.startIndex();
+
+    onDataInvalidated();
+  }
+
+  @Override
+  public void onDataNeededAroundIndex(int aroundIndex) {
+    serializationExecutor.execute(() -> {
+      lastRequestedIndex = aroundIndex;
+      activeController.onDataNeededAroundIndex(aroundIndex);
+    });
+  }
+
+  @Override
+  public void onDataInvalidated() {
+    serializationExecutor.execute(() -> {
+      if (activeController != null) {
+        activeController.onDataInvalidated();
+      }
+
+      activeController = new FixedSizePagingController<>(dataSource, config, dataStream, dataSource.size());
+      activeController.onDataNeededAroundIndex(lastRequestedIndex);
+    });
+  }
+
+  @Override
+  public void onDataItemChanged(Key key) {
+    serializationExecutor.execute(() -> {
+      if (activeController != null) {
+        activeController.onDataItemChanged(key);
+      }
+    });
+  }
+
+  @Override
+  public void onDataItemInserted(Key key, int position) {
+    serializationExecutor.execute(() -> {
+      if (activeController != null) {
+        activeController.onDataItemInserted(key, position);
+      }
+    });
+  }
+}

paging/lib/src/main/java/org/signal/paging/CompressedList.java

@@ -0,0 +1,48 @@
+package org.signal.paging;
+
+import androidx.annotation.NonNull;
+
+import java.util.AbstractList;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * A placeholder class for efficiently storing lists that are mostly empty space.
+ * TODO [greyson][paging]
+ */
+public class CompressedList<E> extends AbstractList<E> {
+
+  private final List<E> wrapped;
+
+  public CompressedList(@NonNull List<E> source) {
+    this.wrapped = new ArrayList<>(source);
+  }
+
+  public CompressedList(int totalSize) {
+    this.wrapped = new ArrayList<>(totalSize);
+
+    for (int i = 0; i < totalSize; i++) {
+      wrapped.add(null);
+    }
+  }
+
+  @Override
+  public int size() {
+    return wrapped.size();
+  }
+
+  @Override
+  public E get(int index) {
+    return wrapped.get(index);
+  }
+
+  @Override
+  public E set(int globalIndex, E element) {
+    return wrapped.set(globalIndex, element);
+  }
+
+  @Override
+  public void add(int index, E element) {
+    wrapped.add(index, element);
+  }
+}

paging/lib/src/main/java/org/signal/paging/DataStatus.java

@@ -0,0 +1,86 @@
+package org.signal.paging;
+
+import androidx.annotation.NonNull;
+import androidx.core.util.Pools;
+
+import java.util.BitSet;
+
+/**
+ * Keeps track of what data is empty vs filled with an emphasis on doing so in a space-efficient way.
+ */
+class DataStatus {
+
+  private static final Pools.Pool<BitSet> POOL = new Pools.SynchronizedPool<>(1);
+
+  private final BitSet state;
+
+  private int size;
+
+  public static DataStatus obtain(int size) {
+    BitSet bitset = POOL.acquire();
+    if (bitset == null) {
+      bitset = new BitSet(size);
+    } else {
+      bitset.clear();
+    }
+
+    return new DataStatus(size, bitset);
+  }
+
+  private DataStatus(int size, @NonNull BitSet bitset) {
+    this.size  = size;
+    this.state = bitset;
+  }
+
+  void mark(int position) {
+    state.set(position, true);
+  }
+
+  void markRange(int startInclusive, int endExclusive) {
+    state.set(startInclusive, endExclusive, true);
+  }
+
+  int getEarliestUnmarkedIndexInRange(int startInclusive, int endExclusive) {
+    for (int i = startInclusive; i < endExclusive; i++) {
+      if (!state.get(i)) {
+        return i;
+      }
+    }
+    return -1;
+  }
+
+  int getLatestUnmarkedIndexInRange(int startInclusive, int endExclusive) {
+    for (int i = endExclusive - 1; i >= startInclusive; i--) {
+      if (!state.get(i)) {
+        return i;
+      }
+    }
+    return -1;
+  }
+
+  boolean get(int position) {
+    return state.get(position);
+  }
+
+  void insertState(int position, boolean value) {
+    if (position < 0 || position > size + 1) {
+      throw new IndexOutOfBoundsException();
+    }
+
+    for (int i = size; i > position; i--) {
+      state.set(i, state.get(i - 1));
+    }
+
+    state.set(position, value);
+
+    this.size = size + 1;
+  }
+
+  int size() {
+    return size;
+  }
+
+  void recycle() {
+    POOL.release(state);
+  }
+}

paging/lib/src/main/java/org/signal/paging/DataStream.java

@@ -0,0 +1,10 @@
+package org.signal.paging;
+
+import java.util.List;
+
+/**
+ * An abstraction over different types of ways the paging lib can provide data, e.g. Observables vs LiveData.
+ */
+interface DataStream<Data> {
+  void next(List<Data> data);
+}

paging/lib/src/main/java/org/signal/paging/FixedSizePagingController.java

@@ -0,0 +1,257 @@
+package org.signal.paging;
+
+import androidx.annotation.NonNull;
+
+import org.signal.core.util.ThreadUtil;
+import org.signal.core.util.concurrent.SignalExecutors;
+import org.signal.core.util.logging.Log;
+
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.Executor;
+
+/**
+ * The workhorse of managing page requests.
+ *
+ * A controller whose life focuses around one invalidation cycle of a data set, and therefore has
+ * a fixed size throughout. It assumes that all interface methods are called on a single thread,
+ * which allows it to keep track of pending requests in a thread-safe way, while spinning off
+ * tasks to fetch data on its own executor.
+ */
+class FixedSizePagingController<Key, Data> implements PagingController<Key> {
+
+  private static final String TAG = Log.tag(FixedSizePagingController.class);
+
+  private static final Executor FETCH_EXECUTOR = SignalExecutors.newCachedSingleThreadExecutor("signal-FixedSizePagingController", ThreadUtil.PRIORITY_UI_BLOCKING_THREAD);
+  private static final boolean  DEBUG          = false;
+
+  private final PagedDataSource<Key, Data>  dataSource;
+  private final PagingConfig                config;
+  private final DataStream<Data>            dataStream;
+  private final DataStatus                  loadState;
+  private final Map<Key, Integer>           keyToPosition;
+
+  private List<Data> data;
+
+  private volatile boolean invalidated;
+
+  FixedSizePagingController(@NonNull PagedDataSource<Key, Data> dataSource,
+                            @NonNull PagingConfig config,
+                            @NonNull DataStream<Data> dataStream,
+                            int size)
+  {
+    this.dataSource    = dataSource;
+    this.config        = config;
+    this.dataStream    = dataStream;
+    this.loadState     = DataStatus.obtain(size);
+    this.data          = new CompressedList<>(loadState.size());
+    this.keyToPosition = new HashMap<>();
+
+    if (DEBUG) Log.d(TAG, "[Constructor] Creating with size " + size + " (loadState.size() = " + loadState.size() + ")");
+  }
+
+  /**
+   * We assume this method is always called on the same thread, so we can read our
+   * {@code loadState} and construct the parameters of a fetch request. That fetch request can
+   * then be performed on separate single-thread executor.
+   */
+  @Override
+  public void onDataNeededAroundIndex(int aroundIndex) {
+    if (invalidated) {
+      Log.w(TAG, buildDataNeededLog(aroundIndex, "Invalidated! At very beginning."));
+      return;
+    }
+
+    final int loadStart;
+    final int loadEnd;
+    final int totalSize;
+
+    synchronized (loadState) {
+      if (loadState.size() == 0) {
+        dataStream.next(Collections.emptyList());
+        return;
+      }
+
+      int leftPageBoundary  = (aroundIndex / config.pageSize()) * config.pageSize();
+      int rightPageBoundary = leftPageBoundary + config.pageSize();
+      int buffer            = config.bufferPages() * config.pageSize();
+
+      int leftLoadBoundary  = Math.max(0, leftPageBoundary - buffer);
+      int rightLoadBoundary = Math.min(loadState.size(), rightPageBoundary + buffer);
+
+      loadStart = loadState.getEarliestUnmarkedIndexInRange(leftLoadBoundary, rightLoadBoundary);
+
+      if (loadStart < 0) {
+        if (DEBUG) Log.i(TAG, buildDataNeededLog(aroundIndex, "loadStart < 0"));
+        return;
+      }
+
+      loadEnd = loadState.getLatestUnmarkedIndexInRange(Math.max(leftLoadBoundary, loadStart), rightLoadBoundary) + 1;
+
+      if (loadEnd <= loadStart) {
+        if (DEBUG) Log.i(TAG, buildDataNeededLog(aroundIndex, "loadEnd <= loadStart, loadEnd: " + loadEnd + ", loadStart: " + loadStart));
+        return;
+      }
+
+      totalSize = loadState.size();
+
+      loadState.markRange(loadStart, loadEnd);
+
+      if (DEBUG) Log.i(TAG, buildDataNeededLog(aroundIndex, "start: " + loadStart + ", end: " + loadEnd + ", totalSize: " + totalSize));
+    }
+
+    FETCH_EXECUTOR.execute(() -> {
+      if (invalidated) {
+        Log.w(TAG, buildDataNeededLog(aroundIndex, "Invalidated! At beginning of load task."));
+        return;
+      }
+
+      List<Data> loaded = dataSource.load(loadStart, loadEnd - loadStart, totalSize, () -> invalidated);
+
+      if (invalidated) {
+        Log.w(TAG, buildDataNeededLog(aroundIndex, "Invalidated! Just after data was loaded."));
+        return;
+      }
+
+      List<Data> updated = new CompressedList<>(data);
+
+      for (int i = 0, len = Math.min(loaded.size(), data.size() - loadStart); i < len; i++) {
+        int  position = loadStart + i;
+        Data item     = loaded.get(i);
+
+        updated.set(position, item);
+        keyToPosition.put(dataSource.getKey(item), position);
+      }
+
+      data = updated;
+      dataStream.next(updated);
+    });
+  }
+
+  @Override
+  public void onDataInvalidated() {
+    if (invalidated) {
+      return;
+    }
+
+    invalidated = true;
+    loadState.recycle();
+  }
+
+  @Override
+  public void onDataItemChanged(Key key) {
+    if (DEBUG) Log.d(TAG, buildItemChangedLog(key, ""));
+
+    FETCH_EXECUTOR.execute(() -> {
+      Integer position = keyToPosition.get(key);
+
+      if (position == null) {
+        Log.i(TAG, "Notified of key " + key + " but it wasn't in the cache!");
+        return;
+      }
+
+      if (invalidated) {
+        Log.w(TAG, "Invalidated! Just before individual change was loaded for position " + position);
+        return;
+      }
+
+      synchronized (loadState) {
+        loadState.mark(position);
+      }
+
+      Data item = dataSource.load(key);
+
+      if (item == null) {
+        Log.w(TAG, "Notified of key " + key + " but the loaded item was null!");
+        return;
+      }
+
+      if (invalidated) {
+        Log.w(TAG, "Invalidated! Just after individual change was loaded for position " + position);
+        return;
+      }
+
+      List<Data> updatedList = new CompressedList<>(data);
+
+      updatedList.set(position, item);
+      data = updatedList;
+      dataStream.next(updatedList);
+
+      if (DEBUG) Log.d(TAG, buildItemChangedLog(key, "Published updated data"));
+    });
+  }
+
+  @Override
+  public void onDataItemInserted(Key key, int inputPosition) {
+    if (DEBUG) Log.d(TAG, buildItemInsertedLog(key, inputPosition, ""));
+
+    FETCH_EXECUTOR.execute(() -> {
+      int position = inputPosition;
+      if (position == POSITION_END) {
+        position = data.size();
+      }
+
+      if (keyToPosition.containsKey(key)) {
+        Log.w(TAG, "Notified of key " + key + " being inserted at " + position + ", but the item already exists!");
+        return;
+      }
+
+      if (invalidated) {
+        Log.w(TAG, "Invalidated! Just before individual insert was loaded for position " + position);
+        return;
+      }
+
+      synchronized (loadState) {
+        loadState.insertState(position, true);
+        if (DEBUG) Log.d(TAG, buildItemInsertedLog(key, position, "Size of loadState updated to " + loadState.size()));
+      }
+
+      Data item = dataSource.load(key);
+
+      if (item == null) {
+        Log.w(TAG, "Notified of key " + key + " being inserted at " + position + ", but the loaded item was null!");
+        return;
+      }
+
+      if (invalidated) {
+        Log.w(TAG, "Invalidated! Just after individual insert was loaded for position " + position);
+        return;
+      }
+
+      List<Data> updatedList = new CompressedList<>(data);
+
+      updatedList.add(position, item);
+      rebuildKeyToPositionMap(keyToPosition, updatedList, dataSource);
+
+      data = updatedList;
+      dataStream.next(updatedList);
+
+      if (DEBUG) Log.d(TAG, buildItemInsertedLog(key, position, "Published updated data"));
+    });
+  }
+
+  private void rebuildKeyToPositionMap(@NonNull Map<Key, Integer> map, @NonNull List<Data> dataList, @NonNull PagedDataSource<Key, Data> dataSource) {
+    map.clear();
+
+    for (int i = 0, len = dataList.size(); i < len; i++) {
+      Data item = dataList.get(i);
+      if (item != null) {
+        map.put(dataSource.getKey(item), i);
+      }
+    }
+  }
+
+  private String buildDataNeededLog(int aroundIndex, String message) {
+    return "[onDataNeededAroundIndex(" + aroundIndex + "), size: " + loadState.size() + "] " + message;
+  }
+
+  private String buildItemInsertedLog(Key key, int position, String message) {
+    return "[onDataItemInserted(" + key + ", " + position + "), size: " + loadState.size() + "] " + message;
+  }
+
+  private String buildItemChangedLog(Key key, String message) {
+    return "[onDataItemChanged(" + key + "), size: " + loadState.size() + "] " + message;
+  }
+}

paging/lib/src/main/java/org/signal/paging/LivePagedData.java

@@ -0,0 +1,25 @@
+package org.signal.paging;
+
+import androidx.annotation.AnyThread;
+import androidx.annotation.NonNull;
+import androidx.lifecycle.LiveData;
+
+import java.util.List;
+
+/**
+ * An implementation of {@link PagedData} that will provide data as a {@link LiveData}.
+ */
+public class LivePagedData<Key, Data> extends PagedData<Key> {
+
+  private final LiveData<List<Data>>  data;
+
+  LivePagedData(@NonNull LiveData<List<Data>> data, @NonNull PagingController<Key> controller) {
+    super(controller);
+    this.data = data;
+  }
+
+  @AnyThread
+  public @NonNull LiveData<List<Data>> getData() {
+    return data;
+  }
+}

paging/lib/src/main/java/org/signal/paging/ObservablePagedData.java

@@ -0,0 +1,27 @@
+package org.signal.paging;
+
+import androidx.annotation.AnyThread;
+import androidx.annotation.NonNull;
+
+import java.util.List;
+
+import io.reactivex.rxjava3.core.Observable;
+import io.reactivex.rxjava3.subjects.Subject;
+
+/**
+ * An implementation of {@link PagedData} that will provide data as an {@link Observable}.
+ */
+public class ObservablePagedData<Key, Data> extends PagedData<Key> {
+
+  private final Observable<List<Data>> data;
+
+  ObservablePagedData(@NonNull Observable<List<Data>> data, @NonNull PagingController<Key> controller) {
+    super(controller);
+    this.data = data;
+  }
+
+  @AnyThread
+  public @NonNull Observable<List<Data>> getData() {
+    return data;
+  }
+}

paging/lib/src/main/java/org/signal/paging/PagedData.java

@@ -0,0 +1,42 @@
+package org.signal.paging;
+
+import androidx.annotation.AnyThread;
+import androidx.annotation.NonNull;
+import androidx.lifecycle.MutableLiveData;
+
+import java.util.List;
+
+import io.reactivex.rxjava3.subjects.BehaviorSubject;
+import io.reactivex.rxjava3.subjects.Subject;
+
+/**
+ * The primary entry point for creating paged data.
+ */
+public class PagedData<Key> {
+
+  private final PagingController<Key> controller;
+
+  protected PagedData(PagingController<Key> controller) {
+    this.controller = controller;
+  }
+
+  @AnyThread
+  public static <Key, Data> LivePagedData<Key, Data> createForLiveData(@NonNull PagedDataSource<Key, Data> dataSource, @NonNull PagingConfig config) {
+    MutableLiveData<List<Data>> liveData   = new MutableLiveData<>();
+    PagingController<Key>       controller = new BufferedPagingController<>(dataSource, config, liveData::postValue);
+
+    return new LivePagedData<>(liveData, controller);
+  }
+
+  @AnyThread
+  public static <Key, Data> ObservablePagedData<Key, Data> createForObservable(@NonNull PagedDataSource<Key, Data> dataSource, @NonNull PagingConfig config) {
+    Subject<List<Data>>   subject    = BehaviorSubject.create();
+    PagingController<Key> controller = new BufferedPagingController<>(dataSource, config, subject::onNext);
+
+    return new ObservablePagedData<>(subject, controller);
+  }
+
+  public PagingController<Key> getController() {
+    return controller;
+  }
+}

paging/lib/src/main/java/org/signal/paging/PagedDataSource.java

@@ -0,0 +1,42 @@
+package org.signal.paging;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+import androidx.annotation.WorkerThread;
+
+import java.util.List;
+
+/**
+ * Represents a source of data that can be queried.
+ */
+public interface PagedDataSource<Key, Data> {
+  /**
+   * @return The total size of the data set.
+   */
+  @WorkerThread
+  int size();
+
+  /**
+   * @param start              The index of the first item that should be included in your results.
+   * @param length             The total number of items you should return.
+   * @param totalSize          The total number of items in the data source
+   * @param cancellationSignal An object that you can check to see if the load operation was canceled.
+   * @return A list of length {@code length} that represents the data starting at {@code start}.
+   * If you don't have the full range, just populate what you can.
+   */
+  @WorkerThread
+  @NonNull List<Data> load(int start, int length, int totalSize, @NonNull CancellationSignal cancellationSignal);
+
+  @WorkerThread
+  @Nullable Data load(Key key);
+
+  @WorkerThread
+  @NonNull Key getKey(@NonNull Data data);
+
+  interface CancellationSignal {
+    /**
+     * @return True if the operation has been canceled, otherwise false.
+     */
+    boolean isCanceled();
+  }
+}

paging/lib/src/main/java/org/signal/paging/PagingConfig.java

@@ -0,0 +1,81 @@
+package org.signal.paging;
+
+import androidx.annotation.NonNull;
+
+import java.util.concurrent.Executor;
+
+/**
+ * Describes various properties of how you'd like paging to be handled.
+ */
+public final class PagingConfig {
+
+  private final int bufferPages;
+  private final int startIndex;
+  private final int pageSize;
+
+  private PagingConfig(@NonNull Builder builder) {
+    this.bufferPages = builder.bufferPages;
+    this.startIndex  = builder.startIndex;
+    this.pageSize    = builder.pageSize;
+  }
+
+  /**
+   * @return How many pages of 'buffer' you want ahead of and behind the active position. i.e. if
+   *         the {@code pageSize()} is 10 and you specify 2 buffer pages, then there will always be
+   *         at least 20 items ahead of and behind the current position.
+   */
+  int bufferPages() {
+    return bufferPages;
+  }
+
+  /**
+   * @return How much data to load at a time when paging data.
+   */
+  int pageSize() {
+    return pageSize;
+  }
+
+  /**
+   * @return What position to start loading at
+   */
+  int startIndex() {
+    return startIndex;
+  }
+
+  public static class Builder {
+    private int bufferPages = 1;
+    private int startIndex  = 0;
+    private int pageSize    = 50;
+
+    public @NonNull Builder setBufferPages(int bufferPages) {
+      if (bufferPages < 1) {
+        throw new IllegalArgumentException("You must have at least one buffer page! Requested: " + bufferPages);
+      }
+
+      this.bufferPages = bufferPages;
+      return this;
+    }
+
+    public @NonNull Builder setPageSize(int pageSize) {
+      if (pageSize < 1) {
+        throw new IllegalArgumentException("You must have a page size of at least one! Requested: " + pageSize);
+      }
+
+      this.pageSize = pageSize;
+      return this;
+    }
+
+    public @NonNull Builder setStartIndex(int startIndex) {
+      if (startIndex < 0) {
+        throw new IndexOutOfBoundsException("Requested: " + startIndex);
+      }
+
+      this.startIndex = startIndex;
+      return this;
+    }
+
+    public @NonNull PagingConfig build() {
+      return new PagingConfig(this);
+    }
+  }
+}

paging/lib/src/main/java/org/signal/paging/PagingController.java

@@ -0,0 +1,11 @@
+package org.signal.paging;
+
+
+public interface PagingController<Key> {
+  int POSITION_END = -1;
+
+  void onDataNeededAroundIndex(int aroundIndex);
+  void onDataInvalidated();
+  void onDataItemChanged(Key key);
+  void onDataItemInserted(Key key, int position);
+}

paging/lib/src/main/java/org/signal/paging/ProxyPagingController.java

@@ -0,0 +1,48 @@
+package org.signal.paging;
+
+import androidx.annotation.Nullable;
+
+/**
+ * A controller that forwards calls to a secondary, proxied controller. This is useful when you want
+ * to keep a single, static controller, even when the true controller may be changing due to data
+ * source changes.
+ */
+public class ProxyPagingController<Key> implements PagingController<Key> {
+
+  private PagingController<Key> proxied;
+
+  @Override
+  public synchronized void onDataNeededAroundIndex(int aroundIndex) {
+    if (proxied != null) {
+      proxied.onDataNeededAroundIndex(aroundIndex);
+    }
+  }
+
+  @Override
+  public synchronized void onDataInvalidated() {
+    if (proxied != null) {
+      proxied.onDataInvalidated();
+    }
+  }
+
+  @Override
+  public void onDataItemChanged(Key key) {
+    if (proxied != null) {
+      proxied.onDataItemChanged(key);
+    }
+  }
+
+  @Override
+  public void onDataItemInserted(Key key, int position) {
+    if (proxied != null) {
+      proxied.onDataItemInserted(key, position);
+    }
+  }
+
+  /**
+   * Updates the underlying controller to the one specified.
+   */
+  public synchronized void set(@Nullable PagingController<Key> bound) {
+    this.proxied = bound;
+  }
+}

paging/lib/src/test/java/org/signal/paging/DataStatusTest.kt

@@ -0,0 +1,56 @@
+package org.signal.paging
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class DataStatusTest {
+  @Test
+  fun insertState_initiallyEmpty_InsertAtZero() {
+    val subject = DataStatus.obtain(0)
+    subject.insertState(0, true)
+
+    assertEquals(1, subject.size())
+    assertTrue(subject[0])
+  }
+
+  @Test
+  fun insertState_someData_InsertAtZero() {
+    val subject = DataStatus.obtain(2)
+    subject.mark(1)
+
+    subject.insertState(0, true)
+
+    assertEquals(3, subject.size())
+    assertTrue(subject[0])
+    assertFalse(subject[1])
+    assertTrue(subject[2])
+  }
+
+  @Test
+  fun insertState_someData_InsertAtOne() {
+    val subject = DataStatus.obtain(3)
+    subject.mark(1)
+
+    subject.insertState(1, true)
+
+    assertEquals(4, subject.size())
+    assertFalse(subject[0])
+    assertTrue(subject[1])
+    assertTrue(subject[2])
+    assertFalse(subject[3])
+  }
+
+  @Test(expected = IndexOutOfBoundsException::class)
+  fun insertState_negativeThrows() {
+    val subject = DataStatus.obtain(0)
+    subject.insertState(-1, true)
+  }
+
+  @Test(expected = IndexOutOfBoundsException::class)
+  fun insertState_largerThanSizePlusOneThrows() {
+    val subject = DataStatus.obtain(0)
+    subject.insertState(2, true)
+  }
+}