Register now for Android Dev Summit 2019!

Builder

class Builder<Key : Any!, Value : Any!>
kotlin.Any
   ↳ androidx.paging.PagedList.Builder

Builder class for PagedList.

DataSource, Config, main thread and background executor must all be provided.

A PagedList queries initial data from its DataSource 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<...>>.

Summary

Public constructors

<init>(@NonNull dataSource: DataSource<Key, Value>, @NonNull config: PagedList.Config)

Create a PagedList.

<init>(@NonNull dataSource: DataSource<Key, Value>, pageSize: Int)

Create a PagedList.

Public methods

PagedList<Value>

Creates a PagedList with the given parameters.

PagedList.Builder<Key, Value>
setBoundaryCallback(@Nullable boundaryCallback: PagedList.BoundaryCallback<Any!>?)

The BoundaryCallback for out of data events.

PagedList.Builder<Key, Value>
setFetchExecutor(@NonNull fetchExecutor: Executor)

The executor used to fetch additional pages from the DataSource.

PagedList.Builder<Key, Value>
setInitialKey(@Nullable initialKey: Key?)

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

PagedList.Builder<Key, Value>
setNotifyExecutor(@NonNull notifyExecutor: Executor)

The executor defining where page loading updates are dispatched.

Public constructors

<init>

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

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

Parameters
dataSource DataSource<Key, Value>: DataSource the PagedList will load from.
config DataSource<Key, Value>: Config that defines how the PagedList loads data from its DataSource.

<init>

Builder(@NonNull dataSource: DataSource<Key, Value>, pageSize: Int)

Create a PagedList.Builder with the provided DataSource and page size.

This method is a convenience for:

PagedList.Builder(dataSource,
                  new PagedList.Config.Builder().setPageSize(pageSize).build());
          
Parameters
dataSource DataSource<Key, Value>: DataSource the PagedList will load from.
pageSize DataSource<Key, Value>: Config that defines how the PagedList loads data from its DataSource.

Public methods

build

@WorkerThread @NonNull fun build(): PagedList<Value>

Creates a PagedList with the given parameters.

This call will dispatch the DataSource's loadInitial method immediately. If a DataSource posts all of its work (e.g. to a network thread), the PagedList will be immediately created as empty, and grow to its initial size when the initial load completes.

If the DataSource implements its load synchronously, doing the load work immediately in the loadInitial method, the PagedList will block on that load before completing construction. In this case, use a background thread to create a PagedList.

It's fine to create a PagedList with an async DataSource on the main thread, such as in the constructor of a ViewModel. An async network load won't block the initialLoad function. For a synchronous DataSource such as one created from a Room database, a LiveData<PagedList> can be safely constructed with 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 DataSource. This can happen for example if the DataSource is invalidated during its initial load. If this happens, the PagedList will be immediately detached, and you can retry construction (including setting a new DataSource).

Return
PagedList<Value>: The newly constructed PagedList

setBoundaryCallback

@NonNull fun setBoundaryCallback(@Nullable boundaryCallback: PagedList.BoundaryCallback<Any!>?): PagedList.Builder<Key, Value>

The BoundaryCallback for out of data events.

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

Parameters
boundaryCallback PagedList.BoundaryCallback<Any!>?: BoundaryCallback for listening to out-of-data events.
Return
PagedList.Builder<Key, Value>: this

setFetchExecutor

@NonNull fun setFetchExecutor(@NonNull fetchExecutor: Executor): PagedList.Builder<Key, Value>

The executor used to fetch additional pages from the DataSource. Does not affect initial load, which will be done immediately on whichever thread the PagedList is created on.

Parameters
fetchExecutor Executor: Executor used to fetch from DataSources, generally a background thread pool for e.g. I/O or network loading.
Return
PagedList.Builder<Key, Value>: this

setInitialKey

@NonNull fun setInitialKey(@Nullable initialKey: Key?): PagedList.Builder<Key, Value>

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

Parameters
initialKey Key?: Key the DataSource should load around as part of initialization.
Return
PagedList.Builder<Key, Value>: this

setNotifyExecutor

@NonNull fun setNotifyExecutor(@NonNull notifyExecutor: Executor): PagedList.Builder<Key, Value>

The executor defining where page loading updates are dispatched.

Parameters
notifyExecutor Executor: Executor that receives PagedList updates, and where Callback calls are dispatched. Generally, this is the ui/main thread.
Return
PagedList.Builder<Key, Value>: this