Skip to content

Most visited

Recently visited

navigation

PositionalDataSource

public abstract class PositionalDataSource
extends DataSource<Integer, T>

java.lang.Object
   ↳ android.arch.paging.DataSource<java.lang.Integer, T>
     ↳ android.arch.paging.PositionalDataSource<T>


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

class PositionalDataSource.LoadInitialCallback<T>

Callback for loadInitial(LoadInitialParams, LoadInitialCallback) to return data, position, and count. 

class PositionalDataSource.LoadInitialParams

Holder object for inputs to loadInitial(LoadInitialParams, LoadInitialCallback)

class PositionalDataSource.LoadRangeCallback<T>

Callback for PositionalDataSource loadRange(LoadRangeParams, LoadRangeCallback) to return data. 

class PositionalDataSource.LoadRangeParams

Holder object for inputs to loadRange(LoadRangeParams, LoadRangeCallback)

Public constructors

PositionalDataSource()

Public methods

static int computeInitialLoadPosition(PositionalDataSource.LoadInitialParams params, int totalCount)

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

static int computeInitialLoadSize(PositionalDataSource.LoadInitialParams params, int initialLoadPosition, int totalCount)

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

abstract void loadInitial(PositionalDataSource.LoadInitialParams params, LoadInitialCallback<T> callback)

Load initial list data.

abstract void loadRange(PositionalDataSource.LoadRangeParams params, LoadRangeCallback<T> callback)

Called to load a range of data from the DataSource.

Inherited methods

From class android.arch.paging.DataSource
From class java.lang.Object

Public constructors

PositionalDataSource

PositionalDataSource ()

Public methods

computeInitialLoadPosition

int computeInitialLoadPosition (PositionalDataSource.LoadInitialParams params, 
                int totalCount)

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 int: Total size of the data set.

Returns
int Position to start loading at.

computeInitialLoadSize

int computeInitialLoadSize (PositionalDataSource.LoadInitialParams params, 
                int initialLoadPosition, 
                int totalCount)

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 int: Value returned by computeInitialLoadPosition(LoadInitialParams, int)

totalCount int: Total size of the data set.

Returns
int Number of items to load.

loadInitial

void loadInitial (PositionalDataSource.LoadInitialParams params, 
                LoadInitialCallback<T> callback)

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

loadRange

void loadRange (PositionalDataSource.LoadRangeParams params, 
                LoadRangeCallback<T> callback)

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 LoadRangeCallback: Callback that receives loaded data.

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience. (Dec 2017 Android Platform & Tools Survey)