{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}
public abstract class ItemKeyedDataSource<Key extends Object, Value extends Object> extends DataSource
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 extends Object> |
Type of data used to query Value types out of the |
<Value extends Object> |
Type of items being loaded by the |
Nested types |
|
---|---|
ItemKeyedDataSource.LoadCallback |
Callback for ItemKeyedDataSource |
ItemKeyedDataSource.LoadInitialCallback |
Callback for |
ItemKeyedDataSource.LoadInitialParams |
Holder object for inputs to |
ItemKeyedDataSource.LoadParams |
Holder object for inputs to |
Public fields |
|
---|---|
boolean |
Public constructors |
|
---|---|
<Key extends Object, Value extends Object> ItemKeyedDataSource() |
Public methods |
|
---|---|
abstract @NonNull Key |
Return a key associated with the given item. |
abstract void |
loadAfter( Load list data after the key specified in |
abstract void |
loadBefore( Load list data before the key specified in |
abstract void |
loadInitial( Load initial data. |
final @NonNull ItemKeyedDataSource<@NonNull Key, @NonNull ToValue> |
Applies the given function to each value emitted by the DataSource. |
final @NonNull ItemKeyedDataSource<@NonNull Key, @NonNull ToValue> |
Applies the given function to each value emitted by the DataSource. |
final @NonNull ItemKeyedDataSource<@NonNull Key, @NonNull ToValue> |
<ToValue extends Object> mapByPage( Applies the given function to each value emitted by the DataSource. |
final @NonNull ItemKeyedDataSource<@NonNull Key, @NonNull ToValue> |
<ToValue extends Object> mapByPage( Applies the given function to each value emitted by the DataSource. |
Inherited methods |
||||||
---|---|---|---|---|---|---|
|
@NonNull
public boolean isInvalid
Returns | |
---|---|
boolean |
|
@NonNull
public final <Key extends Object, Value extends Object> ItemKeyedDataSource()
Parameters | |
---|---|
<Key extends Object> |
Type of data used to query Value types out of the |
<Value extends Object> |
Type of items being loaded by the |
@NonNull
public abstract Key getKey(@NonNull Value item)
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 | |
---|---|
@NonNull Value item |
Item to get the key from. |
Returns | |
---|---|
Key |
Key associated with given item. |
@NonNull
public abstract void loadAfter(
@NonNull ItemKeyedDataSource.LoadParams<@NonNull Key> params,
@NonNull ItemKeyedDataSource.LoadCallback<@NonNull Value> callback
)
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 | |
---|---|
@NonNull ItemKeyedDataSource.LoadParams<@NonNull Key> params |
Parameters for the load, including the key to load after, and requested size. |
@NonNull ItemKeyedDataSource.LoadCallback<@NonNull Value> callback |
Callback that receives loaded data. |
@NonNull
public abstract void loadBefore(
@NonNull ItemKeyedDataSource.LoadParams<@NonNull Key> params,
@NonNull ItemKeyedDataSource.LoadCallback<@NonNull Value> callback
)
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 | |
---|---|
@NonNull ItemKeyedDataSource.LoadParams<@NonNull Key> params |
Parameters for the load, including the key to load before, and requested size. |
@NonNull ItemKeyedDataSource.LoadCallback<@NonNull Value> callback |
Callback that receives loaded data. |
@NonNull
public abstract void loadInitial(
@NonNull ItemKeyedDataSource.LoadInitialParams<@NonNull Key> params,
@NonNull ItemKeyedDataSource.LoadInitialCallback<@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.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 | |
---|---|
@NonNull ItemKeyedDataSource.LoadInitialParams<@NonNull Key> params |
Parameters for initial load, including initial key and requested size. |
@NonNull ItemKeyedDataSource.LoadInitialCallback<@NonNull Value> callback |
Callback that receives initial load data. |
@NonNull
public final ItemKeyedDataSource<@NonNull Key, @NonNull ToValue> <ToValue extends Object> map(
@NonNull <ERROR CLASS><@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 <ERROR CLASS><@NonNull Value, @NonNull ToValue> function |
Function that runs on each loaded item, returning items of a potentially new type. |
Returns | |
---|---|
ItemKeyedDataSource<@NonNull Key, @NonNull ToValue> |
A new DataSource, which transforms items using the given function. |
@NonNull
public final ItemKeyedDataSource<@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.
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 | |
---|---|
ItemKeyedDataSource<@NonNull Key, @NonNull ToValue> |
A new DataSource, which transforms items using the given function. |
@NonNull
public final ItemKeyedDataSource<@NonNull Key, @NonNull ToValue> <ToValue extends Object> mapByPage(
@NonNull <ERROR CLASS><@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 <ERROR CLASS><@NonNull List<@NonNull Value>, @NonNull List<@NonNull ToValue>> function |
Function that runs on each loaded page, returning items of a potentially new type. |
Returns | |
---|---|
ItemKeyedDataSource<@NonNull Key, @NonNull ToValue> |
A new DataSource, which transforms items using the given function. |
@NonNull
public final ItemKeyedDataSource<@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.
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 | |
---|---|
ItemKeyedDataSource<@NonNull Key, @NonNull ToValue> |
A new DataSource, which transforms items using the given function. |