xmartlabs/fountain

A smart and simple way to work with paged endpoints. To see an example of how to use it, check out the introducing Fountain posts: part one and part two.

Atention: since all of Fountain functionalities are present in android official Paging3 library, Fountain is deprecated and we recommend using that tool.

Overview

Fountain is an Android Kotlin library conceived to make your life easier when dealing with paged endpoint services, where the paging is based on incremental page numbers (e.g. 1, 2, 3, ...). It uses the Google Android Architecture Components, mainly the Android Paging Library to make it easier to work with paged services.

The main goal of the library is to easily provide a Listing component from a common service specification. Listing provides essentially five elements to take control of the paged list:

data class Listing<T>(
    val pagedList: LiveData<PagedList<T>>,
    val networkState: LiveData<NetworkState>,
    val refreshState: LiveData<NetworkState>,
    val refresh: () -> Unit,
    val retry: () -> Unit
)

1. pagedList: A changing data stream of type T represented as a LiveData of a PagedList.
2. networkState: A stream that notifies network state changes, such as when a new page started loading (so you can show a spinner in the UI).
3. refresh: A refresh function, to refresh all data.
4. refreshState: A stream that notifies the status of the refresh request.
5. retry: A retry function to execute if something failed.

Basically, you could manage all data streams with a Listing component, which is awesome! It's really flexible and useful to display the paged list entities and reflect the network status changes in the UI.

This library was designed to work with paged endpoints. However, it also supports working with not paged endpoints. That means that you can use all Listing features in services that return a list that's not paged.

Fountain provides two ways to generate a Listing component from paged services:

1. Network support: Provides a Listing based on a common Retrofit service implementation. Note entities won't be saved in memory nor disk.
2. Cache + Network support: Provides a Listing with cache support using a common Retrofit service implementation, and a DataSource for caching the data. We recommend you use Room to provide the DataSource, because it will be easier. However, you could use any other DataSource.

Fountain supports 2 types of Retrofit service adapters:

• A RxJava2 Retrofit adapter.
• A Coroutine Retrofit adapter.

It also supports not using any of them, as you could work with a simple Retrofit call.

Download

Add library to project dependencies with JitPack.

repositories {
    maven { url "https://jitpack.io" }
}

dependencies {
    // This dependency is required only if you want to use a Retrofit service without a special adapter. 
    implementation 'com.github.xmartlabs.fountain:fountain-retrofit:0.5.0'

    // This dependency is required only if you want to use a Coroutine retrofit adapter.
    implementation 'com.github.xmartlabs.fountain:fountain-coroutines:0.5.0'

    // This dependency is required only if you want to use a RxJava2 retrofit adapter.
    implementation 'com.github.xmartlabs.fountain:fountain-rx2:0.5.0'
}

Fountain is using Kotlin 1.3, if you are using Kotlin 1.2.X, please use Fountain 0.4.0.

Despite Fountain is in experimental state, we believe the API won't receive major changes.

Usage

You can read the full documentation.

Factory constructors

There's one static factory object class for each each dependency.

• FountainCoroutines: Used to get a Listing from a Retrofit service which uses a Coroutine adapter.
• FountainRetrofit: Used to get a Listing from a Retrofit service without using a special adapter.
• FountainRx: Used to get a Listing from a Retrofit service which uses a RxJava2 adapter.

Each static factory has the same constructors with different params:

• createNetworkListing: A constructor to get a Listing component from a common paged Retrofit service implementation.
• createNotPagedNetworkListing: A constructor to get a Listing component from a common not paged Retrofit service implementation.
• createNetworkWithCacheSupportListing: A constructor to get a Listing component with cache support from a common paged Retrofit service implementation.
• createNotPagedNetworkWithCacheSupportListing: A constructor to get a Listing component with cache support from a common not paged Retrofit service implementation.

Network support

Provides a Listing based on a common Retrofit service implementation. In this mode the fetched entities are volatile, they won't be saved in memory nor disk.

Network support for paged endpoints

The Listing with network support for paged endpoints can be obtained invoking createNetworkListing from the static factory class.

It requires only one argument, a NetworkDataSourceAdapter, which provides all operations that the library will use to handle the paging.

The NetworkDataSourceAdapter contains two main functions: a method to check if a page can be fetched and a property to fetch it.

interface NetworkDataSourceAdapter<PageFetcher> {
  val pageFetcher: PageFetcher

  @CheckResult
  fun canFetch(page: Int, pageSize: Int): Boolean
}

PageFetcher is a structure that provides a way to fetch a page from a service call. There is one page fetcher per library adapter, we will refer to any of them as PageFetcher throughout the documentation.

interface RetrofitPageFetcher<T : ListResponse<*>> {
  fun fetchPage(page: Int, pageSize: Int): Call<T>
}

interface CoroutinePageFetcher<T : ListResponse<*>> {
  fun fetchPage(page: Int, pageSize: Int): Deferred<T>
}

interface RxPageFetcher<T : ListResponse<*>> {
  fun fetchPage(page: Int, pageSize: Int): Single<T>
}

