{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}
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 PagedList
s 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 |
<Value extends Object> |
Type of items held and loaded by the |
Public constructors |
|
---|---|
<Key extends Object, Value extends Object> Builder( Create a |
|
<Key extends Object, Value extends Object> Builder( Create a |
|
<Key extends Object, Value extends Object> Builder( Create a |
|
<Key extends Object, Value extends Object> Builder( Create a |
Public methods |
|
---|---|
final @NonNull PagedList<@NonNull Value> |
build() Creates a |
final @NonNull PagedList.Builder<@NonNull Key, @NonNull Value> |
setBoundaryCallback( The |
final @NonNull PagedList.Builder<@NonNull Key, @NonNull Value> |
setCoroutineScope(@NonNull CoroutineScope coroutineScope) Set the |
final @NonNull PagedList.Builder<@NonNull Key, @NonNull Value> |
setFetchDispatcher(@NonNull CoroutineDispatcher fetchDispatcher) The |
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(@Nullable Key initialKey) Sets the initial key the |
final @NonNull PagedList.Builder<@NonNull Key, @NonNull Value> |
setNotifyDispatcher(@NonNull CoroutineDispatcher notifyDispatcher) The |
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 |
@NonNull
public final <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 |
|
@NonNull PagedList.Config config |
|
@NonNull
public final <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 |
|
int pageSize |
Size of loaded pages when the |
@NonNull
public final <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 |
|
@NonNull PagingSource.LoadResult.Page<@NonNull Key, @NonNull Value> initialPage |
Initial page loaded from the |
@NonNull PagedList.Config config |
|
@NonNull
public final <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 |
|
@NonNull PagingSource.LoadResult.Page<@NonNull Key, @NonNull Value> initialPage |
Initial page loaded from the |
int pageSize |
Size of loaded pages when the |
@NonNull
public final 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
).
Throws | |
---|---|
kotlin.IllegalArgumentException |
if |
@NonNull
public final PagedList.Builder<@NonNull Key, @NonNull Value> setBoundaryCallback(
@Nullable 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 | |
---|---|
@Nullable PagedList.BoundaryCallback<@NonNull Value> boundaryCallback |
|
Returns | |
---|---|
PagedList.Builder<@NonNull Key, @NonNull Value> |
this |
@NonNull
public final 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 | |
---|---|
PagedList.Builder<@NonNull Key, @NonNull Value> |
this |
@NonNull
public final 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 |
|
Returns | |
---|---|
PagedList.Builder<@NonNull Key, @NonNull Value> |
this |
@NonNull
public final 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 |
|
Returns | |
---|---|
PagedList.Builder<@NonNull Key, @NonNull Value> |
this |
@NonNull
public final PagedList.Builder<@NonNull Key, @NonNull Value> setInitialKey(@Nullable Key initialKey)
Sets the initial key the PagingSource
should load around as part of initialization.
Parameters | |
---|---|
@Nullable Key initialKey |
Key the |
Returns | |
---|---|
PagedList.Builder<@NonNull Key, @NonNull Value> |
this |
@NonNull
public final PagedList.Builder<@NonNull Key, @NonNull Value> setNotifyDispatcher(@NonNull CoroutineDispatcher notifyDispatcher)
The CoroutineDispatcher
defining where page loading updates are dispatched.
Parameters | |
---|---|
@NonNull CoroutineDispatcher notifyDispatcher |
|
Returns | |
---|---|
PagedList.Builder<@NonNull Key, @NonNull Value> |
this |
@NonNull
public final PagedList.Builder<@NonNull Key, @NonNull Value>setNotifyExecutor(@NonNull Executor notifyExecutor)
The Executor
defining where page loading updates are dispatched.
Parameters | |
---|---|
@NonNull Executor notifyExecutor |
|
Returns | |
---|---|
PagedList.Builder<@NonNull Key, @NonNull Value> |
this |