Description
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](https://developer.android.com/topic/libraries/architecture/), mainly the [Android Paging Library](https://developer.android.com/topic/libraries/architecture/paging/) to make it easier to work with paged services.
The main goal of the library is to easily provide a [Listing](https://xmartlabs.gitbook.io/fountain/listing) component from a common service specification.
Why not use the [Android Paging Library] directly?
To be able to integrate these kind of services you'll have to write a lot of code to obtain the necessary paging component, `LiveData>`.
Once you have it, the paging issue becomes trivial, but getting it is not. And this is only if you don't need database support, in that case you'll have to write a lot more code.
This is where [Fountain] comes to life.
It provides everything that you'll need to work with these services and more, easily and without boilerplate.
Take a look at the [introducing Fountain post](https://blog.xmartlabs.com/2018/07/16/Introducing-Fountain-Part-One/)
fountain alternatives and similar packages
Based on the "Kotlin" category.
Alternatively, view fountain alternatives based on common mentions on social networks and blogs.
-
android-youtube-player
YouTube Player library for Android and Chromecast, stable and customizable. -
CalendarView
A highly customizable calendar view and compose library for Android. -
Balloon
:balloon: Modernized and sophisticated tooltips, fully customizable with an arrow and animations for Android. -
Kotterknife
Android view injection writen in Kotlin based on ButterKnife -
Shortbread
Android library that creates app shortcuts from annotations -
kotlin-android-template
Android + Kotlin + Github Actions + ktlint + Detekt + Gradle Kotlin DSL + buildSrc = โค๏ธ -
NotyKT ๐๏ธ
๐ NotyKT is a complete ๐Kotlin-stack (Backend + Android) ๐ฑ application built to demonstrate the use of Modern development tools with best practices implementation๐ฆธ. -
Material Chip View
Material Chip view. Can be used as tags for categories, contacts or creating text clouds -
DrawableToolbox
๐ ๏ธ The missing drawable toolbox for Android. Create drawables programmatically and get rid of the boring and always repeated drawable.xml files. -
Navigation Toolbar for Android
:octocat: Navigation toolbar is a slide-modeled UI navigation controller made by @Ramotion -
CodeView
Display code with syntax highlighting :sparkles: in native way. -
Carousel Recyclerview
Carousel Recyclerview let's you create carousel layout with the power of recyclerview by creating custom layout manager. -
Pluto Debug Framework
Android Pluto is a on-device debugging framework for Android applications, which helps intercept Network calls, capture Crashes & ANRs, manipulate application data on-the-go, and much more. -
Pdf Viewer For Android
A Lightweight PDF Viewer Android library which only occupies around 125kb while most of the Pdf viewer occupies up to 16MB space. -
Android Kotlin Samples
Some basic samples of Kotlin for Android -
MaterialTimelineView
With MaterialTimelineView you can easily create a material looking timeline. -
CrunchyCalendar โ awesome calendar widget for android apps
A beautiful material calendar with endless scroll, range selection and a lot more! -
sliding-panel
Android sliding panel that is part of the view hierarchy, not above it. -
Capturable
๐Jetpack Compose utility library for capturing Composable content and transforming it into Bitmap Image๐ผ๏ธ -
MaterialDrawerKt
A Kotlin DSL wrapper around the mikepenz/MaterialDrawer library. -
SSComposeCookBook
A Collection of major Jetpack compose UI components which are commonly used.๐๐๐ -
Transition X
{ } Declarative Kotlin DSL for choreographing Android transitions -
Only
:bouquet: An easy way to persist and run code block only as many times as necessary on Android. -
SSCustomBottomNavigation
Animated TabBar with native control and Jetpack Navigation support..โจ๐๐ -
Swagger Gradle Codegen
๐ซ A Gradle Plugin to generate your networking code from Swagger -
Permission Flow for Android
Know about real-time state of a Android app Permissions with Kotlin Flow APIs. -
EasyPermissions-ktx
๐ Kotlin version of the popular google/easypermissions wrapper library to simplify basic system permissions logic on Android M or higher. -
Awesome Jetpack compose
A collaborative list of awesome jetpack compose resources. -
Nextflix-Composable
Includes jetpack compose, navigation, paging, hilt, retrofit, coil, coroutines, flow.. -
DeviceInfo-Sample
[Android Library] Get easy access to device information super fast, real quick -
Intro Showcase View
Highlight different features of the app using Jetpack Compose -
Aimybox voice assistant
Embeddable custom voice assistant for Android applications -
Events Calendar
Events Calendar is a user-friendly library that helps you achieve a cool Calendar UI with events mapping. You can customise every pixel of the calendar as per your wish and still achieve in implementing all the functionalities of the native android calendar in addition with adding dots to the calendar which represents the presence of an event on the respective dates. It can be done easily, you are just a few steps away from implementing your own badass looking Calendar for your very own project! -
ZoomHelper
ZoomHelper will make any view to be zoomable just like Instagram pinch-to-zoom -
Mutekt
Simplify mutating "immutable" state models (a Kotlin multiplatform library) -
SSCustomEditTextOutLineBorder
Same as the Outlined text fields presented on the Material Design page but with some dynamic changes. ๐ ๐ -
Maildroid
Maildroid is a small robust android library for sending emails using SMTP server -
TimelineView
A customizable and easy-to-use Timeline View library for Android. Works as a RecyclerView decorator (ItemDecoration) -
Turtle ๐ข
Run shell commands from Kotlin scripts, apps or Gradle tasks with ease. -
Compose Compiler Reports to HTML Generator
A utility (Gradle Plugin + CLI) to convert Jetpack Compose compiler metrics and reports to beautified HTML page. -
Vanilla Place Picker
Simple(vanilla) yet 'Do it all' place picker for your place picking needs in Android -
Crowdin Android SDK
Crowdin Android SDK delivers all new translations from Crowdin project to the application immediately -
Awesome Mobile Libraries
This repo contains all the Open-source Libraries from iOS, Android, Flutter and React-Native.โจ
Appwrite - The Open Source Firebase alternative introduces iOS support
Do you think we are missing an alternative of fountain or a related project?
README
[Fountain](images/banner.png)
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.
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 aLiveData
of aPagedList
. - 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 aDataSource
for caching the data. We recommend you use Room to provide theDataSource
, because it will be easier. However, you could use any otherDataSource
.
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.
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 aListing
component from a common paged Retrofit service implementation.createNotPagedNetworkListing
: A constructor to get aListing
component from a common not paged Retrofit service implementation.createNetworkWithCacheSupportListing
: A constructor to get aListing
component with cache support from a common paged Retrofit service implementation.createNotPagedNetworkWithCacheSupportListing
: A constructor to get aListing
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:
- A
NetworkDataSourceAdapter<out ListResponse<NetworkValue>>
to fetch all pages. - A
CachedDataSourceAdapter<NetworkValue, DataSourceValue>
to update theDataSource
. It's the interface that the library will use to take control of theDataSource
.
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 theDataSource
. It's the interface that the library will use to take control of theDataSource
.
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 theLivePagedListBuilder
.runInTransaction
will be used to apply multipleDataSource
operations in a single transaction. That means that if something fails, all operations will fail.saveEntities
will be invoked to save all entities into theDataSource
. This will be executed in a transaction.dropEntities
will be used to delete all cached entities from theDataSource
. 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](CONTRIBUTING.md) file.
Changelog
The changelog for this project can be found in the [CHANGELOG](CHANGELOG.md) file.
About
Made with โค๏ธ by XMARTLABS
*Note that all licence references and agreements mentioned in the fountain README section above
are relevant to that project's source code only.