Paging library data components and considerations

This guide builds upon the Paging Library
overview, discussing how you can
customize your app's data-loading solution to meet your app's architecture
needs.

Construct an observable list

Typically, your UI code observes a
LiveData<PagedList> object (or,
if you're using RxJava2, a
Flowable<PagedList> or Observable<PagedList> object), which resides in your
app's ViewModel. This
observable object forms a connection between the presentation and contents of
your app's list data.

Prefetch distance:
Given the last visible item in an app's UI, the number of items beyond this last
item that the Paging Library should attempt to fetch in advance. This value
should be several times larger than the page size.

Choose the correct data source type

It's important to connect to the data source that best handles your source
data's structure:

Use
PageKeyedDataSource if
pages you load embed next/previous keys. For example, if you're fetching social
media posts from the network, you may need to pass a nextPage token from one
load into a subsequent load.

Use
ItemKeyedDataSource if
you need to use data from item N to fetch item N+1. For example, if you're fetching threaded comments for a discussion app, you might need to pass the ID
of the last comment to get the contents of the next comment.

Use
PositionalDataSource if
you need to fetch pages of data from any location you choose in your data store.
This class supports requesting a set of data items beginning from whatever
location you select. For example, the request might return the 20 data items
beginning with location 1200.

Notify when data is invalid

When using the Paging Library, it's up to the data layer to notify the
other layers of your app when a table or row has become stale. To do so, call
invalidate() from the
DataSource class that you've
chosen for your app.

Note: Your app's UI can trigger this data invalidation functionality using
a swipe to refresh model.

Build your own data sources

If you use a custom local data solution, or if you load data directly from a
network, you can implement one of the
DataSource subclassses. The
following code snippet shows a data source that's keyed off of a given concert's
start time:

You can then load this customized data into PagedList objects by creating a
concrete subclass of
DataSource.Factory. The
following code snippet shows how to generate new instances of the custom data
source defined in the preceding code snippet:

Consider how content updates work

If you are using a paged network API, you typically have a user interaction,
such as "swipe to refresh", serve as a signal for invalidating your current
DataSource and requesting a new
one. This behavior appears in the following code snippet:

This can be useful if you want to wrap, convert, or prepare items after they're
loaded. Because this work is done on the fetch executor, you can do potentially
expensive work, such as reading from disk or querying a separate database.

Note: JOIN queries are always more efficient that requerying as part of map().