RxCache中文文档

RxCache官方文档翻译

本文翻译自:RxCache官方GitHub地址
版本号:RxCache 1.8.1-2.x

欢迎转载,转发请注明文章来源
http://write.blog.csdn.net/mdeditor#!postId=78056742 @却把清梅嗅

中文文档已发布GitHub,详情请点击

RxCache基本使用方法、Demo请参阅笔者的相关文章:

Android RxCache使用详解

Android RxCache原理解析


1 概述

2 基本使用

2.1 依赖配置

2.2 接口配置

2.3 新建Provider实例并使用它

2.4 再次回顾整个流程

3 RxCache使用场景

4 RxCache API

4.1 EvictProvider:驱逐缓存数据

4.2 DynamicKey:筛选数据

4.3 DynamicKeyGroup:分页和过滤

5 Actionable RxCache API

6 高级选项

6.1 数据迁移

6.2 数据加密

6.3 常规配置

6.3.1 配置要保留的数据的大小限制(以兆字节为单位)

6.3.2 如果未加载到数据,使用过期的缓存数据

6.4 Android注意事项

6.5 和Retrofit搭配使用

7 其他

7.1 RxCache原理

7.2 代码混淆

7.3 关于作者

7.4 RxCache Swift版本

7.5 作者其它使用RxJava的库

8 关于中文文档

概述

本库的 目标 很简单: 就像Picasso 缓存您的图片一样,毫不费力缓存您的数据对象。

每个Android Application都是一个客户端应用程序,这意味着仅仅为缓存数据创建数据库并进行维护毫无意义。

事实上,传统方式通过数据库来缓存数据并没有解决根本性的问题:以更加灵活简单的方式配置缓存。

灵感来源于 Retrofit , RxCache是一个用于Android和Java的响应式缓存库,它可将您的缓存需求转换为一个接口进行配置。

当提供一个 observable, single, maybe or flowable (这些是RxJava2支持的响应式数据类型) 这些由耗时操作提供的数据,RxCache确定是否需要subscribe,或覆盖先前缓存的数据。

此决定是基于RxCache的Providers进行配置的。

基本使用

依赖配置

在您的Project级的build.gradle中添加JitPack仓库:

allprojects {
    repositories {
        jcenter()
        maven { url "https://jitpack.io" }
    }
}

将下列的依赖添加到Module的build.gradle中:

dependencies {
    compile "com.github.VictorAlbertos.RxCache:runtime:1.8.1-2.x"
    compile "io.reactivex.rxjava2:rxjava:2.0.6"
}

因为RxCache在内部使用 Jolyglot 对数据进行序列化和反序列化, 您需要选择下列的依赖中选择一个进行添加:

dependencies {
    // To use Gson 
    compile 'com.github.VictorAlbertos.Jolyglot:gson:0.0.3'

    // To use Jackson
    compile 'com.github.VictorAlbertos.Jolyglot:jackson:0.0.3'

    // To use Moshi
    compile 'com.github.VictorAlbertos.Jolyglot:moshi:0.0.3'
}

接口配置

声明一个接口,常规使用方式中(以Retrofit网络请求为例),创建和API需求同样多的Providers来缓存您的数据。

这意味着,项目中Retrofit的APIService接口有多少个抽象方法的API需要实现缓存,一一对应,就需要Providers提供多少个缓存API方法

interface Providers {

        @ProviderKey("mocks")
        Observable<List<Mock>> getMocks(Observable<List<Mock>> oMocks);

        @ProviderKey("mocks-5-minute-ttl")
        @LifeCache(duration = 5, timeUnit = TimeUnit.MINUTES)   //缓存有效期5分钟
        Observable<List<Mock>> getMocksWith5MinutesLifeTime(Observable<List<Mock>> oMocks);

        @ProviderKey("mocks-evict-provider")
        Observable<List<Mock>> getMocksEvictProvider(Observable<List<Mock>> oMocks, EvictProvider evictProvider);

