PagedList.Builder

Added in 2.0.0
Deprecated in 3.0.0

public final class PagedList.Builder<Key extends Object, Value extends Object>


Builder class for PagedList.

pagingSource, config, notifyDispatcher and fetchDispatcher must all be provided.

A PagedList queries initial data from its PagingSource during construction, to avoid empty PagedLists being presented to the UI when possible. It's preferred to present initial data, so that the UI doesn't show an empty list, or placeholders for a few frames, just before showing initial content.

LivePagedListBuilder does this creation on a background thread automatically, if you want to receive a LiveData<PagedList<...>>.

Parameters
<Key extends Object>

Type of key used to load data from the PagingSource.

<Value extends Object>

Type of items held and loaded by the PagedList.

Summary

Public constructors

<Key extends Object, Value extends Object> Builder(
    @NonNull DataSource<@NonNull Key, @NonNull Value> dataSource,
    @NonNull PagedList.Config config
)

Create a Builder with the provided DataSource and Config.

<Key extends Object, Value extends Object> Builder(
    @NonNull DataSource<@NonNull Key, @NonNull Value> dataSource,
    int pageSize
)

Create a PagedList.Builder with the provided DataSource and pageSize.

<Key extends Object, Value extends Object> Builder(
    @NonNull PagingSource<@NonNull Key, @NonNull Value> pagingSource,
    @NonNull PagingSource.LoadResult.Page<@NonNull Key, @NonNull Value> initialPage,
    @NonNull PagedList.Config config
)

Create a PagedList.Builder with the provided PagingSource, initial PagingSource.LoadResult.Page, and PagedList.Config.

<Key extends Object, Value extends Object> Builder(
    @NonNull PagingSource<@NonNull Key, @NonNull Value> pagingSource,
    @NonNull PagingSource.LoadResult.Page<@NonNull Key, @NonNull Value> initialPage,
    int pageSize
)

Create a PagedList.Builder with the provided PagingSource, initial PagingSource.LoadResult.Page, and pageSize.

Public methods

final @NonNull PagedList<@NonNull Value>

Creates a PagedList with the given parameters.

final @NonNull PagedList.Builder<@NonNull Key, @NonNull Value>
setBoundaryCallback(
    PagedList.BoundaryCallback<@NonNull Value> boundaryCallback
)

The BoundaryCallback for out of data events.

final @NonNull PagedList.Builder<@NonNull Key, @NonNull Value>

Set the CoroutineScope that page loads should be launched within.

final @NonNull PagedList.Builder<@NonNull Key, @NonNull Value>

The CoroutineDispatcher used to fetch additional pages from the PagingSource.

final @NonNull PagedList.Builder<@NonNull Key, @NonNull Value>

This method is deprecated. Passing an executor will cause it get wrapped as a CoroutineDispatcher, consider passing a CoroutineDispatcher directly

final @NonNull PagedList.Builder<@NonNull Key, @NonNull Value>
setInitialKey(Key initialKey)

Sets the initial key the PagingSource should load around as part of initialization.

final @NonNull PagedList.Builder<@NonNull Key, @NonNull Value>

The CoroutineDispatcher defining where page loading updates are dispatched.

final @NonNull PagedList.Builder<@NonNull Key, @NonNull Value>

This method is deprecated. Passing an executor will cause it get wrapped as a CoroutineDispatcher, consider passing a CoroutineDispatcher directly

Public constructors

Builder

public <Key extends Object, Value extends Object> Builder(
    @NonNull DataSource<@NonNull Key, @NonNull Value> dataSource,
    @NonNull PagedList.Config config
)

Create a Builder with the provided DataSource and Config.

Parameters
@NonNull DataSource<@NonNull Key, @NonNull Value> dataSource

DataSource the PagedList will load from.

@NonNull PagedList.Config config

PagedList.Config that defines how the PagedList loads data from its DataSource.

Builder

public <Key extends Object, Value extends Object> Builder(
    @NonNull DataSource<@NonNull Key, @NonNull Value> dataSource,
    int pageSize
)

Create a PagedList.Builder with the provided DataSource and pageSize.

This method is a convenience for:

PagedList.Builder(dataSource,
new PagedList.Config.Builder().setPageSize(pageSize).build());
Parameters
@NonNull DataSource<@NonNull Key, @NonNull Value> dataSource

DataSource the PagedList will load from.

int pageSize

Size of loaded pages when the PagedList loads data from its DataSource.

Builder

public <Key extends Object, Value extends Object> Builder(
    @NonNull PagingSource<@NonNull Key, @NonNull Value> pagingSource,
    @NonNull PagingSource.LoadResult.Page<@NonNull Key, @NonNull Value> initialPage,
    @NonNull PagedList.Config config
)

Create a PagedList.Builder with the provided PagingSource, initial PagingSource.LoadResult.Page, and PagedList.Config.

Parameters
@NonNull PagingSource<@NonNull Key, @NonNull Value> pagingSource

PagingSource the PagedList will load from.

@NonNull PagingSource.LoadResult.Page<@NonNull Key, @NonNull Value> initialPage

Initial page loaded from the PagingSource.

@NonNull PagedList.Config config

PagedList.Config that defines how the PagedList loads data from its PagingSource.

Builder

public <Key extends Object, Value extends Object> Builder(
    @NonNull PagingSource<@NonNull Key, @NonNull Value> pagingSource,
    @NonNull PagingSource.LoadResult.Page<@NonNull Key, @NonNull Value> initialPage,
    int pageSize
)

Create a PagedList.Builder with the provided PagingSource, initial PagingSource.LoadResult.Page, and pageSize.

