PageKeyedDataSource

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

Object
   ↳ DataSource
     ↳ 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

PageKeyedDataSource.LoadCallback

Callback for loadBefore and loadAfter to return data.

PageKeyedDataSource.LoadInitialCallback

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

PageKeyedDataSource.LoadInitialParams

Holder object for inputs to loadInitial.

PageKeyedDataSource.LoadParams

Holder object for inputs to loadBefore and loadAfter.

Public constructors

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

Public methods

abstract void
loadAfter(
    PageKeyedDataSource.LoadParams<Key> params,
    PageKeyedDataSource.LoadCallback<Key, Value> callback
)

Append page with the key specified by LoadParams.key.

abstract void
loadBefore(
    PageKeyedDataSource.LoadParams<Key> params,
    PageKeyedDataSource.LoadCallback<Key, Value> callback
)

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(Function<Value, ToValue> function)

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

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

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

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

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

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

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

Inherited methods

From class DataSource
@AnyThread void

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

@AnyThread void

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

@AnyThread void

Remove a previously added invalidate callback.

Public constructors

PageKeyedDataSource

public final <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

public abstract void loadAfter(
    PageKeyedDataSource.LoadParams<Key> params,
    PageKeyedDataSource.LoadCallback<Key, 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
PageKeyedDataSource.LoadParams<Key> params

Parameters for the load, including the key for the new page, and requested load size.

PageKeyedDataSource.LoadCallback<Key, Value> callback

Callback that receives loaded data.

loadBefore

public abstract void