Paging

#Introduction

The paging library lets your app use both network bandwidth and system resources more efficiently.

When working with large datasets, loading all the data at once can lead to high memory consumption and slow performance. Instead, it’s more efficient to load and display data in smaller chunks as needed.

#Project

Create a new Kotlin project with Amper.

dependencies:
  - androidx.lifecycle:lifecycle-viewmodel-compose:2.8.5
  - androidx.paging:paging-compose:3.4.0-alpha04
  - org.jetbrains.kotlinx:kotlinx-coroutines-swing:1.10.2

#PagingSource

The first step is to define a PagingSource implementation to identify the data source. The PagingSource API class includes the load() method, which you override to indicate how to retrieve paged data from the corresponding data source.

PagingSource<Key, Value> has two type parameters: Key and Value. The key defines the identifier used to load the data, and the value is the type of the data itself.

The following example implements a PagingSource that loads pages of items by page number. The Key type is Int and the Value type is Item.

class ItemPagingSource : PagingSource<Int, Item>() {

    override suspend fun load(params: LoadParams<Int>): LoadResult<Int, Item> {

        val start = params.key ?: 0
        val range = start.until(start + params.loadSize)

        return LoadResult.Page(
            data = range.map { number -> Item(id = number, name = "Item $number") },
            prevKey = when (start) {
                0 -> null
                else -> max(0, range.first - params.loadSize)
            },
            nextKey = range.last + 1
        )
    }

    override fun getRefreshKey(state: PagingState<Int, Item>): Int? {

        return state.anchorPosition?.let { anchorPosition ->
            val anchorPage = state.closestPageToPosition(anchorPosition)
            anchorPage?.prevKey?.plus(1) ?: anchorPage?.nextKey?.minus(1)
        }
    }

}

The LoadParams object contains information about the load operation to be performed. This includes the key to be loaded and the number of items to be loaded.

The [LoadResult] object contains the result of the load operation. LoadResult is a sealed class that takes one of two forms, depending on whether the load() call succeeded:

• If the load is successful, return a LoadResult.Page object.
• If the load is not successful, return a LoadResult.Error object.

The PagingSource implementation must also implement a getRefreshKey() method that takes a PagingState object as a parameter.

It returns the key to pass into the load() method when the data is refreshed or invalidated after the initial load. The Paging Library calls this method automatically on subsequent refreshes of the data.

#Handle errors

Requests to load data can fail for a number of reasons, especially when loading over a network. Report errors encountered during loading by returning a LoadResult.Error object from the load() method.

For example, you can catch and report loading errors by adding the following to the load() method:

catch (e: IOException) {
  // IOException for network failures.
  return LoadResult.Error(e)
} catch (e: HttpException) {
  // HttpException for any non-2xx HTTP status codes.
  return LoadResult.Error(e)
}

PagingSource collects and delivers LoadResult.Error objects to the UI so that you can act on them. For more information on exposing the loading state in the UI, see Manage and present loading states.

#Pager

The Pager class provides methods that expose a reactive stream of PagingData objects from a PagingSource.

You must provide the instance with a PagingConfig configuration object and a function that tells Pager how to get an instance of your PagingSource implementation:

val pages: Flow<PagingData<Item>> = Pager(PagingConfig(pageSize = 20)) {
        ItemPagingSource()
}.flow