This method is a convenience for:

PagedList.Builder(
pagingSource,
page,
PagedList.Config.Builder().setPageSize(pageSize).build()
)
Parameters
@NonNull PagingSource<@NonNull Key, @NonNull Value> pagingSource

PagingSource the PagedList will load from.

@NonNull PagingSource.LoadResult.Page<@NonNull Key, @NonNull Value> initialPage

Initial page loaded from the PagingSource.

int pageSize

Size of loaded pages when the PagedList loads data from its PagingSource.

Public methods

build

Added in 2.0.0
Deprecated in 3.0.0
public final @NonNull PagedList<@NonNull Value> build()

Creates a PagedList with the given parameters.

This call will dispatch the androidx.paging.PagingSource's loadInitial method immediately on the current thread, and block the current on the result. This method should always be called on a worker thread to prevent blocking the main thread.

It's fine to create a PagedList with an async PagingSource on the main thread, such as in the constructor of a ViewModel. An async network load won't block the initial call to the Load function. For a synchronous PagingSource such as one created from a Room database, a LiveData<PagedList> can be safely constructed with androidx.paging.LivePagedListBuilder on the main thread, since actual construction work is deferred, and done on a background thread.

While build will always return a PagedList, it's important to note that the PagedList initial load may fail to acquire data from the PagingSource. This can happen for example if the PagingSource is invalidated during its initial load. If this happens, the PagedList will be immediately detached, and you can retry construction (including setting a new PagingSource).

Returns
@NonNull PagedList<@NonNull Value>

The newly constructed PagedList

setBoundaryCallback

Added in 3.0.0
Deprecated in 3.0.0
public final @NonNull PagedList.Builder<@NonNull Key, @NonNull Value> setBoundaryCallback(
    PagedList.BoundaryCallback<@NonNull Value> boundaryCallback
)

The BoundaryCallback for out of data events.

Pass a BoundaryCallback to listen to when the PagedList runs out of data to load.

Parameters
PagedList.BoundaryCallback<@NonNull Value> boundaryCallback

BoundaryCallback for listening to out-of-data events.

Returns
@NonNull PagedList.Builder<@NonNull Key, @NonNull Value>

this

setCoroutineScope

Added in 3.0.0
Deprecated in 3.0.0
public final @NonNull PagedList.Builder<@NonNull Key, @NonNull Value> setCoroutineScope(@NonNull CoroutineScope coroutineScope)

Set the CoroutineScope that page loads should be launched within.

The set coroutineScope allows a PagingSource to cancel running load operations when the results are no longer needed - for example, when the containing Activity is destroyed.

Defaults to GlobalScope.

Parameters
@NonNull CoroutineScope coroutineScope
Returns
@NonNull PagedList.Builder<@NonNull Key, @NonNull Value>

this

setFetchDispatcher

Added in 3.0.0
Deprecated in 3.0.0
public final @NonNull PagedList.Builder<@NonNull Key, @NonNull Value> setFetchDispatcher(@NonNull CoroutineDispatcher fetchDispatcher)

The CoroutineDispatcher used to fetch additional pages from the PagingSource.

Does not affect initial load, which will be done immediately on whichever thread the PagedList is created on.

Parameters
@NonNull CoroutineDispatcher fetchDispatcher

CoroutineDispatcher used to fetch from PagingSources, generally a background thread pool for e.g. I/O or network loading.

Returns
@NonNull PagedList.Builder<@NonNull Key, @NonNull Value>

this

setFetchExecutor

Added in 2.0.0
Deprecated in 3.0.0
public final @NonNull PagedList.Builder<@NonNull Key, @NonNull Value> setFetchExecutor(@NonNull Executor fetchExecutor)

The Executor used to fetch additional pages from the PagingSource.

Does not affect initial load, which will be done immediately on whichever thread the PagedList is created on.

Parameters
@NonNull Executor fetchExecutor

Executor used to fetch from PagingSources, generally a background thread pool for e.g. I/O or network loading.

Returns
@NonNull PagedList.Builder<@NonNull Key, @NonNull Value>

this

setInitialKey

Added in 2.0.0
Deprecated in 3.0.0
public final @NonNull PagedList.Builder<@NonNull Key, @NonNull Value> setInitialKey(Key initialKey)

Sets the initial key the PagingSource should load around as part of initialization.

Parameters
Key initialKey

Key the PagingSource should load around as part of initialization.

Returns
@NonNull PagedList.Builder<@NonNull Key, @NonNull Value>

this

setNotifyDispatcher

Added in 3.0.0
Deprecated in 3.0.0
public final @NonNull PagedList.Builder<@NonNull Key, @NonNull Value> setNotifyDispatcher(@NonNull CoroutineDispatcher notifyDispatcher)

The CoroutineDispatcher defining where page loading updates are dispatched.

Parameters
@NonNull CoroutineDispatcher notifyDispatcher

CoroutineDispatcher that receives PagedList updates, and where PagedList.Callback calls are dispatched. Generally, this is the ui/main thread.

Returns
@NonNull PagedList.Builder<@NonNull Key, @NonNull Value>

this

setNotifyExecutor

Added in 2.0.0
Deprecated in 3.0.0
public final @NonNull PagedList.Builder<@NonNull Key, @NonNull Value> setNotifyExecutor(@NonNull Executor notifyExecutor)

The Executor defining where page loading updates are dispatched.

Parameters
@NonNull Executor notifyExecutor

Executor that receives PagedList updates, and where PagedList.Callback calls are dispatched. Generally, this is the ui/main thread.

Returns
@NonNull PagedList.Builder<@NonNull Key, @NonNull Value>

this