        @ProviderKey("mocks-paginate")
        Observable<List<Mock>> getMocksPaginate(Observable<List<Mock>> oMocks, DynamicKey page);

        @ProviderKey("mocks-paginate-evict-per-page")
        Observable<List<Mock>> getMocksPaginateEvictingPerPage(Observable<List<Mock>> oMocks, DynamicKey page, EvictDynamicKey evictPage);

        @ProviderKey("mocks-paginate-evict-per-filter")
        Observable<List<Mock>> getMocksPaginateWithFiltersEvictingPerFilter(Observable<List<Mock>> oMocks, DynamicKeyGroup filterPage, EvictDynamicKey evictFilter);
}

RxCache暴露了evictAll()方法来清除一行中的整个缓存。

RxCache的Provider配置中,方法所需要的参数用来配置Provider处理缓存的方式:

  • 无论如何,必不可少的参数是RxJava提供的响应式基本数据类型(如Observable),这个参数的意义是将你想缓存的Retrofit接口作为参数传入,并以相同的RxJava数据类型作为返回。

    这意味着,您可以不配置任何可选项,但是您必须将您要缓存的数据作为参数交给RxCache进行缓存.

  • EvictProvider 是否驱逐与该Provider相关联的所有缓存数据.
    该对象通过构造方法进行实例化,创建时需要传入boolean类型的参数,当参数为true时,RxCache会直接驱逐该Provider的缓存数据,进行最新的网络请求并进行缓存;若参数为false,若缓存数据未过期,正常加载缓存数据
  • @ProviderKey 保护用户数据的Provider方法的注解,强烈建议使用这个注解! 如果不使用该注解,该方法的名称会被作为该Provider的key进行文件缓存, 使用了代码混淆的用户很快会遇到问题,详情请参阅 Proguard . 如果不使用代码混淆,该注解也很有用,因为它可以确保您可以随心所欲修改Provider数据缓存的方法名,而无需为旧缓存文件迁移问题而苦恼。
    该注解是最近版本添加的,在考虑到代码混淆(方法名的改变导致缓存文件命名的改变)和缓存数据迁移,强烈建议使用该注解!
  • EvictDynamicKey 是否驱逐具体的缓存数据 DynamicKey.
    缓存数据驱逐范围比EvictProvider小(后者是驱逐所有缓存),比EvictDynamicKeyGroup大(后者是驱逐更精细分类的缓存),举例,若将userId(唯一)作为参数传入DynamicKey,清除缓存时,仅清除该userId下的对应缓存
  • EvictDynamicKeyGroup 是否驱逐更加具体的缓存数据 DynamicKeyGroup.
    和EvictDynamicKey对比,上述案例中,DynamicKeyGroup可以filter到某userId下缓存的某一页数据进行驱逐,其他缓存不驱逐
  • DynamicKey 通过传入一个对象参数(比如userId)实现和对应缓存数据的绑定, 清除该key相关联的缓存数据请使用 EvictDynamicKey.
  • DynamicKeyGroup 通过传入一个Group参数(比如userId,数据的分类)实现和对应缓存数据的绑定, 清除该keyGroup相关联的缓存数据请使用EvictDynamicKeyGroup.

Supported annotations:

新建Provider实例并使用它

最后,使用RxCache.Builder实例化Provider接口,并提供一个有效的文件系统路径,这将允许RxCache在磁盘上写入缓存数据。

//获取缓存的文件存放路径
File cacheDir = getFilesDir();
Providers providers = new RxCache.Builder()
                            .persistence(cacheDir, new GsonSpeaker())//配置缓存的文件存放路径,以及数据的序列化和反序列化
                            .using(Providers.class);    //和Retrofit相似,传入缓存API的接口

再次回顾整个流程

interface Providers {
    //配置要缓存的数据,以及是否驱逐缓存数据并请求网络
    @ProviderKey("mocks-evict-provider")
    Observable<List<Mock>> getMocksEvictProvider(Observable<List<Mock>> oMocks, EvictProvider evictProvider);

