PageKeyedDataSource

Added in 2.0.0
Deprecated in 3.0.0

public abstract class PageKeyedDataSource<Key extends Object, Value extends Object> extends DataSource

java.lang.Object
   ↳ androidx.paging.DataSource
     ↳ 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.

Parameters
<Key extends Object>

Type of data used to query Value types out of the DataSource.
<Value extends Object>

Type of items being loaded by the DataSource.

Summary

Nested types
public abstract class PageKeyedDataSource.LoadCallback<Key extends Object, Value extends Object>

Callback for loadBefore and loadAfter to return data.
public abstract class PageKeyedDataSource.LoadInitialCallback<Key extends Object, Value extends Object>

Callback for loadInitial to return data and, optionally, position/count information.
public class PageKeyedDataSource.LoadInitialParams<Key extends Object>

Holder object for inputs to loadInitial.
public class PageKeyedDataSource.LoadParams<Key extends Object>

Holder object for inputs to loadBefore and loadAfter.

Public constructors
<Key extends Object, Value extends Object> PageKeyedDataSource()

Public methods
abstract void

Append page with the key specified by LoadParams.key.
abstract void

Prepend page with the key specified by LoadParams.key.
abstract void

Load initial data.
final @NonNull PageKeyedDataSource<@NonNull Key, @NonNull ToValue>
<ToValue extends Object> map(
    @NonNull Function<@NonNull Value, @NonNull ToValue> function
)

Applies the given function to each value emitted by the DataSource.
final @NonNull PageKeyedDataSource<@NonNull Key, @NonNull ToValue>
<ToValue extends Object> map(
    @NonNull Function1<@NonNull Value, @NonNull ToValue> function
)

Applies the given function to each value emitted by the DataSource.
final @NonNull PageKeyedDataSource<@NonNull Key, @NonNull ToValue>
<ToValue extends Object> mapByPage(
    @NonNull Function<@NonNull List<@NonNull Value>, @NonNull List<@NonNull ToValue>> function
)

Applies the given function to each value emitted by the DataSource.
final @NonNull PageKeyedDataSource<@NonNull Key, @NonNull ToValue>
<ToValue extends Object> mapByPage(
    @NonNull Function1<@NonNull List<@NonNull Value>, @NonNull List<@NonNull ToValue>> function
)

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

Inherited methods
From androidx.paging.DataSource
void

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

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

Remove a previously added invalidate callback.

Public constructors

PageKeyedDataSource

public <Key extends Object, Value extends Object> PageKeyedDataSource()
Parameters
<Key extends Object>

Type of data used to query Value types out of the DataSource.
<Value extends Object>

Type of items being loaded by the DataSource.

Public methods

loadAfter

Added in 2.0.0
Deprecated in 3.0.0
public abstract void loadAfter(
    @NonNull PageKeyedDataSource.LoadParams<@NonNull Key> params,
    @NonNull PageKeyedDataSource.LoadCallback<@NonNull Key, @NonNull Value> callback
)

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
@NonNull PageKeyedDataSource.LoadParams<@NonNull Key> params

Parameters for the load, including the key for the new page, and requested load size.
@NonNull PageKeyedDataSource.LoadCallback<@NonNull Key, @NonNull Value> callback

Callback that receives loaded data.

loadBefore

Added in 2.0.0
Deprecated in 3.0.0
public abstract void loadBefore(
    @NonNull PageKeyedDataSource.LoadParams<@NonNull Key> params,
    @NonNull PageKeyedDataSource.LoadCallback<@NonNull Key, @NonNull Value> callback
)

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
@NonNull PageKeyedDataSource.LoadParams<@NonNull Key> params

Parameters for the load, including the key for the new page, and requested load size.
@NonNull PageKeyedDataSource.LoadCallback<@NonNull Key, @NonNull Value> callback

Callback that receives loaded data.

loadInitial

Added in 2.0.0
Deprecated in 3.0.0
public abstract void loadInitial(
    @NonNull PageKeyedDataSource.LoadInitialParams<@NonNull Key> params,
    @NonNull PageKeyedDataSource.LoadInitialCallback<@NonNull Key, @NonNull Value> callback
)

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
@NonNull PageKeyedDataSource.LoadInitialParams<@NonNull Key> params

Parameters for initial load, including requested load size.
@NonNull PageKeyedDataSource.LoadInitialCallback<@NonNull Key, @NonNull Value> callback

Callback that receives initial load data.

map

Added in 3.3.5
Deprecated in 3.3.5
public final @NonNull PageKeyedDataSource<@NonNull Key, @NonNull ToValue> <ToValue extends Object> map(
    @NonNull Function<@NonNull Value, @NonNull ToValue> function
)

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

Same as mapByPage, but operates on individual items.

Parameters
<ToValue extends Object>

Type of items produced by the new DataSource, from the passed function.
@NonNull Function<@NonNull Value, @NonNull ToValue> function

Function that runs on each loaded item, returning items of a potentially new type.
Returns
@NonNull PageKeyedDataSource<@NonNull Key, @NonNull ToValue>

A new DataSource, which transforms items using the given function.
See also
mapByPage
map
mapByPage

map

Added in 3.0.0
Deprecated in 3.0.0
public final @NonNull PageKeyedDataSource<@NonNull Key, @NonNull ToValue> <ToValue extends Object> map(
    @NonNull Function1<@NonNull Value, @NonNull ToValue> function
)

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 extends Object>

Type of items produced by the new DataSource, from the passed function.
@NonNull Function1<@NonNull Value, @NonNull ToValue> function

Function that runs on each loaded item, returning items of a potentially new type.
Returns
@NonNull PageKeyedDataSource<@NonNull Key, @NonNull ToValue>

A new DataSource, which transforms items using the given function.
See also
mapByPage
map

mapByPage

Added in 3.3.5
Deprecated in 3.3.5
public final @NonNull PageKeyedDataSource<@NonNull Key, @NonNull ToValue> <ToValue extends Object> mapByPage(
    @NonNull Function<@NonNull List<@NonNull Value>, @NonNull List<@NonNull ToValue>> function
)

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

Same as map, but allows for batch conversions.

Parameters
<ToValue extends Object>

Type of items produced by the new DataSource, from the passed function.
@NonNull Function<@NonNull List<@NonNull Value>, @NonNull List<@NonNull ToValue>> function

Function that runs on each loaded page, returning items of a potentially new type.
Returns
@NonNull PageKeyedDataSource<@NonNull Key, @NonNull ToValue>

A new DataSource, which transforms items using the given function.
See also
map
map
mapByPage

mapByPage

public final @NonNull PageKeyedDataSource<@NonNull Key, @NonNull ToValue> <ToValue extends Object> mapByPage(
    @NonNull Function1<@NonNull List<@NonNull Value>, @NonNull List<@NonNull ToValue>> function
)

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 extends Object>

Type of items produced by the new DataSource, from the passed function.
@NonNull Function1<@NonNull List<@NonNull Value>, @NonNull List<@NonNull ToValue>> function

Function that runs on each loaded page, returning items of a potentially new type.
Returns
@NonNull PageKeyedDataSource<@NonNull Key, @NonNull ToValue>

A new DataSource, which transforms items using the given function.
See also
map
map
mapByPage