PositionalDataSource

Kotlin |Java

abstract class PositionalDataSource<T : Any> : DataSource<Int, T>

kotlin.Any
↳	androidx.paging.DataSource<kotlin.Int, T>
	↳	androidx.paging.PositionalDataSource

Position-based data loader for a fixed-size, countable data set, supporting fixed-size loads at arbitrary page positions.

Extend PositionalDataSource if you can load pages of a requested size at arbitrary positions, and provide a fixed item count. If your data source can't support loading arbitrary requested page sizes (e.g. when network page size constraints are only known at runtime), either use PageKeyedDataSource or ItemKeyedDataSource, or pass the initial result with the two parameter LoadInitialCallback.onResult.

Room can generate a Factory of PositionalDataSources for you:

@Dao
interface UserDao {
    @Query("SELECT * FROM user ORDER BY age DESC")
    public abstract DataSource.Factory<Integer, User> loadUsersByAgeDesc();
}

Summary

Nested classes
abstract	LoadInitialCallback Callback for loadInitial to return data, position, and count.
open	LoadInitialParams Holder object for inputs to loadInitial.
abstract	LoadRangeCallback Callback for PositionalDataSource loadRange to return data.
open	LoadRangeParams Holder object for inputs to loadRange.

Public constructors
<init>() Position-based data loader for a fixed-size, countable data set, supporting fixed-size loads at arbitrary page positions.

Public methods
abstract Unit	loadInitial(params: PositionalDataSource.LoadInitialParams, callback: PositionalDataSource.LoadInitialCallback<T>) Load initial list data.
abstract Unit	loadRange(params: PositionalDataSource.LoadRangeParams, callback: PositionalDataSource.LoadRangeCallback<T>) Called to load a range of data from the DataSource.
PositionalDataSource<V>	map(function: Function<T, V>) Applies the given function to each value emitted by the DataSource.
PositionalDataSource<V>	map(function: (T) -> V) Applies the given function to each value emitted by the DataSource.
PositionalDataSource<V>	mapByPage(function: Function<List<T>, List<V>>) Applies the given function to each value emitted by the DataSource.
PositionalDataSource<V>	mapByPage(function: (List<T>) -> List<V>) Applies the given function to each value emitted by the DataSource.

Inherited functions

From class DataSource Unit addInvalidatedCallback(onInvalidatedCallback: DataSource.InvalidatedCallback) 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. Unit addInvalidatedCallback(onInvalidatedCallback: () -> Unit) 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. This is a redundant override of addInvalidatedCallback, which accepts Kotlin functions. Unit invalidate() Signal the data source to stop loading, and notify its callback. If invalidate has already been called, this method does nothing. Unit removeInvalidatedCallback(onInvalidatedCallback: DataSource.InvalidatedCallback) Remove a previously added invalidate callback. Unit removeInvalidatedCallback(onInvalidatedCallback: () -> Unit) Remove a previously added invalidate callback. This is a redundant override of removeInvalidatedCallback, which accepts Kotlin functions.

Inherited properties
From class DataSource Boolean isInvalid

Public constructors

<init>

PositionalDataSource()

Position-based data loader for a fixed-size, countable data set, supporting fixed-size loads at arbitrary page positions.

Extend PositionalDataSource if you can load pages of a requested size at arbitrary positions, and provide a fixed item count. If your data source can't support loading arbitrary requested page sizes (e.g. when network page size constraints are only known at runtime), either use PageKeyedDataSource or ItemKeyedDataSource, or pass the initial result with the two parameter LoadInitialCallback.onResult.

Room can generate a Factory of PositionalDataSources for you:

@Dao
interface UserDao {
    @Query("SELECT * FROM user ORDER BY age DESC")
    public abstract DataSource.Factory<Integer, User> loadUsersByAgeDesc();
}

Parameters
T	Type of items being loaded by the PositionalDataSource.

Public methods

loadInitial

@WorkerThread abstract fun loadInitial(
    params: PositionalDataSource.LoadInitialParams, 
    callback: PositionalDataSource.LoadInitialCallback<T>
): Unit

Load initial list data.

This method is called to load the initial page(s) from the DataSource.

LoadResult list must be a multiple of pageSize to enable efficient tiling.

Parameters
params: PositionalDataSource.LoadInitialParams	Parameters for initial load, including requested start position, load size, and page size.
callback: PositionalDataSource.LoadInitialCallback<T>	Callback that receives initial load data, including position and total data set size.

loadRange

@WorkerThread abstract fun loadRange(
    params: PositionalDataSource.LoadRangeParams, 
    callback: PositionalDataSource.LoadRangeCallback<T>
): Unit

Called to load a range of data from the DataSource.

This method is called to load additional pages from the DataSource after the LoadInitialCallback passed to dispatchLoadInitial has initialized a PagedList.

Unlike loadInitial, this method must return the number of items requested, at the position requested.

Parameters
params: PositionalDataSource.LoadRangeParams	Parameters for load, including start position and load size.
callback: PositionalDataSource.LoadRangeCallback<T>	Callback that receives loaded data.

map

fun <V : Any> map(function: Function<T, V>): PositionalDataSource<V>

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

Same as mapByPage, but operates on individual items.

Parameters
function: Function<T, V>	Function that runs on each loaded item, returning items of a potentially new type.
ToValue	Type of items produced by the new DataSource, from the passed function.

Return
A new DataSource,	which transforms items using the given function.

See Also

• mapByPage
• DataSource.Factory.map
• DataSource.Factory.mapByPage

map

fun <V : Any> map(function: (T) -> V): PositionalDataSource<V>

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
function: (T) -> V	Function that runs on each loaded item, returning items of a potentially new type.
ToValue	Type of items produced by the new DataSource, from the passed function.

Return
A new DataSource,	which transforms items using the given function.

See Also

• mapByPage
• DataSource.Factory.map

mapByPage

fun <V : Any> mapByPage(function: Function<List<T>, List<V>>): PositionalDataSource<V>

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

Same as map, but allows for batch conversions.

Parameters
function: Function<List<T>, List<V>>	Function that runs on each loaded page, returning items of a potentially new type.
ToValue	Type of items produced by the new DataSource, from the passed function.

Return
A new DataSource,	which transforms items using the given function.

See Also

• map
• DataSource.Factory.map
• DataSource.Factory.mapByPage

mapByPage

fun <V : Any> mapByPage(function: (List<T>) -> List<V>): PositionalDataSource<V>

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
function: (List<T>) -> List<V>	Function that runs on each loaded page, returning items of a potentially new type.
ToValue	Type of items produced by the new DataSource, from the passed function.

Return
A new	DataSource, which transforms items using the given function.

See Also

• map
• DataSource.Factory.map
• DataSource.Factory.mapByPage