ItemKeyedDataSource

Added in 2.0.0
Deprecated in 3.0.0

Incremental data loader for paging keyed content, where loaded content uses previously loaded items as input to future loads.

Implement a DataSource using ItemKeyedDataSource if you need to use data from item N - 1 to load item N. This is common, for example, in uniquely sorted database queries where attributes of the item such just before the next query define how to execute it.

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

Parameters
<Key : Any>

Type of data used to query Value types out of the DataSource.

<Value : Any>

Type of items being loaded by the DataSource.

Summary

Nested types

abstract class ItemKeyedDataSource.LoadCallback<Value : Any?>

Callback for ItemKeyedDataSource loadBefore and loadAfter to return data.

Callback for loadInitial to return data and, optionally, position/count information.

Holder object for inputs to loadInitial.

Holder object for inputs to loadBefore and loadAfter.

Public constructors

<Key : Any, Value : Any> ItemKeyedDataSource()
android

Public functions

abstract Key
getKey(item: Value)

Return a key associated with the given item.

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

Load list data after the key specified in LoadParams.key.

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

Load list data before the key specified in LoadParams.key.

android
abstract Unit

Load initial data.

android
final ItemKeyedDataSource<Key, ToValue>
<ToValue : Any> map(function: Function<Value, ToValue>)

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

android
final ItemKeyedDataSource<Key, ToValue>
<ToValue : Any> map(function: (Value) -> ToValue)

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

android
final ItemKeyedDataSource<Key, ToValue>
<ToValue : Any> mapByPage(function: Function<List<Value>, List<ToValue>>)

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

android
final ItemKeyedDataSource<Key, ToValue>
<ToValue : Any> mapByPage(function: (List<Value>) -> List<ToValue>)

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

android

Inherited functions

From androidx.paging.DataSource
open Unit

Add a callback to invoke when the DataSource is first invalidated.

android
open Unit

Signal the data source to stop loading, and notify its callback.

android
open Unit

Remove a previously added invalidate callback.

android

Inherited properties

From androidx.paging.DataSource
open Boolean
android

Public constructors

ItemKeyedDataSource

<Key : Any, Value : Any> ItemKeyedDataSource()
Parameters
<Key : Any>

Type of data used to query Value types out of the DataSource.

<Value : Any>

Type of items being loaded by the DataSource.

Public functions

getKey

abstract fun getKey(item: Value): Key

Return a key associated with the given item.

If your ItemKeyedDataSource is loading from a source that is sorted and loaded by a unique integer ID, you would return item.getID() here. This key can then be passed to loadBefore or loadAfter to load additional items adjacent to the item passed to this function.

If your key is more complex, such as when you're sorting by name, then resolving collisions with integer ID, you'll need to return both. In such a case you would use a wrapper class, such as Pair<String, Integer> or, in Kotlin, data class Key(val name: String, val id: Int)

Parameters
item: Value

Item to get the key from.

Returns
Key

Key associated with given item.

loadAfter

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

Load list data after the key specified in 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 loadAfter 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: ItemKeyedDataSource.LoadParams<Key>

Parameters for the load, including the key to load after, and requested size.

callback: ItemKeyedDataSource.LoadCallback<Value>

Callback that receives loaded data.

loadBefore

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

Load list data before the key specified in 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.

Note: Data returned will be prepended just before the key passed, so if you vary size, ensure that the last item is adjacent to the passed key.

Data may be passed synchronously during the loadBefore method, or deferred and called at a later time. Further loads going up 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: ItemKeyedDataSource.LoadParams<Key>

Parameters for the load, including the key to load before, and requested size.

callback: ItemKeyedDataSource.LoadCallback<Value>

Callback that receives loaded data.

loadInitial

abstract fun loadInitial(
    params: ItemKeyedDataSource.LoadInitialParams<Key>,
    callback: ItemKeyedDataSource.LoadInitialCallback<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.requestedInitialKey and LoadInitialParams.requestedLoadSize are hints, not requirements, so they may be altered or ignored. Note that ignoring the requestedInitialKey can prevent subsequent PagedList/DataSource pairs from initializing at the same location. If your DataSource never invalidates (for example, loading from the network without the network ever signalling that old data must be reloaded), it's fine to ignore the initialLoadKey and always start from the beginning of the data set.

Parameters
params: ItemKeyedDataSource.LoadInitialParams<Key>

Parameters for initial load, including initial key and requested size.

callback: ItemKeyedDataSource.LoadInitialCallback<Value>

Callback that receives initial load data.

map

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

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

Same as mapByPage, but operates on individual items.

Parameters
<ToValue : Any>

Type of items produced by the new DataSource, from the passed function.

function: Function<Value, ToValue>

Function that runs on each loaded item, returning items of a potentially new type.

Returns
ItemKeyedDataSource<Key, ToValue>

A new DataSource, which transforms items using the given function.

map

final fun <ToValue : Any> map(function: (Value) -> ToValue): ItemKeyedDataSource<Key, ToValue>

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

An overload of map that accepts a kotlin function type.

Same as mapByPage, but operates on individual items.

Parameters
<ToValue : Any>

Type of items produced by the new DataSource, from the passed function.

function: (Value) -> ToValue

Function that runs on each loaded item, returning items of a potentially new type.

Returns
ItemKeyedDataSource<Key, ToValue>

A new DataSource, which transforms items using the given function.

See also
mapByPage
map

mapByPage

final fun <ToValue : Any> mapByPage(function: Function<List<Value>, List<ToValue>>): ItemKeyedDataSource<Key, ToValue>

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

Same as map, but allows for batch conversions.

Parameters
<ToValue : Any>

Type of items produced by the new DataSource, from the passed function.

function: Function<List<Value>, List<ToValue>>

Function that runs on each loaded page, returning items of a potentially new type.

Returns
ItemKeyedDataSource<Key, ToValue>

A new DataSource, which transforms items using the given function.

See also
map
map
mapByPage

mapByPage

final fun <ToValue : Any> mapByPage(function: (List<Value>) -> List<ToValue>): ItemKeyedDataSource<Key, ToValue>

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

An overload of mapByPage that accepts a kotlin function type.

Same as map, but allows for batch conversions.

Parameters
<ToValue : Any>

Type of items produced by the new DataSource, from the passed function.

function: (List<Value>) -> List<ToValue>

Function that runs on each loaded page, returning items of a potentially new type.

Returns
ItemKeyedDataSource<Key, ToValue>

A new DataSource, which transforms items using the given function.

See also
map
map
mapByPage