SnapshotLoader


@VisibleForTesting
public final class SnapshotLoader<Value extends Object>


Contains the public APIs for load operations in tests.

Tracks generational information and provides the listener to LoaderCallback on PagingDataPresenter operations.

Summary

Public methods

final void
appendScrollWhile(
    @NonNull Function1<@NonNull item, @NonNull Boolean> predicate
)

Imitates scrolling down paged items, appending data until the given predicate returns false.

final void
flingTo(int index)

Imitates flinging from current index to the target index.

final void
prependScrollWhile(
    @NonNull Function1<@NonNull item, @NonNull Boolean> predicate
)

Imitates scrolling up paged items, prepending data until the given predicate returns false.

final void

Refresh the data that is presented on the UI.

final void
scrollTo(int index)

Imitates scrolling from current index to the target index.

Public methods

appendScrollWhile

public final void appendScrollWhile(
    @NonNull Function1<@NonNull item, @NonNull Boolean> predicate
)

Imitates scrolling down paged items, appending data until the given predicate returns false.

Note: This API loads an item before passing it into the predicate. This means the loaded pages may include the page which contains the item that does not match the predicate. For example, if pageSize = 2, the predicate {item: Int -> item < 3 } will return items [1, 2,3, 4] where 3, 4 is the page containing the boundary item3 not matching the predicate.

The loaded pages are also dependent on PagingConfig settings such as PagingConfig.prefetchDistance:

  • if prefetchDistance 0, the resulting appends will include prefetched items. For example, if pageSize = 2 and prefetchDistance = 2, the predicate {item: Int -> item < 3 } will load items [1, 2, 3, 4, 5, 6] where 5, 6 is the prefetched page.

Parameters
@NonNull Function1<@NonNull item, @NonNull Boolean> predicate

the predicate to match (return true) to continue append scrolls

flingTo

public final void flingTo(int index)

Imitates flinging from current index to the target index. It will continue scrolling even as data is being loaded in. Returns all available data that has been scrolled through.

The scroll direction (prepend or append) is dependent on current index and target index. In general, scrolling to a smaller index triggers PREPEND while scrolling to a larger index triggers APPEND.

This function will scroll into placeholders. This means jumping is supported when PagingConfig.enablePlaceholders is true and the amount of placeholders traversed has reached PagingConfig.jumpThreshold. Jumping is disabled when PagingConfig.enablePlaceholders is false.

When PagingConfig.enablePlaceholders is false, the index is scoped within currently loaded items. For example, in a list of items(0-20) with currently loaded items(10-15), index0 = item(10), index4 = item(15).

Supports index beyond currently loaded items when PagingConfig.enablePlaceholders is false:

  1. For prepends, it supports negative indices for as long as there are still available data to load from. For example, take a list of items(0-20), pageSize = 1, with currently loaded items(10-15). With index0 = item(10), a scrollTo(-4) will scroll to item(6) and update index0 = item(6).

  2. For appends, it supports indices >= loadedDataSize. For example, take a list of items(0-20), pageSize = 1, with currently loaded items(10-15). With index4 = item(15), a scrollTo(7) will scroll to item(18) and update index7 = item(18). Note that both examples does not account for prefetches.

The index accounts for separators/headers/footers where each one of those consumes one scrolled index.

For both append/prepend, this function stops loading prior to fulfilling requested scroll distance if there are no more data to load from.

Parameters
int index

The target index to scroll to

See also
scrollTo

for faking scrolls that awaits for placeholders to load before continuing to scroll.

prependScrollWhile

public final void prependScrollWhile(
    @NonNull Function1<@NonNull item, @NonNull Boolean> predicate
)

Imitates scrolling up paged items, prepending data until the given predicate returns false.

Note: This API loads an item before passing it into the predicate. This means the loaded pages may include the page which contains the item that does not match the predicate. For example, if pageSize = 2, initialKey = 3, the predicate {item: Int -> item >= 3 } will return items [1, 2,3, 4] where 1, 2 is the page containing the boundary item2 not matching the predicate.

The loaded pages are also dependent on PagingConfig settings such as PagingConfig.prefetchDistance:

  • if prefetchDistance 0, the resulting prepends will include prefetched items. For example, if pageSize = 2, initialKey = 3, and prefetchDistance = 2, the predicate {item: Int -> item 4 } will load items [1, 2, 3, 4, 5, 6] where both 1,2 and 5, 6 are the prefetched pages.

Parameters
@NonNull Function1<@NonNull item, @NonNull Boolean> predicate

the predicate to match (return true) to continue prepend scrolls

refresh

public final void refresh()

Refresh the data that is presented on the UI.

refresh triggers a new generation of PagingData / PagingSource to represent an updated snapshot of the backing dataset.

This fake paging operation mimics UI-driven refresh signals such as swipe-to-refresh.

scrollTo

public final void scrollTo(int index)

Imitates scrolling from current index to the target index. It waits for an item to be loaded in before triggering load on next item. Returns all available data that has been scrolled through.

The scroll direction (prepend or append) is dependent on current index and target index. In general, scrolling to a smaller index triggers PREPEND while scrolling to a larger index triggers APPEND.

When PagingConfig.enablePlaceholders is false, the index is scoped within currently loaded items. For example, in a list of items(0-20) with currently loaded items(10-15), index0 = item(10), index4 = item(15).

Supports index beyond currently loaded items when PagingConfig.enablePlaceholders is false:

  1. For prepends, it supports negative indices for as long as there are still available data to load from. For example, take a list of items(0-20), pageSize = 1, with currently loaded items(10-15). With index0 = item(10), a scrollTo(-4) will scroll to item(6) and update index0 = item(6).

  2. For appends, it supports indices >= loadedDataSize. For example, take a list of items(0-20), pageSize = 1, with currently loaded items(10-15). With index4 = item(15), a scrollTo(7) will scroll to item(18) and update index7 = item(18). Note that both examples does not account for prefetches.

The index accounts for separators/headers/footers where each one of those consumes one scrolled index.

For both append/prepend, this function stops loading prior to fulfilling requested scroll distance if there are no more data to load from.

Parameters
int index

The target index to scroll to

See also
flingTo

for faking a scroll that continues scrolling without waiting for items to be loaded in. Supports jumping.