Save the date! Android Dev Summit is coming to Sunnyvale, CA on Oct 23-24, 2019.

PageKeyedDataSource

abstract class PageKeyedDataSource<Key : Any!, Value : Any!> : ContiguousDataSource<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
open

Holder object for inputs to loadInitial(LoadInitialParams, LoadInitialCallback).

open

Holder object for inputs to loadBefore(LoadParams, LoadCallback) and loadAfter(LoadParams, LoadCallback).

abstract

Callback for loadInitial(LoadInitialParams, LoadInitialCallback) to return data and, optionally, position/count information.

abstract

Callback for PageKeyedDataSource loadBefore(LoadParams, LoadCallback) and loadAfter(LoadParams, LoadCallback) to return data.

Public constructors

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

Public methods
abstract Unit
loadInitial(@NonNull params: PageKeyedDataSource.LoadInitialParams<Key>, @NonNull callback: PageKeyedDataSource.LoadInitialCallback<Key, Value>)

Load initial data.

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

Append page with the key specified by LoadParams.key.

PageKeyedDataSource<Key, ToValue>
map(@NonNull function: Function<Value, ToValue>)

PageKeyedDataSource<Key, ToValue>
mapByPage(@NonNull function: Function<MutableList<Value>!, MutableList<ToValue>!>)

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

Prepend page with the key specified by LoadParams.key.

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.

Public methods

loadInitial

abstract fun loadInitial(@NonNull params: PageKeyedDataSource.LoadInitialParams<Key>, @NonNull 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(List, int, int, Object, Object). 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.LoadInitialParams<Key>: Callback that receives initial load data.

loadAfter

abstract fun loadAfter(@NonNull params: PageKeyedDataSource.LoadParams<Key>, @NonNull 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 safer 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.LoadParams<Key>: Callback that receives loaded data.

map

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

mapByPage

@NonNull fun <ToValue : Any!> mapByPage(@NonNull function: Function<MutableList<Value>!, MutableList<ToValue>!>): PageKeyedDataSource<Key, ToValue>

loadBefore

abstract fun loadBefore(@NonNull params: PageKeyedDataSource.LoadParams<Key>, @NonNull 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 safer 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.LoadParams<Key>: Callback that receives loaded data.