PagedList

public abstract class PagedList
extends AbstractList<T>

Lazy loading list that pages in immutable content from a DataSource.

A PagedList is a List which loads its data in chunks (pages) from a DataSource. Items can be accessed with get(int), and further loading can be triggered with loadAround(int). To display a PagedList, see PagedListAdapter, which enables the binding of a PagedList to a RecyclerView.

Loading Data

All data in a PagedList is loaded from its DataSource. Creating a PagedList loads the first chunk of data from the DataSource immediately, and should for this reason be done on a background thread. The constructed PagedList may then be passed to and used on the UI thread. This is done to prevent passing a list with no loaded content to the UI thread, which should generally not be presented to the user.

A PagedList initially presents this first partial load as its content, and expands over time as content is loaded in. When loadAround(int) is called, items will be loaded in near the passed list index. If placeholder nulls are present in the list, they will be replaced as content is loaded. If not, newly loaded items will be inserted at the beginning or end of the list.

PagedList can present data for an unbounded, infinite scrolling list, or a very large but countable list. Use PagedList.Config to control how many items a PagedList loads, and when.

If you use LivePagedListBuilder to get a LiveData<PagedList>, it will initialize PagedLists on a background thread for you.

Placeholders

There are two ways that PagedList can represent its not-yet-loaded data - with or without null placeholders.

With placeholders, the PagedList is always the full size of the data set. get(N) returns the Nth item in the data set, or null if its not yet loaded.

Without null placeholders, the PagedList is the sublist of data that has already been loaded. The size of the PagedList is the number of currently loaded items, and get(N) returns the Nth loaded item. This is not necessarily the Nth item in the data set.

Placeholders have several benefits:

• They express the full sized list to the presentation layer (often a PagedListAdapter), and so can support scrollbars (without jumping as pages are loaded) and fast-scrolling to any position, whether loaded or not.
• They avoid the need for a loading spinner at the end of the loaded list, since the list is always full sized.

They also have drawbacks:

• Your Adapter (or other presentation mechanism) needs to account for null items. This often means providing default values in data you bind to a RecyclerView.ViewHolder.
• They don't work well if your item views are of different sizes, as this will prevent loading items from cross-fading nicely.
• They require you to count your data set, which can be expensive or impossible, depending on where your data comes from.

Placeholders are enabled by default, but can be disabled in two ways. They are disabled if the DataSource does not count its data set in its initial load, or if false is passed to setEnablePlaceholders(boolean) when building a PagedList.Config.

Mutability and Snapshots

If a PagedList attempts to load from an invalid DataSource, it will detach() from the DataSource, meaning that it will no longer attempt to load data. It will return true from isImmutable(), and a new DataSource / PagedList pair must be created to load further data. See DataSource and LivePagedListBuilder for how new PagedLists are created to represent changed data.

A PagedList snapshot is simply an immutable shallow copy of the current state of the PagedList as a List. It will reference the same inner items, and contain the same null placeholders, if present.

Summary

Public methods

void addWeakCallback (List<T> previousSnapshot, 
                PagedList.Callback callback)

void detach ()

T get (int index)

PagedList.Config getConfig ()

DataSource<?, T> getDataSource ()

Object getLastKey ()

int getPositionOffset ()

boolean isDetached ()

boolean isImmutable ()

void loadAround (int index)

void removeWeakCallback (PagedList.Callback callback)

int size ()

List<T> snapshot ()