Introduction
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 provide a Listing component from a common service specification, where the paginated strategy is based on an incremental page number. It provides an awesome way of displaying the paged entity list and reflecting the network state in the UI. If you use this library, you can create an MVVM architecture app and combine it with the repository pattern. If you get a repository which provides a Listing component of each paged list, you will be creating a robuster app.
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.
It also provides two ways to go: a mode with network support and a mode with network + cache support.
The strategy you choose will depend on your problem.
Modules
Fountain supports 2 types of Retrofit service adapters:
It also supports not using any of them, as you could work with a simple Retrofit call.
It has 3 different dependencies that you can include depending on what libraries are you using.
Factory constructors
There's one static factory object class for each each dependency.
FountainCoroutines: Used to get a
Listingfrom a Retrofit service which uses a Coroutine adapter.FountainRetrofit: Used to get a
Listingfrom a Retrofit service without using a special adapter.FountainRx: Used to get a
Listingfrom a Retrofit service which uses a RxJava2 adapter.
Each static factory has the same constructors with different params:
createNetworkListing: A constructor to get aListingcomponent from a common paged Retrofit service implementation.createNotPagedNetworkListing: A constructor to get aListingcomponent from a common not paged Retrofit service implementation.createNetworkWithCacheSupportListing: A constructor to get aListingcomponent with cache support from a common paged Retrofit service implementation.createNotPagedNetworkWithCacheSupportListing: A constructor to get aListingcomponent with cache support from a common not paged Retrofit service implementation.
Fountain Modes
Fountain has two modes: a mode with network support and another one with network + cache support.
Take into account that this is merely an introduction. The full documentation for all of Fountain's modes is available in each module's page:
Network Support
It provides a Listing structure based on a common Retrofit service implementation. Note that the entities aren't saved anywhere.
Network + Cache Support
Provides a Listing with cache support using a common Retrofit service implementation and a DataSource for caching the data.
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 the data has 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.
Last updated