    //配置要缓存的数据,简单的缓存数据分类,以及是否驱逐该分类下的缓存数据并请求网络
    @ProviderKey("mocks-paginate-evict-per-page")
    Observable<List<Mock>> getMocksPaginateEvictingPerPage(Observable<List<Mock>> oMocks, DynamicKey page, EvictDynamicKey evictPage);

    //配置要缓存的数据,复杂的缓存数据分类,以及是否驱逐该详细分类下的缓存数据并请求网络
    @ProviderKey("mocks-paginate-evict-per-filter")
    Observable<List<Mock>> getMocksPaginateWithFiltersEvictingPerFilter(Observable<List<Mock>> oMocks, DynamicKeyGroup filterPage, EvictDynamicKey evictFilter);
}
public class Repository {
    private final Providers providers;

    //初始化RxCache的Provider
    public Repository(File cacheDir) {
        providers = new RxCache.Builder()
                .persistence(cacheDir, new GsonSpeaker())
                .using(Providers.class);
    }

    //参数update:是否加载最新数据
    public Observable<List<Mock>> getMocks(final boolean update) {
        return providers.getMocksEvictProvider(getExpensiveMocks(), new EvictProvider(update));
    }

    //参数page:第几页的数据,update:是否加载该页的最新数据
    public Observable<List<Mock>> getMocksPaginate(final int page, final boolean update) {
        return providers.getMocksPaginateEvictingPerPage(getExpensiveMocks(), new DynamicKey(page), new EvictDynamicKey(update));
    }

    //参数filter:某个条件(比如userName),参数page:第几页数据,参数updateFilter:是否加载该userName该页的最新数据
    public Observable<List<Mock>> getMocksWithFiltersPaginate(final String filter, final int page, final boolean updateFilter) {
        return providers.getMocksPaginateWithFiltersEvictingPerFilter(getExpensiveMocks(), new DynamicKeyGroup(filter, page), new EvictDynamicKey(updateFilter));
    }

    //这个方法的返回值代替了现实开发中,您通过耗时操作获得的数据类型(比如Observable<T>)
    //如果这里您使用了Retrofit进行网络请求,那么可以说是拿来即用。
    private Observable<List<Mock>> getExpensiveMocks() {
        return Observable.just(Arrays.asList(new Mock("")));
    }
}

RxCache使用场景

  • 使用经典的RxCache API进行文件的读写操作。
  • 使用Actionable的API,专用于文件的写操作。

RxCache API

下面的用例说明了一些常见的情况,这将有助于您了解“DynamicKey”和“DynamicKeyGroup”类的使用以及清除数据。

EvictProvider:驱逐缓存数据

不驱逐数据

Observable<List<Mock>> getMocks(Observable<List<Mock>> oMocks);

驱逐数据

Observable<List<Mock>> getMocksEvictProvider(Observable<List<Mock>> oMocks, EvictProvider evictProvider);

业务代码中使用:


//接收到Observable时驱逐该Provider所有缓存数据并重新请求
getMocksEvictProvider(oMocks, new EvictProvider(true))

//这行会抛出一个IllegalArgumentException:“提供了EvictDynamicKey但没有提供任何DynamicKey”
getMocksEvictProvider(oMocks, new EvictDynamicKey(true))

DynamicKey:筛选数据

指定某个条件,不驱逐该条件下的缓存数据

Observable<List<Mock>> getMocksFiltered(Observable<List<Mock>> oMocks, DynamicKey filter);

指定某个条件,可选择是否驱逐该条件下的缓存数据

Observable<List<Mock>> getMocksFilteredEvict(Observable<List<Mock>> oMocks, DynamicKey filter, EvictProvider evictDynamicKey);

业务代码中使用:


//接收到Observable时驱逐该Provider所有缓存数据并重新请求
getMocksFilteredEvict(oMocks, new DynamicKey("actives"), new EvictProvider(true))

