PageKeyedDataSource

Kotlin |Java

abstract class PageKeyedDataSource<Key : Any, Value : Any> : DataSource<Key, Value>

kotlin.Any
↳	androidx.paging.DataSource<Key, Value>
	↳	androidx.paging.PageKeyedDataSource

Incremental data loader for page-keyed content, where requests return keys for next/previous pages.

Implement a DataSource using PageKeyedDataSource if you need to use data from page N - 1 to load page N. This is common, for example, in network APIs that include a next/previous link or key with each page load.

The InMemoryByPageRepository in the PagingWithNetworkSample shows how to implement a network PageKeyedDataSource using Retrofit, while handling swipe-to-refresh, network errors, and retry.

Summary

Nested classes
abstract	LoadCallback Callback for loadBefore and loadAfter to return data.
abstract	LoadInitialCallback Callback for loadInitial to return data and, optionally, position/count information.
open	LoadInitialParams Holder object for inputs to loadInitial.
open	LoadParams Holder object for inputs to loadBefore and loadAfter.

Public constructors
<init>() Incremental data loader for page-keyed content, where requests return keys for next/previous pages.

Public methods
abstract Unit	loadAfter(params: PageKeyedDataSource.LoadParams<Key>, callback: PageKeyedDataSource.LoadCallback<Key, Value>) Append page with the key specified by LoadParams.key.
abstract Unit	loadBefore(params: PageKeyedDataSource.LoadParams<Key>, callback: PageKeyedDataSource.LoadCallback<Key, Value>) Prepend page with the key specified by LoadParams.key.
abstract Unit	loadInitial(params: PageKeyedDataSource.LoadInitialParams<Key>, callback: PageKeyedDataSource.LoadInitialCallback<Key, Value>) Load initial data.
PageKeyedDataSource<Key, ToValue>	map(function: Function<Value, ToValue>) Applies the given function to each value emitted by the DataSource.
PageKeyedDataSource<Key, ToValue>	map(function: (Value) -> ToValue) Applies the given function to each value emitted by the DataSource.
PageKeyedDataSource<Key, ToValue>	mapByPage(function: Function<List<Value>, List<ToValue>>) Applies the given function to each value emitted by the DataSource.
PageKeyedDataSource<Key, ToValue>	mapByPage(function: (List<Value>) -> List<ToValue>) Applies the given function to each value emitted by the DataSource.

Inherited functions

From class DataSource Unit <no name provided>() Invalidation callback for DataSource. Used to signal when a DataSource a data source has become invalid, and that a new data source is needed to continue loading data. Unit addInvalidatedCallback(onInvalidatedCallback: DataSource.InvalidatedCallback) Add a callback to invoke when the DataSource is first invalidated. Once invalidated, a data source will not become valid again. A data source will only invoke its callbacks once - the first time invalidate is called, on that thread. Unit invalidate() Signal the data source to stop loading, and notify its callback. If invalidate has already been called, this method does nothing. Unit removeInvalidatedCallback(onInvalidatedCallback: DataSource.InvalidatedCallback) Remove a previously added invalidate callback.

Inherited properties
From class DataSource Boolean isInvalid

Public constructors

<init>

PageKeyedDataSource()

Incremental data loader for page-keyed content, where requests return keys for next/previous pages.

Implement a DataSource using PageKeyedDataSource if you need to use data from page N - 1 to load page N. This is common, for example, in network APIs that include a next/previous link or key with each page load.

The InMemoryByPageRepository in the PagingWithNetworkSample shows how to implement a network PageKeyedDataSource using Retrofit, while handling swipe-to-refresh, network errors, and retry.

Parameters
Key	Type of data used to query Value types out of the DataSource.
Value	Type of items being loaded by the DataSource.

Public methods

loadAfter

abstract fun loadAfter(
    params: PageKeyedDataSource.LoadParams<Key>, 
    callback: PageKeyedDataSource.LoadCallback<Key, Value>
): Unit

Append page with the key specified by LoadParams.key.

It's valid to return a different list size than the page size if it's easier, e.g. if your backend defines page sizes. It is generally preferred to increase the number loaded than reduce.

Data may be passed synchronously during the load method, or deferred and called at a later time. Further loads going down will be blocked until the callback is called.

If data cannot be loaded (for example, if the request is invalid, or the data would be stale and inconsistent), it is valid to call invalidate to invalidate the data source, and prevent further loading.

Parameters
params: PageKeyedDataSource.LoadParams<Key>	Parameters for the load, including the key for the new page, and requested load size.
callback: PageKeyedDataSource.LoadCallback<Key, Value>	Callback that receives loaded data.

loadBefore

abstract fun loadBefore(
    params: PageKeyedDataSource.LoadParams<Key>, 
    callback: PageKeyedDataSource.LoadCallback<Key, Value>
): Unit

Prepend page with the key specified by LoadParams.key.

It's valid to return a different list size than the page size if it's easier, e.g. if your backend defines page sizes. It is generally preferred to increase the number loaded than reduce.

Data may be passed synchronously during the load method, or deferred and called at a later time. Further loads going down will be blocked until the callback is called.

If data cannot be loaded (for example, if the request is invalid, or the data would be stale and inconsistent), it is valid to call invalidate to invalidate the data source, and prevent further loading.

Parameters
params: PageKeyedDataSource.LoadParams<Key>	Parameters for the load, including the key for the new page, and requested load size.
callback: PageKeyedDataSource.LoadCallback<Key, Value>	Callback that receives loaded data.

loadInitial

abstract fun loadInitial(
    params: PageKeyedDataSource.LoadInitialParams<Key>, 
    callback: PageKeyedDataSource.LoadInitialCallback<Key, Value>
): Unit

Load initial data.

This method is called first to initialize a PagedList with data. If it's possible to count the items that can be loaded by the DataSource, it's recommended to pass the loaded data to the callback via the three-parameter LoadInitialCallback.onResult. This enables PagedLists presenting data from this source to display placeholders to represent unloaded items.

LoadInitialParams.requestedLoadSize is a hint, not a requirement, so it may be may be altered or ignored.

Parameters
params: PageKeyedDataSource.LoadInitialParams<Key>	Parameters for initial load, including requested load size.
callback: PageKeyedDataSource.LoadInitialCallback<Key, Value>	Callback that receives initial load data.

map

fun <ToValue : Any> map(function: Function<Value, ToValue>): PageKeyedDataSource<Key, ToValue>

Applies the given function to each value emitted by the DataSource.

Same as mapByPage, but operates on individual items.

Parameters