PagedList

Added in 2.0.0
Deprecated in 3.0.0

public abstract class PagedList<T extends Object> extends AbstractList


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 it's 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

@MainThread
public abstract class PagedList.BoundaryCallback<T extends Object>

This class is deprecated. PagedList is deprecated and has been replaced by PagingData

public final class PagedList.Builder<Key extends Object, Value extends Object>

This class is deprecated. PagedList is deprecated and has been replaced by PagingData, which no longer supports constructing snapshots of loaded data manually.

public abstract class PagedList.Callback

This class is deprecated. PagedList is deprecated and has been replaced by PagingData

public final class PagedList.Config

This class is deprecated. PagedList is deprecated and has been replaced by PagingData

public final class PagedList.Config.Builder

This class is deprecated. PagedList is deprecated and has been replaced by PagingData

Public methods

final void

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

final void
addWeakCallback(
    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

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

abstract void

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

T
get(int index)

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

final @NonNull PagedList.Config

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

final @NonNull DataSource<@NonNull ?, @NonNull T>

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

abstract Object

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

final int

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

final int

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

int

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

abstract boolean

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

boolean

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

final void
loadAround(int index)

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

final void

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

final void

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

void

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

final @NonNull List<@NonNull T>

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

Inherited fields

From java.util.AbstractList
final int

This field is deprecated. PagedList is deprecated and has been replaced by PagingData

Inherited methods

From java.util.AbstractCollection
boolean

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

boolean

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

boolean

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

boolean

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

boolean

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

boolean

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

boolean

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

@NonNull Object[]

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

@NonNull T[]

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

@NonNull String

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

From java.util.AbstractList
boolean
add(@NonNull T element)

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

void
add(int index, @NonNull T element)

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

boolean
addAll(int index, @RecentlyNonNull @NonNull Collection<@NonNull T> elements)

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

void

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

boolean

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

int

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

int

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

@NonNull Iterator<@NonNull T>

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

int

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

@NonNull ListIterator<@NonNull T>

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

@NonNull ListIterator<@NonNull T>

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

@NonNull T
removeAt(int p0)

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

void
removeRange(int p0, int p1)

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

@NonNull T
set(int index, @NonNull T element)

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

@NonNull List<@NonNull T>
@RecentlyNonNull
subList(int fromIndex, int toIndex)

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

From kotlin.collections.Collection
@NonNull Stream<@NonNull T>

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

@NonNull Spliterator<@NonNull T>

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

@NonNull Stream<@NonNull T>

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

@NonNull T[]

This method is deprecated. This member is not fully supported by Kotlin compiler, so it may be absent or have different signature in next major version

From kotlin.collections.Iterable
void

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

From kotlin.collections.List
@NonNull List<@NonNull T>

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

From kotlin.collections.MutableCollection
boolean

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

From kotlin.collections.MutableList
void

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

void

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

@NonNull T

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

@NonNull T

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

void

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

void

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

Public methods

addWeakCallback

Added in 3.0.0
Deprecated in 3.0.0
public final void addWeakCallback(@NonNull PagedList.Callback callback)

Adds a callback.

The callback is internally held as weak reference, so PagedList doesn't hold a strong reference to its observer, such as a androidx.paging.PagedListAdapter. If an adapter were held with a strong reference, it would be necessary to clear its PagedList observer before it could be GC'd.

Parameters
@NonNull PagedList.Callback callback

Callback to dispatch to.

addWeakCallback

Added in 2.0.0
public final void addWeakCallback(
    List<@NonNull T> previousSnapshot,
    @NonNull PagedList.Callback callback
)

Adds a callback, and issues updates since the previousSnapshot was created.

If previousSnapshot is passed, the callback will also immediately be dispatched any differences between the previous snapshot, and the current state. For example, if the previousSnapshot was of 5 nulls, 10 items, 5 nulls, and the current state was 5 nulls, 12 items, 3 nulls, the callback would immediately receive a call ofonChanged(14, 2).

This allows an observer that's currently presenting a snapshot to catch up to the most recent version, including any changes that may have been made.

The callback is internally held as weak reference, so PagedList doesn't hold a strong reference to its observer, such as a PagedListAdapter. If an adapter were held with a strong reference, it would be necessary to clear its PagedList observer before it could be GC'd.

Parameters
List<@NonNull T> previousSnapshot

Snapshot previously captured from this List, or null.

@NonNull PagedList.Callback callback

PagedList.Callback to dispatch to.

addWeakLoadStateListener

Added in