Skip to content

Most visited

Recently visited

navigation

PagedList

public abstract class PagedList
extends AbstractList<T>

java.lang.Object
   ↳ java.util.AbstractCollection<T>
     ↳ java.util.AbstractList<T>
       ↳ android.arch.paging.PagedList<T>


Lazy loading list that pages in 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). 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 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.

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.

Summary

Nested classes

class PagedList.BoundaryCallback<T>

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

class PagedList.Builder<Key, Value>

Builder class for PagedList. 

class PagedList.Callback

Callback signaling when content is loaded into the list. 

class PagedList.Config

Configures how a PagedList loads content from its DataSource. 

Fields

protected final ArrayList<WeakReference<PagedList.Callback>> mCallbacks

Inherited fields

From class java.util.AbstractList

Public methods

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

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

void detach()

Detach the PagedList from its DataSource, and attempt to load no more data.

T get(int index)

Get the item in the list of loaded items at the provided index.

PagedList.Config getConfig()

Return the Config used to construct this PagedList.

abstract Object getLastKey()

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

int getPositionOffset()

Position offset of the data in the list.

boolean isDetached()

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

boolean isImmutable()

Returns whether the list is immutable.

void loadAround(int index)

Load adjacent items to passed index.

void removeWeakCallback(PagedList.Callback callback)

Removes a previously added callback.

int size()

Returns size of the list, including any not-yet-loaded null padding.

List<T> snapshot()

Returns an immutable snapshot of the PagedList.

Inherited methods

From class java.util.AbstractList
From class java.util.AbstractCollection
From class java.lang.Object
From interface java.util.List
From interface java.util.Collection
From interface java.lang.Iterable

Fields

mCallbacks

ArrayList<WeakReference<PagedList.Callback>> mCallbacks

Public methods

addWeakCallback

void addWeakCallback (List<T> previousSnapshot, 
                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 of onChanged(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
previousSnapshot List: Snapshot previously captured from this List, or null.

callback PagedList.Callback: Callback to dispatch to.

detach

void detach ()

Detach the PagedList from its DataSource, and attempt to load no more data.

This is called automatically when a DataSource load returns null, which is a signal to stop loading. The PagedList will continue to present existing data, but will not initiate new loads.

get

T get (int index)

Get the item in the list of loaded items at the provided index.

Parameters
index int: Index in the loaded item list. Must be >= 0, and < size()

Returns
T The item at the passed index, or null if a null placeholder is at the specified position.

See also:

getConfig

PagedList.Config getConfig ()

Return the Config used to construct this PagedList.

Returns
PagedList.Config the Config of this PagedList

getLastKey

Object getLastKey ()

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

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 LivePagedListBuilder, it will do this for you.

Returns
Object Key of position most recently passed to loadAround(int).

getPositionOffset

int getPositionOffset ()

Position offset of the data in the list.

If data is supplied by a PositionalDataSource, the item returned from get(i) has a position of i + getPositionOffset().

If the DataSource is a ItemKeyedDataSource or PageKeyedDataSource, it doesn't use positions, returns 0.

Returns
int

isDetached

boolean isDetached ()

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

Returns
boolean True if the data source is detached.

isImmutable

boolean isImmutable ()

Returns whether the list is immutable. Immutable lists may not become mutable again, and may safely be accessed from any thread.

Returns
boolean True if the PagedList is immutable.

loadAround

void loadAround (int index)

Load adjacent items to passed index.

Parameters
index int: Index at which to load.

removeWeakCallback

void removeWeakCallback (PagedList.Callback callback)

Removes a previously added callback.

Parameters
callback PagedList.Callback: Callback, previously added.

size

int size ()

Returns size of the list, including any not-yet-loaded null padding.

Returns
int Current total size of the list.

snapshot

List<T> snapshot ()

Returns an immutable snapshot of the PagedList. If this PagedList is already immutable, it will be returned.

Returns
List<T> Immutable snapshot of PagedList data.

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)