cesarferreira / rxpaper Goto Github PK

Reactive extension for NoSQL data storage on Android

License: MIT License

Java 100.00%

rxpaper's Introduction

RxPaper

RxPaper is a RxJava wrapper for the cool paper library, a fast NoSQL data storage for Android that lets you save/restore Java objects by using efficient Kryo serialization and handling data structure changes automatically.

For the RxJava 2 version please go to RxPaper2 made by Pakoito.

What's new for the new `PaperDB 2.0` (starting on `0.5.0`+ version)

Update internal Kryo serializer to 4.0. The data format is changed, but Paper supports backward data compatibility automatically;
Now 58% less methods count : 4037;
Depends on data structure you may experience faster reading but slower writing.

Add dependency

repositories {
    jcenter()
    maven { url "https://jitpack.io" }
 }
dependencies {
    compile 'com.cesarferreira.rxpaper:rxpaper:0.5.0'
}

Install

Init the library in your Application class

public class SampleApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();

        RxPaper.init(this);
    }
}

Save

Save data object. Your custom classes must have no-arg constructor. Paper creates separate data file for each key.

RxPaper.book()
        .write(key, value)
        .subscribe(success -> /* all good */ );

I'm serious: Your custom classes must have no-arg constructor.

Read

Read data objects. Paper instantiates exactly the classes which has been used in saved data. The limited backward and forward compatibility is supported. See Handle data class changes.

Use default values if object doesn't exist in the storage.

RxPaper.book()
        .read(key, defaultPersonValue)
        .subscribe(person -> /* all good */ );

Delete

Delete data for one key.

RxPaper.book()
       .delete(key)
       .subscribe();

Completely destroys Paper storage.

RxPaper.book()
       .destroy()
       .subscribe();

Exists

Check if a key is persisted

RxPaper.book()
       .exists(key)
       .subscribe(success -> /* all good */);

Get all keys

Returns all keys for objects in the book.

RxPaper.book()
       .getAllKeys()
       .subscribe(allKeys -> /* all good */);

Use custom book

You can create custom Book book separate storage using

RxPaper.book("custom-book")...;

Any changes in one book doesn't affect to others books.

Important information

Don't forget to specify which threads you want to use before subscribing to any data manipulation, or else it'll run on the UI thread.

...
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe(...

Handle data structure changes

Class fields which has been removed will be ignored on restore and new fields will have their default values. For example, if you have following data class saved in Paper storage:

class Person {
    public String firstName; // Cesar
    public String middleName; // Costa
}

And then you realized you need to change the class like:

class Person {
    public String firstName; // Cesar
    // public String middleName; removed field, who cares about middle names
    public String lastName; // New field
}

Then on restore the middleName field will be ignored and new lastName field will have its default value null.

Exclude fields

Use transient keyword for fields which you want to exclude from saving process.

public transient String tempId = "default"; // Won't be saved

Proguard config

Keep data classes:

-keep class my.package.data.model.** { *; }

alternatively you can implement Serializable in all your data classes and keep all of them using:

-keep class * implements java.io.Serializable { *; }

Keep library classes and its dependencies

-keep class io.paperdb.** { *; }
-keep class com.esotericsoftware.** { *; }
-dontwarn com.esotericsoftware.**
-keep class de.javakaffee.kryoserializers.** { *; }
-dontwarn de.javakaffee.kryoserializers.**

How it works

Paper is based on the following assumptions:

Saved data on mobile are relatively small;
Random file access on flash storage is very fast.

So each data object is saved in separate file and write/read operations write/read whole file.

The Kryo is used for object graph serialization and to provide data compatibility support.

Benchmark results

Running Benchmark on Nexus 4, in ms:

Benchmark	Paper	Hawk
Read/write 500 contacts	187	447
Write 500 contacts	108	221
Read 500 contacts	79	155

rxpaper's People

Contributors

Stargazers

Watchers

Forkers

menht suxinde2009 25343215 mkpowers gfpf mysmartapk mstart franciscoe-hudl rafakob jalsoncc matrixy mapleskip diegorodriguezaguila wangpeng1 trikke dandycheung classicvalues tlaiamz

rxpaper's Issues

getAllKeys() + hasBook() implementation leads to unwanted behaviour

public Observable<List<String>> getAllKeys() {

    return Observable.create(new Observable.OnSubscribe<List<String>>() {
        @Override
        public void call(Subscriber<? super List<String>> subscriber) {

            if (!subscriber.isUnsubscribed()) {

                try {
                    List<String> keys;
                    if (hasBook()) {
                        keys = Paper.book(mCustomBook).getAllKeys();
                    } else {
                        keys = Paper.book().getAllKeys();
                    }
                    subscriber.onNext(keys);
                } catch (Exception e) {
                    subscriber.onError(new UnableToPerformOperationException("Can't collect all keys"));
                }

                subscriber.onCompleted();
            }
        }
    });
}

private static boolean hasBook() {
return !TextUtils.isEmpty(mCustomBook);
}

In my implementation I work with multiple books.
Problem: I don't know at runtime if a book has entries or not.
If I call "getAllKeys()" at a time where a book is empty I get all keys from default book.

I will overcome this problem by not using default book. However, I suggest to just return zero keys if a custom book is empty and not fall back to default book keys.

Observable retains Context but doesn't use it

Being the #1 cause of leaks on Android, retaining a Context is rarely recommended. It is still required by the main observable, but it's never used, becoming a pointless pain point: https://github.com/cesarferreira/RxPaper/blob/master/rxpaper/src/main/java/com/cesarferreira/rxpaper/RxPaper.java

Could you please release a new version with that change, and deprecating the old use?

No ability to have multiple instances of RxPaper

RxPaper contains 2 static fields to hold the instances of the current RxPaper and custom book you'd be using.

private static RxPaper mRxPaper;
private static String sCustomBook;

There are 2 issues with this setup which both relate to having multiple custom books (or preferably, instances of RxPaper)

Problem 1:

RxPaper.book("custom-book1").read(...)
RxPaper.book("custom-book2").read(...)
RxPaper.book("custom-book1").read(...)

This will instantiate 3 instances on RxPaper (3x overriding the same static field). So if i use 2 custom books i will create a lot of useless instances.

Problem 2:

I can not have multiple classes which each have a separate RxPaper with a custom book because of the above. The last class create will determine which custom book the will all share.

Initializing Paper too much times?

What is the need to pass a context to RxPaper.with(..) method, which initilalizes Paper.init(...) for every call?, In Paper docs states that Paper.init(context); must be called only once in Application.onCreate(...). I'm temporary workarounding it by creating another initializer, but I think the context is not necesary in any way.

RxJava 2 support

Any plans to support RxJava2?

Respect the Observable contract for errors

https://github.com/cesarferreira/RxPaper/blob/master/rxpaper/src/main/java/com/cesarferreira/rxpaper/RxPaper.java#L50

https://github.com/cesarferreira/RxPaper/blob/master/rxpaper/src/main/java/com/cesarferreira/rxpaper/RxPaper.java#L89

https://github.com/cesarferreira/RxPaper/blob/master/rxpaper/src/main/java/com/cesarferreira/rxpaper/RxPaper.java#L104

An exception is an exception, and should come onError.

As I see in the code
https://github.com/cesarferreira/RxPaper/blob/master/rxpaper/src/main/java/com/cesarferreira/rxpaper/RxPaper.java#L43
write is performed immediately as RxPaper.with(ctx).write(key, value) is called. This should be doing in onSuscribe instead so disk i/o could be postponed and scheduled in the bg thread using Rx.