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), use either PageKeyedDataSource or ItemKeyedDataSource instead.

Note that unless placeholders are disabled PositionalDataSource requires counting the size of the data set. This allows pages to be tiled in at arbitrary, non-contiguous locations based upon what the user observes in a PagedList. If placeholders are disabled, initialize with the two parameter LoadInitialCallback#onResult(List, int).

Room can generate a Factory of PositionalDataSources for you:

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

Summary

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

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

Public methods
open static Int	computeInitialLoadPosition(@NonNull params: PositionalDataSource.LoadInitialParams, totalCount: Int) Helper for computing an initial position in loadInitial(LoadInitialParams, LoadInitialCallback) when total data set size can be computed ahead of loading.
open static Int	computeInitialLoadSize(@NonNull params: PositionalDataSource.LoadInitialParams, initialLoadPosition: Int, totalCount: Int) Helper for computing an initial load size in loadInitial(LoadInitialParams, LoadInitialCallback) when total data set size can be computed ahead of loading.
abstract Unit	loadInitial(@NonNull params: PositionalDataSource.LoadInitialParams, @NonNull callback: PositionalDataSource.LoadInitialCallback<T>) Load initial list data.
abstract Unit	loadRange(@NonNull params: PositionalDataSource.LoadRangeParams, @NonNull callback: PositionalDataSource.LoadRangeCallback<T>) Called to load a range of data from the DataSource.
PositionalDataSource<V>	map(@NonNull function: Function<T, V>)
PositionalDataSource<V>	mapByPage(@NonNull function: Function<MutableList<T>!, MutableList<V>!>)

Inherited functions

From class DataSource Unit addInvalidatedCallback(@NonNull 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 invalidate() Signal the data source to stop loading, and notify its callback. If invalidate has already been called, this method does nothing. Boolean isInvalid() Returns true if the data source is invalid, and can no longer be queried for data. Unit removeInvalidatedCallback(@NonNull onInvalidatedCallback: DataSource.InvalidatedCallback) Remove a previously added invalidate callback.

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), use either PageKeyedDataSource or ItemKeyedDataSource instead.

Note that unless placeholders are disabled PositionalDataSource requires counting the size of the data set. This allows pages to be tiled in at arbitrary, non-contiguous locations based upon what the user observes in a PagedList. If placeholders are disabled, initialize with the two parameter LoadInitialCallback#onResult(List, int).

Room can generate a Factory of PositionalDataSources for you:

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

Public methods

computeInitialLoadPosition

open static fun computeInitialLoadPosition(@NonNull params: PositionalDataSource.LoadInitialParams, totalCount: Int): Int

Helper for computing an initial position in loadInitial(LoadInitialParams, LoadInitialCallback) when total data set size can be computed ahead of loading.

The value computed by this function will do bounds checking, page alignment, and positioning based on initial load size requested.

Example usage in a PositionalDataSource subclass:

class ItemDataSource extends PositionalDataSource<Item> {
          private int computeCount() {
              // actual count code here
          }
     
          private List<Item> loadRangeInternal(int startPosition, int loadCount) {
              // actual load code here
          }
     
          @Override
          public void loadInitial(@NonNull LoadInitialParams params,
                  @NonNull LoadInitialCallback<Item> callback) {
              int totalCount = computeCount();
              int position = computeInitialLoadPosition(params, totalCount);
              int loadSize = computeInitialLoadSize(params, position, totalCount);
              callback.onResult(loadRangeInternal(position, loadSize), position, totalCount);
          }
     
          @Override
          public void loadRange(@NonNull LoadRangeParams params,
                  @NonNull LoadRangeCallback<Item> callback) {
              callback.onResult(loadRangeInternal(params.startPosition, params.loadSize));
          }
      }

Parameters
params	PositionalDataSource.LoadInitialParams: Params passed to loadInitial(LoadInitialParams, LoadInitialCallback), including page size, and requested start/loadSize.
totalCount	PositionalDataSource.LoadInitialParams: Total size of the data set.

Return
Int: Position to start loading at.

See Also

• #computeInitialLoadSize(LoadInitialParams, int, int)

computeInitialLoadSize

open static fun computeInitialLoadSize(@NonNull params: PositionalDataSource.LoadInitialParams, initialLoadPosition: Int, totalCount: Int): Int

Helper for computing an initial load size in loadInitial(LoadInitialParams, LoadInitialCallback) when total data set size can be computed ahead of loading.

This function takes the requested load size, and bounds checks it against the value returned by computeInitialLoadPosition(LoadInitialParams, int).

Example usage in a PositionalDataSource subclass:

class ItemDataSource extends PositionalDataSource<Item> {
          private int computeCount() {
              // actual count code here
          }
     
          private List<Item> loadRangeInternal(int startPosition, int loadCount) {
              // actual load code here
          }
     
          @Override
          public void loadInitial(@NonNull LoadInitialParams params,
                  @NonNull LoadInitialCallback<Item> callback) {
              int totalCount = computeCount();
              int position = computeInitialLoadPosition(params, totalCount);
              int loadSize = computeInitialLoadSize(params, position, totalCount);
              callback.onResult(loadRangeInternal(position, loadSize), position, totalCount);
          }
     
          @Override
          public void loadRange(@NonNull LoadRangeParams params,
                  @NonNull LoadRangeCallback<Item> callback) {
              callback.onResult(loadRangeInternal(params.startPosition, params.loadSize));
          }
      }

Parameters
params	PositionalDataSource.LoadInitialParams: Params passed to loadInitial(LoadInitialParams, LoadInitialCallback), including page size, and requested start/loadSize.
initialLoadPosition	PositionalDataSource.LoadInitialParams: Value returned by computeInitialLoadPosition(LoadInitialParams, int)
totalCount	PositionalDataSource.LoadInitialParams: Total size of the data set.

Return
Int: Number of items to load.

See Also

• #computeInitialLoadPosition(LoadInitialParams, int)

loadInitial

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

Load initial list data.

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

Result 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.LoadInitialParams: Callback that receives initial load data, including position and total data set size.

loadRange

@WorkerThread abstract fun loadRange(@NonNull params: PositionalDataSource.LoadRangeParams, @NonNull 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(LoadInitialParams, LoadInitialCallback), 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.LoadRangeParams: Callback that receives loaded data.

map

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

mapByPage

@NonNull fun <V : Any!> mapByPage(@NonNull function: Function<MutableList<T>!, MutableList<V>!>): PositionalDataSource<V>