//通过使用EvictDynamicKey,接收到Observable时,驱逐该DynamicKey("actives")下所有缓存数据并重新请求
getMocksFilteredEvict(oMocks, new DynamicKey("actives"), new EvictDynamicKey(true))

//这行抛出一个IllegalArgumentException:“提供了EvictDynamicKeyGroup,但没有提供任何DynamicKeyGroup”
getMocksFilteredEvict(oMocks, new DynamicKey("actives"), new EvictDynamicKeyGroup(true))

DynamicKeyGroup:分页和过滤

List数据的分页和过滤,不驱逐缓存数据

Observable<List<Mock>> getMocksFilteredPaginate(Observable<List<Mock>> oMocks, DynamicKey filterAndPage);

List数据的分页和过滤,包含是否驱逐缓存数据选项

Observable<List<Mock>> getMocksFilteredPaginateEvict(Observable<List<Mock>> oMocks, DynamicKeyGroup filterAndPage, EvictProvider evictProvider);

运行时使用:


//接收到Observable时驱逐该Provider所有缓存数据并重新请求
getMocksFilteredPaginateEvict(oMocks, new DynamicKeyGroup("actives", "page1"), new EvictProvider(true))

//通过使用EvictDynamicKey,接收到Observable时,驱逐该DynamicKey("actives", "page1")下所有缓存数据并重新请求
getMocksFilteredPaginateEvict(oMocks, new DynamicKeyGroup("actives", "page1"), new EvictDynamicKey(true))

//通过使用EvictDynamicKey,接收到Observable时,驱逐该DynamicKeyGroup("actives", "page1")下所有缓存数据并重新请求
getMocksFilteredPaginateInvalidate(oMocks, new DynamicKeyGroup("actives", "page1"), new EvictDynamicKeyGroup(true))

正如你所看到的,使用“DynamicKey”或“DynamicKeyGroup”以及“EvictProvider”类的重点就是在根据不同范围下,驱逐缓存数据对象。

上述示例代码中展示了方法接收“EvictProvider”的参数,以及EvictProvider的子类DynamicKey、DynamicKeyGroup,保证更详细的数据分类和筛选,并进行缓存。

上述代码中,我已经做到了这一点,您总是可以通过自己的筛选,将数据的key类别缩小到你真正需要驱逐的类型。对于最后一个例子,我将在实际产品代码中使用“EvictDynamicKey”,因为这样我就可以对已过滤的项目进行分页,并将其按过滤器排除,例如通过刷新来触发。

这里还有完整的例子 Android and Java projects.

Actionable RxCache API

限制:目前actionable的API仅支持Observable的数据类型。

这个actionable的API提供了一种Application执行文件写入操作的简单方法。 尽管使用RxCache经典的api也可以实现写入操作,但经典的api有着复杂性且容易出错。实际上,Actions类是围绕经典api的进行了一层包装。

为了能够使用该actionable API,首先,你需要添加 repository compiler 的依赖到您的build.gradle:

dependencies {
     // other classpath definitions here
     classpath 'com.neenbedankt.gradle.plugins:android-apt:1.8'
 }

然后确保在您的app / build.gradle中应用该插件,并添加编译器依赖关系:

apply plugin: 'com.neenbedankt.android-apt'

dependencies {
    // apt command comes from the android-apt plugin
    apt "com.github.VictorAlbertos.RxCache:compiler:1.8.0-1.x"
}

配置完成后,为每个Provider添加注解 @Actionable annotation

编译器会生成一个新的类,该类与接口名称相同,但是附加了一个“Actionable”后缀,并暴露出和该接口同样多的方法

参数供应中的顺序必须与以下示例保持一致:

public interface RxProviders {
    @Actionable
    Observable<List<Mock.InnerMock>> mocks(Observable<List<Mock.InnerMock>> message, EvictProvider evictProvider);

    @Actionable
    Observable<List<Mock>> mocksDynamicKey(Observable<List<Mock>> message, DynamicKey dynamicKey, EvictDynamicKey evictDynamicKey);

