{% setvar book_path %}/reference/kotlin/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}
abstract class PageKeyedDataSource<Key : Any, Value : Any> : DataSource
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 : Any> |
Type of data used to query Value types out of the |
<Value : Any> |
Type of items being loaded by the |
Nested types |
|
---|---|
PageKeyedDataSource.LoadCallback |
Callback for |
PageKeyedDataSource.LoadInitialCallback |
Callback for |
PageKeyedDataSource.LoadInitialParams |
Holder object for inputs to |
PageKeyedDataSource.LoadParams |
Holder object for inputs to |
Public constructors |
|
---|---|
<Key : Any, Value : Any> PageKeyedDataSource() |
Public functions |
|
---|---|
abstract Unit |
loadAfter( Append page with the key specified by |
abstract Unit |
loadBefore( Prepend page with the key specified by |
abstract Unit |
loadInitial( Load initial data. |
final PageKeyedDataSource<Key, ToValue> |
<ToValue : Any> map(function: <ERROR CLASS><Value, ToValue>) Applies the given function to each value emitted by the DataSource. |
final PageKeyedDataSource<Key, ToValue> |
Applies the given function to each value emitted by the DataSource. |
final PageKeyedDataSource<Key, ToValue> |
<ToValue : Any> mapByPage( Applies the given function to each value emitted by the DataSource. |
final PageKeyedDataSource<Key, ToValue> |
Applies the given function to each value emitted by the DataSource. |
Inherited functions |
||||||
---|---|---|---|---|---|---|
|
open val isInvalid: Boolean
Returns | |
---|---|
Boolean |
|
<Key : Any, Value : Any> PageKeyedDataSource()
Parameters | |
---|---|
<Key : Any> |
Type of data used to query Value types out of the |
<Value : Any> |
Type of items being loaded by the |
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. |
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. |
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. |
final fun <ToValue : Any> map(function: <ERROR CLASS><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 | |
---|---|
<ToValue : Any> |
Type of items produced by the new DataSource, from the passed function. |
function: <ERROR CLASS><Value, ToValue> |
Function that runs on each loaded item, returning items of a potentially new type. |
Returns | |
---|---|
PageKeyedDataSource<Key, ToValue> |
A new DataSource, which transforms items using the given function. |
final fun <ToValue : Any> map(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 | |
---|---|
<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 | |
---|---|
PageKeyedDataSource<Key, ToValue> |
A new DataSource, which transforms items using the given function. |
final fun <ToValue : Any> mapByPage(
function: <ERROR CLASS><List<Value>, List<ToValue>>
): PageKeyedDataSource<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: <ERROR CLASS><List<Value>, List<ToValue>> |
Function that runs on each loaded page, returning items of a potentially new type. |
Returns | |
---|---|
PageKeyedDataSource<Key, ToValue> |
A new DataSource, which transforms items using the given function. |
final fun <ToValue : Any> mapByPage(function: (List<Value>) -> List<ToValue>): PageKeyedDataSource<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: (List<Value>) -> List<ToValue> |
Function that runs on each loaded page, returning items of a potentially new type. |
Returns | |
---|---|
PageKeyedDataSource<Key, ToValue> |
A new DataSource, which transforms items using the given function. |