RxObservableDiskCache is a library to save the results of Single
s or single value Observable
s request on a local disk cache, so the next time the same request is called you get an immediate result.
For the RxJava 2.X version, please go to RxObservableDiskCache2.
RxObservableDiskCache was created with a single purpose: help you store your network results in a disk cache and refetch them as soon as they're re-requested. It also solves displaying values while waiting for network results, when the user is offline, or when the server is unavailable.
To provide a good UX your app should be able to work offline and also display results as soon as they're requested. Historically this has been done by storing your data on SQLite, or a custom network cache. These options introduce maintenance overhead: SQLite requires a strict data model, careful database updates, and usage of syntactic sugar libraries like ORMs to make it palatable. The custom network cache depends on your server team introducing etags and other similar mechanisms, which are not always available.
RxObservableDiskCache relies on a technology that's common on desktop and server: key-value disk stores. By using RxPaper behind the scenes it's able to efficiently store any result in an schemaless document just to refetch it later. This makes caching transparent for most network calls, you just need to configure them once with the correct caching policy. It's just one method call that wraps your Single
or single value Observable
.
To avoid your data getting stale due to time limits or versioning, RxObservableDiskCache allows you to store an arbitrary caching Policy. This Policy is any simple object that helps you identify whether your data is outdated and has to be removed. RxObservableDiskCache provides three different Policy objects, but you can create and use your own. This way you can decide how to handle staleness the same way you would do in SQLite or when using etags: by dropping the data, or programming defensively to account for model changes.
As PaperDb 2.0 has updated from Kryo 3 to Kryo 4, the internal representation model has changed. PaperDb deals with these changes internally, so the migration should be transparent. If you find any data compatibility bug, please create a ticket.
RxObservableDiskCache uses RxPaper internally, so it's recommended to go to its README for reference on what Values are serializable, and what other behaviours are expected. RxObservableDiskCache is not opinionanted about the RxPaperBook
you pass onto it, so feel free to use it externally to read, modify, or purge any data outside the RxObservableDiskCache scope.
Behind the scenes Policy objects are stored and retrieved separately from Values to avoid unnecessary deserialization. They're checked before the Value is retrieved to see if it has to be deleted instead. Policy objects are recommended to be kept as small as possible.
Three simple Policy classes are included with RxObservableDiskCache: TimePolicy, VersionPolicy, and TimeAndVersionPolicy. You can still use any other class as Policy.
Any storage errors are: logged with a "cache miss" message, the current key and value get deleted, and the error is forwarded.
Any errors on the operation are forwarded too, like with any Observable
.
Expect 0 results for cache and operation failures, 1 result when the cache is not found or valid and the operation succeeds, 1 result when the cache is found and valid but the operation fails, and 2 results when both the cache and the operation succeed.
There is a full test suite with examples on the sample project.
The configuration parameters are:
- The
Single
or single valueObservable
operation to be wrapped. - A key string under which the Value will be stored.
- The RxPaperBook database where the Value and Policy will be stored.
- A creation and validation functions for the Policy.
RxObservableDiskCache.transform()
are a set of methods you can call with any observable and configuration parameters that will return the transformed Observable
.
RxObservableDiskCache.
<UserProfile, TimeAndVersionPolicy> transform(
userRequest(),
"user_profile",
RxPaperBook.with("my_app_cache"),
TimeAndVersionPolicy.<UserProfile>create(BuildConfig.VERSION_CODE),
TimeAndVersionPolicy.validate(BuildConfig.VERSION_CODE))
.subscribe(/* Do something withe the data */);
RxObservableDiskCache.create()
creates an instance of RxObservableDiskCache for the same book, Value and Policy that can be reused for different Single
s or single value Observable
s.
RxObservableDiskCache<UserProfile, TimeAndVersionPolicy> myCache =
RxObservableDiskCache.create(
RxPaperBook.with("my_app_cache"),
TimeAndVersionPolicy.<UserProfile>create(BuildConfig.VERSION_CODE),
TimeAndVersionPolicy.validate(BuildConfig.VERSION_CODE));
myCache.transform(userRequest(), "user_profile").subscribe(/* Do something withe the data */);
myCache.transform(userRequest("54663"), "friend_54663_profile").subscribe(/* Do something withe the data */);
Add as a dependency to your build.gradle
repositories {
...
maven { url "https://jitpack.io" }
...
}
dependencies {
...
compile 'com.github.pakoito:RxObservableDiskCache:2.0.0'
...
}
or to your pom.xml
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<dependency>
<groupId>com.github.pakoito</groupId>
<artifactId>RxObservableDiskCache</artifactId>
<version>2.0.0</version>
</dependency>
As fast as the underlying Paper library. Policy is used to reduce deserialization overhead when it's not required, so Values are only fetched when they're surely required and validated. Kryo is binary serialization faster than Jackson and Gson.
Same way you do on SQLite: you drop the data or code defensively. The storage is schemaless, so no update scripts are required. The data is deserialized under the same premises as Paper/Kryo, so their documentation is the best reference. The usage of Policy was introduced to automate the process, but you're free to ignore it and operate directly on the RxPaperBook you pass to the transformation.
Because it transforms from Single
to Observable
, and I wanted to keep the transformation explicit.
Although it doesn't make much sense to me to duplicate every value on an Observable
operation, you can do it like this:
myNotSingleObservable.flatMap(
value ->
RxObservableDiskCache.transform(
Single.just(value), /* rest of parameters */))
Database operations are not meant to be cancellable, and shouldn't be applied directly to UI precisely to avoid leaks. Apply them to a PublishSubject
instead, and bind that subject directly to the view making sure that you unsubscribe()
it when required.
PRs and suggestions for new features welcome.
For any error report please send an issue with a full stack trace and reproduction steps.
Copyright (c) pakoito 2016
The Apache Software License, Version 2.0
See LICENSE.md