    @Actionable
    Observable<List<Mock>> mocksDynamicKeyGroup(Observable<List<Mock>> message, DynamicKeyGroup dynamicKeyGroup, EvictDynamicKeyGroup evictDynamicKey);
}

请注意,Observable内的值必须是“List”类型,否则将抛出异常。

这样上面的RxProviders接口将会在生成的“RxProvidersActionable”类中暴露出下面的方法:

RxProvidersActionable.mocks(RxProviders proxy);
RxProvidersActionable.mocksDynamicKey(RxProviders proxy, DynamicKey dynamicKey);
RxProvidersActionable.mocksDynamicKeyGroup(RxProviders proxy, DynamicKeyGroup dynamicKeyGroup);

这些方法返回“Actions”类的一个实例,现在你已经可以尝试使用每个可用的写操作 Actions .建议您浏览ActionsTest类,以查看哪些操作适合更适合你的现实需求。

一些示例代码:

ActionsProviders.mocks(rxProviders)
    .addFirst(new Mock())
    .addLast(new Mock())
    //Add a new mock at 5 position
    .add((position, count) -> position == 5, new Mock())

    .evictFirst()
    //Evict first element if the cache has already 300 records
    .evictFirst(count -> count > 300)
    .evictLast()
    //Evict last element if the cache has already 300 records
    .evictLast(count -> count > 300)
    //Evict all inactive elements
    .evictIterable((position, count, mock) -> mock.isInactive())
    .evictAll()

    //Update the mock with id 5
    .update(mock -> mock.getId() == 5, mock -> {
        mock.setActive();
        return mock;
    })
    //Update all inactive mocks
    .updateIterable(mock -> mock.isInactive(), mock -> {
        mock.setActive();
        return mock;
    })
    .toObservable()
    .subscribe(processedMocks -> {})

之前的每个Action只有在composed的observable接收到subscribe之后才会执行。

高级选项

数据迁移

RxCache提供了一种处理版本之间缓存数据迁移的简单方式。

简单来说,最新的版本中某个接口返回值类型内部发生了改变,从而获取数据的方式发生了改变,但是存储在本地的数据,是未改变的版本,这样在反序列化时就可能发生错误,为了规避这个风险,作者就加入了数据迁移的功能

您需要为您的Provider接口添加注解 @SchemeMigration. 这个注解接受一个数组 @Migration ,反过来,Migration注释同时接受一个版本号和一个Classes的数组,这些数组将从持久层中删除。

@SchemeMigration({
            @Migration(version = 1, evictClasses = {Mock.class}),
            @Migration(version = 2, evictClasses = {Mock2.class}),
            @Migration(version = 3, evictClasses = {Mock3.class})
    })
interface Providers {}

只有当RxCache使用的Class类中数据结构发生了改变,才需要添加新的迁移注解。

比如说,您的缓存数据User中有 int userId这个属性,新的版本中变成了 long userId,这样缓存数据的反序列化就会出现问题,因此需要配置迁移注解

删除类或删除类的字段将由RxCache自动处理,因此当字段或整个类被删除时,不需要迁移新的注解。

@SchemeMigration({
            @Migration(version = 1, evictClasses = {Mock.class}),
            @Migration(version = 2, evictClasses = {Mock2.class})
    })
interface Providers {}

但是现在,“Mock”类已经从项目中删除了,所以不可能再引用它的类了。 要解决这个问题,只需删除这行迁移的注解即可。

@SchemeMigration({
            @Migration(version = 2, evictClasses = {Mock2.class})
    })
interface Providers {}

因为RxCache需要内部进程才能清理内存,所以数据最终将被全部清除。

数据加密

RxCache提供了一种加密数据的简单机制。

您需要为您的Provider接口添加注解@EncryptKey. 这个annotation接受一个字符串作为加密/解密数据所必需的key。 但是,您需要使用@Encrypt对Provider的缓存进行注解,以便缓存数据加密。 如果没有设置@Encrypt,则不会进行加密。

重要提示:如果提供的“key”值 @EncryptKey 在编译期间进行了修改,那么以前的缓存数据将无法被RxCache驱逐/获取。

