Android’s Paging Library — Stripped

A simple paging solution.

by Jeroen, altered black & white, licensed under the Creative Commons Attribution 2.0 Generic license

Prolog

A long time ago, in ancient Egypt, people started writing words onto papyrus. Text was written on large papyrus rolls, also referred to as scroll. Papyrus was “joined together side by side and rolled up into a scroll, an early form of a book” (Wikipedia, Papyrus)

A scroll “is usually divided up into pages” or “unrolled so that one page is exposed at a time”. Later, “the Romans invented the codex form of the book, folding the scroll into pages which made reading and handling the document much easier” (Wikipedia, Scroll).

Nowadays, our apps contain ScrollViews, which go actually a bit back to what was done in ancient Egypt. The reason for that is that we solved the problem of readability of a scroll differently: The simple gesture of scrolling lets us now easily advance while reading.

The RecyclerView already does a great job in optimizing view rendering. But still, loading the whole “scroll” into an adapter is not recommended if it’s a big data set.

The paging library from Jetpack’s architecture components is a good utility for optimizing the data / adapter load. It takes care of cutting the big data set into pieces. It enables an application to load data subsequently into an adapter — it again folds / cuts the whole scroll.

This article will use the Paging Library without the rest of its architecture siblings like LiveData or Room . Let’s keep it simple for now.

This example assumes

• you get a complete list of Items from some sort of data source — your scroll so to say,
• you get it as a Deferred object — from a Kotlin coroutine’s suspend function,
• you are working with a PagedListAdapter or can easily migrate from a ListAdapter.

If you need to migrate from a RecyclerView.Adapter first follow these instructions.

Now — let the story unroll.

Getting started

To use the Paging Library you have to include the dependency into your project at first.

Then simply follow this checklist to get things started:

• Change your ListAdapter to PagedListAdapter — its submitList method accepts a PagedList instead of a List
• Create a DataSourceFactory
• Create a DataSource

When creating the DataSource class you can choose between 3 different implementations:

• PageKeyedDataSource
• ItemKeyedDataSource
• PositionalDataSource

Check out the official documentation to find the best source type for yourself. This example uses the ItemKeyedDataSource which creates pages before or after the currently displayed items.

Implementation

Check out the following piece of code on how to implement ItemKeyedDataSource:

Let’s assume a given Item class

To get the DataSource a DataSourceFactory is needed — a class which inherits from DataSource.Factory<Int, Item>().

You can ignore the companion object for now. It’s used to provide a paging configuration to the PagedListAdapter . You’ll need it in the very end.

ItemSourceFactory contains an abstract create() method, which has to be overridden and returns an ItemDataSource . This is where all the logic happens. So let’s have a look at this class

We fetch the items asynchronously, store it in a variable for using it from the other functions and inform the ui about the first available sublist by using the provided callback — initial key defaults to 0 if nothing else is specified. The scroll starts at the beginning.

The DataSource can only work with the items if it knows what to take as current index. So getKey has to be overridden.

As DataSource needs to know how to proceed when the user starts scrolling down and what happens when she / he scrolls up again, you have to implement loadAfter and loadBefore .

loadAfter — loading items from (current item index + 1) until (current item index + 1 + requestedLoadSize)

The goal here is to load items after the current item, so loadAfter needs to use the next available index which is the current item index + 1. The requestedLoadSize is something that is defined in the PagingConfig — see above.

loadBefore — loading items from (current item index - 1) until (current item index - 1 - requestedLoadSize)

The goal here is to load items before the current one — so it’s simply the other way round. Nothing fancy so far.

In both functions loadAfter and loadBefore the result is passed to the callback parameter again.

Now, the logic we use in both functions: getSubList

The only thing you have to pay attention to is that the indices are within the list bounds when scrolling up to 0 and down to the list end. This happens inside the inRange method. As the getSubList method is used for before and after there is a when clause corresponding to the before parameter. I guess, it’s clear what going on there.

That’s it - you actually now use this whole construct in your Fragment :

The config parameter is what I told you to ignore in the beginning — the construction of the PagedList.Config object inside the ItemSourceFactory .

Check out more about the config builder here .

Et voilà, with these “few” lines of (Boilerplate) code you have a working paging solution based on the officially recommended way to do paging. So now go out and scroll the hell out of your adapters… and throw away the deprecated papyrus scroll, cut it into pages and read more efficiently.

For more information on the Paging library the official documentation is a good place to continue from here.

Thanks for your interest. And happy paging.

If you learned something, please don’t forget to hit the applause button.