Overview

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

Summary

Constructors

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

Parameters:

dataSource: DataSource the PagedList will load from.
config: Config that defines how the PagedList loads data from its DataSource.

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 the PagedList will load from.
pageSize: Config that defines how the PagedList loads data from its DataSource.

Methods

The executor defining where page loading updates are dispatched.

Parameters:

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

Returns:

this

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 used to fetch from DataSources, generally a background thread pool for e.g. I/O or network loading.

Returns:

this

The BoundaryCallback for out of data events.

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

Parameters:

boundaryCallback: BoundaryCallback for listening to out-of-data events.

Returns:

this

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

Parameters:

initialKey: Key the DataSource should load around as part of initialization.

Returns:

this

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

Returns:

The newly constructed PagedList