@EncryptKey("myStrongKey-1234")
interface Providers {
        @Encrypt
        Observable<List<Mock>> getMocksEncrypted(Observable<List<Mock>> oMocks);

        Observable<List<Mock>> getMocksNotEncrypted(Observable<List<Mock>> oMocks);
}

常规配置

RxCache允许在构建Provider实例时设置某些参数:

配置要保留的数据的大小限制(以兆字节为单位)

默认情况下,RxCache将限制设置为100M,但您可以在构建Provider实例时调用setMaxMBPersistenceCache方法来更改此值。

new RxCache.Builder()
            .setMaxMBPersistenceCache(maxMgPersistenceCache)
            .persistence(cacheDir)
            .using(Providers.class);

当达到此限制时,RxCache将无法继续缓存数据。 这就是为何当缓存数据容量即将达到阈值时,RxCache有一个自动化的过程来驱逐任何记录,即使没有满足失效时间的缓存数据也被驱逐。

唯一的例外是,当您的Provider的某方法用@Expirable 注解注释,并将其值设置为false将会被保存,而不会被RxCache自动化驱逐。

interface Providers {
    //即使缓存数据达到阈值,也不会被RxCache自动驱逐
    @Expirable(false)
    Observable<List<Mock>> getMocksNotExpirable(Observable<List<Mock>> oMocks);
}

如果未加载到数据,使用过期的缓存数据

默认情况下,如果缓存的数据已过期并且observable loader返回的数据为空,RxCache将抛出RuntimeException异常。

您可以修改此行为,允许RxCache在这种情况下提供被驱逐的数据,使用方式很简单,通过将useExpiredDataIfLoaderNotAvailable的值设置为true:

new RxCache.Builder()
            .useExpiredDataIfLoaderNotAvailable(true)   //RxCache提供被驱逐的数据
            .persistence(cacheDir)
            .using(Providers.class);

Android注意事项

要构建由RxCache提供的接口实例,您需要提供对文件系统的引用。 在Android上,您可以从Application类获取文件引用调用getFilesDir()。

此外,建议您在应用程序的整个生命周期中使用此Android应用程序类来提供RxCache的唯一实例(全局单例)。

为了在子线程上执行Observable,并通过主UI线程上的onNext发出结果,您应该使用RxAndroid提供的内置方法。

即 observable.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe();

你可以查看Demo: Android example

和Retrofit搭配使用

RxCache和Retrofit完美搭配,两者配合可以实现从始至终的自动管理缓存数据库。
您可以检查RxCache和Retrofit的一个示例

其他

RxCache原理

RxCache的数据来源取决于下面三个数据层中某一层:

*内存层 - >由Apache ReferenceMap提供支持。
*持久层 - > RxCache内部使用Jolyglot来对对象进行序列化和反序列化。
*加载器层(由客户端库提供的Observable请求,比如网络请求)

*如果请求的数据在内存中,并且尚未过期,则从内存中获取。
*否则请求的数据在持久层中,并且尚未过期,则从持久层获取。
*否则从加载器层请求获取数据。

代码混淆

-dontwarn io.rx_cache.internal.**
-keepclassmembers enum io.rx_cache.Source { *; }

关于作者

Víctor Albertos

RxCache Swift版本:

RxCache: Reactive caching library for Swift.

作者其它使用RxJava的库:

  • Mockery: Android and Java library for mocking and testing networking layers with built-in support for Retrofit.
  • RxActivityResult: A reactive-tiny-badass-vindictive library to break with the OnActivityResult implementation as it breaks the observables chain.
  • RxFcm: RxJava extension for Android Firebase Cloud Messaging (aka fcm).
  • RxSocialConnect: OAuth RxJava extension for Android.

关于中文文档

翻译

参考

©️2020 CSDN 皮肤主题: 成长之路 设计师: Amelia_0503 返回首页
实付0元
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、C币套餐、付费专栏及课程。

余额充值