AsyncPagingDataDiffer

Kotlin |Java

class AsyncPagingDataDiffer<T : Any>

kotlin.Any
↳	androidx.paging.AsyncPagingDataDiffer

Helper class for mapping a PagingData into a RecyclerView.Adapter.

For simplicity, PagingDataAdapter can often be used in place of this class. AsyncPagingDataDiffer is exposed for complex cases, and where overriding PagingDataAdapter to support paging isn't convenient.

Summary

Public constructors
<init>(diffCallback: DiffUtil.ItemCallback<T>, updateCallback: ListUpdateCallback, mainDispatcher: CoroutineDispatcher = Dispatchers.Main, workerDispatcher: CoroutineDispatcher = Dispatchers.Default) Helper class for mapping a PagingData into a RecyclerView.Adapter.

Public methods
Unit	addLoadStateListener(listener: (CombinedLoadStates) -> Unit) Add a CombinedLoadStates listener to observe the loading state of the current PagingData.
T?	getItem(@IntRange(0) index: Int) Get the item from the current PagedList at the specified index.
T?	peek(@IntRange(0) index: Int) Returns the presented item at the specified position, without notifying Paging of the item access that would normally trigger page loads.
Unit	refresh() Refresh the data presented by this AsyncPagingDataDiffer.
Unit	removeLoadStateListener(listener: (CombinedLoadStates) -> Unit) Remove a previously registered CombinedLoadStates listener.
Unit	retry() Retry any failed load requests that would result in a LoadState.Error update to this AsyncPagingDataDiffer.
ItemSnapshotList<T>	snapshot() Returns a new ItemSnapshotList representing the currently presented items, including any placeholders if they are enabled.
suspend Unit	submitData(pagingData: PagingData<T>) Present a PagingData until it is invalidated by a call to refresh or PagingSource.invalidate.
Unit	submitData(lifecycle: Lifecycle, pagingData: PagingData<T>) Present a PagingData until it is either invalidated or another call to submitData is made.

Properties
Int	itemCount Get the number of items currently presented by this Differ.
Flow<CombinedLoadStates>	loadStateFlow A hot Flow of CombinedLoadStates that emits a snapshot whenever the loading state of the current PagingData changes.

Public constructors

<init>

AsyncPagingDataDiffer(
    diffCallback: DiffUtil.ItemCallback<T>, 
    updateCallback: ListUpdateCallback, 
    mainDispatcher: CoroutineDispatcher = Dispatchers.Main, 
    workerDispatcher: CoroutineDispatcher = Dispatchers.Default)

Helper class for mapping a PagingData into a RecyclerView.Adapter.

For simplicity, PagingDataAdapter can often be used in place of this class. AsyncPagingDataDiffer is exposed for complex cases, and where overriding PagingDataAdapter to support paging isn't convenient.

Public methods

addLoadStateListener

fun addLoadStateListener(listener: (CombinedLoadStates) -> Unit): Unit

Add a CombinedLoadStates listener to observe the loading state of the current PagingData.

As new PagingData generations are submitted and displayed, the listener will be notified to reflect the current CombinedLoadStates.

val adapter = UserPagingAdapter()
adapter.addLoadStateListener {
    // show a retry button outside the list when refresh hits an error
    retryButton.isVisible = it.refresh is LoadState.Error

    // swipeRefreshLayout displays whether refresh is occurring
    swipeRefreshLayout.isRefreshing = it.refresh is LoadState.Loading

    // show an empty state over the list when loading initially, before items are loaded
    emptyState.isVisible = it.refresh is LoadState.Loading && adapter.itemCount == 0
}

Parameters
listener: (CombinedLoadStates) -> Unit	LoadStates listener to receive updates.

See Also

• removeLoadStateListener

getItem

fun getItem(@IntRange(0) index: Int): T?

Get the item from the current PagedList at the specified index.

Note that this operates on both loaded items and null padding within the PagedList.

Parameters
index: Int	Index of item to get, must be >= 0, and < itemCount

Return
The item,	or null, if a null placeholder is at the specified position.

peek

fun peek(@IntRange(0) index: Int): T?

Returns the presented item at the specified position, without notifying Paging of the item access that would normally trigger page loads.

Parameters
index: Int	Index of the presented item to return, including placeholders.

Return
The presented item at position	index, null if it is a placeholder

refresh

fun refresh(): Unit

Refresh the data presented by this AsyncPagingDataDiffer.

refresh triggers the creation of a new PagingData with a new instance of PagingSource to represent an updated snapshot of the backing dataset. If a RemoteMediator is set, calling refresh will also trigger a call to RemoteMediator.load with LoadType to allow RemoteMediator to check for updates to the dataset backing PagingSource.

Note: This API is intended for UI-driven refresh signals, such as swipe-to-refresh. Invalidation due repository-layer signals, such as DB-updates, should instead use PagingSource.invalidate.

class MyActivity : AppCompatActivity() {
    private lateinit var binding: MyActivityBinding
    private val pagingAdapter = UserPagingAdapter()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        binding = MyActivityBinding.inflate(layoutInflater)
        setContentView(binding.root)

        binding.recyclerView.adapter = pagingAdapter
        pagingAdapter.addLoadStateListener { loadStates ->
            binding.swipeRefreshLayout.isRefreshing = loadStates.refresh is LoadState.Loading
        }

        binding.swipeRefreshLayout.setOnRefreshListener {
            pagingAdapter.refresh()
        }
    }
}

See Also

• PagingSource.invalidate

removeLoadStateListener

fun removeLoadStateListener(listener: (CombinedLoadStates) -> Unit): Unit

Remove a previously registered CombinedLoadStates listener.

Parameters
listener: (CombinedLoadStates) -> Unit	Previously registered listener.

See Also

• addLoadStateListener

retry

fun retry(): Unit

Retry any failed load requests that would result in a LoadState.Error update to this AsyncPagingDataDiffer.

Unlike refresh, this does not invalidate PagingSource, it only retries failed loads within the same generation of PagingData.

LoadState.Error can be generated from two types of load requests:

• PagingSource.load returning PagingSource.LoadResult.Error
• RemoteMediator.load returning RemoteMediator.MediatorResult.Error

snapshot

fun snapshot(): ItemSnapshotList<T>

Returns a new ItemSnapshotList representing the currently presented items, including any placeholders if they are enabled.

submitData

suspend fun submitData(pagingData: PagingData<T>): Unit

Present a PagingData until it is invalidated by a call to refresh or PagingSource.invalidate.

submitData should be called on the same CoroutineDispatcher where updates will be dispatched to UI, typically Dispatchers.Main. (this is done for you if you use lifecycleScope.launch {}).

This method is typically used when collecting from a Flow produced by Pager. For RxJava or LiveData support, use the non-suspending overload of submitData, which accepts a Lifecycle.

Note: This method suspends while it is actively presenting page loads from a PagingData, until the PagingData is invalidated. Although cancellation will propagate to this call automatically, collecting from a Pager.flow with the intention of presenting the most up-to-date representation of your backing dataset should typically be done using collectLatest.

See Also

• Pager

submitData

fun submitData(
    lifecycle: Lifecycle, 
    pagingData: PagingData<T>
): Unit

Present a PagingData until it is either invalidated or another call to submitData is made.

This method is typically used when observing a RxJava or LiveData stream produced by Pager. For Flow support, use the suspending overload of submitData, which automates cancellation via CoroutineScope instead of relying of Lifecycle.

See Also

• submitData
• Pager

Properties