PagedList

public abstract class PagedList<T extends Object>

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

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

Loading Data

All data in a PagedList is loaded from its PagingSource. Creating a PagedList loads the first chunk of data from the PagingSource 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 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 androidx.paging.LivePagedListBuilder to get a androidx.lifecycle.LiveData, 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 androidx.paging.PagedListAdapter), and so can support scrollbars (without jumping as pages are loaded or dropped) and fast-scrolling to any position, 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 needs to account for null items. This often means providing default values in data you bind to a androidx.recyclerview.widget.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 your PagingSource.

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

Mutability and Snapshots

A PagedList is mutable while loading, or ready to load from its PagingSource. As loads succeed, a mutable PagedList will be updated via Runnables on the main thread. You can listen to these updates with a PagedList.Callback. (Note that androidx.paging .PagedListAdapter will listen to these to signal RecyclerView about the updates/changes).

If a PagedList attempts to load from an invalid PagingSource, it will detach from the PagingSource, meaning that it will no longer attempt to load data. It will return true from isImmutable, and a new PagingSource / PagedList pair must be created to load further data.

See PagingSource and androidx.paging.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.

Parameters
<T extends Object>

The type of the entries in the list.

Summary

Nested types
PagedList.BoundaryCallback

Signals when a PagedList has reached the end of available data.
PagedList.Builder

Builder class for PagedList.
PagedList.Callback

Callback signaling when content is loaded into the list.
PagedList.Config

Configures how a PagedList loads content from its PagingSource.
PagedList.Config.Builder

Builder class for PagedList.Config.

Public fields
final @NonNull PagedList.Config

Return the Config used to construct this PagedList.
final @NonNull DataSource<@NonNull ?, @NonNull T>

This field is deprecated. DataSource is deprecated and has been replaced by PagingSource.
abstract boolean

True if the PagedList has detached the PagingSource it was loading from, and will no longer load new data.
boolean

Returns whether the list is immutable.
abstract @Nullable Object

Return the key for the position passed most recently to loadAround.
final int

Returns the number of items loaded in the PagedList.
final int
final int

Position offset of the data in the list.
int

Size of the list, including any placeholders (not-yet-loaded null padding).

Public methods
final void
addWeakCallback(
    @Nullable List<@NonNull T> previousSnapshot,
    @NonNull PagedList.Callback callback
)

This method is deprecated. Dispatching a diff since snapshot created is behavior that can be instead tracked by attaching a Callback to the PagedList that is mutating, and tracking changes since calling PagedList.snapshot().
final void

Adds a callback.
final void

Add a listener to observe the loading state of the PagedList.
abstract void

Detach the PagedList from its PagingSource, and attempt to load no more data.
@Nullable T
get(int index)

Get the item in the list of loaded items at the provided index.
final void
loadAround(int index)

Load adjacent items to passed index.
final void

Removes a previously added callback.
final void

Remove a previously registered load state listener.
void

Retry any errors associated with this PagedList.
final @NonNull List<@NonNull T>

Returns an immutable snapshot of the PagedList in its current state.

Inherited methods
From class AbstractCollection
boolean
boolean
boolean
boolean
boolean
boolean
boolean
@RecentlyNonNull @NonNull Array<@NonNull Object>
@RecentlyNonNull @NonNull Array<@NonNull T>
@RecentlyNonNull @NonNull String
From class AbstractList
boolean
add(@NonNull T element)
void
add(int index, @NonNull T element)
boolean
addAll(int index, @RecentlyNonNull @NonNull Collection<@NonNull T> elements)
void
boolean
int
int
@RecentlyNonNull @NonNull Iterator<@NonNull T>
int
@RecentlyNonNull @NonNull ListIterator<@NonNull T>
@RecentlyNonNull @NonNull ListIterator<@NonNull T>
listIterator(int index)
@NonNull T
removeAt(int p0)
void
removeRange(int p0, int p1)
@NonNull T
set(int index, @NonNull T element)
@RecentlyNonNull @NonNull List<@NonNull T>
subList(int fromIndex, int toIndex)
From class Collection
@RecentlyNonNull @NonNull Stream<@NonNull T>
@RecentlyNonNull @NonNull Spliterator<@NonNull T>
@RecentlyNonNull @NonNull Stream<@NonNull T>
From class Iterable
void
From class MutableCollection
boolean
From class MutableList
void
void

Public fields

config

@NonNull
public final @NonNull PagedList.Config config

Return the Config used to construct this PagedList.

Returns
@NonNull PagedList.Config

the Config of this PagedList

dataSource

@NonNull
public final @NonNull DataSource<@NonNull ?, @NonNull T> dataSource
Throws
kotlin.IllegalStateException

if this PagedList was instantiated without a wrapping a backing DataSource

isDetached

@NonNull
public abstract boolean isDetached

True if the PagedList has detached the PagingSource it was loading from, and will no longer load new data.

A detached list is immutable.

Returns
boolean

true if the data source is detached.

isImmutable

@NonNull
public boolean isImmutable

Returns whether the list is immutable.

Immutable lists may not become mutable again, and may safely be accessed from any thread.

In the future, this method may return true when a PagedList has completed loading from its PagingSource. Currently, it is equivalent to isDetached.

Returns
boolean

true if the PagedList is immutable.

lastKey

@Nullable
public abstract @Nullable Object lastKey

Return the key for the position passed most recently to loadAround.

When a PagedList is invalidated, you can pass the key returned by this function to initialize the next PagedList. This ensures (depending on load times) that the next PagedList that arrives will have data that overlaps. If you use androidx.paging.LivePagedListBuilder, it will do this for you.

Returns
@Nullable Object

Key of position most recently passed to loadAround.

loadedCount

@NonNull
public final int loadedCount

Returns the number of items loaded in the PagedList.

Unlike size this counts only loaded items, not placeholders.

If placeholders are disabled, this method is equivalent to size.

Returns
int

Number of items currently loaded, not counting placeholders.
See also
size

modCount

@NonNull
public final int modCount

positionOffset

@NonNull
public final int positionOffset

Position offset of the data in the list.

If the PagingSource backing this PagedList is counted, the item returned from get(i) has a position in the original data set of i + getPositionOffset().

If placeholders are enabled, this value is always 0, since get(i) will return either the data in its original index, or null if it is not loaded.

size

@NonNull
public int size

Size of the list, including any placeholders (not-yet-loaded null padding).

To get the number of loaded items, not counting placeholders, use loadedCount.

<t