# PagedList Summary:[Nested Classes](https://developer.android.com/reference/android/arch/paging/PagedList#nestedclasses)\|[Inherited Fields](https://developer.android.com/reference/android/arch/paging/PagedList#inhfields)\|[Methods](https://developer.android.com/reference/android/arch/paging/PagedList#pubmethods)\|[Inherited Methods](https://developer.android.com/reference/android/arch/paging/PagedList#inhmethods) # PagedList | The`android.arch`Architecture Components packages are no longer maintained. They have been superseded by the corresponding[androidx.\*](https://developer.android.com/jetpack/androidx/migrate)packages. See[androidx.paging.PagedList](https://developer.android.com/reference/androidx/paging/PagedList)instead. ` public abstract class PagedList ` ` `` `` extends AbstractList `` ` |---|---|---|------------------------------------| | java.lang.Object |||| | ↳ | java.util.AbstractCollection\ ||| | | ↳ | java.util.AbstractList\ || | | | ↳ | android.arch.paging.PagedList\ |
*** ** * ** *** Lazy loading list that pages in immutable content from a[DataSource](https://developer.android.com/reference/android/arch/paging/DataSource). A PagedList is a[List](https://developer.android.com/reference/java/util/List)which loads its data in chunks (pages) from a[DataSource](https://developer.android.com/reference/android/arch/paging/DataSource). Items can be accessed with[get(int)](https://developer.android.com/reference/android/arch/paging/PagedList#get(int)), and further loading can be triggered with[loadAround(int)](https://developer.android.com/reference/android/arch/paging/PagedList#loadAround(int)). To display a PagedList, see[PagedListAdapter](https://developer.android.com/reference/android/arch/paging/PagedListAdapter), which enables the binding of a PagedList to a[RecyclerView](https://developer.android.com/reference/android/support/v7/widget/RecyclerView). #### Loading Data All data in a PagedList is loaded from its[DataSource](https://developer.android.com/reference/android/arch/paging/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)](https://developer.android.com/reference/android/arch/paging/PagedList#loadAround(int))is called, items will be loaded in near the passed list index. If placeholder`null`s 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](https://developer.android.com/reference/android/arch/paging/PagedList.Config)to control how many items a PagedList loads, and when. If you use[LivePagedListBuilder](https://developer.android.com/reference/android/arch/paging/LivePagedListBuilder)to get a[LiveData](https://developer.android.com/reference/android/arch/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`N`th 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`N`th*loaded* item. This is not necessarily the`N`th item in the data set. Placeholders have several benefits: - They express the full sized list to the presentation layer (often a[PagedListAdapter](https://developer.android.com/reference/android/arch/paging/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](https://developer.android.com/reference/android/support/v7/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 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)](https://developer.android.com/reference/android/arch/paging/PagedList.Config.Builder#setEnablePlaceholders(boolean))when building a[PagedList.Config](https://developer.android.com/reference/android/arch/paging/PagedList.Config). #### Mutability and Snapshots A PagedList is*mutable* while loading, or ready to load from its DataSource. 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](https://developer.android.com/reference/android/arch/paging/PagedList.Callback). (Note that[PagedListAdapter](https://developer.android.com/reference/android/arch/paging/PagedListAdapter)will listen to these to signal RecyclerView about the updates/changes). If a PagedList attempts to load from an invalid DataSource, it will[detach()](https://developer.android.com/reference/android/arch/paging/PagedList#detach())from the DataSource, meaning that it will no longer attempt to load data. It will return true from[isImmutable()](https://developer.android.com/reference/android/arch/paging/PagedList#isImmutable()), and a new DataSource / PagedList pair must be created to load further data. See[DataSource](https://developer.android.com/reference/android/arch/paging/DataSource)and[LivePagedListBuilder](https://developer.android.com/reference/android/arch/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. ## Summary | ### Nested classes || |----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ` class` | [PagedList.BoundaryCallback](https://developer.android.com/reference/android/arch/paging/PagedList.BoundaryCallback)`` Signals when a PagedList has reached the end of available data. | | ` class` | [PagedList.Builder](https://developer.android.com/reference/android/arch/paging/PagedList.Builder)`` Builder class for PagedList. | | ` class` | [PagedList.Callback](https://developer.android.com/reference/android/arch/paging/PagedList.Callback) Callback signaling when content is loaded into the list. | | ` class` | [PagedList.Config](https://developer.android.com/reference/android/arch/paging/PagedList.Config) Configures how a PagedList loads content from its DataSource. | | ### Inherited fields | |----------------------------------------------------------------------------------------------------------------------| | From class`java.util.AbstractList` |------------------|-------------------| | ` protected int` | `modCount`
| | | ### Public methods || |----------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ` void` | ` `[addWeakCallback](https://developer.android.com/reference/android/arch/paging/PagedList#addWeakCallback(java.util.List, android.arch.paging.PagedList.Callback))`(List previousSnapshot, `[PagedList.Callback](https://developer.android.com/reference/android/arch/paging/PagedList.Callback)` callback) ` Adds a callback, and issues updates since the previousSnapshot was created. | | ` void` | ` `[detach](https://developer.android.com/reference/android/arch/paging/PagedList#detach())`() ` Detach the PagedList from its DataSource, and attempt to load no more data. | | ` T` | ` `[get](https://developer.android.com/reference/android/arch/paging/PagedList#get(int))`(int index) ` Get the item in the list of loaded items at the provided index. | | ` `[PagedList.Config](https://developer.android.com/reference/android/arch/paging/PagedList.Config) | ` `[getConfig](https://developer.android.com/reference/android/arch/paging/PagedList#getConfig())`() ` Return the Config used to construct this PagedList. | | ` abstract `[DataSource](https://developer.android.com/reference/android/arch/paging/DataSource)`` | ` `[getDataSource](https://developer.android.com/reference/android/arch/paging/PagedList#getDataSource())`() ` Return the DataSource that provides data to this PagedList. | | ` abstract Object` | ` `[getLastKey](https://developer.android.com/reference/android/arch/paging/PagedList#getLastKey())`() ` Return the key for the position passed most recently to[loadAround(int)](https://developer.android.com/reference/android/arch/paging/PagedList#loadAround(int)). | | ` int` | ` `[getPositionOffset](https://developer.android.com/reference/android/arch/paging/PagedList#getPositionOffset())`() ` Position offset of the data in the list. | | ` boolean` | ` `[isDetached](https://developer.android.com/reference/android/arch/paging/PagedList#isDetached())`() ` True if the PagedList has detached the DataSource it was loading from, and will no longer load new data. | | ` boolean` | ` `[isImmutable](https://developer.android.com/reference/android/arch/paging/PagedList#isImmutable())`() ` Returns whether the list is immutable. | | ` void` | ` `[loadAround](https://developer.android.com/reference/android/arch/paging/PagedList#loadAround(int))`(int index) ` Load adjacent items to passed index. | | ` void` | ` `[removeWeakCallback](https://developer.android.com/reference/android/arch/paging/PagedList#removeWeakCallback(android.arch.paging.PagedList.Callback))`(`[PagedList.Callback](https://developer.android.com/reference/android/arch/paging/PagedList.Callback)` callback) ` Removes a previously added callback. | | ` int` | ` `[size](https://developer.android.com/reference/android/arch/paging/PagedList#size())`() ` Returns size of the list, including any not-yet-loaded null padding. | | ` List` | ` `[snapshot](https://developer.android.com/reference/android/arch/paging/PagedList#snapshot())`() ` Returns an immutable snapshot of the PagedList in its current state. | | ### Inherited methods | |-----------------------|---| | From class` java.util.AbstractList ` |--------------------|----------------------------------------------------| | ` void` | ` add(int arg0, T arg1) ` | | ` boolean` | ` add(T arg0) ` | | ` boolean` | ` addAll(int arg0, Collection arg1) ` | | ` void` | ` clear() ` | | ` boolean` | ` equals(Object arg0) ` | | ` abstract T` | ` get(int arg0) ` | | ` int` | ` hashCode() ` | | ` int` | ` indexOf(Object arg0) ` | | ` Iterator` | ` iterator() ` | | ` int` | ` lastIndexOf(Object arg0) ` | | ` ListIterator` | ` listIterator(int arg0) ` | | ` ListIterator` | ` listIterator() ` | | ` T` | ` remove(int arg0) ` | | ` void` | ` removeRange(int arg0, int arg1) ` | | ` T` | ` set(int arg0, T arg1) ` | | ` List` | ` subList(int arg0, int arg1) ` | || | From class` java.util.AbstractCollection ` |-------------------------|------------------------------------------| | ` boolean` | ` add(T arg0) ` | | ` boolean` | ` addAll(Collection arg0) ` | | ` void` | ` clear() ` | | ` boolean` | ` contains(Object arg0) ` | | ` boolean` | ` containsAll(Collection arg0) ` | | ` boolean` | ` isEmpty() ` | | ` abstract Iterator` | ` iterator() ` | | ` boolean` | ` remove(Object arg0) ` | | ` boolean` | ` removeAll(Collection arg0) ` | | ` boolean` | ` retainAll(Collection arg0) ` | | ` abstract int` | ` size() ` | | ` T[]` | ` toArray(T[] arg0) ` | | ` Object[]` | ` toArray() ` | | ` String` | ` toString() ` | || | From class` java.lang.Object ` |-------------------|-------------------------------| | ` Object` | ` clone() ` | | ` boolean` | ` equals(Object arg0) ` | | ` void` | ` finalize() ` | | ` final Class` | ` getClass() ` | | ` int` | ` hashCode() ` | | ` final void` | ` notify() ` | | ` final void` | ` notifyAll() ` | | ` String` | ` toString() ` | | ` final void` | ` wait(long arg0, int arg1) ` | | ` final void` | ` wait(long arg0) ` | | ` final void` | ` wait() ` | || | From interface` java.util.List ` |-----------------------------|----------------------------------------------------| | ` abstract boolean` | ` add(T arg0) ` | | ` abstract void` | ` add(int arg0, T arg1) ` | | ` abstract boolean` | ` addAll(Collection arg0) ` | | ` abstract boolean` | ` addAll(int arg0, Collection arg1) ` | | ` abstract void` | ` clear() ` | | ` abstract boolean` | ` contains(Object arg0) ` | | ` abstract boolean` | ` containsAll(Collection arg0) ` | | ` abstract boolean` | ` equals(Object arg0) ` | | ` abstract T` | ` get(int arg0) ` | | ` abstract int` | ` hashCode() ` | | ` abstract int` | ` indexOf(Object arg0) ` | | ` abstract boolean` | ` isEmpty() ` | | ` abstract Iterator` | ` iterator() ` | | ` abstract int` | ` lastIndexOf(Object arg0) ` | | ` abstract ListIterator` | ` listIterator(int arg0) ` | | ` abstract ListIterator` | ` listIterator() ` | | ` abstract T` | ` remove(int arg0) ` | | ` abstract boolean` | ` remove(Object arg0) ` | | ` abstract boolean` | ` removeAll(Collection arg0) ` | | ` default void` | ` replaceAll(UnaryOperator arg0) ` | | ` abstract boolean` | ` retainAll(Collection arg0) ` | | ` abstract T` | ` set(int arg0, T arg1) ` | | ` abstract int` | ` size() ` | | ` default void` | ` sort(Comparator arg0) ` | | ` default Spliterator` | ` spliterator() ` | | ` abstract List` | ` subList(int arg0, int arg1) ` | | ` abstract Object[]` | ` toArray() ` | | ` abstract T[]` | ` toArray(T[] arg0) ` | || | From interface` java.util.Collection ` |---------------------------|------------------------------------------| | ` abstract boolean` | ` add(T arg0) ` | | ` abstract boolean` | ` addAll(Collection arg0) ` | | ` abstract void` | ` clear() ` | | ` abstract boolean` | ` contains(Object arg0) ` | | ` abstract boolean` | ` containsAll(Collection arg0) ` | | ` abstract boolean` | ` equals(Object arg0) ` | | ` abstract int` | ` hashCode() ` | | ` abstract boolean` | ` isEmpty() ` | | ` abstract Iterator` | ` iterator() ` | | ` default Stream` | ` parallelStream() ` | | ` abstract boolean` | ` remove(Object arg0) ` | | ` abstract boolean` | ` removeAll(Collection arg0) ` | | ` default boolean` | ` removeIf(Predicate arg0) ` | | ` abstract boolean` | ` retainAll(Collection arg0) ` | | ` abstract int` | ` size() ` | | ` default Spliterator` | ` spliterator() ` | | ` default Stream` | ` stream() ` | | ` abstract T[]` | ` toArray(T[] arg0) ` | | ` abstract Object[]` | ` toArray() ` | || | From interface` java.lang.Iterable ` |---------------------------|---------------------------------------| | ` default void` | ` forEach(Consumer arg0) ` | | ` abstract Iterator` | ` iterator() ` | | ` default Spliterator` | ` spliterator() ` | || ## Public methods ### addWeakCallback ``` void addWeakCallback (List 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](https://developer.android.com/reference/android/arch/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 || |--------------------|----------------------------------------------------------------------| | `previousSnapshot` | `List`: Snapshot previously captured from this List, or null.
| | `callback` | `PagedList.Callback`: Callback to dispatch to.
| **See also:** - [removeWeakCallback(Callback)](https://developer.android.com/reference/android/arch/paging/PagedList#removeWeakCallback(android.arch.paging.PagedList.Callback)) ### 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()](https://developer.android.com/reference/android/arch/paging/PagedList#size())
| | Returns || |-----|--------------------------------------------------------------------------------------------------| | `T` | The item at the passed index, or null if a null placeholder is at the specified position.
| **See also:** - [size()](https://developer.android.com/reference/android/arch/paging/PagedList#size()) ### getConfig ``` PagedList.Config getConfig () ``` Return the Config used to construct this PagedList.
| Returns || |--------------------------------------------------------------------------------------------------|-------------------------------------| | [PagedList.Config](https://developer.android.com/reference/android/arch/paging/PagedList.Config) | the Config of this PagedList
| ### getDataSource ``` DataSource getDataSource () ``` Return the DataSource that provides data to this PagedList.
| Returns || |----------------------------------------------------------------------------------------------|------------------------------------------| | [DataSource](https://developer.android.com/reference/android/arch/paging/DataSource)`` | the DataSource of this PagedList.
| ### getLastKey ``` Object getLastKey () ``` Return the key for the position passed most recently to[loadAround(int)](https://developer.android.com/reference/android/arch/paging/PagedList#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](https://developer.android.com/reference/android/arch/paging/LivePagedListBuilder), it will do this for you.
| Returns || |----------|---------------------------------------------------------------------------------------------------------------------------------------------------------| | `Object` | Key of position most recently passed to[loadAround(int)](https://developer.android.com/reference/android/arch/paging/PagedList#loadAround(int)).
| ### getPositionOffset ``` int getPositionOffset () ``` Position offset of the data in the list. If data is supplied by a[PositionalDataSource](https://developer.android.com/reference/android/arch/paging/PositionalDataSource), the item returned from`get(i)`has a position of`i + getPositionOffset()`. If the DataSource is a[ItemKeyedDataSource](https://developer.android.com/reference/android/arch/paging/ItemKeyedDataSource)or[PageKeyedDataSource](https://developer.android.com/reference/android/arch/paging/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. A detached list is[immutable](https://developer.android.com/reference/android/arch/paging/PagedList#isImmutable()).
| 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. In the future, this method may return true when a PagedList has completed loading from its DataSource. Currently, it is equivalent to[isDetached()](https://developer.android.com/reference/android/arch/paging/PagedList#isDetached()).
| 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.
| **See also:** - [addWeakCallback(List, Callback)](https://developer.android.com/reference/android/arch/paging/PagedList#addWeakCallback(java.util.List, android.arch.paging.PagedList.Callback)) ### 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 snapshot () ``` Returns an immutable snapshot of the PagedList in its current state. If this PagedList[is immutable](https://developer.android.com/reference/android/arch/paging/PagedList#isImmutable())due to its DataSource being invalid, it will be returned.
| Returns || |-----------|----------------------------------------------| | `List` | Immutable snapshot of PagedList data.
| - ## Interfaces - [DataSource.InvalidatedCallback](https://developer.android.com/reference/android/arch/paging/DataSource.InvalidatedCallback) - ## Classes - [AsyncPagedListDiffer](https://developer.android.com/reference/android/arch/paging/AsyncPagedListDiffer) - [DataSource](https://developer.android.com/reference/android/arch/paging/DataSource) - [DataSource.Factory](https://developer.android.com/reference/android/arch/paging/DataSource.Factory) - [ItemKeyedDataSource](https://developer.android.com/reference/android/arch/paging/ItemKeyedDataSource) - [ItemKeyedDataSource.LoadCallback](https://developer.android.com/reference/android/arch/paging/ItemKeyedDataSource.LoadCallback) - [ItemKeyedDataSource.LoadInitialCallback](https://developer.android.com/reference/android/arch/paging/ItemKeyedDataSource.LoadInitialCallback) - [ItemKeyedDataSource.LoadInitialParams](https://developer.android.com/reference/android/arch/paging/ItemKeyedDataSource.LoadInitialParams) - [ItemKeyedDataSource.LoadParams](https://developer.android.com/reference/android/arch/paging/ItemKeyedDataSource.LoadParams) - [LivePagedListBuilder](https://developer.android.com/reference/android/arch/paging/LivePagedListBuilder) - [PagedList](https://developer.android.com/reference/android/arch/paging/PagedList) - [PagedList.BoundaryCallback](https://developer.android.com/reference/android/arch/paging/PagedList.BoundaryCallback) - [PagedList.Builder](https://developer.android.com/reference/android/arch/paging/PagedList.Builder) - [PagedList.Callback](https://developer.android.com/reference/android/arch/paging/PagedList.Callback) - [PagedList.Config](https://developer.android.com/reference/android/arch/paging/PagedList.Config) - [PagedList.Config.Builder](https://developer.android.com/reference/android/arch/paging/PagedList.Config.Builder) - [PagedListAdapter](https://developer.android.com/reference/android/arch/paging/PagedListAdapter) - [PageKeyedDataSource](https://developer.android.com/reference/android/arch/paging/PageKeyedDataSource) - [PageKeyedDataSource.LoadCallback](https://developer.android.com/reference/android/arch/paging/PageKeyedDataSource.LoadCallback) - [PageKeyedDataSource.LoadInitialCallback](https://developer.android.com/reference/android/arch/paging/PageKeyedDataSource.LoadInitialCallback) - [PageKeyedDataSource.LoadInitialParams](https://developer.android.com/reference/android/arch/paging/PageKeyedDataSource.LoadInitialParams) - [PageKeyedDataSource.LoadParams](https://developer.android.com/reference/android/arch/paging/PageKeyedDataSource.LoadParams) - [PositionalDataSource](https://developer.android.com/reference/android/arch/paging/PositionalDataSource) - [PositionalDataSource.LoadInitialCallback](https://developer.android.com/reference/android/arch/paging/PositionalDataSource.LoadInitialCallback) - [PositionalDataSource.LoadInitialParams](https://developer.android.com/reference/android/arch/paging/PositionalDataSource.LoadInitialParams) - [PositionalDataSource.LoadRangeCallback](https://developer.android.com/reference/android/arch/paging/PositionalDataSource.LoadRangeCallback) - [PositionalDataSource.LoadRangeParams](https://developer.android.com/reference/android/arch/paging/PositionalDataSource.LoadRangeParams) - [RxPagedListBuilder](https://developer.android.com/reference/android/arch/paging/RxPagedListBuilder)