xmartlabs/fountain is a GitHub project with 169 stars.
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
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
)
pagedList: A changing data stream of type T represented as a LiveData of a PagedList.
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).
refresh: A refresh function, to refresh all data.
refreshState: A stream that notifies the status of the refresh request.
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:
Network support: Provides a Listing based on a common Retrofit service implementation.
Note entities won't be saved in memory nor disk.
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.
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:
A NetworkDataSourceAdapter<out ListResponse<NetworkValue>> to fetch all pages.
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:
A NotPagedPageFetcher<out ListResponse<NetworkValue>> to fetch the data.
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.
xmartlabs/fountain has 169 GitHub stars — refresh the page for the live number, or check github.com/xmartlabs/fountain. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
Is xmartlabs/fountain open source?
TopGit's metadata for xmartlabs/fountain does not record a license. Most public repositories on GitHub ARE open source, but the exact terms vary — verify by opening the LICENSE file directly.
Is xmartlabs/fountain still maintained?
TopGit's metadata for xmartlabs/fountain does not include a recent push date. Check the commit history on the GitHub repository page for the most authoritative activity timeline.
What is xmartlabs/fountain?
xmartlabs/fountain (xmartlabs/fountain) is a multi-language project tracked by TopGit. The repository has 169 GitHub stars at the time of our last sync.
What language is xmartlabs/fountain written in?
TopGit's last sync did not record a primary language for xmartlabs/fountain. Open the repository on GitHub to see the full breakdown by file extension.
Where do I read more about xmartlabs/fountain?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/xmartlabs/fountain is the definitive source.
Read full README in the tab above.
Is fountain worth your time?
ChatGPT, Claude and Perplexity can all read this page. Ask one of them what it makes of fountain.