DataSource
public
abstract
class
DataSource
extends Object
java.lang.Object | |
↳ | android.arch.paging.DataSource<Key, Value> |
Base class for loading pages of snapshot data into a PagedList
.
DataSource is queried to load pages of content into a PagedList
. A PagedList can grow as
it loads more data, but the data loaded cannot be updated. If the underlying data set is
modified, a new PagedList / DataSource pair must be created to represent the new data.
Loading Pages
PagedList queries data from its DataSource in response to loading hints.PagedListAdapter
calls loadAround(int)
to load content as the user scrolls in a RecyclerView.
To control how and when a PagedList queries data from its DataSource, see
PagedList.Config
. The Config object defines things like load sizes and prefetch distance.
Updating Paged Data
A PagedList / DataSource pair are a snapshot of the data set. A new pair of PagedList / DataSource must be created if an update occurs, such as a reorder, insert, delete, or content update occurs. A DataSource must detect that it cannot continue loading its snapshot (for instance, when Database query notices a table being invalidated), and callinvalidate()
. Then a new PagedList / DataSource pair would be created to load data from
the new state of the Database query.
To page in data that doesn't update, you can create a single DataSource, and pass it to a single PagedList. For example, loading from network when the network's paging API doesn't provide updates.
To page in data from a source that does provide updates, you can create a
DataSource.Factory
, where each DataSource created is invalidated when an update to the
data set occurs that makes the current snapshot invalid. For example, when paging a query from
the Database, and the table being queried inserts or removes items. You can also use a
DataSource.Factory to provide multiple versions of network-paged lists. If reloading all content
(e.g. in response to an action like swipe-to-refresh) is required to get a new version of data,
you can connect an explicit refresh signal to call invalidate()
on the current
DataSource.
If you have more granular update signals, such as a network API signaling an update to a single item in the list, it's recommended to load data from network into memory. Then present that data to the PagedList via a DataSource that wraps an in-memory snapshot. Each time the in-memory copy changes, invalidate the previous DataSource, and a new one wrapping the new state of the snapshot can be created.
Implementing a DataSource
To implement, extend one of the subclasses:PageKeyedDataSource
,
ItemKeyedDataSource
, or PositionalDataSource
.
Use PageKeyedDataSource
if pages you load embed keys for loading adjacent pages. For
example a network response that returns some items, and a next/previous page links.
Use ItemKeyedDataSource
if you need to use data from item N-1
to load item
N
. For example, if requesting the backend for the next comments in the list
requires the ID or timestamp of the most recent loaded comment, or if querying the next users
from a name-sorted database query requires the name and unique ID of the previous.
Use PositionalDataSource
if you can load pages of a requested size at arbitrary
positions, and provide a fixed item count. PositionalDataSource supports querying pages at
arbitrary positions, so can provide data to PagedLists in arbitrary order. Note that
PositionalDataSource is required to respect page size for efficient tiling. If you want to
override page size (e.g. when network page size constraints are only known at runtime), use one
of the other DataSource classes.
Because a null
item indicates a placeholder in PagedList
, DataSource may not
return null
items in lists that it loads. This is so that users of the PagedList
can differentiate unloaded placeholder items from content that has been paged in.
Summary
Nested classes | |
---|---|
class |
DataSource.Factory<Key, Value>
Factory for DataSources. |
interface |
DataSource.InvalidatedCallback
Invalidation callback for DataSource. |
Public methods | |
---|---|
void
|
addInvalidatedCallback(DataSource.InvalidatedCallback onInvalidatedCallback)
Add a callback to invoke when the DataSource is first invalidated. |
void
|
invalidate()
Signal the data source to stop loading, and notify its callback. |
boolean
|
isInvalid()
Returns true if the data source is invalid, and can no longer be queried for data. |
abstract
<ToValue>
DataSource<Key, ToValue>
|
map(Function<Value, ToValue> function)
Applies the given function to each value emitted by the DataSource. |
abstract
<ToValue>
DataSource<Key, ToValue>
|
mapByPage(Function<List<Value>, List<ToValue>> function)
Applies the given function to each value emitted by the DataSource. |
void
|
removeInvalidatedCallback(DataSource.InvalidatedCallback onInvalidatedCallback)
Remove a previously added invalidate callback. |
Inherited methods | |
---|---|
Public methods
addInvalidatedCallback
void addInvalidatedCallback (DataSource.InvalidatedCallback onInvalidatedCallback)
Add a callback to invoke when the DataSource is first invalidated.
Once invalidated, a data source will not become valid again.
A data source will only invoke its callbacks once - the first time invalidate()
is called, on that thread.
Parameters | |
---|---|
onInvalidatedCallback |
DataSource.InvalidatedCallback : The callback, will be invoked on thread that
invalidate() is called on.
|
invalidate
void invalidate ()
Signal the data source to stop loading, and notify its callback.
If invalidate has already been called, this method does nothing.
isInvalid
boolean isInvalid ()
Returns true if the data source is invalid, and can no longer be queried for data.
Returns | |
---|---|
boolean |
True if the data source is invalid, and can no longer return data. |
map
DataSource<Key, ToValue> map (Function<Value, ToValue> function)
Applies the given function to each value emitted by the DataSource.
Same as mapByPage(Function)
, but operates on individual items.
Parameters | |
---|---|
function |
Function : Function that runs on each loaded item, returning items of a potentially
new type. |
Returns | |
---|---|
DataSource<Key, ToValue> |
A new DataSource, which transforms items using the given function. |
mapByPage
DataSource<Key, ToValue> mapByPage (Function<List<Value>, List<ToValue>> function)
Applies the given function to each value emitted by the DataSource.
Same as map(Function)
, but allows for batch conversions.
Parameters | |
---|---|
function |
Function : Function that runs on each loaded page, returning items of a potentially
new type. |
Returns | |
---|---|
DataSource<Key, ToValue> |
A new DataSource, which transforms items using the given function. |
removeInvalidatedCallback
void removeInvalidatedCallback (DataSource.InvalidatedCallback onInvalidatedCallback)
Remove a previously added invalidate callback.
Parameters | |
---|---|
onInvalidatedCallback |
DataSource.InvalidatedCallback : The previously added callback.
|
Interfaces
Classes
- AsyncPagedListDiffer
- DataSource
- DataSource.Factory
- ItemKeyedDataSource
- ItemKeyedDataSource.LoadCallback
- ItemKeyedDataSource.LoadInitialCallback
- ItemKeyedDataSource.LoadInitialParams
- ItemKeyedDataSource.LoadParams
- LivePagedListBuilder
- PagedList
- PagedList.BoundaryCallback
- PagedList.Builder
- PagedList.Callback
- PagedList.Config
- PagedList.Config.Builder
- PagedListAdapter
- PageKeyedDataSource
- PageKeyedDataSource.LoadCallback
- PageKeyedDataSource.LoadInitialCallback
- PageKeyedDataSource.LoadInitialParams
- PageKeyedDataSource.LoadParams
- PositionalDataSource
- PositionalDataSource.LoadInitialCallback
- PositionalDataSource.LoadInitialParams
- PositionalDataSource.LoadRangeCallback
- PositionalDataSource.LoadRangeParams
- RxPagedListBuilder
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-04-11 UTC.