Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kittinunf/fuse
The simple generic LRU memory/disk cache for Android written in Kotlin
https://github.com/kittinunf/fuse
android cache disklrucache kotlin lru-cache
Last synced: 9 days ago
JSON representation
The simple generic LRU memory/disk cache for Android written in Kotlin
- Host: GitHub
- URL: https://github.com/kittinunf/fuse
- Owner: kittinunf
- Created: 2016-04-25T18:00:04.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2022-06-01T07:42:44.000Z (over 2 years ago)
- Last Synced: 2024-08-02T06:16:23.621Z (3 months ago)
- Topics: android, cache, disklrucache, kotlin, lru-cache
- Language: Kotlin
- Homepage: https://kittinunf.gitbook.io/fuse/
- Size: 5.44 MB
- Stars: 280
- Watchers: 11
- Forks: 26
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
Awesome Lists containing this project
README
# Fuse
[](https://search.maven.org/search?q=g:com.github.kittinunf.fuse)
[](https://travis-ci.org/kittinunf/fuse)
[](https://codecov.io/gh/kittinunf/Fuse)
The simple generic LRU cache for Android, backed by both memory cache ([LruCache](http://developer.android.com/reference/android/util/LruCache.html)) and disk-based cache ([DiskLruCache](https://github.com/JakeWharton/DiskLruCache)) by Jake Wharton
# Installation
The core package has following dependencies;
- [](http://kotlinlang.org)
- [Result](https://github.com/kittinunf/Result) - 5.2.1
```groovy
//core
implementation 'com.github.kittinunf.fuse:fuse:'
//android
implementation 'com.github.kittinunf.fuse:fuse-android:'
```
# How to use
`Fuse` is designed to be simple and easy to use. All you need is `CacheBuilder` to setup configuration for your cache.
```kotlin
private val tempDir = createTempDir().absolutePath // use any readable/writable directory of your choice
val convertible = // there are couple of built-in Convertibles such as DataConvertible, StringDataConvertible
val cache = CacheBuilder.config(tempDir, convertible) {
// do more configuration here
}.build()
```
Then, you can build `Cache` from the `CacheBuilder` and, you can start using your cache like;
```kotlin
cache = //cache instance that was instantiated earlier
//put value "world" for key "hello", "put" will always add new value into the cache
cache.put("hello", { "world" })
//later
cache.get("hello") // this returns Result.Success["world"]
val (result, source) = cache.getWithSource("hello") // this also returns Source which is one of the following, 1. MEM, 2. DISK, 3. ORIGIN
val result = cache.get("hello", { "world" }) // this return previously cached value otherwise it will save value "world" into the cache for later use
when (result) {
is Success -> { // value is successfully return/fetch, result.value is data
}
is Failure -> { // something wrong, check result.error for more details
}
}
```
### Source
`Source` gives you an information where the data is coming from.
```kotlin
enum class Source {
ORIGIN,
DISK,
MEM
}
```
- ORIGIN - The data is coming from the original source. This means that it is being fetched from the `Fetcher` class.
- DISK - The data is coming from the Disk cache. In this cache, it is specifically retrieved from DiskLruCache
- MEM - The data is coming from the memory cache.
All of the interfaces that provides `Source` have `WithSource` suffix, i.e. `getWithSource()` etc.
### Android Usage
For Android, it is basically a thin layer on top of the memory cache by using a [LruCache](https://developer.android.com/reference/android/util/LruCache)
```kotlin
// same configuration as above
val cache = CacheBuilder.config(tempDir, convertible) {
// do more configuration here
memCache = defaultAndroidMemoryCache() // this will utilize the LruCache provided by Android SDK
}.build()
```
By default, the Cache is perpetual meaning that it will never expired by itself. Please check [Detail Usage] for more information about expirable cache.
# Detailed usage
The default Cache that is provided by Fuse is a perpetual cache that will never expire the entry. In some cases, this is not what you want. If you are looking for non-perpetual cache, luckily, Fuse also provides you with a `ExpirableCache` as well.
The usage of `ExpirableCache` is almost exactly the same as a regular cache, but with a time constraint that is configurable for the entry to be expired.
```kotlin
private val cache = CacheBuilder.config(tempDir, StringDataConvertible()).build().let(::ExpirableCache)
// cache is ExpirableCache type
val (value, error) = expirableCache.get("hello", { "world" }) // this works the same as regular cache
println(value) //Result.Success["world"]
// after 5 seconds has passed
val (value, error) = expirableCache.get("hello", { "new world" }, timeLimit = 5.seconds) // if the cached value has a lifetime longer than 5 seconds, entry becomes invalid
println(value) //Result.Success["new world"], it got refreshed as the entry is expired
```
# Sample
Please see the sample Android app that utilize Fuse in the [Sample](https://github.com/kittinunf/Fuse/tree/master/sample) folder
## License
Fuse is released under [MIT](https://opensource.org/licenses/MIT), but as Fuse depends on LruCache and DiskLruCache. Licenses agreement on both dependencies applies.
```
Copyright 2011 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```