PagedList.Builder

public static final class PagedList.Builder
extends Object

java.lang.Object
   ↳ android.arch.paging.PagedList.Builder<Key, Value>

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

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

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

PagedList.Builder(DataSource<Key, Value> dataSource, int pageSize)

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

Public methods

PagedList<Value> build()

Creates a PagedList with the given parameters.

Builder<Key, Value> setBoundaryCallback(BoundaryCallback boundaryCallback)

The BoundaryCallback for out of data events.

Builder<Key, Value> setFetchExecutor(Executor fetchExecutor)

The executor used to fetch additional pages from the DataSource.

Builder<Key, Value> setInitialKey(Key initialKey)

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

Builder<Key, Value> setNotifyExecutor(Executor notifyExecutor)

The executor defining where page loading updates are dispatched.

Inherited methods

Public constructors

PagedList.Builder

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

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

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

PagedList.Builder

PagedList.Builder (DataSource<Key, Value> dataSource, 
                int pageSize)

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

Public methods

build

PagedList<Value> build ()

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

Returns
PagedList<Value> The newly constructed PagedList

setBoundaryCallback

Builder<Key, Value> setBoundaryCallback (BoundaryCallback boundaryCallback)

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: BoundaryCallback for listening to out-of-data events.
Returns
Builder<Key, Value> this

setFetchExecutor

Builder<Key, Value> setFetchExecutor (Executor fetchExecutor)

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.
Returns
Builder<Key, Value> this

setInitialKey

Builder<Key, Value> setInitialKey (Key initialKey)

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.
Returns
Builder<Key, Value> this

setNotifyExecutor

Builder<Key, Value> setNotifyExecutor (Executor notifyExecutor)

The executor defining where page loading updates are dispatched.

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