Network support for not paged endpoints

The Listing with network support for not paged endpoints can be obtained invoking createNetworkListing from the static factory class.

It requires only one argument, a NotPagedPageFetcher, which provides a method to fetch the data from a service source.

There is one NotPagedPageFetcher per library adapter, we will refer to any of them as NotPagedPageFetcher throughout the documentation.

interface NotPagedRetrifitPageFetcher<T : ListResponse<*>> {
  fun fetchData(): Call<T>
}

interface NotPagedCoroutinePageFetcher<T : ListResponse<*>> {
  fun fetchData(): Deferred<T>
}

interface NotPagedRxPageFetcher<T : ListResponse<*>> {
  fun fetchData(): Single<T>
}

List Responses

The library defines a common service response type which is used to fetch the pages.

interface ListResponse<T> {
  fun getElements(): List<T>
}

Additionally, there are other response types that can be used when the service provides more information in the response.

ListResponseWithEntityCount: Used when the service provides the amount of entities.

interface ListResponseWithEntityCount<T> : ListResponse<T> {
  fun getEntityCount() : Long
}

ListResponseWithPageCount: Used when the service provides the amount of pages.

interface ListResponseWithPageCount<T> : ListResponse<T> {
  fun getPageCount(): Long
}

If you use either ListResponseWithPageCount or ListResponseWithEntityCount you can convert a PageFetcher to a NetworkDataSourceAdapter. That means that if the response has the number of pages or entities you can get a NetworkDataSourceAdapter without implementing the canFetch method.

To do that Fountain provides some extensions:

fun <ServiceResponse : ListResponseWithEntityCount<*>>
    PageFetcher<ServiceResponse>.toTotalEntityCountNetworkDataSourceAdapter(firstPage: Int)
fun <ServiceResponse : ListResponseWithPageCount<*>>
    PageFetcher<ServiceResponse>.toTotalPageCountNetworkDataSourceAdapter(firstPage: Int)

Cache + Network support

Provides a Listing with cache support using a common Retrofit service implementation, and a DataSource for caching the data.

Cache + Network support for paged endpoints

The Listing with network and cache support for paged endpoints can be obtained invoking createNetworkWithCacheSupportListing from the static factory class.

It has two required components:

1. A NetworkDataSourceAdapter<out ListResponse<NetworkValue>> to fetch all pages.
2. A CachedDataSourceAdapter<NetworkValue, DataSourceValue> to update the DataSource. It's the interface that the library will use to take control of the DataSource.

Cache + Network support for not paged endpoints

The Listing with network and cache support for not paged endpoints can be obtained invoking createNotPagedNetworkWithCacheSupportListing from the static factory class.

It has two required components:

1. A NotPagedPageFetcher<out ListResponse<NetworkValue>> to fetch the data.
2. A CachedDataSourceAdapter<NetworkValue, DataSourceValue> to update the DataSource. It's the interface that the library will use to take control of the DataSource.

CachedDataSourceAdapter

interface CachedDataSourceAdapter<NetworkValue, DataSourceValue> {
  fun getDataSourceFactory(): DataSource.Factory<*, DataSourceValue>

  @WorkerThread
  fun saveEntities(response: List<NetworkValue>)

  @WorkerThread
  fun dropEntities()

  @WorkerThread
  fun runInTransaction(transaction: () -> Unit)
}

It has only four methods that you should implement:

• getDataSourceFactory will be used to list the cached elements. The returned value is used to create the LivePagedListBuilder.
• runInTransaction will be used to apply multiple DataSource operations in a single transaction. That means that if something fails, all operations will fail.
• saveEntities will be invoked to save all entities into the DataSource. This will be executed in a transaction.
• dropEntities will be used to delete all cached entities from the DataSource. This will be executed in a transaction.

Caching strategy

The pagination strategy that Fountain is using can be seen in the following image:

It starts with an initial service data request. By default the initial data requested is three pages, but this value can be changed, in the PagedList.Config, using the setInitialLoadSizeHint method. This parameter can be set in the factory constructor method. When the service data comes from the service, all data is refreshed in the DataSource using the CachedDataSourceAdapter. Note that the Listing component will notify that data changed.

After that, the Android Paging Library will require pages when the local data is running low. When a new page is required, the paging library will invoke a new service call, and will use the CachedDataSourceAdapter to save the returned data into the DataSource.

Architecture recommendations

It's strongly recommended to integrate this component in a MVVM architecture combined with the Repository Pattern. The Listing component should be provided by the repository. The ViewModel, can use the different Listing elements, provided by the repository, to show the data and the network changes in the UI.

You can take a look at the example project to see how everything comes together.

Getting involved

• If you want to contribute please feel free to submit pull requests.
• If you have a feature request please open an issue.
• If you found a bug check older issues before submitting a new one.
• If you need help or would like to ask a general question, use StackOverflow. (Tag fountain).

Before contributing, please check the CONTRIBUTING file.

Changelog

The changelog for this project can be found in the CHANGELOG file.

About

Made with ❤️ by XMARTLABS